chartflow 0.1__py3-none-any.whl

chartflow/node/_node_interaction.py

@@ -0,0 +1,488 @@
+"""
+节点交互 Mixin 模块
+
+定义 _NodeInteractionMixin —— hover/鼠标/名称编辑/选中/事件/连线更新、
+标记(start/single/custom)与悬浮按钮(hover button)动画相关行为。
+本类不含 __init__, 通过覆写 _NodeCore._init_interaction / _init_markers
+钩子创建相应属性。
+
+依赖关系: _NodeInteractionMixin 不继承 _NodeCore(避免循环导入与 MRO 问题);
+运行时由 NodeItem(_NodePortMixin, _NodeInteractionMixin, _NodeCore) 组合,
+所有 self.xxx 调用经 MRO 在 _NodeCore/_NodePortMixin/NodeItem 上解析。
+标记辅助类从 _node_markers 导入(独立模块, 打破循环)。
+"""
+
+from typing import Optional
+
+from PyQt6.QtCore import Qt, QPointF, QPropertyAnimation, QEasingCurve
+from PyQt6.QtGui import QColor
+from PyQt6.QtWidgets import QGraphicsItem
+
+from chartflow.node.enums import NodeState
+from chartflow.node.connection_item import ConnectionItem
+from chartflow.node._node_markers import (
+    HoverButton, StartMarker, SingleMarker, CustomMarker,
+)
+from chartflow.node._node_base import (
+    BUTTON_RADIUS_RATIO,
+    ANIMATION_DURATION_SHOW,
+    ANIMATION_DURATION_HIDE,
+    HOVER_MOVE_THRESHOLD_SQ,
+)
+
+
+class _NodeInteractionMixin:
+    """交互 Mixin
+
+    承载:
+    - hover 事件: hoverEnterEvent/hoverMoveEvent/hoverLeaveEvent/_handleHoverAnchorMove
+    - 鼠标事件: mousePressEvent/itemChange/eventFilter
+    - 名称编辑: _startNameEdit/_finishNameEdit/isEditingName
+    - 连线更新: _updateConnections
+    - 悬浮按钮: setEditWindowOpen/_showHoverButtonImmediately/_hideHoverButton/
+      _onHideAnimationFinished/_onHoverButtonClicked
+    - 标记: setStartMarkerVisible/setSingleMarkerVisible/setCustomMarkerVisible/
+      setCustomMarkerStyle/getCustomMarkerStyle 及 *_HideFinished 回调
+    """
+
+    # ------------------------------------------------------------------ #
+    # 初始化钩子(覆写 _NodeCore._init_interaction / _init_markers)
+    # ------------------------------------------------------------------ #
+    def _init_interaction(self) -> None:
+        """创建悬浮按钮及其动画属性"""
+        # 悬浮按钮在 __init__ 后续步骤中创建并连接信号; 此处仅声明状态标志
+        self._is_button_visible: bool = False
+        self._edit_window_open: bool = False  # 编辑窗口是否打开
+        # 占位, 由 _setup_overlays 在 QGraphicsItem 初始化完成后创建
+        self._hover_button: Optional[HoverButton] = None
+        self._opacity_animation: Optional[QPropertyAnimation] = None
+
+    def _setup_overlays(self) -> None:
+        """创建悬浮按钮(以本节点为父项)并连接信号/动画"""
+        # 悬浮按钮（左上角的编辑按钮）
+        self._hover_button = HoverButton(self)
+        self._hover_button.clicked.connect(self._onHoverButtonClicked)
+
+        # 透明度动画
+        self._opacity_animation = QPropertyAnimation(self._hover_button, b"opacity")
+        self._opacity_animation.setEasingCurve(QEasingCurve.Type.InOutQuad)
+
+    def _init_markers(self) -> None:
+        """创建标记(start/single/custom)占位属性(懒创建)"""
+        self._start_marker: Optional[StartMarker] = None
+        self._is_start_marker_visible: bool = False
+        self._start_marker_animation: Optional[QPropertyAnimation] = None
+
+        self._single_marker: Optional[SingleMarker] = None
+        self._is_single_marker_visible: bool = False
+        self._single_marker_animation: Optional[QPropertyAnimation] = None
+
+        self._custom_marker: Optional[CustomMarker] = None
+        self._is_custom_marker_visible: bool = False
+        self._custom_marker_animation: Optional[QPropertyAnimation] = None
+
+    # ------------------------------------------------------------------ #
+    # hover 事件
+    # ------------------------------------------------------------------ #
+    def hoverEnterEvent(self, event) -> None:
+        """鼠标进入事件"""
+        if self._state != NodeState.SELECTED:
+            self._state = NodeState.HOVER
+            self._applyStyle()
+
+        # 进入节点本体: 计时显示全部端口 label(悬停 dot 时不触发);
+        # 记录锚点用于判断鼠标是否静止
+        self._node_hovered = True
+        self._hover_anchor = event.scenePos()
+        self._maybeStartPortShowAll()
+        super().hoverEnterEvent(event)
+
+    def hoverMoveEvent(self, event) -> None:
+        """鼠标移动: 若在节点本体上移动超过阈值, 则打断"显示全部"并重置等待"""
+        if self._node_hovered and self._hovered_port_count == 0:
+            self._handleHoverAnchorMove(event.scenePos())
+        super().hoverMoveEvent(event)
+
+    def _handleHoverAnchorMove(self, pos: QPointF) -> None:
+        """根据鼠标位置判断是否"移动": 超过阈值则打断显示全部并重置等待"""
+        anchor = self._hover_anchor
+        if anchor is None:
+            self._hover_anchor = QPointF(pos)
+            return
+        dx = pos.x() - anchor.x()
+        dy = pos.y() - anchor.y()
+        if dx * dx + dy * dy > HOVER_MOVE_THRESHOLD_SQ:
+            # 移动打断: 隐藏已显示的全部 label, 重新计时, 更新锚点
+            self._setAllPortsShowAll(False)
+            self._port_label_timer.start()
+            self._hover_anchor = QPointF(pos)
+
+    def hoverLeaveEvent(self, event) -> None:
+        """鼠标离开事件"""
+        if self._state != NodeState.SELECTED:
+            self._state = NodeState.IDLE
+            self._applyStyle()
+
+        # 离开节点: 取消计时, 隐藏全部端口 label 并清除 dot 的 hover 描边
+        self._node_hovered = False
+        self._hover_anchor = None
+        self._port_label_timer.stop()
+        self._resetPortHover()
+        super().hoverLeaveEvent(event)
+
+    # ------------------------------------------------------------------ #
+    # 鼠标事件
+    # ------------------------------------------------------------------ #
+    def mousePressEvent(self, event) -> None:
+        """鼠标按下事件"""
+        # 检查是否点击了悬浮按钮
+        if self._is_button_visible and self._hover_button.mousePressEvent(event):
+            return
+
+        # 检查是否点击了名称编辑区域（开始编辑名称）
+        if event.button() == Qt.MouseButton.LeftButton:
+            # 将场景坐标转换为本地坐标
+            local_pos = self.mapFromScene(event.scenePos())
+            if self._name_edit_area.contains(local_pos):
+                self._startNameEdit()
+                return
+
+        super().mousePressEvent(event)
+
+    def mouseMoveEvent(self, event) -> None:
+        """拖动节点时: 立即隐藏全部端口 label, 并停止'显示全部'计时。
+
+        鼠标按下后 Qt 进入 mouse grab, hoverMoveEvent 不再派发, 端口 label 的
+        '静止 0.5s 显示'判定在此期间失效。此处显式打断: 只要开始拖动, 已显示的
+        端口 label 立即隐藏, 且拖动期间不再重新计时(松开鼠标后才恢复)。
+        判定仍以场景(画布)坐标为准, 与 hoverMoveEvent 一致。
+        """
+        if self._node_hovered and self._hovered_port_count == 0:
+            self._port_label_timer.stop()
+            self._setAllPortsShowAll(False)
+            self._hover_anchor = QPointF(event.scenePos())
+        super().mouseMoveEvent(event)
+
+    def mouseReleaseEvent(self, event) -> None:
+        """松开鼠标: 若仍在节点本体上, 恢复'静止 0.5s 显示全部'计时。"""
+        super().mouseReleaseEvent(event)
+        if self._node_hovered and self._hovered_port_count == 0:
+            self._hover_anchor = QPointF(event.scenePos())
+            self._port_label_timer.start()
+
+    def itemChange(self, change: QGraphicsItem.GraphicsItemChange, value):
+        """项状态改变事件"""
+        if change == QGraphicsItem.GraphicsItemChange.ItemSelectedChange:
+            if value:
+                self._state = NodeState.SELECTED
+            else:
+                self._state = NodeState.IDLE
+            self._applyStyle()
+        elif change == QGraphicsItem.GraphicsItemChange.ItemPositionHasChanged:
+            # 位置已改变，更新连接
+            if self.scene():
+                self._updateConnections()
+
+        return super().itemChange(change, value)
+
+    def _updateConnections(self) -> None:
+        """更新与此节点相关的所有连接"""
+        if not self.scene():
+            return
+
+        for item in self.scene().items():
+            if isinstance(item, ConnectionItem):
+                if item.sourceNode == self or item.targetNode == self:
+                    item.updatePath()
+
+    # ------------------------------------------------------------------ #
+    # 名称编辑
+    # ------------------------------------------------------------------ #
+    def _startNameEdit(self) -> None:
+        """开始编辑节点名称 - 使用QGraphicsTextItem原生编辑，完全贴合文本"""
+        if self._is_editing_name:
+            return
+
+        self._is_editing_name = True
+
+        # 启用文本项的编辑功能（原位编辑，完全贴合文本）
+        self._text_item.setTextInteractionFlags(Qt.TextInteractionFlag.TextEditorInteraction)
+        self._text_item.setFocus()
+
+        # 选中全部文本
+        cursor = self._text_item.textCursor()
+        cursor.select(cursor.SelectionType.Document)
+        self._text_item.setTextCursor(cursor)
+
+    def _finishNameEdit(self) -> None:
+        """完成名称编辑"""
+        if not self._is_editing_name:
+            return
+
+        # 获取新名称（从文本项）
+        new_name = self._text_item.toPlainText().strip()
+
+        # 禁用文本项的编辑功能
+        self._text_item.setTextInteractionFlags(Qt.TextInteractionFlag.NoTextInteraction)
+
+        # 更新名称（这会重新居中并更新虚线框）
+        if new_name and new_name != self._name:
+            self.name = new_name
+
+        # 清除文本选中和焦点，避免全选高亮在退出编辑后残留。
+        # 注意: 即便上面 setPlainText 已重置光标, 当名称未变化或为空时
+        # 旧选区仍会保留, 因此这里必须显式清除。
+        cursor = self._text_item.textCursor()
+        cursor.clearSelection()
+        self._text_item.setTextCursor(cursor)
+        self._text_item.clearFocus()
+
+        self._is_editing_name = False
+
+    @property
+    def isEditingName(self) -> bool:
+        """是否正在编辑名称"""
+        return self._is_editing_name
+
+    def eventFilter(self, watched, event) -> bool:
+        """事件过滤器 - 检测点击编辑框外部来取消编辑
+
+        Note: 名称编辑已改为原位编辑 _text_item（无独立代理控件），
+        点击外部取消的逻辑统一在 NodeCanvas.mousePressEvent 中处理，
+        此过滤器当前未被 installEventFilter 安装，保留以兼容外部子类。
+        """
+        if not self._is_editing_name:
+            return False
+
+        if event.type() == event.Type.GraphicsSceneMousePress:
+            # 原位编辑：用 _text_item 的场景边界判断点击是否落在编辑文本内
+            edit_item = getattr(self, "_text_item", None)
+            if edit_item is not None:
+                edit_rect = edit_item.sceneBoundingRect()
+                click_pos = event.scenePos()
+                if not edit_rect.contains(click_pos):
+                    self._finishNameEdit()
+                    return False  # 允许事件继续传递
+
+        return False  # 其他事件不处理，继续传递
+
+    # ------------------------------------------------------------------ #
+    # 悬浮按钮(hover button)
+    # ------------------------------------------------------------------ #
+    def setEditWindowOpen(self, open: bool) -> None:
+        """设置编辑窗口是否打开，控制悬浮按钮的显示（带动画）"""
+        self._edit_window_open = open
+        if open:
+            self._showHoverButtonImmediately()
+        else:
+            self._hideHoverButton()
+
+    def _showHoverButtonImmediately(self) -> None:
+        """显示悬浮按钮（带淡入动画）- 当编辑窗口打开时调用"""
+        if not self._edit_window_open:
+            return
+
+        # 计算按钮半径
+        rect = self.rect()
+        button_radius = BUTTON_RADIUS_RATIO * min(rect.width(), rect.height())
+        self._hover_button.setRadius(button_radius)
+
+        self._hover_button.show()
+        self._is_button_visible = True
+
+        # 淡入动画
+        self._opacity_animation.stop()
+        self._opacity_animation.setDuration(ANIMATION_DURATION_SHOW)
+        self._opacity_animation.setStartValue(self._hover_button.getOpacity())
+        self._opacity_animation.setEndValue(1.0)
+        self._opacity_animation.start()
+
+    def _hideHoverButton(self) -> None:
+        """隐藏悬浮按钮（带淡出动画）"""
+        if not self._is_button_visible:
+            return
+
+        # 淡出动画
+        self._opacity_animation.stop()
+        self._opacity_animation.setDuration(ANIMATION_DURATION_HIDE)
+        self._opacity_animation.setStartValue(self._hover_button.getOpacity())
+        self._opacity_animation.setEndValue(0.0)
+        self._opacity_animation.finished.connect(self._onHideAnimationFinished)
+        self._opacity_animation.start()
+
+    def _onHideAnimationFinished(self) -> None:
+        """隐藏动画完成回调"""
+        self._opacity_animation.finished.disconnect(self._onHideAnimationFinished)
+        if not self._edit_window_open:
+            self._hover_button.hide()
+            self._is_button_visible = False
+
+    def _onHoverButtonClicked(self) -> None:
+        """悬浮按钮点击回调"""
+        self._signal_helper.editRequested.emit(self)
+
+    # ------------------------------------------------------------------ #
+    # 标记: 起点(Start)
+    # ------------------------------------------------------------------ #
+    def setStartMarkerVisible(self, visible: bool) -> None:
+        """设置起点标记的显示状态"""
+        if visible == self._is_start_marker_visible:
+            return
+
+        self._is_start_marker_visible = visible
+
+        if visible:
+            # 创建起点标记
+            if self._start_marker is None:
+                self._start_marker = StartMarker(self)
+                self._start_marker_animation = QPropertyAnimation(self._start_marker, b"opacity")
+                self._start_marker_animation.setEasingCurve(QEasingCurve.Type.InOutQuad)
+
+            # 显示动画
+            self._start_marker.show()
+            self._start_marker_animation.stop()
+            self._start_marker_animation.setDuration(ANIMATION_DURATION_SHOW)
+            self._start_marker_animation.setStartValue(self._start_marker.getOpacity())
+            self._start_marker_animation.setEndValue(1.0)
+            self._start_marker_animation.start()
+        else:
+            # 隐藏动画
+            if self._start_marker is not None:
+                self._start_marker_animation.stop()
+                self._start_marker_animation.setDuration(ANIMATION_DURATION_HIDE)
+                self._start_marker_animation.setStartValue(self._start_marker.getOpacity())
+                self._start_marker_animation.setEndValue(0.0)
+                self._start_marker_animation.finished.connect(self._onStartMarkerHideFinished)
+                self._start_marker_animation.start()
+
+    def _onStartMarkerHideFinished(self) -> None:
+        """起点标记隐藏动画完成回调"""
+        self._start_marker_animation.finished.disconnect(self._onStartMarkerHideFinished)
+        if not self._is_start_marker_visible and self._start_marker is not None:
+            self._start_marker.hide()
+
+    # ------------------------------------------------------------------ #
+    # 标记: Single
+    # ------------------------------------------------------------------ #
+    def setSingleMarkerVisible(self, visible: bool) -> None:
+        """设置 single 标记的显示状态"""
+        if visible == self._is_single_marker_visible:
+            return
+
+        self._is_single_marker_visible = visible
+
+        if visible:
+            # 创建 single 标记
+            if self._single_marker is None:
+                self._single_marker = SingleMarker(self)
+                self._single_marker_animation = QPropertyAnimation(self._single_marker, b"opacity")
+                self._single_marker_animation.setEasingCurve(QEasingCurve.Type.InOutQuad)
+
+            # 显示动画
+            self._single_marker.show()
+            self._single_marker_animation.stop()
+            self._single_marker_animation.setDuration(ANIMATION_DURATION_SHOW)
+            self._single_marker_animation.setStartValue(self._single_marker.getOpacity())
+            self._single_marker_animation.setEndValue(1.0)
+            self._single_marker_animation.start()
+        else:
+            # 隐藏动画
+            if self._single_marker is not None:
+                self._single_marker_animation.stop()
+                self._single_marker_animation.setDuration(ANIMATION_DURATION_HIDE)
+                self._single_marker_animation.setStartValue(self._single_marker.getOpacity())
+                self._single_marker_animation.setEndValue(0.0)
+                self._single_marker_animation.finished.connect(self._onSingleMarkerHideFinished)
+                self._single_marker_animation.start()
+
+    def _onSingleMarkerHideFinished(self) -> None:
+        """single 标记隐藏动画完成回调"""
+        self._single_marker_animation.finished.disconnect(self._onSingleMarkerHideFinished)
+        if not self._is_single_marker_visible and self._single_marker is not None:
+            self._single_marker.hide()
+
+    # ------------------------------------------------------------------ #
+    # 标记: Custom
+    # ------------------------------------------------------------------ #
+    def setCustomMarkerVisible(self, visible: bool) -> None:
+        """设置 custom 标记的显示状态"""
+        if visible == self._is_custom_marker_visible:
+            return
+
+        self._is_custom_marker_visible = visible
+
+        if visible:
+            # 创建 custom 标记
+            if self._custom_marker is None:
+                self._custom_marker = CustomMarker(self)
+                self._custom_marker_animation = QPropertyAnimation(self._custom_marker, b"opacity")
+                self._custom_marker_animation.setEasingCurve(QEasingCurve.Type.InOutQuad)
+
+            # 显示动画
+            self._custom_marker.show()
+            self._custom_marker_animation.stop()
+            self._custom_marker_animation.setDuration(ANIMATION_DURATION_SHOW)
+            self._custom_marker_animation.setStartValue(self._custom_marker.getOpacity())
+            self._custom_marker_animation.setEndValue(1.0)
+            self._custom_marker_animation.start()
+        else:
+            # 隐藏动画
+            if self._custom_marker is not None:
+                self._custom_marker_animation.stop()
+                self._custom_marker_animation.setDuration(ANIMATION_DURATION_HIDE)
+                self._custom_marker_animation.setStartValue(self._custom_marker.getOpacity())
+                self._custom_marker_animation.setEndValue(0.0)
+                self._custom_marker_animation.finished.connect(self._onCustomMarkerHideFinished)
+                self._custom_marker_animation.start()
+
+    def _onCustomMarkerHideFinished(self) -> None:
+        """custom 标记隐藏动画完成回调"""
+        self._custom_marker_animation.finished.disconnect(self._onCustomMarkerHideFinished)
+        if not self._is_custom_marker_visible and self._custom_marker is not None:
+            self._custom_marker.hide()
+
+    def setCustomMarkerStyle(
+        self,
+        text: str = None,
+        bg_color: QColor = None,
+        fg_color: QColor = None,
+        border_color: QColor = None,
+        border_width: float = None,
+        radius: float = None
+    ) -> None:
+        """
+        设置 custom 标记的样式
+
+        Args:
+            text: 显示字符
+            bg_color: 背景色
+            fg_color: 前景色（文本颜色）
+            border_color: 边框颜色
+            border_width: 边框厚度
+            radius: 标记半径
+        """
+        # 如果标记不存在，先创建它
+        if self._custom_marker is None:
+            self._custom_marker = CustomMarker(self)
+            self._custom_marker_animation = QPropertyAnimation(self._custom_marker, b"opacity")
+            self._custom_marker_animation.setEasingCurve(QEasingCurve.Type.InOutQuad)
+
+        self._custom_marker.setStyle(
+            text=text,
+            bg_color=bg_color,
+            fg_color=fg_color,
+            border_color=border_color,
+            border_width=border_width,
+            radius=radius
+        )
+
+    def getCustomMarkerStyle(self) -> dict:
+        """
+        获取 custom 标记的当前样式配置
+
+        Returns:
+            包含样式的字典，如果标记未创建则返回空字典
+        """
+        if self._custom_marker is None:
+            return {}
+        return self._custom_marker.getStyle()