Groups

A Group is a visual container for nodes. It is not a Node: it has no sockets, it takes no part in evaluation, and the nodes inside it keep their positions and edges when the group is collapsed.

nodeeditor.node_group_node is a backward-compatible alias for this module.

nodeeditor.node_group ¶

Reliable ground-up grouping system.

Design notes (v2, clean break): - Group is a pure visual container (QGraphicsRectItem + Serializable), NOT a Node. - Nodes keep their positions/sizes at all times. Collapse only hides/shows, never resizes/scales nodes. This removes the fragile 0.2/scale(0)/width==5 hacks. - Logical Edges never mutate on collapse. Only their graphics endpoints are overridden to per-edge stub rows on the collapsed box. - Auto-fit + header-drag only. Child moves auto-expand, never auto-remove. - Serialization is versioned (version=2, type="Group", key "children"). Old files (type="GroupNode", "child_node_ids") load best-effort as expanded. - Delete-key semantics (handled in view): delete group + children. Context menu offers Ungroup (delete only the group, keep nodes). - Stub stacking: per-edge rows, left=incoming (end inside), right=outgoing (start inside).

Group ¶

Bases: Serializable, QGraphicsRectItem

Visual container grouping Nodes together.

addNode ¶

addNode(node)

Add a node to the group.

A node belongs to at most one group, so adding it here detaches it from the group it was in before.

:param node: the :class:~nodeeditor.node_node.Node to add

removeNode ¶

removeNode(node, update_bounds=True)

Detach a node from the group, keeping the node itself.

:param node: the node to detach from the group :param update_bounds: recalculate the group box afterwards

getChildNodes ¶

getChildNodes()

Return a copy of the list of nodes in the group.

contains ¶

contains(node)

Return whether the given node is a member of this group.

isCollapsed ¶

isCollapsed()

Return whether the group is currently collapsed.

calculateBounds ¶

calculateBounds()

Return the rectangle that tightly fits the child nodes.

The result is at least :attr:MIN_WIDTH by :attr:MIN_HEIGHT_EXPANDED and leaves :attr:PADDING around the children.

updateBounds ¶

updateBounds()

Recompute expanded bounds to tightly fit children.

onChildMoved ¶

onChildMoved(node)

Recalculate the group boundary whenever a child node moves.

Tight refit (may grow, shrink, or shift the origin). Never removes nodes — use Ungroup/detach explicitly. Collapsed groups ignore child moves (children are hidden and move with the container instead).

externalEdges ¶

externalEdges()

Return the edges that cross the group boundary.

:return: a tuple of (incoming, outgoing) edges, where an incoming edge ends inside the group and an outgoing edge starts inside it

stubPosFor ¶

stubPosFor(edge)

Scene position of the stub for edge on THIS collapsed group, or None.

refreshExternalEdges ¶

refreshExternalEdges()

Show or hide edges according to the collapsed state.

External edges are rerouted to their stub rows on the collapsed box, internal edges are hidden while the group is collapsed.

collapse ¶

collapse()

Collapse the group into its title bar.

Child nodes and the edges between them are hidden, the box shrinks to the collapsed width, and the edges crossing the boundary are rerouted to stub rows. Node positions are preserved, so expanding restores the graph exactly as it was.

expand ¶

expand()

Expand the group, restoring the hidden nodes and edges.

The children reappear at the positions they had before the group was collapsed.

restoreExpandedVisuals ¶

restoreExpandedVisuals()

Idempotent expanded visuals for undo/redo/load (mirrors expand without toggling).

toggleCollapse ¶

toggleCollapse()

Collapse the group if it is expanded, expand it otherwise.

setCollapsed ¶

setCollapsed(collapsed)

Collapse or expand the group.

:param collapsed: True to collapse the group, False to expand it

setTitle ¶

setTitle(title)

Set group title. Returns True if changed.

renameInteractive ¶

renameInteractive(parent=None)

Open rename dialog. Returns True if renamed (caller stores history).

setColors ¶

setColors(color=None, title_color=None, border_color=None)

Set group colors. Any None arg is left unchanged. Returns True if changed.

recolorInteractive ¶

recolorInteractive(parent=None)

Open color dialog for fill color. Returns True if changed.

setDropHighlight ¶

setDropHighlight(enabled)

Highlight the group while nodes are dragged over it.

:param enabled: whether the drop highlight should be shown

ungroup ¶

ungroup()

Delete only the group, keep all child nodes (explicit, no auto-remove elsewhere).

deleteWithChildren ¶

deleteWithChildren()

Delete-key semantics: delete container AND all child nodes (and their edges).

dispose ¶

dispose()

Remove the group from the scene and from the graphics scene.

This is the low-level removal used by :meth:ungroup and :meth:deleteWithChildren.

shape ¶

shape()

Hit-testing only: expanded = header (+toggle) only, collapsed = full rect.

boundingRect()/paint() stay full so the background still draws; only clicks/selection/rubber-band/itemAt ignore the expanded body, making it behave like plain canvas.

mousePressEvent ¶

mousePressEvent(event)

Handle a press on the group.

The collapse toggle is handled first; a press on the title bar afterwards starts a drag of the group and its children.

mouseDoubleClickEvent ¶

mouseDoubleClickEvent(event)

Rename the group when its title bar is double-clicked.

mouseMoveEvent ¶

mouseMoveEvent(event)

Move the group and its children while the title bar is dragged.

mouseReleaseEvent ¶

mouseReleaseEvent(event)

Finish dragging the group and store the move in the history.

hoverEnterEvent ¶

hoverEnterEvent(event)

Highlight the title bar when the mouse moves onto it.

hoverMoveEvent ¶

hoverMoveEvent(event)

Track the mouse over the title bar to keep the hover state.

hoverLeaveEvent ¶

hoverLeaveEvent(event)

Remove the title bar highlight when the mouse leaves it.

contextMenuEvent ¶

contextMenuEvent(event)

Show the group context menu.

The menu offers collapsing, renaming, the colour presets, ungrouping and deleting the group together with its children.

paint ¶

paint(painter, option, widget=None)

Paint the group box, its title bar and the collapse toggle.

serialize ¶

serialize()

Return the group as a JSON-serializable dictionary.

The format is versioned with :data:GROUP_SERIALIZATION_VERSION.

deserialize ¶

deserialize(data, hashmap=None, restore_id=True)

Restore the group from a dictionary created by :meth:serialize.

Files written by the old GroupNode format are loaded as expanded.

:param data: the serialized group :param hashmap: mapping of ids to objects, used to relink the children :param restore_id: whether the id stored in the file is restored :return: whether the group was restored

applyCollapsedAfterLoad ¶

applyCollapsedAfterLoad()

Apply collapsed visuals after Scene linked children (no history).