chartflow 0.1__py3-none-any.whl

chartflow/node/popmenu.py

@@ -0,0 +1,472 @@
+"""
+右键菜单模块 - 画布 / 节点 / 连线 三种弹出菜单
+
+按右键命中的目标拆分为三种菜单, 每种各有一个 Protocol 契约(IXxxPopMenu)
+和一个 QMenu 实现类(QXxxPopMenu)。契约仅用于静态类型检查与文档, 不参与
+运行时继承(结构子类型)。
+
+持有关系(由宿主持有):
+  - ``NodeCanvas.menu``  -> ``QCanvasPopMenu``   (画布空白右键, 长期持有)
+  - ``NodeCanvas.lmenu`` -> ``QLinePopMenu``     (连线/箭头右键, 每次右键重构)
+  - ``NodeItem.menu``    -> ``QNodePopMenu``     (节点右键, 由 canvas.addNode 注入)
+
+构造签名:
+  - ``QCanvasPopMenu(canvas)``
+  - ``QNodePopMenu(canvas, node)``
+  - ``QLinePopMenu(canvas, source, target)``  其中端点为 NodeItem 或 QNodePort
+
+实现约定: 每个 exec() 调用都先 ``clear()`` 再 ``addAction`` 重建菜单项,
+使动态状态(节点当前形状、Set as Start 的 enabled、节点计数等)总是最新。
+"""
+
+from typing import Optional, Union, Protocol, runtime_checkable, TYPE_CHECKING
+
+from PyQt6.QtWidgets import QMenu
+from PyQt6.QtCore import QPointF
+
+from chartflow.node.enums import NodeShape
+
+if TYPE_CHECKING:
+    from chartflow.node.node_canvas import QNodeCanvas
+    from chartflow.node.node_item import QNodeItem
+    from chartflow.node.connection_item import ConnectionItem
+    from chartflow.node.port_item import QNodePort
+
+
+# 连线端点: 可为节点(NodeItem)或端口渲染项(QNodePort)。
+# 端口优先: 若该端锚定到 port, 用 QNodePort; 否则用 NodeItem。
+PortEndpoint = Union["NodeItem", "QNodePort"]
+
+
+# ====================================================================== #
+# 画布右键菜单
+# ====================================================================== #
+@runtime_checkable
+class ICanvasPopMenu(Protocol):
+    """画布右键菜单接口契约
+
+    声明空白画布右键菜单应具备的对外属性与方法。具体实现由
+    :class:`QCanvasPopMenu` 承担。
+
+    动作:
+    - **Add Node**: 在右键场景坐标处添加节点(命名 ``Node{N+1}``)
+    - **Layout**: 自动布局(Compact/Circular/Grid/Hierarchical/Force Directed)
+    - **Fit to Viewport**: 自动适应视口
+    """
+
+    @property
+    def canvas(self) -> "QNodeCanvas":
+        """菜单绑定的画布(只读)。"""
+        ...
+
+    def addNode(self, pos: QPointF) -> None:
+        """在场景坐标 ``pos`` 处添加一个新节点。"""
+        ...
+
+    def layout(self, strategy: str) -> None:
+        """执行自动布局。
+
+        Args:
+            strategy: 布局策略, 取值 ``compact`` / ``circular`` / ``grid`` /
+                ``hierarchical`` / ``force``。
+        """
+        ...
+
+    def fitViewport(self) -> None:
+        """自动适应视口(缩放并居中到全部节点)。"""
+        ...
+
+    def exec(self, global_pos, scene_pos: Optional[QPointF] = None) -> None:
+        """重建菜单项并弹出。
+
+        Args:
+            global_pos: 菜单弹出的全局坐标(QPoint)。
+            scene_pos: 右键命中位置的场景坐标(QPointF); Add Node 动作用作新节点
+                的落点。``None`` 时回退到原点。
+        """
+        ...
+
+
+class QCanvasPopMenu(QMenu):
+    """画布右键菜单实现
+
+    长期持有(由 ``NodeCanvas.menu`` 持有); 每次 :meth:`exec` 先 ``clear()``
+    再重建动作, 保证动态状态新鲜。
+    """
+
+    def __init__(self, canvas: "QNodeCanvas", parent=None) -> None:
+        super().__init__(parent)
+        self._canvas: "QNodeCanvas" = canvas
+
+    @property
+    def canvas(self) -> "QNodeCanvas":
+        """获取绑定的画布"""
+        return self._canvas
+
+    # ---- 槽位(转发到画布私有辅助方法) ----
+    def addNode(self, pos: QPointF) -> None:
+        """在指定场景坐标添加节点"""
+        self._canvas._onAddNodeAt(pos)
+
+    def layout(self, strategy: str) -> None:
+        """执行自动布局"""
+        self._canvas._onLayout(strategy)
+
+    def fitViewport(self) -> None:
+        """自动适应视口"""
+        self._canvas._onFitViewport()
+
+    def exec(self, global_pos, scene_pos: Optional[QPointF] = None) -> None:
+        """重建并弹出菜单。
+
+        Args:
+            global_pos: 菜单弹出的全局坐标。
+            scene_pos: 右键命中位置的场景坐标; 作为 Add Node 的落点。
+        """
+        self.clear()
+
+        # 添加节点
+        add_node_action = self.addAction("Add Node")
+        self.addSeparator()
+
+        # 布局动作
+        layout_menu = self.addMenu("Layout")
+        layout_actions = {
+            "Compact": "compact",
+            "Circular": "circular",
+            "Grid": "grid",
+            "Hierarchical": "hierarchical",
+            "Force Directed": "force",
+        }
+        for label, key in layout_actions.items():
+            action = layout_menu.addAction(label)
+            action.triggered.connect(lambda _checked=False, k=key: self.layout(k))
+
+        self.addSeparator()
+
+        # 自动适应视口
+        fit_viewport_action = self.addAction("Fit to Viewport")
+
+        chosen = super().exec(global_pos)
+        if chosen == add_node_action:
+            self.addNode(scene_pos if scene_pos is not None else QPointF())
+        elif chosen == fit_viewport_action:
+            self.fitViewport()
+
+
+# ====================================================================== #
+# 节点右键菜单
+# ====================================================================== #
+@runtime_checkable
+class INodePopMenu(Protocol):
+    """节点右键菜单接口契约
+
+    声明节点右键菜单应具备的对外属性与方法。具体实现由
+    :class:`QNodePopMenu` 承担。
+
+    动作:
+    - **Edit**: 请求编辑(有 editorClass 则打开, 否则发射 editRequested 信号)
+    - **Rename**: 重命名(占位, 暂未实现)
+    - **Delete**: 删除节点
+    - **Shape**: 切换形状(Ellipse/Rectangle/Diamond, checkable)
+    - **Set as Start Node**: 设为起点(enabled 当 canvas.startNode != node)
+    """
+
+    @property
+    def node(self) -> "QNodeItem":
+        """菜单绑定的节点(只读)。"""
+        ...
+
+    def edit(self) -> None:
+        """请求编辑本节点。"""
+        ...
+
+    def rename(self) -> None:
+        """重命名本节点(占位)。"""
+        ...
+
+    def delete(self, canvas: "QNodeCanvas") -> None:
+        """删除本节点。
+
+        Args:
+            canvas: 节点所在的画布。
+        """
+        ...
+
+    def setShape(self, shape: NodeShape) -> None:
+        """切换节点形状。
+
+        Args:
+            shape: 目标形状(NodeShape.ELLIPSE/RECTANGLE/DIAMOND)。
+        """
+        ...
+
+    def setAsStart(self, canvas: "QNodeCanvas") -> None:
+        """将本节点设为起点。
+
+        Args:
+            canvas: 节点所在的画布。
+        """
+        ...
+
+    def exec(self, global_pos, canvas: Optional["QNodeCanvas"] = None) -> None:
+        """重建菜单项并弹出。
+
+        Args:
+            global_pos: 菜单弹出的全局坐标(QPoint)。
+            canvas: 画布引用; 传入时启用 Delete / Set as Start 动作,
+                ``None`` 时这两项被禁用。默认沿用构造时的 canvas。
+        """
+        ...
+
+
+class QNodePopMenu(QMenu):
+    """节点右键菜单实现
+
+    由 ``NodeCanvas.addNode`` 注入到 ``node.menu``。每次 :meth:`exec` 先
+    ``clear()`` 再重建动作。
+    """
+
+    def __init__(
+        self,
+        canvas: "QNodeCanvas",
+        node: "QNodeItem",
+        parent=None,
+    ) -> None:
+        super().__init__(parent)
+        self._canvas: "QNodeCanvas" = canvas
+        self._node: "QNodeItem" = node
+
+    @property
+    def node(self) -> "QNodeItem":
+        """获取绑定的节点"""
+        return self._node
+
+    # ---- 槽位 ----
+    def edit(self) -> None:
+        """请求编辑本节点。
+
+        有 editorClass 时实例化并打开编辑器; 否则发射 editRequested 信号,
+        由宿主(画布/窗口)处理。与原 _onNodeEditRequested 行为一致。
+        """
+        node = self._node
+        if node.editorClass:
+            editor = node.editorClass(node)
+            editor.setWindowTitle(editor.getTitle())
+            editor.show()
+        else:
+            node.editRequested.emit(node)
+
+    def rename(self) -> None:
+        """重命名(占位, 暂未实现)"""
+        # TODO: 实现重命名功能
+        pass
+
+    def delete(self, canvas: "QNodeCanvas") -> None:
+        """删除本节点"""
+        canvas.removeNode(self._node)
+
+    def setShape(self, shape: NodeShape) -> None:
+        """切换节点形状"""
+        self._node.nodeShape = shape
+
+    def setAsStart(self, canvas: "QNodeCanvas") -> None:
+        """将本节点设为起点"""
+        canvas.startNode = self._node
+
+    def exec(self, global_pos, canvas: Optional["QNodeCanvas"] = None) -> None:
+        """重建并弹出菜单。
+
+        Args:
+            global_pos: 菜单弹出的全局坐标。
+            canvas: 画布引用; 默认沿用构造时的 canvas。``None`` 时 Delete /
+                Set as Start 被禁用。
+        """
+        c = canvas if canvas is not None else self._canvas
+
+        self.clear()
+
+        # 编辑和重命名
+        edit_action = self.addAction("Edit")
+        rename_action = self.addAction("Rename")
+        delete_action = self.addAction("Delete")
+        delete_action.setEnabled(c is not None)
+        self.addSeparator()
+
+        # 形状切换子菜单
+        shape_menu = self.addMenu("Shape")
+        shape_actions: dict = {}
+        for shape, label in (
+            (NodeShape.ELLIPSE, "Ellipse"),
+            (NodeShape.RECTANGLE, "Rectangle"),
+            (NodeShape.DIAMOND, "Diamond"),
+        ):
+            action = shape_menu.addAction(label)
+            action.setCheckable(True)
+            action.setChecked(self._node.nodeShape == shape)
+            shape_actions[action] = shape
+
+        self.addSeparator()
+
+        # 设置起点
+        set_start_action = self.addAction("Set as Start Node")
+        set_start_action.setEnabled(c is not None and c.startNode is not self._node)
+
+        chosen = super().exec(global_pos)
+        if chosen == edit_action:
+            self.edit()
+        elif chosen == rename_action:
+            self.rename()
+        elif chosen == delete_action and c is not None:
+            self.delete(c)
+        elif chosen in shape_actions:
+            self.setShape(shape_actions[chosen])
+        elif chosen == set_start_action and c is not None:
+            self.setAsStart(c)
+
+
+# ====================================================================== #
+# 连线右键菜单
+# ====================================================================== #
+@runtime_checkable
+class ILinePopMenu(Protocol):
+    """连线右键菜单接口契约
+
+    声明连线/箭头右键菜单应具备的对外属性与方法。具体实现由
+    :class:`QLinePopMenu` 承担。
+
+    动作:
+    - **Toggle Line Type (Bezier/Straight)**: 切换连线类型(贝塞尔 <-> 直线)
+    - **Delete Connection**: 删除该连线
+
+    Note:
+        连线由两端点(source/target)标识, 每个端点为节点或端口。构造时传入
+        两端点, 菜单据此在画布的连接列表中精确定位到目标 ConnectionItem。
+    """
+
+    @property
+    def canvas(self) -> "QNodeCanvas":
+        """菜单绑定的画布(只读)。"""
+        ...
+
+    @property
+    def source(self) -> PortEndpoint:
+        """连线源端点(NodeItem 或 QNodePort, 只读)。"""
+        ...
+
+    @property
+    def target(self) -> PortEndpoint:
+        """连线目标端点(NodeItem 或 QNodePort, 只读)。"""
+        ...
+
+    def toggleLineType(self) -> None:
+        """切换连线类型(贝塞尔 <-> 直线)。"""
+        ...
+
+    def removeConnection(self) -> None:
+        """删除该连线。"""
+        ...
+
+    def exec(self, global_pos) -> None:
+        """重建菜单项并弹出。
+
+        Args:
+            global_pos: 菜单弹出的全局坐标(QPoint)。
+        """
+        ...
+
+
+class QLinePopMenu(QMenu):
+    """连线右键菜单实现
+
+    每次右键由画布 ``contextMenuEvent`` 重构(``canvas.lmenu = QLinePopMenu(...)``)
+    再 :meth:`exec`, 因为两端点随右键目标变化。原箭头菜单的 "Remove Connection"
+    合并入 "Delete Connection"(同一行为)。
+    """
+
+    def __init__(
+        self,
+        canvas: "QNodeCanvas",
+        source: PortEndpoint,
+        target: PortEndpoint,
+        parent=None,
+    ) -> None:
+        super().__init__(parent)
+        self._canvas: "QNodeCanvas" = canvas
+        self._source: PortEndpoint = source
+        self._target: PortEndpoint = target
+
+    @property
+    def canvas(self) -> "QNodeCanvas":
+        """获取绑定的画布"""
+        return self._canvas
+
+    @property
+    def source(self) -> PortEndpoint:
+        """获取源端点"""
+        return self._source
+
+    @property
+    def target(self) -> PortEndpoint:
+        """获取目标端点"""
+        return self._target
+
+    def _findConnection(self) -> Optional["ConnectionItem"]:
+        """按 (源端点, 目标端点) 在画布连接列表中精确定位连线。
+
+        端点为 QNodePort 时用 ``is`` 比较; 为 NodeItem 时要求该端 port 为 None
+        (即节点边缘锚定, 非 port 锚定)。端点组合唯一确定一条连线。
+        """
+        from chartflow.node.port_item import QNodePort as _QNodePort
+
+        src_is_port = isinstance(self._source, _QNodePort)
+        tgt_is_port = isinstance(self._target, _QNodePort)
+
+        for conn in self._canvas._connections:
+            if src_is_port:
+                src_match = conn.sourcePort is self._source
+            else:
+                src_match = (conn.sourceNode is self._source
+                             and conn.sourcePort is None)
+            if not src_match:
+                continue
+            if tgt_is_port:
+                tgt_match = conn.targetPort is self._target
+            else:
+                tgt_match = (conn.targetNode is self._target
+                             and conn.targetPort is None)
+            if tgt_match:
+                return conn
+        return None
+
+    # ---- 槽位 ----
+    def toggleLineType(self) -> None:
+        """切换连线类型(贝塞尔 <-> 直线)"""
+        conn = self._findConnection()
+        if conn is not None:
+            conn.toggleConnectionType()
+
+    def removeConnection(self) -> None:
+        """删除该连线"""
+        conn = self._findConnection()
+        if conn is not None:
+            self._canvas.removeConnection(conn)
+
+    def exec(self, global_pos) -> None:
+        """重建并弹出菜单。
+
+        Args:
+            global_pos: 菜单弹出的全局坐标。
+        """
+        self.clear()
+
+        # 切换连接类型
+        toggle_type_action = self.addAction("Toggle Line Type (Bezier/Straight)")
+        self.addSeparator()
+        remove_action = self.addAction("Delete Connection")
+
+        chosen = super().exec(global_pos)
+        if chosen == toggle_type_action:
+            self.toggleLineType()
+        elif chosen == remove_action:
+            self.removeConnection()