Core Concepts

Understanding QtNodes' architecture helps you make the right design decisions for your application.

Model-View Architecture

QtNodes follows Qt's Model-View pattern. Your data (the Model) is separate from its visualization (the View).

.. image:: /_static/diagrams/architecture-diagram.png :alt: Model-View architecture diagram :align: center :width: 600px

.. SCREENSHOT NEEDED: architecture-diagram.png Create a simple diagram showing:

+------------------+ +----------------------+ | AbstractGraph | ------> | BasicGraphicsScene | | Model | | (QGraphicsScene) | +------------------+ +----------------------+ ^ | | v Your Data +----------------------+ (nodes, connections, | GraphicsView | positions, etc.) | (QGraphicsView) | +----------------------+

Use boxes and arrows. Can be created in any diagramming tool. Size: ~600px wide

Benefits of this separation:

• Run graph logic without any GUI (headless mode)
• Multiple views of the same data
• Clear ownership: you own your data, the library owns the visuals
• Easy testing of graph logic

Nodes and Connections

Graphs consist of nodes and connections.

.. image:: /_static/screenshots/node-anatomy.png :alt: Anatomy of a node :align: center :width: 400px

Node identification:

• Each node has a unique NodeId (unsigned integer)
• You generate IDs in your model via newNodeId()
• The library never creates or manages IDs for you

Connections:

• A ConnectionId links an output port to an input port
• Contains: outNodeId, outPortIndex, inNodeId, inPortIndex
• Connections are directional: data flows from Out to In

.. code-block:: cpp

// A connection from Node 1, Port 0 -> Node 2, Port 0 ConnectionId conn{ .outNodeId = 1, .outPortIndex = 0, .inNodeId = 2, .inPortIndex = 0 };

The Two Programming Models

QtNodes supports two distinct approaches:

.. list-table:: :widths: 50 50 :header-rows: 1

• • Simple Graph Model
  • Data Flow Model
• • You subclass AbstractGraphModel
  • You use DataFlowGraphModel + delegates
• • You store all graph data yourself
  • Library manages node instances for you
• • No automatic data propagation
  • Data flows automatically through connections
• • Full control, more code
  • Less code, follows conventions
• • BasicGraphicsScene
  • DataFlowGraphicsScene

Choose Simple Graph Model when:

• You have existing graph data structures to wrap
• You need custom graph semantics
• You don't need data to flow between nodes

Choose Data Flow Model when:

• Building visual programming tools
• Nodes process inputs and produce outputs
• You want automatic data propagation

NodeRole and PortRole

The model provides data about nodes and ports through roles (similar to Qt's ItemDataRole).

NodeRole -- Information about a node:

.. code-block:: cpp

// Get node position QPointF pos = model.nodeData(nodeId, NodeRole::Position).toPointF();

// Set node caption model.setNodeData(nodeId, NodeRole::Caption, "My Node");

Key roles: Type, Position, Caption, InPortCount, OutPortCount, Widget

PortRole -- Information about a port:

.. code-block:: cpp

// Get port data type auto type = model.portData(nodeId, PortType::In, 0, PortRole::DataType);

Key roles: Data, DataType, Caption, ConnectionPolicyRole

See :doc:/guide/graph-models for the complete role reference.

Graphics Object Hierarchy

When visualized, each model element becomes a graphics object:

.. code-block:: text

GraphicsView (QGraphicsView) └── BasicGraphicsScene (QGraphicsScene) ├── NodeGraphicsObject (for each node) │ └── Embedded QWidget (optional) └── ConnectionGraphicsObject (for each connection)

Painters control how objects are drawn:

• AbstractNodePainter → DefaultNodePainter
• AbstractConnectionPainter → DefaultConnectionPainter

You can replace these with custom painters for different visual styles.

Data Flow Deep Dive

In the data flow model, delegates handle node-specific logic:

.. image:: /_static/diagrams/dataflow-diagram.png :alt: Data flow between nodes :align: center :width: 500px

.. SCREENSHOT NEEDED: dataflow-diagram.png Show data flowing through connected nodes:

[Source Node] --> [Operator Node] --> [Display Node] | | | "emits data" "receives, processes, "receives, emits result" displays"

Use arrows showing dataUpdated signal flow. Size: ~500px wide

The flow:

1. Source node calls emit dataUpdated(portIndex)
2. DataFlowGraphModel catches this signal
3. It calls outData(port) on the source delegate
4. It calls setInData(data, port) on all connected delegates
5. Connected nodes process and may emit their own dataUpdated

Next Steps

• :doc:/guide/graph-models -- Implement your own graph model
• :doc:/guide/data-flow -- Use the data flow pattern
• :doc:/examples/index -- Study working examples