✨ NodeLink Documentation

NodeLink is a Qt/QML node editor library for building node-based and dataflow-oriented applications. It provides a ready-made scene engine with customizable nodes, ports, and connections, while staying flexible enough to be integrated into complex systems and domain-specific tools.

This documentation gives you a high-level overview, a guided setup, and reference material for working with NodeLink from both QML and C++.

What is NodeLink?

NodeLink is a Qt/QML-based framework for building node-based applications. It follows a Model-View-Controller (MVC) design, separating rendering and interaction (View) from the logical graph structure (Model).

• Model: Represents the graph structure, application data, and evaluation logic.
• View: QML scene that renders nodes, ports, and connections and handles user input.
• Controller: Glue between UI actions and model changes (selection, create/delete, connect/disconnect, undo/redo, etc.).

The same model can be used in a headless mode (no visible node editor) or attached to one or more NodeLink views.

Key Features

NodeLink ships with a rich set of features for building production-grade node editors:

• MVC design with clear separation between data model and QML UI.
• Custom node visuals and logic (QML or C++).
• Custom connection rendering (Bezier, straight, orthogonal, etc.).
• Scene overview (minimap-style view), zoom, panning and selection tools.
• Dynamic links and ports: create/remove ports at runtime.
• Undo / redo stack for most scene operations.
• Built-in save / load capabilities for graphs.
• Snapping and grid-based positioning for precise layouts.

📋 Requirements

Supported Platforms

• Linux (x64, gcc ≥ 7.0, clang ≥ 7.0)
• Windows (Win32/x64, MSVC 2019 or compatible, MinGW if supported)
• macOS (Apple Clang / Xcode toolchain)

C++ / Build Toolchain

• C++ standard: C++17
• CMake: ≥ 3.8 (recommended: 3.20+)
• Git (with submodule support)

Qt / QML

• Qt: ≥ 6.2.4
• Required modules:
  • QtQuick
  • QtQuick.Controls
  • QtQml
  • QtQuick.Layouts

📦 Installation

Clone the repository (including submodules) and add it to your CMake project.

Clone

# Recommended (single step)
git clone --recursive https://github.com/Roniasoft/NodeLink.git
cd NodeLink

# If you cloned without --recursive
git submodule update --init --recursive

Integrate with CMake

In your existing CMake project, add NodeLink as a subdirectory and link it to your target.

# CMakeLists.txt (top-level or within your app)
add_subdirectory(NodeLink)

target_link_libraries(MyApp
    PRIVATE
        NodeLinkQml    # or the library target exported by NodeLink
)

🛠️ Building & Running

Command-line build (Linux / macOS)

mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)
sudo make install   # optional, if you want to install

Build with Qt Creator

1. Open CMakeLists.txt as a project.
2. Run CMake configuration.
3. Build all targets.
4. Run one of the example applications or your own.

git submodule update --init --recursive

🚀 Quick Start: Your First Custom Node

In this section, we'll create a simple "HelloWorld" node that displays a message. This will take approximately 10 minutes.

Step 1: Create Project Directory (1 minute)

Create a new directory for your project:

mkdir HelloNodeLink
cd HelloNodeLink

Step 2: Create main.cpp (1 minute)

Create main.cpp:

#include <QGuiApplication>
#include <QQmlApplicationEngine>
#include <QtQuickControls2/QQuickStyle>

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    // Set Material style
    QQuickStyle::setStyle("Material");

    QQmlApplicationEngine engine;
    const QUrl url(QStringLiteral("qrc:/HelloNodeLink/main.qml"));

    QObject::connect(&engine, &QQmlApplicationEngine::objectCreated,
                     &app, [url](QObject *obj, const QUrl &objUrl) {
        if (!obj && url == objUrl)
            QCoreApplication::exit(-1);
    }, Qt::QueuedConnection);

    engine.load(url);

    return app.exec();
}

Step 3: Create HelloWorldNode.qml (2 minutes)

Create HelloWorldNode.qml:

import QtQuick
import NodeLink

Node {
    // Set unique type identifier
    type: 0

    // Configure node data
    nodeData: I_NodeData {}

    // Configure GUI
    guiConfig.width: 200
    guiConfig.height: 120
    guiConfig.color: "#4A90E2"

    // Custom property for input text
    property string inputText: ""

    // Add ports when node is created
    Component.onCompleted: addPorts();

    // Update output when input changes
    onInputTextChanged: {
        if (inputText.length > 0) {
            nodeData.data = "Hello, " + inputText;
        } else {
            nodeData.data = "";
        }
    }

    // Function to add ports
    function addPorts() {
        // Input port (left side)
        let inputPort = NLCore.createPort();
        inputPort.portType = NLSpec.PortType.Input;
        inputPort.portSide = NLSpec.PortPositionSide.Left;
        inputPort.title = "Input";
        inputPort.color = "#4A90E2";
        addPort(inputPort);

        // Output port (right side)
        let outputPort = NLCore.createPort();
        outputPort.portType = NLSpec.PortType.Output;
        outputPort.portSide = NLSpec.PortPositionSide.Right;
        outputPort.title = "Output";
        outputPort.color = "#7ED321";
        addPort(outputPort);
    }

    // Handle data from connected nodes
    function processInput() {
        // This will be called by the scene when data flows
        var inputPort = findPortByPortSide(NLSpec.PortPositionSide.Left);
        if (inputPort) {
            // Get data from connected node (simplified - actual implementation depends on your scene)
            // For now, we'll use the inputText property
            if (nodeData.input !== undefined && nodeData.input !== null) {
                inputText = String(nodeData.input);
            }
        }
    }
}

Step 4: Create main.qml (3 minutes)

Create main.qml:

import QtQuick
import QtQuickStream
import QtQuick.Controls
import NodeLink

Window {
    id: window

    // Scene property (will be overridden by load)
    property Scene scene: Scene { }

    // Node registry setup
    property NLNodeRegistry nodeRegistry: NLNodeRegistry {
        _qsRepo: NLCore.defaultRepo
        imports: ["HelloNodeLink", "NodeLink"]
        defaultNode: 0
    }

    width: 1280
    height: 960
    visible: true
    title: qsTr("Hello NodeLink - Your First Custom Node")
    color: "#1e1e1e"

    Material.theme: Material.Dark
    Material.accent: "#4890e2"

    Component.onCompleted: {
        // Register HelloWorldNode
        var nodeType = 0;
        nodeRegistry.nodeTypes[nodeType] = "HelloWorldNode";
        nodeRegistry.nodeNames[nodeType] = "Hello World";
        nodeRegistry.nodeIcons[nodeType] = "\uf075";  // Font Awesome comment icon
        nodeRegistry.nodeColors[nodeType] = "#4A90E2";

        // Initialize QtQuickStream repository
        NLCore.defaultRepo = NLCore.createDefaultRepo(["QtQuickStream", "NodeLink", "HelloNodeLink"])
        NLCore.defaultRepo.initRootObject("Scene");

        // Set registry to scene
        window.scene = Qt.binding(function() {
            return NLCore.defaultRepo.qsRootObject;
        });
        window.scene.nodeRegistry = Qt.binding(function() {
            return window.nodeRegistry;
        });
    }

    // Main view
    NLView {
        id: view
        scene: window.scene
        anchors.fill: parent
    }

    // Instructions label
    Rectangle {
        anchors.top: parent.top
        anchors.left: parent.left
        anchors.margins: 20
        width: 300
        height: 150
        color: "#2d2d2d"
        radius: 5
        border.color: "#4890e2"
        border.width: 1

        Column {
            anchors.fill: parent
            anchors.margins: 10
            spacing: 5

            Text {
                text: "Instructions:"
                color: "#ffffff"
                font.bold: true
                font.pixelSize: 14
            }

            Text {
                text: "1. Right-click to create nodes"
                color: "#cccccc"
                font.pixelSize: 12
            }

            Text {
                text: "2. Drag from ports to connect"
                color: "#cccccc"
                font.pixelSize: 12
            }

            Text {
                text: "3. Your HelloWorld node is ready!"
                color: "#7ED321"
                font.pixelSize: 12
            }
        }
    }
}

Step 5: Create CMakeLists.txt (2 minutes)

Create CMakeLists.txt:

cmake_minimum_required(VERSION 3.16)

# Require C++17
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_AUTOMOC ON)

# Configure Qt
find_package(QT NAMES Qt6 Qt5 COMPONENTS Core Gui QuickControls2 REQUIRED)
find_package(Qt${QT_VERSION_MAJOR} COMPONENTS Core Gui QuickControls2 REQUIRED)

# Set QML import path
set(QML_IMPORT_PATH ${CMAKE_BINARY_DIR}/qml/NodeLink/resources/View)
set(QT_QML_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/qml)

# Add NodeLink as subdirectory (adjust path to your NodeLink installation)
# Option 1: If NodeLink is in parent directory
add_subdirectory(../NodeLink NodeLink)

# Option 2: If NodeLink is installed system-wide, use find_package instead
# find_package(NodeLink REQUIRED)

# Create executable
qt_add_executable(HelloNodeLink main.cpp)

# Define QML module
qt_add_qml_module(HelloNodeLink
    URI "HelloNodeLink"
    VERSION 1.0

    QML_FILES
        main.qml
        HelloWorldNode.qml

    SOURCES
)

# Include directories
target_include_directories(HelloNodeLink PUBLIC
    Qt${QT_VERSION_MAJOR}::QuickControls2)

# Link libraries
target_link_libraries(HelloNodeLink PRIVATE
    Qt${QT_VERSION_MAJOR}::Core
    Qt${QT_VERSION_MAJOR}::Gui
    Qt${QT_VERSION_MAJOR}::QuickControls2
    NodeLinkplugin
    QtQuickStreamplugin
)

# Debug definitions
target_compile_definitions(HelloNodeLink
    PRIVATE $<$,$>:QT_QML_DEBUG>)

Important: Adjust the add_subdirectory path to point to your NodeLink installation directory.

Step 6: Build and Run (1 minute)

Using Command Line:

# Create build directory
mkdir build
cd build

# Configure
cmake ..

# Build
cmake --build . --config Release

# Run
./HelloNodeLink  # Linux/macOS
# or
HelloNodeLink.exe  # Windows

Using Qt Creator:

1. CMakeLists.txt in Qt Creator
2. Configure the project
3. Build (Ctrl+B / Cmd+B)
4. Run (Ctrl+R / Cmd+R)

Expected Result:

Calculator Example

Overview

The Calculator Example is a visual node-based calculator application built with NodeLink and Qt Quick. It demonstrates how to create a functional node graph system where users can connect different types of nodes to perform mathematical calculations. This example serves as an excellent introduction to building custom node-based applications using the NodeLink framework.

a. Purpose and Use Cases

Purpose

The Calculator Example demonstrates:

1. Node-Based Data Flow: Shows how data flows through a network of connected nodes, where each node performs a specific operation or holds a value.

2. Custom Node Types: Illustrates how to define and implement custom node types with specific behaviors, ports, and data handling.

3. Real-Time Updates: Demonstrates automatic data propagation through the node graph when connections are made, modified, or removed.

4. Visual Programming: Provides a visual interface for building mathematical expressions without writing code.

5. Scene Management: Shows how to manage a scene with multiple nodes, links, and their relationships.

Use Cases

• Educational Tool: Learn how to build node-based applications with NodeLink
• Prototyping: Quickly prototype mathematical workflows or data processing pipelines
• Visual Expression Builder: Create complex mathematical expressions visually
• Framework Demonstration: Showcase NodeLink capabilities to potential users or developers
• Custom Application Foundation: Use as a starting point for building more complex node-based applications

Example Scenarios

• Simple Calculations: Connect Source nodes to operation nodes to perform basic arithmetic
• Complex Expressions: Build multi-step calculations like (a + b) * (c - d) / e
• Data Flow Visualization: Understand how data propagates through a node network
• Interactive Learning: Experiment with different node connections and observe results in real-time

b. Node Types Explained

The Calculator Example implements six distinct node types, each serving a specific role in the calculation pipeline.

1. Source Node (SourceNode)

Purpose: Provides input values for calculations.

Type ID: CSpecs.NodeType.Source (0)

Properties:
- Contains a single output port named "value"
- Users can directly edit the numeric value in the node
- Acts as the starting point for data flow

Ports:
- Output Port: "value" (Right side) - Emits the numeric value entered by the user

Usage:
- Place Source nodes to input numbers into your calculation
- Connect the output port to operation nodes or Result nodes
- Edit the value by clicking on the node and typing a number

Example: A Source node with value 5 outputs 5 through its output port.

2. Additive Node (AdditiveNode)

Purpose: Performs addition of two input values.

Type ID: CSpecs.NodeType.Additive (1)

Properties:
- Inherits from OperationNode
- Has two input ports and one output port
- Performs: output = input1 + input2

Ports:
- Input Port 1: "input 1" (Left side)
- Input Port 2: "input 2" (Left side)
- Output Port: "value" (Right side) - Emits the sum of the two inputs

Behavior:
- Waits for both inputs to be connected and have valid data
- Automatically calculates the result when both inputs are available
- Outputs null if either input is missing

Example:
- Input 1: 3, Input 2: 7 → Output: 10

3. Multiplier Node (MultiplierNode)

Purpose: Performs multiplication of two input values.

Type ID: CSpecs.NodeType.Multiplier (2)

Properties:
- Inherits from OperationNode
- Has two input ports and one output port
- Performs: output = input1 * input2

Ports:
- Input Port 1: "input 1" (Left side)
- Input Port 2: "input 2" (Left side)
- Output Port: "value" (Right side) - Emits the product of the two inputs

Behavior:
- Requires both inputs to be connected and have valid data
- Calculates result automatically when both inputs are available

Example:
- Input 1: 4, Input 2: 6 → Output: 24

4. Subtraction Node (SubtractionNode)

Purpose: Performs subtraction of two input values.

Type ID: CSpecs.NodeType.Subtraction (3)

Properties:
- Inherits from OperationNode
- Has two input ports and one output port
- Performs: output = input1 - input2

Ports:
- Input Port 1: "input 1" (Left side)
- Input Port 2: "input 2" (Left side)
- Output Port: "value" (Right side) - Emits the difference of the two inputs

Behavior:
- Subtracts the second input from the first input
- Requires both inputs to be connected

Example:
- Input 1: 10, Input 2: 3 → Output: 7

5. Division Node (DivisionNode)

Purpose: Performs division of two input values.

Type ID: CSpecs.NodeType.Division (4)

Properties:
- Inherits from OperationNode
- Has two input ports and one output port
- Performs: output = input1 / input2

Ports:
- Input Port 1: "input 1" (Left side)
- Input Port 2: "input 2" (Left side)
- Output Port: "value" (Right side) - Emits the quotient of the two inputs

Behavior:
- Divides the first input by the second input
- Handles division by zero: outputs "undefined (Divide by zero)" if the second input is 0
- Requires both inputs to be connected

Example:
- Input 1: 20, Input 2: 4 → Output: 5
- Input 1: 10, Input 2: 0 → Output: "undefined (Divide by zero)"

6. Result Node (ResultNode)

Purpose: Displays the final result of a calculation.

Type ID: CSpecs.NodeType.Result (5)

Properties:
- Contains a single input port
- Displays the value received from connected nodes
- Read-only (cannot be edited directly)

Ports:
- Input Port: "value" (Left side) - Receives the calculated result

Behavior:
- Displays whatever value is connected to its input port
- Updates automatically when the input value changes
- Resets to null when cloned or when the input connection is removed

Usage:
- Connect the output of any node (Source or Operation) to a Result node to view the final value
- Useful for displaying intermediate or final results in complex calculations

Example:
- Connect a Source node with value 42 → Result displays 42
- Connect an Additive node output → Result displays the sum

Node Type Summary Table

c. Step-by-Step Building Guide

This guide will walk you through building the Calculator Example from scratch, explaining each component and how they work together.

Prerequisites

• Qt 6.2.4 or later (Qt 6.10.0 recommended)
• CMake 3.1.0 or later
• C++ compiler with C++14 support (MSVC 2019/2022 on Windows)
• NodeLink framework built and installed
• QtQuickStream module built and installed

Step 1: Project Setup

1.1 Create Project Structure

Create the following directory structure:

calculator/
├── CMakeLists.txt
├── main.cpp
├── main.qml
└── resources/
    ├── Core/
    └── View/
    └── fonts/

1.2 Configure CMakeLists.txt

Create CMakeLists.txt with the following configuration:

cmake_minimum_required(VERSION 3.1.0)

set(CMAKE_AUTOMOC ON)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Configure Qt
find_package(QT NAMES Qt6 Qt5 COMPONENTS Core Gui QuickControls2 REQUIRED)
find_package(Qt${QT_VERSION_MAJOR} COMPONENTS Core Gui QuickControls2 REQUIRED)

list(APPEND QML_IMPORT_PATH ${CMAKE_BINARY_DIR}/qml)

# Create executable
qt_add_executable(Calculator main.cpp)

# Set CSpecs as singleton
set_source_files_properties(
    resources/Core/CSpecs.qml
    PROPERTIES
        QT_QML_SINGLETON_TYPE True
)

# Define QML module
qt_add_qml_module(Calculator
    URI "Calculator"
    VERSION 1.0
    QML_FILES
        main.qml
        resources/Core/CSpecs.qml
        resources/Core/SourceNode.qml
        resources/Core/OperationNode.qml
        resources/Core/ResultNode.qml
        resources/Core/AdditiveNode.qml
        resources/Core/MultiplierNode.qml
        resources/Core/SubtractionNode.qml
        resources/Core/DivisionNode.qml
        resources/Core/CalculatorScene.qml
        resources/Core/OperationNodeData.qml
        resources/View/CalculatorView.qml
        resources/View/CalculatorNodeView.qml
    RESOURCES
        resources/fonts/Font\ Awesome\ 6\ Pro-Thin-100.otf
        resources/fonts/Font\ Awesome\ 6\ Pro-Solid-900.otf
        resources/fonts/Font\ Awesome\ 6\ Pro-Regular-400.otf
        resources/fonts/Font\ Awesome\ 6\ Pro-Light-300.otf
)

target_include_directories(Calculator PUBLIC
    Qt${QT_VERSION_MAJOR}::QuickControls2)

target_link_libraries(Calculator PRIVATE
    Qt${QT_VERSION_MAJOR}::Core
    Qt${QT_VERSION_MAJOR}::Gui
    Qt${QT_VERSION_MAJOR}::QuickControls2
    NodeLinkplugin
    QtQuickStreamplugin
)

Key Points:
- Links to NodeLinkplugin and QtQuickStreamplugin
- Sets CSpecs.qml as a singleton for global access
- Includes Font Awesome fonts for icons

Step 2: Create Specifications (CSpecs.qml)

Create resources/Core/CSpecs.qml - a singleton that defines node type constants:

pragma Singleton

import QtQuick

QtObject {
    enum NodeType {
        Source      = 0,
        Additive    = 1,
        Multiplier  = 2,
        Subtraction = 3,
        Division    = 4,
        Result      = 5,
        Operation   = 6,
        Unknown     = 99
    }

    enum OperationType {
        Additive     = 0,
        Multiplier   = 1,
        Subtraction  = 2,
        Division     = 3,
        Unknown = 99
    }
}

Purpose: Provides type-safe constants for node types used throughout the application.

Step 3: Create Node Data Models

3.1 OperationNodeData.qml

Create resources/Core/OperationNodeData.qml - data model for operation nodes:

import QtQuick
import NodeLink

I_NodeData {
    property var inputFirst:  null
    property var inputSecond: null
}

Purpose: Extends I_NodeData to store two input values for binary operations.

Step 4: Create Base Node Types

4.1 SourceNode.qml

Create resources/Core/SourceNode.qml:

import QtQuick
import NodeLink

Node {
    type: CSpecs.NodeType.Source
    nodeData: I_NodeData {}

    guiConfig.autoSize: true
    guiConfig.width: 150
    guiConfig.height: 100

    Component.onCompleted: addPorts();

    function addPorts() {
        let _port1 = NLCore.createPort();
        _port1.portType = NLSpec.PortType.Output
        _port1.portSide = NLSpec.PortPositionSide.Right
        _port1.title    = "value";
        addPort(_port1);
    }
}

Key Features:
- Single output port on the right side
- Auto-sized node with fixed dimensions
- Users can edit the value directly in the node view

4.2 OperationNode.qml (Base Class)

Create resources/Core/OperationNode.qml - base class for all operation nodes:

import QtQuick
import NodeLink

Node {
    property int operationType: CSpecs.OperationType.Additive

    type: CSpecs.NodeType.Operation
    nodeData: OperationNodeData {}

    guiConfig.autoSize: false
    guiConfig.minWidth: 150
    guiConfig.minHeight: 80
    guiConfig.baseContentWidth: 120

    Component.onCompleted: addPorts();

    function addPorts() {
        let _port1 = NLCore.createPort();
        let _port2 = NLCore.createPort();
        let _port3 = NLCore.createPort();

        _port1.portType = NLSpec.PortType.Input
        _port1.portSide = NLSpec.PortPositionSide.Left
        _port1.enable   = false;
        _port1.title    = "input 1";

        _port2.portType = NLSpec.PortType.Input
        _port2.portSide = NLSpec.PortPositionSide.Left
        _port2.enable   = false;
        _port2.title    = "input 2";

        _port3.portType = NLSpec.PortType.Output
        _port3.portSide = NLSpec.PortPositionSide.Right
        _port3.title    = "value";

        addPort(_port1);
        addPort(_port2);
        addPort(_port3);
    }
}

Key Features:
- Two input ports (left side) and one output port (right side)
- Uses OperationNodeData to store input values
- Base class for all arithmetic operations

4.3 ResultNode.qml

Create resources/Core/ResultNode.qml:

import QtQuick
import NodeLink

Node {
    type: CSpecs.NodeType.Result
    nodeData: I_NodeData {}

    guiConfig.autoSize: true
    guiConfig.width: 150
    guiConfig.height: 100

    Component.onCompleted: addPorts();

    onCloneFrom: function (baseNode) {
        nodeData.data = null;
    }

    function addPorts() {
        let _port1 = NLCore.createPort();
        _port1.portType = NLSpec.PortType.Input
        _port1.portSide = NLSpec.PortPositionSide.Left
        _port1.enable   = false;
        _port1.title    = "value";
        addPort(_port1);
    }
}

Key Features:
- Single input port (left side)
- Resets data when cloned
- Read-only display of results

Step 5: Create Specific Operation Nodes

5.1 AdditiveNode.qml

Create resources/Core/AdditiveNode.qml:

import QtQuick
import Calculator

OperationNode {
    operationType: CSpecs.OperationType.Additive

    function updataData() {
        if (!nodeData.inputFirst || !nodeData.inputSecond) {
            nodeData.data = null;
            return;
        }
        var input1 = parseFloat(nodeData.inputFirst);
        var input2 = parseFloat(nodeData.inputSecond)
        nodeData.data = input1 + input2;
    }
}

Key Features:
- Inherits from OperationNode
- Implements updataData() to perform addition
- Validates inputs before calculation

5.2 MultiplierNode.qml

Create resources/Core/MultiplierNode.qml:

import QtQuick
import Calculator

OperationNode {
    operationType: CSpecs.OperationType.Multiplier

    function updataData() {
        if (!nodeData.inputFirst || !nodeData.inputSecond) {
            nodeData.data = null;
            return;
        }
        var input1 = parseFloat(nodeData.inputFirst);
        var input2 = parseFloat(nodeData.inputSecond)
        nodeData.data = input1 * input2;
    }
}

5.3 SubtractionNode.qml

Create resources/Core/SubtractionNode.qml:

import QtQuick
import Calculator

OperationNode {
    operationType: CSpecs.OperationType.Subtraction

    function updataData() {
        if (!nodeData.inputFirst || !nodeData.inputSecond) {
            nodeData.data = null;
            return;
        }
        var input1 = parseFloat(nodeData.inputFirst);
        var input2 = parseFloat(nodeData.inputSecond)
        nodeData.data = input1 - input2;
    }
}

5.4 DivisionNode.qml

Create resources/Core/DivisionNode.qml:

import QtQuick
import Calculator

OperationNode {
    operationType: CSpecs.OperationType.Division

    function updataData() {
        if (!nodeData.inputFirst || !nodeData.inputSecond) {
            nodeData.data = null;
            return;
        }
        var input1 = parseFloat(nodeData.inputFirst);
        var input2 = parseFloat(nodeData.inputSecond)
        if (input2 !== 0)
            nodeData.data = input1 / input2;
        else
            nodeData.data = "undefined (Divide by zero)"
    }
}

Key Features:
- Includes division-by-zero handling
- Returns error message for invalid operations

Step 6: Create the Scene

6.1 CalculatorScene.qml

Create resources/Core/CalculatorScene.qml - the main scene that manages nodes and links:

import QtQuick
import QtQuick.Controls
import NodeLink
import Calculator

I_Scene {
    id: scene

    nodeRegistry: NLNodeRegistry {
        _qsRepo: scene._qsRepo
        imports: ["Calculator"]
        defaultNode: CSpecs.NodeType.Source

        nodeTypes: [
            CSpecs.NodeType.Source      = "SourceNode",
            CSpecs.NodeType.Additive    = "AdditiveNode",
            CSpecs.NodeType.Multiplier  = "MultiplierNode",
            CSpecs.NodeType.Subtraction = "SubtractionNode",
            CSpecs.NodeType.Division    = "DivisionNode",
            CSpecs.NodeType.Result      = "ResultNode"
        ];

        nodeNames: [
            CSpecs.NodeType.Source      = "Source",
            CSpecs.NodeType.Additive    = "Additive",
            CSpecs.NodeType.Multiplier  = "Multiplier",
            CSpecs.NodeType.Subtraction = "Subtraction",
            CSpecs.NodeType.Division    = "Division",
            CSpecs.NodeType.Result      = "Result"
        ];

        nodeIcons: [
            CSpecs.NodeType.Source      = "\ue4e2",
            CSpecs.NodeType.Additive    = "+",
            CSpecs.NodeType.Multiplier  = "\uf00d",
            CSpecs.NodeType.Subtraction = "-",
            CSpecs.NodeType.Division    = "/",
            CSpecs.NodeType.Result      = "\uf11b",
        ];

        nodeColors: [
            CSpecs.NodeType.Source     = "#444",
            CSpecs.NodeType.Additive    = "#444",
            CSpecs.NodeType.Multiplier  = "#444",
            CSpecs.NodeType.Subtraction = "#444",
            CSpecs.NodeType.Division    = "#444",
            CSpecs.NodeType.Result      = "#444",
        ];
    }

    selectionModel: SelectionModel {
        existObjects: [...Object.keys(nodes), ...Object.keys(links)]
    }

    property UndoCore _undoCore: UndoCore {
        scene: scene
    }

    // Update node data when links/nodes change
    onLinkRemoved: _upateDataTimer.start();
    onNodeRemoved: _upateDataTimer.start();
    onLinkAdded:   updateData();

    property Timer _upateDataTimer: Timer {
        repeat: false
        running: false
        interval: 1
        onTriggered: scene.updateData();
    }

    // Create a node with specific type and position
    function createCustomizeNode(nodeType: int, xPos: real, yPos: real): string {
        var title = nodeRegistry.nodeNames[nodeType] + "_" +
                   (Object.values(scene.nodes).filter(node => node.type === nodeType).length + 1);
        return createSpecificNode(nodeRegistry.imports, nodeType,
                                 nodeRegistry.nodeTypes[nodeType],
                                 nodeRegistry.nodeColors[nodeType],
                                 title, xPos, yPos);
    }

    // Link validation and creation
    function linkNodes(portA: string, portB: string) {
        if (!canLinkNodes(portA, portB)) {
            console.error("[Scene] Cannot link Nodes");
            return;
        }
        let link = Object.values(links).find(conObj =>
            conObj.inputPort._qsUuid === portA &&
            conObj.outputPort._qsUuid === portB);
        if (link === undefined)
            createLink(portA, portB);
    }

    // Validation rules for linking
    function canLinkNodes(portA: string, portB: string): bool {
        // ... (validation logic - see source file)
        return true;
    }

    // Update all node data based on connections
    function updateData() {
        var notReadyLinks = [];

        // Initialize node data
        Object.values(nodes).forEach(node => {
            switch (node.type) {
                case CSpecs.NodeType.Additive:
                case CSpecs.NodeType.Multiplier:
                case CSpecs.NodeType.Subtraction:
                case CSpecs.NodeType.Division: {
                    node.nodeData.data = null;
                    node.nodeData.inputFirst = null;
                    node.nodeData.inputSecond = null
                } break;
                case CSpecs.NodeType.Result: {
                    node.nodeData.data = null;
                } break;
            }
        });

        // Process links and update data
        Object.values(links).forEach(link => {
            // ... (data propagation logic)
        });

        // Handle nodes waiting for multiple inputs
        while (notReadyLinks.length > 0) {
            // ... (process remaining links)
        }
    }

    // Update specific node data
    function upadateNodeData(upstreamNode: Node, downStreamNode: Node) {
        switch (downStreamNode.type) {
            case CSpecs.NodeType.Additive:
            case CSpecs.NodeType.Multiplier:
            case CSpecs.NodeType.Subtraction:
            case CSpecs.NodeType.Division: {
                if (!downStreamNode.nodeData.inputFirst)
                    downStreamNode.nodeData.inputFirst = upstreamNode.nodeData.data;
                else if (!downStreamNode.nodeData.inputSecond)
                    downStreamNode.nodeData.inputSecond = upstreamNode.nodeData.data;
                downStreamNode.updataData();
            } break;
            case CSpecs.NodeType.Result: {
                downStreamNode.nodeData.data = upstreamNode.nodeData.data;
            } break;
        }
    }
}

Key Features:
- Node Registry: Defines all available node types, names, icons, and colors
- Link Validation: Ensures valid connections (no cycles, single input per port, etc.)
- Data Propagation: Automatically updates node values when connections change
- Undo Support: Integrated undo/redo functionality

Data Flow Logic:
1. When a link is added/removed, updateData() is called
2. All operation nodes are reset
3. Data flows from Source nodes through operation nodes
4. Operation nodes wait for both inputs before calculating
5. Results propagate to connected nodes

Step 7: Create Views

7.1 CalculatorNodeView.qml

Create resources/View/CalculatorNodeView.qml - custom view for displaying nodes:

import QtQuick
import QtQuick.Controls
import NodeLink
import Calculator

NodeView {
    id: nodeView

    contentItem: Item {
        id: mainContentItem
        property bool iconOnly: ((node?.operationType ?? -1) > -1) ||
                                nodeView.isNodeMinimal

        // Header with icon and title
        Item {
            id: titleItem
            anchors.left: parent.left
            anchors.right: parent.right
            anchors.top: parent.top
            anchors.margins: 12
            visible: !mainContentItem.iconOnly
            height: 20

            Text {
                id: iconText
                font.family: NLStyle.fontType.font6Pro
                font.pixelSize: 20
                anchors.left: parent.left
                anchors.verticalCenter: parent.verticalCenter
                text: scene.nodeRegistry.nodeIcons[node.type]
                color: node.guiConfig.color
            }

            NLTextArea {
                id: titleTextArea
                anchors.right: parent.right
                anchors.left: iconText.right
                anchors.verticalCenter: parent.verticalCenter
                anchors.leftMargin: 5
                height: 40
                readOnly: !nodeView.edit
                placeholderText: qsTr("Enter title")
                color: NLStyle.primaryTextColor
                text: node.title
                onTextChanged: {
                    if (node && node.title !== text)
                        node.title = text;
                }
            }
        }

        // Value display/input field
        NLTextField {
            id: textArea
            anchors.top: titleItem.bottom
            anchors.right: parent.right
            anchors.bottom: parent.bottom
            anchors.left: parent.left
            anchors.margins: 12
            anchors.topMargin: 5
            visible: !mainContentItem.iconOnly
            placeholderText: qsTr("Number")
            color: NLStyle.primaryTextColor
            text: node?.nodeData?.data
            readOnly: !nodeView.edit || (node.type === CSpecs.NodeType.Result)
            validator: DoubleValidator {}
            onTextChanged: {
                if (node && (node.nodeData?.data ?? "") !== text) {
                    if (node.type === CSpecs.NodeType.Source) {
                        node.nodeData.data = text;
                        scene.updateData();
                    }
                }
            }
        }

        // Minimal view (icon only at low zoom)
        Rectangle {
            id: minimalRectangle
            anchors.fill: parent
            anchors.margins: 10
            color: mainContentItem.iconOnly ? "#282828" : "transparent"
            radius: NLStyle.radiusAmount.nodeView

            Text {
                font.family: NLStyle.fontType.font6Pro
                font.pixelSize: 60
                anchors.centerIn: parent
                text: scene.nodeRegistry.nodeIcons[node.type]
                color: node.guiConfig.color
                visible: mainContentItem.iconOnly
            }
        }
    }
}

Key Features:
- Editable Title: Users can rename nodes
- Value Display: Shows node data (read-only for Result, editable for Source)
- Minimal Mode: Shows icon only when zoomed out
- Validation: Uses DoubleValidator for numeric input

7.2 CalculatorView.qml

Create resources/View/CalculatorView.qml - main view container:

import QtQuick
import QtQuick.Controls
import NodeLink
import QtQuickStream
import Calculator

Item {
    id: view
    property CalculatorScene scene

    property SceneSession sceneSession: SceneSession {
        enabledOverview: false;
        doNodesNeedImage: false
    }

    // Nodes Scene (flickable canvas)
    NodesScene {
        id: nodesScene
        anchors.fill: parent
        scene: view.scene
        sceneSession: view.sceneSession
        sceneContent: NodesRect {
            scene: view.scene
            sceneSession: view.sceneSession
            nodeViewComponent: Qt.createComponent("CalculatorNodeView.qml")
        }
    }

    // Side menu for adding nodes
    SideMenu {
        scene: view.scene
        sceneSession: view.sceneSession
        anchors.right: parent.right
        anchors.rightMargin: 45
        anchors.top: parent.top
        anchors.topMargin: 50
    }
}

Key Features:
- NodesScene: Provides the scrollable canvas for nodes
- SideMenu: Allows users to add new nodes to the scene
- SceneSession: Manages view state and interactions

Step 8: Create Main Application

8.1 main.cpp

Create main.cpp:

#include <QtGui/QGuiApplication>
#include <QQmlApplicationEngine>
#include <QQuickStyle>

int main(int argc, char* argv[])
{
    QGuiApplication app(argc, argv);
    QQmlApplicationEngine engine;

    // Set Material style
    QQuickStyle::setStyle("Material");

    // Import all items into QML engine
    engine.addImportPath(":/");

    const QUrl url(u"qrc:/Calculator/main.qml"_qs);
    QObject::connect(&engine, &QQmlApplicationEngine::objectCreated,
                     &app, [url](QObject *obj, const QUrl &objUrl) {
        if (!obj && url == objUrl)
            QCoreApplication::exit(-1);
    }, Qt::QueuedConnection);
    engine.load(url);

    return app.exec();
}

Key Features:
- Uses Material design style
- Loads QML resources from the Calculator module
- Standard Qt Quick application setup

8.2 main.qml

Create main.qml:

import QtQuick
import QtQuick.Dialogs
import QtQuick.Controls

import QtQuickStream
import NodeLink
import Calculator

Window {
    id: window
    property CalculatorScene scene: null

    width: 1280
    height: 960
    visible: true
    title: qsTr("Calculator Example")
    color: "#1e1e1e"

    Material.theme: Material.Dark
    Material.accent: "#4890e2"

    Component.onCompleted: {
        // Create root object
        NLCore.defaultRepo = NLCore.createDefaultRepo(["QtQuickStream", "Calculator"])
        NLCore.defaultRepo.initRootObject("CalculatorScene");
        window.scene = Qt.binding(function() {
            return NLCore.defaultRepo.qsRootObject;
        });
    }

    // Load Font Awesome fonts
    FontLoader { source: "qrc:/Calculator/resources/fonts/Font Awesome 6 Pro-Thin-100.otf" }
    FontLoader { source: "qrc:/Calculator/resources/fonts/Font Awesome 6 Pro-Solid-900.otf" }
    FontLoader { source: "qrc:/Calculator/resources/fonts/Font Awesome 6 Pro-Regular-400.otf" }
    FontLoader { source: "qrc:/Calculator/resources/fonts/Font Awesome 6 Pro-Light-300.otf" }

    // Main view
    CalculatorView {
        id: view
        scene: window.scene
        anchors.fill: parent
    }
}

Key Features:
- Dark Theme: Material Dark theme with custom accent color
- Scene Initialization: Creates the CalculatorScene using QtQuickStream
- Font Loading: Loads Font Awesome icons
- Full-Screen View: CalculatorView fills the window

Step 9: Build and Run

9.1 Configure Build

1. Create a build directory:
   bash mkdir build cd build

2. Configure with CMake:
   bash cmake .. -DCMAKE_PREFIX_PATH=<Qt_Install_Path>

3. Build the project:
   bash cmake --build .

9.2 Run the Application

Run the executable:

./Calculator  # Linux/Mac
Calculator.exe  # Windows

Step 10: Using the Calculator

Basic Usage

1. Add Nodes: Click the side menu to add nodes (Source, Additive, Multiplier, etc.)

2. Set Values:

   • Click on a Source node
   • Type a number in the value field
   • Press Enter or click outside

3. Connect Nodes:

   • Click and drag from an output port (right side)
   • Release on an input port (left side)
   • A link will be created if the connection is valid

4. View Results:

   • Connect operation nodes to a Result node
   • The Result node displays the calculated value
   • Values update automatically when inputs change

Example Calculation: (5 + 3) × 2

1. Add two Source nodes, set values to 5 and 3
2. Add an Additive node
3. Connect Source (5) → Additive input 1
4. Connect Source (3) → Additive input 2
5. Add a Source node with value 2
6. Add a Multiplier node
7. Connect Additive output → Multiplier input 1
8. Connect Source (2) → Multiplier input 2
9. Add a Result node
10. Connect Multiplier output → Result input
11. Result displays 16

Architecture Overview

Data Flow

Source Node → Operation Node → Result Node
     ↓                              ↓                       ↓
  (value)              (input1, input2)      (result)

            

Component Hierarchy

CalculatorScene (I_Scene)
├── NodeRegistry (defines node types)
├── SelectionModel (manages selection)
├── UndoCore (undo/redo support)
└── Nodes & Links
    ├── SourceNode
    ├── OperationNodes (Additive, Multiplier, etc.)
    └── ResultNode

CalculatorView
├── NodesScene (canvas)
    └── NodesRect (renders nodes)
        └── CalculatorNodeView (custom node UI)
└── SideMenu (add nodes)

Key Concepts

Ports

• Input Ports: Receive data from other nodes (left side)
• Output Ports: Send data to other nodes (right side)
• Port Rules:
  • Each input port can only have one connection
  • Output ports can connect to multiple inputs
  • Cannot create cycles in the graph

Data Propagation

1. Source nodes provide initial values
2. Operation nodes wait for both inputs before calculating
3. Results propagate downstream automatically
4. Updates trigger when:
   • Links are added/removed
   • Source node values change
   • Nodes are deleted

Node Lifecycle

1. Creation: Node created via createCustomizeNode()
2. Initialization: Ports added in Component.onCompleted
3. Connection: Links established via linkNodes()
4. Update: Data calculated in updataData()
5. Deletion: Cleanup handled by scene

Extending the Calculator

Adding New Operations

To add a new operation (e.g., Power/Exponentiation):

1. Add to CSpecs.qml:
   qml enum NodeType { // ... existing types Power = 6 }

2. Create PowerNode.qml:
   ```qml
   import QtQuick
   import Calculator

   OperationNode {
   operationType: CSpecs.OperationType.Power
   function updataData() {
   if (!nodeData.inputFirst || !nodeData.inputSecond) {
   nodeData.data = null;
   return;
   }
   var base = parseFloat(nodeData.inputFirst);
   var exponent = parseFloat(nodeData.inputSecond);
   nodeData.data = Math.pow(base, exponent);
   }
   }
   ```

3. Register in CalculatorScene.qml:
   qml nodeTypes: [ // ... existing CSpecs.NodeType.Power = "PowerNode" ]

Customizing Appearance

• Node Colors: Modify nodeColors in CalculatorScene.qml
• Node Icons: Change nodeIcons (Font Awesome codes)
• Node Sizes: Adjust guiConfig properties in node definitions
• View Styling: Modify CalculatorNodeView.qml for custom UI

Troubleshooting

Common Issues

1. Nodes not updating: Check that updateData() is called after link changes
2. Invalid connections: Verify canLinkNodes() validation logic
3. Division by zero: Handled in DivisionNode.qml - displays error message
4. Missing fonts: Ensure Font Awesome fonts are in resources/fonts/

Debug Tips

• Enable console logging in CalculatorScene.qml
• Check node data with: console.log(node.nodeData.data)
• Verify port connections: console.log(link.inputPort, link.outputPort)

Conclusion

The Calculator Example demonstrates the core concepts of building node-based applications with NodeLink:

• Custom Node Types: Define specialized nodes for your domain
• Data Flow: Implement automatic data propagation
• Visual Interface: Create intuitive node views
• Scene Management: Handle nodes, links, and their relationships

Use this example as a foundation for building more complex node-based applications such as:
- Visual programming languages
- Data processing pipelines
- Workflow builders
- Shader editors
- Logic circuit simulators

For more examples, see the other examples in the NodeLink repository.

Logic Circuit

Overview

The Logic Circuit Example demonstrates how to build a visual digital logic circuit simulator using NodeLink. This example allows users to create, connect, and test digital logic gates (AND, OR, NOT) in a visual node-based interface. Users can toggle input switches and observe how signals propagate through the circuit in real-time, making it an excellent tool for learning digital logic, designing circuits, and understanding boolean algebra.

a. Purpose and Use Cases

Purpose

The Logic Circuit Example demonstrates:

1. Visual Circuit Design: Create digital logic circuits using a visual node-based interface without writing code.

2. Real-Time Signal Propagation: Observe how boolean signals (true/false) flow through gates and update outputs instantly.

3. Standard Logic Gates: Implement fundamental logic gates (AND, OR, NOT) with their standard symbols and truth tables.

4. Interactive Input/Output: Toggle input switches and see immediate results on output indicators.

5. Educational Tool: Learn digital logic concepts, boolean algebra, and circuit design principles visually.

6. Gate Symbol Rendering: Display logic gates using standard digital circuit symbols drawn with Canvas.

Use Cases

• Educational Tool: Teach digital logic, boolean algebra, and circuit design to students
• Circuit Prototyping: Quickly prototype and test logic circuits before implementation
• Learning Tool: Understand how logic gates work and how signals propagate
• Truth Table Verification: Test and verify truth tables for various gate combinations
• Circuit Design: Design and test combinational logic circuits
• Framework Demonstration: Showcase NodeLink's capabilities for building interactive simulators

Example Scenarios

• Basic Gate Testing: Test individual gates (AND, OR, NOT) with different input combinations
• Combinational Circuits: Build circuits like half-adders, full-adders, or multiplexers
• Boolean Expression Implementation: Convert boolean expressions into visual circuits
• Signal Propagation: Observe how signals flow through complex circuits
• Interactive Learning: Experiment with different circuit configurations and see results immediately

Real-World Applications

• Digital Electronics Education: Teach students about digital circuits and logic gates
• Circuit Design Tools: Prototype logic circuits before hardware implementation
• Boolean Logic Visualization: Visualize boolean expressions and their evaluation
• Hardware Design: Design and test logic for FPGAs, microcontrollers, or custom chips
• Troubleshooting: Debug logic circuits by visualizing signal flow

b. Node Types Explained

The Logic Circuit Example implements five distinct node types, each representing a fundamental component of digital logic circuits.

1. Input Node (InputNode)

Purpose: Provides boolean input values (ON/OFF) to the circuit through an interactive toggle switch.

Type ID: LSpecs.NodeType.Input (0)

Properties:
- Contains a single output port
- Has an interactive toggle switch that can be clicked
- Outputs true (ON) or false (OFF) boolean values
- Acts as the starting point for all signals in the circuit

Ports:
- Output Port: (Right side) - Emits the current state (true/false)

Properties:
- nodeData.currentState: Boolean value representing ON (true) or OFF (false)
- nodeData.output: Output value (same as currentState)
- nodeData.displayValue: String representation ("ON" or "OFF")

Behavior:
- Initializes to OFF (false) state
- Clicking the switch toggles between ON and OFF
- When toggled, updates the circuit by calling scene.updateLogic()
- Visual indicator shows green for ON, gray for OFF

Visual Appearance:
- Icon: Lightning bolt (⚡)
- Toggle Switch: Rounded rectangle with ON/OFF text
- Color: Green (#A6E3A1) when ON, Gray (#585B70) when OFF
- Interactive: Clickable to toggle state

Usage Example:
- Click Input node → Toggles from OFF to ON
- Output port emits true
- Connected gates receive the signal

Truth Table:
| Input State | Output |
|-------------|--------|
| OFF | false |
| ON | true |

2. AND Gate (AndNode)

Purpose: Performs logical AND operation - output is true only when both inputs are true.

Type ID: LSpecs.NodeType.AND (1)

Properties:
- Has two input ports and one output port
- Implements boolean AND logic: output = inputA && inputB
- Uses standard AND gate symbol (flat left side, curved right side)

Ports:
- Input Port A: (Left side, top)
- Input Port B: (Left side, bottom)
- Output Port: (Right side)

Properties:
- nodeData.inputA: First input value (boolean or null)
- nodeData.inputB: Second input value (boolean or null)
- nodeData.output: Result of AND operation (boolean or null)

Behavior:
- Waits for both inputs to be connected and have valid values
- Calculates: output = inputA && inputB
- Output is null if either input is missing
- Updates automatically when inputs change

Visual Appearance:
- Icon: AND symbol (∧)
- Gate Symbol: Standard AND gate shape (flat left, curved right)
- Drawn using Canvas with white fill and black border
- Color: Black border (#000000)

Usage Example:
- Input A: true, Input B: true → Output: true
- Input A: true, Input B: false → Output: false
- Input A: false, Input B: true → Output: false
- Input A: false, Input B: false → Output: false

Truth Table:
| Input A | Input B | Output |
|---------|---------|--------|
| false | false | false |
| false | true | false |
| true | false | false |
| true | true | true |

Code Implementation:

function updateData() {
    if (nodeData.inputA !== null && nodeData.inputB !== null) {
        nodeData.output = nodeData.inputA && nodeData.inputB;
    } else {
        nodeData.output = null;
    }
}

3. OR Gate (OrNode)

Purpose: Performs logical OR operation - output is true when at least one input is true.

Type ID: LSpecs.NodeType.OR (2)

Properties:
- Has two input ports and one output port
- Implements boolean OR logic: output = inputA || inputB
- Uses standard OR gate symbol (curved shape on both sides)

Ports:
- Input Port A: (Left side, top)
- Input Port B: (Left side, bottom)
- Output Port: (Right side)

Properties:
- nodeData.inputA: First input value (boolean or null)
- nodeData.inputB: Second input value (boolean or null)
- nodeData.output: Result of OR operation (boolean or null)

Behavior:
- Waits for both inputs to be connected and have valid values
- Calculates: output = inputA || inputB
- Output is null if either input is missing
- Updates automatically when inputs change

Visual Appearance:
- Icon: OR symbol (∨)
- Gate Symbol: Standard OR gate shape (curved on both sides)
- Drawn using Canvas with white fill and black border
- Color: Black border (#000000)

Usage Example:
- Input A: true, Input B: true → Output: true
- Input A: true, Input B: false → Output: true
- Input A: false, Input B: true → Output: true
- Input A: false, Input B: false → Output: false

Truth Table:
| Input A | Input B | Output |
|---------|---------|--------|
| false | false | false |
| false | true | true |
| true | false | true |
| true | true | true |

Code Implementation:

function updateData() {
    if (nodeData.inputA !== null && nodeData.inputB !== null) {
        nodeData.output = nodeData.inputA || nodeData.inputB;
    } else {
        nodeData.output = null;
    }
}

4. NOT Gate (NotNode)

Purpose: Performs logical NOT operation (inversion) - output is the opposite of the input.

Type ID: LSpecs.NodeType.NOT (3)

Properties:
- Has one input port and one output port
- Implements boolean NOT logic: output = !inputA
- Uses standard NOT gate symbol (triangle with bubble)

Ports:
- Input Port: (Left side)
- Output Port: (Right side)

Properties:
- nodeData.inputA: Input value (boolean or null)
- nodeData.output: Result of NOT operation (boolean or null)

Behavior:
- Waits for input to be connected and have a valid value
- Calculates: output = !inputA
- Output is null if input is missing
- Updates automatically when input changes

Visual Appearance:
- Icon: NOT symbol (~)
- Gate Symbol: Triangle pointing right with a bubble (circle) on the output
- Drawn using Canvas with white fill and black border
- Color: Black border (#000000)

Usage Example:
- Input: true → Output: false
- Input: false → Output: true

Truth Table:
| Input | Output |
|-------|--------|
| false | true |
| true | false |

Code Implementation:

function updateData() {
    if (nodeData.inputA !== null) {
        nodeData.output = !nodeData.inputA;
    } else {
        nodeData.output = null;
    }
}

5. Output Node (OutputNode)

Purpose: Displays the final result of the logic circuit as a visual indicator (lamp).

Type ID: LSpecs.NodeType.Output (4)

Properties:
- Contains a single input port
- Displays the boolean value received from connected gates
- Shows visual indicator: Green (ON), Red (OFF), or Gray (UNDEFINED)

Ports:
- Input Port: (Left side) - Receives the calculated result

Properties:
- nodeData.inputA: Input value from connected gate (boolean or null)
- nodeData.displayValue: String representation ("ON", "OFF", or "UNDEFINED")
- nodeData.statusColor: Color for the indicator (green, red, or gray)

Behavior:
- Receives input from connected gate or node
- Displays "ON" (green) when input is true
- Displays "OFF" (red) when input is false
- Displays "UNDEFINED" (gray) when input is null or not connected
- Updates automatically when input changes

Visual Appearance:
- Icon: Circle (○)
- Indicator: Circular lamp with colored inner circle
- Colors:
- Green (#4CAF50) for ON (true)
- Red (#F44336) for OFF (false)
- Gray (#9E9E9E) for UNDEFINED (null)
- Smooth color transitions when state changes

Usage Example:
- Connected to AND gate output → Shows result of AND operation
- Connected to OR gate output → Shows result of OR operation
- Not connected → Shows "UNDEFINED" (gray)

Display States:
| Input Value | Display | Color |
|-------------|---------|-------|
| true | "ON" | Green (#4CAF50) |
| false | "OFF" | Red (#F44336) |
| null | "UNDEFINED" | Gray (#9E9E9E) |

Code Implementation:

function updateDisplay(value) {
    if (value === null) {
        nodeData.displayValue = "UNDEFINED";
    } else {
        nodeData.displayValue = value ? "ON" : "OFF";
    }
    nodeData.statusColor = getStatusColor(value);
}

function getStatusColor(value) {
    if (value === null) return "#9E9E9E"; // Gray
    return value ? "#4CAF50" : "#F44336"; // Green or Red
}

Node Type Summary Table

Data Flow Architecture

The logic circuit follows a signal propagation pattern:

Input Node (ON/OFF)
    ↓
Logic Gates (AND/OR/NOT)
    ↓
Output Node (Visual Indicator)

Signals propagate through the circuit in real-time, updating all downstream gates and outputs automatically.

/p>

c. Step-by-Step Building Guide

This guide will walk you through building the Logic Circuit Example from scratch, explaining each component and how they work together.

Prerequisites

• Qt 6.2.4 or later (Qt 6.10.0 recommended)
• CMake 3.1.0 or later
• C++ compiler with C++14 support (MSVC 2019/2022 on Windows)
• NodeLink framework built and installed
• QtQuickStream module built and installed
• Basic understanding of boolean logic (helpful but not required)

Step 1: Project Setup

1.1 Create Project Structure

Create the following directory structure:

logicCircuit/
├── CMakeLists.txt
├── main.cpp
├── main.qml
└── resources/
    ├── Core/
    ├── View/
    └── fonts/

1.2 Configure CMakeLists.txt

Create CMakeLists.txt with the following configuration:

cmake_minimum_required(VERSION 3.1.0)

set(MODULE_NAME LogicCircuit)

set(CMAKE_AUTOMOC ON)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Configure Qt
find_package(QT NAMES Qt6 Qt5 COMPONENTS Core Gui QuickControls2 REQUIRED)
find_package(Qt${QT_VERSION_MAJOR} COMPONENTS Core Gui QuickControls2 REQUIRED)

list(APPEND QML_IMPORT_PATH ${CMAKE_BINARY_DIR}/qml)

# Create executable
qt_add_executable(${MODULE_NAME} main.cpp)

# Set LSpecs as singleton
set_source_files_properties(
    resources/Core/LSpecs.qml
    PROPERTIES
        QT_QML_SINGLETON_TYPE True
)

# Define QML module
qt_add_qml_module(${MODULE_NAME}
    URI "LogicCircuit"
    VERSION 1.0
    QML_FILES
        main.qml
        resources/Core/LSpecs.qml
        resources/Core/LogicCircuitScene.qml
        resources/Core/InputNode.qml
        resources/Core/LogicNode.qml
        resources/Core/AndNode.qml
        resources/Core/OrNode.qml
        resources/Core/NotNode.qml
        resources/Core/OutputNode.qml
        resources/Core/LogicNodeData.qml
        resources/View/LogicCircuitView.qml
        resources/View/LogicCircuitNodeView.qml
    RESOURCES
        resources/fonts/Font\ Awesome\ 6\ Pro-Thin-100.otf
        resources/fonts/Font\ Awesome\ 6\ Pro-Solid-900.otf
        resources/fonts/Font\ Awesome\ 6\ Pro-Regular-400.otf
        resources/fonts/Font\ Awesome\ 6\ Pro-Light-300.otf
)

target_include_directories(${MODULE_NAME} PUBLIC
    Qt${QT_VERSION_MAJOR}::QuickControls2)

target_link_libraries(${MODULE_NAME} PRIVATE
    Qt${QT_VERSION_MAJOR}::Core
    Qt${QT_VERSION_MAJOR}::Gui
    Qt${QT_VERSION_MAJOR}::QuickControls2
    NodeLinkplugin
    QtQuickStreamplugin
)

Key Points:
- Links to NodeLinkplugin and QtQuickStreamplugin
- Sets LSpecs.qml as a singleton for global access
- Includes Font Awesome fonts for icons
- Includes LogicNode.qml as a base class

Step 2: Create Specifications (LSpecs.qml)

Create resources/Core/LSpecs.qml - a singleton that defines node type constants:

pragma Singleton
import QtQuick

QtObject {
    enum NodeType {
        Input   = 0,
        AND     = 1,
        OR      = 2,
        NOT     = 3,
        Output  = 4,
        Logic   = 5,
        Unknown = 99
    }

    enum OperationType {
        AND     = 0,
        OR      = 1,
        NOT     = 2,
        Unknown = 99
    }

    enum BooleanState {
        FALSE = 0,
        TRUE  = 1,
        UNDEFINED = 2
    }
}

Purpose: Provides type-safe constants for node types, operations, and boolean states.

Step 3: Create Node Data Models

3.1 LogicNodeData.qml

Create resources/Core/LogicNodeData.qml - data model for logic nodes:

import QtQuick
import NodeLink

I_NodeData {
    // Input values for logic gates
    property var inputA: null
    property var inputB: null

    // Output value
    property var output: null

    // For InputNode: current state (true=ON, false=OFF)
    property bool currentState: false

    // For display purposes
    property string displayValue: "OFF"

    // Status color for visualization (used by OutputNode)
    property color statusColor: "#9E9E9E"
}

Purpose: Extends I_NodeData to store input/output values and display information for logic gates.

Step 4: Create Base Node Type

4.1 LogicNode.qml

Create resources/Core/LogicNode.qml - base class for all logic nodes:

import QtQuick
import NodeLink
import LogicCircuit

Node {
    id: root
    property int nodeType: LSpecs.NodeType.AND

    type: LSpecs.NodeType.Logic
    nodeData: LogicNodeData {}

    property var logicScene: null

    guiConfig.autoSize: false
    guiConfig.minWidth: 20
    guiConfig.minHeight: 20

    Component.onCompleted: {
        addPorts();
    }

    function addPorts() {
        if (nodeType == LSpecs.NodeType.OR || nodeType == LSpecs.NodeType.AND) {
            addPortsInput();
            addPortsInput();
            addPortsOutput();
        } else if (nodeType == LSpecs.NodeType.Input) {
            addPortsOutput();
        } else if (nodeType == LSpecs.NodeType.Output) {
            addPortsInput();
        } else if (nodeType == LSpecs.NodeType.NOT) {
            addPortsInput();
            addPortsOutput();
        }
    }

    function addPortsInput() {
        let inputPort = NLCore.createPort();
        inputPort.portType = NLSpec.PortType.Input;
        inputPort.portSide = NLSpec.PortPositionSide.Left;
        inputPort.title = "";
        addPort(inputPort);
    }

    function addPortsOutput() {
        let outputPort = NLCore.createPort();
        outputPort.portType = NLSpec.PortType.Output;
        outputPort.portSide = NLSpec.PortPositionSide.Right;
        outputPort.title = "";
        addPort(outputPort);
    }
}

Key Features:
- Base class for all logic nodes
- Dynamically adds ports based on node type
- AND/OR gates: 2 inputs, 1 output
- NOT gate: 1 input, 1 output
- Input node: 1 output
- Output node: 1 input

Step 5: Create Specific Node Types

5.1 InputNode.qml

Create resources/Core/InputNode.qml:

import QtQuick
import NodeLink
import LogicCircuit

LogicNode {
    nodeType: LSpecs.NodeType.Input

    Component.onCompleted: {
        nodeData.currentState = false;
        nodeData.output = false;
        nodeData.displayValue = "OFF";
    }

    function toggleState() {
        nodeData.currentState = !nodeData.currentState;
        nodeData.output = nodeData.currentState;
        nodeData.displayValue = nodeData.currentState ? "ON" : "OFF";

        // Update the entire circuit
        var mainScene = _qsRepo ? _qsRepo.qsRootObject : null;
        if (mainScene && mainScene.updateLogic) {
            mainScene.updateLogic();
        }
    }
}

Key Features:
- Toggleable switch for ON/OFF state
- Updates circuit when toggled
- Initializes to OFF state

5.2 AndNode.qml

Create resources/Core/AndNode.qml:

import QtQuick
import NodeLink
import LogicCircuit

LogicNode {
    nodeType: LSpecs.NodeType.AND

    function updateData() {
        if (nodeData.inputA !== null && nodeData.inputB !== null) {
            nodeData.output = nodeData.inputA && nodeData.inputB;
        } else {
            nodeData.output = null;
        }
    }
}

Key Features:
- Implements AND logic: output = inputA && inputB
- Returns null if inputs are incomplete

5.3 OrNode.qml

Create resources/Core/OrNode.qml:

import QtQuick
import NodeLink
import LogicCircuit

LogicNode {
    nodeType: LSpecs.NodeType.OR

    function updateData() {
        if (nodeData.inputA !== null && nodeData.inputB !== null) {
            nodeData.output = nodeData.inputA || nodeData.inputB;
        } else {
            nodeData.output = null;
        }
    }
}

Key Features:
- Implements OR logic: output = inputA || inputB
- Returns null if inputs are incomplete

5.4 NotNode.qml

Create resources/Core/NotNode.qml:

import QtQuick
import NodeLink
import LogicCircuit

LogicNode {
    nodeType: LSpecs.NodeType.NOT

    function updateData() {
        if (nodeData.inputA !== null) {
            nodeData.output = !nodeData.inputA;
        } else {
            nodeData.output = null;
        }
    }
}

Key Features:
- Implements NOT logic: output = !inputA
- Returns null if input is missing

5.5 OutputNode.qml

Create resources/Core/OutputNode.qml:

import QtQuick
import NodeLink
import LogicCircuit

LogicNode {
    nodeType: LSpecs.NodeType.Output


property color undefinedColor: "#9E9E9E"
property color offColor: "#F44336"
property color onColor: "#4CAF50"

Component.onCompleted: {
    guiConfig.color = "#2A2A2A";
    updateDisplay(nodeData.inputA);
}

function updateDisplay(value) {
    if (value === null) {
        nodeData.displayValue = "UNDEFINED";
    } else {
        nodeData.displayValue = value ? "ON" : "OFF";
    }
    nodeData.statusColor = getStatusColor(value);
}

function getStatusColor(value) {
    if (value === null) return undefinedColor;
    return value ? onColor : offColor;
}

function updateData() {
    updateDisplay(nodeData.inputA);
}

Key Features:
- Displays input value as colored indicator
- Green for ON, Red for OFF, Gray for UNDEFINED
- Smooth color transitions

Step 6: Create the Scene

6.1 LogicCircuitScene.qml

Create resources/Core/LogicCircuitScene.qml - the main scene that manages nodes, links, and signal propagation:

import QtQuick
import QtQuick.Controls
import NodeLink
import LogicCircuit

I_Scene {
    id: scene

    property color borderColor: "#000000"

    nodeRegistry: NLNodeRegistry {
        _qsRepo: scene._qsRepo
        imports: ["LogicCircuit"]
        defaultNode: LSpecs.NodeType.Input

        nodeTypes: [
            LSpecs.NodeType.Input   = "InputNode",
            LSpecs.NodeType.AND     = "AndNode",
            LSpecs.NodeType.OR      = "OrNode",
            LSpecs.NodeType.NOT     = "NotNode",
            LSpecs.NodeType.Output  = "OutputNode"
        ]

        nodeNames: [
            LSpecs.NodeType.Input   = "Input",
            LSpecs.NodeType.AND     = "AND Gate",
            LSpecs.NodeType.OR      = "OR Gate",
            LSpecs.NodeType.NOT     = "NOT Gate",
            LSpecs.NodeType.Output  = "Output"
        ]

        nodeIcons: [
            LSpecs.NodeType.Input   = "⚡",
            LSpecs.NodeType.AND     = "∧",
            LSpecs.NodeType.OR      = "∨",
            LSpecs.NodeType.NOT     = "~",
            LSpecs.NodeType.Output  = "○"
        ]

        nodeColors: [
            LSpecs.NodeType.Input   = borderColor,
            LSpecs.NodeType.AND     = borderColor,
            LSpecs.NodeType.OR      = borderColor,
            LSpecs.NodeType.NOT     = borderColor,
            LSpecs.NodeType.Output  = borderColor
        ]
    }

    selectionModel: SelectionModel {
        existObjects: [...Object.keys(nodes), ...Object.keys(links)]
    }

    property UndoCore _undoCore: UndoCore {
        scene: scene
    }

    // Update logic when connections change
    onLinkRemoved: updateLogic();
    onNodeRemoved: updateLogic();
    onLinkAdded: updateLogic();

    function createCustomizeNode(nodeType, xPos, yPos) {
        var title = nodeRegistry.nodeNames[nodeType] + "_" +
                   (Object.values(scene.nodes).filter(node => node.type === nodeType).length + 1);
        return createSpecificNode(nodeRegistry.imports, nodeType,
                                 nodeRegistry.nodeTypes[nodeType],
                                 nodeRegistry.nodeColors[nodeType],
                                 title, xPos, yPos);
    }

    // Update all logic in the circuit
    function updateLogic() {
        // Reset all operation nodes
        Object.values(nodes).forEach(node => {
            if (node.type === LSpecs.NodeType.AND ||
                node.type === LSpecs.NodeType.OR ||
                node.type === LSpecs.NodeType.NOT) {
                node.nodeData.inputA = null;
                node.nodeData.inputB = null;
                node.nodeData.output = null;
            }
            if (node.type === LSpecs.NodeType.Output) {
                node.nodeData.inputA = null;
                node.nodeData.displayValue = "UNDEFINED";
            }
        });

        // Track connections to prevent same upstream node connecting to multiple inputs
        var connectionMap = {};

        // Propagate values through the circuit (iterative approach)
        var maxIterations = 999;
        var changed = true;

        for (var i = 0; i < maxIterations && changed; i++) {
            changed = false;

            Object.values(links).forEach(link => {
                var upstreamNode = findNode(link.inputPort._qsUuid);
                var downstreamNode = findNode(link.outputPort._qsUuid);

                if (upstreamNode && downstreamNode && upstreamNode.nodeData.output !== null) {
                    var connectionKey = downstreamNode._qsUuid + "_" + upstreamNode._qsUuid;

                    // Handle 2-input gates (AND, OR)
                    if (downstreamNode.type === LSpecs.NodeType.AND ||
                        downstreamNode.type === LSpecs.NodeType.OR) {

                        if (downstreamNode.nodeData.inputA === null && !connectionMap[connectionKey + "_A"]) {
                            downstreamNode.nodeData.inputA = upstreamNode.nodeData.output;
                            connectionMap[connectionKey + "_A"] = true;
                            changed = true;
                        } else if (downstreamNode.nodeData.inputB === null && !connectionMap[connectionKey + "_B"]) {
                            // Ensure inputB comes from a different node than inputA
                            var inputAUpstream = null;
                            Object.keys(connectionMap).forEach(key => {
                                if (key.startsWith(downstreamNode._qsUuid) && key.endsWith("_A")) {
                                    var upstreamId = key.split("_")[1];
                                    inputAUpstream = upstreamId;
                                }
                            });

                            if (inputAUpstream !== upstreamNode._qsUuid) {
                                downstreamNode.nodeData.inputB = upstreamNode.nodeData.output;
                                connectionMap[connectionKey + "_B"] = true;
                                changed = true;
                            }
                        }

                    // Handle single-input gates (NOT, Output)
                    } else if (downstreamNode.type === LSpecs.NodeType.NOT ||
                              downstreamNode.type === LSpecs.NodeType.Output) {
                        if (downstreamNode.nodeData.inputA === null) {
                            downstreamNode.nodeData.inputA = upstreamNode.nodeData.output;
                            changed = true;
                        }
                    }

                    // Update downstream node if it has all required inputs
                    if (downstreamNode.updateData) {
                        var canUpdate = false;
                        switch(downstreamNode.type) {
                            case LSpecs.NodeType.AND:
                            case LSpecs.NodeType.OR:
                                canUpdate = (downstreamNode.nodeData.inputA !== null &&
                                           downstreamNode.nodeData.inputB !== null);
                                break;
                            case LSpecs.NodeType.NOT:
                            case LSpecs.NodeType.Output:
                                canUpdate = (downstreamNode.nodeData.inputA !== null);
                                break;
                        }

                        if (canUpdate) {
                            downstreamNode.updateData();
                        }
                    }
                }
            });
        }
    }

    // Link validation
    function linkNodes(portA, portB) {
        if (canLinkNodes(portA, portB)) {
            createLink(portA, portB);
            updateLogic();
        }
    }

    function canLinkNodes(portA, portB) {
        if (portA.length === 0 || portB.length === 0) return false;

        var portAObj = findPort(portA);
        var portBObj = findPort(portB);

        if (portAObj.portType !== NLSpec.PortType.Output) return false;
        if (portBObj.portType !== NLSpec.PortType.Input) return false;

        // Prevent duplicate links
        var sameLinks = Object.values(links).filter(link =>
            link.inputPort._qsUuid === portA && link.outputPort._qsUuid === portB);
        if (sameLinks.length > 0) return false;

        // Input port can only have one connection
        var portBObjLinks = Object.values(links).filter(link =>
            link.outputPort._qsUuid === portB);
        if (portBObjLinks.length > 0) return false;

        // Prevent self-connection
        var nodeA = findNodeId(portA);
        var nodeB = findNodeId(portB);
        if (nodeA === nodeB) return false;

        return true;
    }
}

Key Features:
- Node Registry: Defines all gate types with symbols and colors
- Signal Propagation: Iterative algorithm that propagates signals through the circuit
- Connection Management: Prevents same upstream node from connecting to multiple inputs of same gate
- Real-Time Updates: Updates all gates when connections or inputs change

Signal Propagation Algorithm:
1. Reset all gate inputs/outputs
2. Iteratively propagate signals from inputs to outputs
3. For each link, if upstream has output, set downstream input
4. Update downstream gate if all inputs are ready
5. Repeat until no more changes occur (or max iterations)

Step 7: Create Views

7.1 LogicCircuitNodeView.qml

Create resources/View/LogicCircuitNodeView.qml - custom view that renders gate symbols:

import QtQuick
import QtQuick.Controls
import NodeLink
import LogicCircuit

NodeView {
    id: nodeView

    // Remove default rectangle background
    color: "transparent"
    border.width: 0
    radius: 0
    isResizable: false

    contentItem: Item {
        // Input Node: Toggle switch
        Rectangle {
            anchors.centerIn: parent
            visible: node.type === LSpecs.NodeType.Input
            width: Math.min(44, parent.width * 0.8)
            height: Math.min(22, parent.height * 0.4)
            radius: height / 2
            color: node.nodeData.currentState ? "#A6E3A1" : "#585B70"
            border.color: Qt.darker(color, 1.2)
            border.width: 1

            Text {
                anchors.centerIn: parent
                text: node.nodeData.currentState ? "ON" : "OFF"
                color: "#1E1E2E"
                font.bold: true
                font.pixelSize: Math.max(8, parent.height * 0.4)
            }

            MouseArea {
                anchors.fill: parent
                cursorShape: Qt.PointingHandCursor
                onClicked: node.toggleState && node.toggleState()
            }
        }

        // Output Node: Lamp indicator
        Rectangle {
            anchors.centerIn: parent
            visible: node.type === LSpecs.NodeType.Output
            width: Math.min(30, parent.width * 0.6)
            height: Math.min(30, parent.height * 0.6)
            radius: width / 2
            color: "white"
            border.color: "#2A2A2A"
            border.width: 2

            Rectangle {
                anchors.centerIn: parent
                width: parent.width * 0.6
                height: parent.height * 0.6
                radius: width / 2
                color: node.nodeData ? node.nodeData.statusColor : "#9E9E9E"

                Behavior on color {
                    ColorAnimation { duration: 200 }
                }
            }
        }

        // Gate symbols (AND, OR, NOT) using Canvas
        Loader {
            id: gateLoader
            anchors.fill: parent
            sourceComponent: {
                switch (node.type) {
                case LSpecs.NodeType.AND:  return andGate
                case LSpecs.NodeType.OR:   return orGate
                case LSpecs.NodeType.NOT:  return notGate
                default: return null
                }
            }
        }

        // AND Gate Component
        Component {
            id: andGate
            Canvas {
                anchors.fill: parent
                onPaint: {
                    var ctx = getContext("2d");
                    ctx.reset();
                    ctx.clearRect(0, 0, width, height);

                    ctx.fillStyle = "white";
                    ctx.strokeStyle = "black";
                    ctx.lineWidth = 2;

                    var margin = width * 0.05;
                    var leftX = margin;
                    var topY = margin;
                    var bottomY = height - margin;
                    var centerY = height / 2;
                    var radius = (height - 2 * margin) / 2;
                    var flatRightX = width - margin - radius;

                    ctx.beginPath();
                    ctx.moveTo(leftX, topY);
                    ctx.lineTo(flatRightX, topY);
                    ctx.arc(flatRightX, centerY, radius, -Math.PI/2, Math.PI/2, false);
                    ctx.lineTo(leftX, bottomY);
                    ctx.closePath();
                    ctx.fill();
                    ctx.stroke();
                }
                onWidthChanged: requestPaint()
                onHeightChanged: requestPaint()
            }
        }

        // OR Gate Component
        Component {
            id: orGate
            Canvas {
                anchors.fill: parent
                onPaint: {
                    var ctx = getContext("2d");
                    ctx.reset();
                    ctx.clearRect(0, 0, width, height);

                    ctx.fillStyle = "white";
                    ctx.strokeStyle = "black";
                    ctx.lineWidth = 2;

                    var margin = width * 0.05;
                    var leftX = margin;
                    var rightX = width - margin;
                    var topY = margin;
                    var bottomY = height - margin;
                    var midY = height / 2;

                    ctx.beginPath();
                    ctx.moveTo(leftX, topY);
                    ctx.quadraticCurveTo(rightX, topY, rightX, midY);
                    ctx.quadraticCurveTo(rightX, bottomY, leftX, bottomY);
                    ctx.quadraticCurveTo(leftX + (width * 0.3), midY, leftX, topY);
                    ctx.closePath();
                    ctx.fill();
                    ctx.stroke();
                }
                onWidthChanged: requestPaint()
                onHeightChanged: requestPaint()
            }
        }

        // NOT Gate Component
        Component {
            id: notGate
            Canvas {
                anchors.fill: parent
                onPaint: {
                    var ctx = getContext("2d");
                    ctx.reset();
                    ctx.clearRect(0, 0, width, height);

                    ctx.fillStyle = "white";
                    ctx.strokeStyle = "black";
                    ctx.lineWidth = 2;

                    var margin = width * 0.05;
                    var leftX = margin;
                    var topY = margin;
                    var bottomY = height - margin;
                    var midY = height / 2;
                    var triangleRight = width - margin - (width * 0.2);
                    var bubbleRadius = Math.min(6, height * 0.1);

                    // Triangle
                    ctx.beginPath();
                    ctx.moveTo(leftX, topY);
                    ctx.lineTo(triangleRight, midY);
                    ctx.lineTo(leftX, bottomY);
                    ctx.closePath();
                    ctx.fill();
                    ctx.stroke();

                    // Bubble
                    ctx.beginPath();
                    ctx.arc(triangleRight + bubbleRadius * 1.5, midY, bubbleRadius, 0, Math.PI * 2);
                    ctx.fill();
                    ctx.stroke();
                }
                onWidthChanged: requestPaint()
                onHeightChanged: requestPaint()
            }
        }
    }
}

Key Features:
- Gate Symbols: Renders standard logic gate symbols using Canvas
- Input Switch: Interactive toggle switch for Input nodes
- Output Lamp: Colored indicator for Output nodes
- No Background: Transparent background to show only gate symbols

7.2 LogicCircuitView.qml

Create resources/View/LogicCircuitView.qml - main view container:

import QtQuick
import QtQuick.Controls
import NodeLink
import QtQuickStream
import LogicCircuit

Item {
    id: view
    property LogicCircuitScene scene

    property SceneSession sceneSession: SceneSession {
        enabledOverview: false
        doNodesNeedImage: false
    }

    // Nodes Scene (flickable canvas)
    NodesScene {
        id: nodesScene
        anchors.fill: parent
        scene: view.scene
        sceneSession: view.sceneSession
        sceneContent: NodesRect {
            scene: view.scene
            sceneSession: view.sceneSession
            nodeViewComponent: Qt.createComponent("LogicCircuitNodeView.qml")
        }
    }

    // Side menu for adding nodes
    SideMenu {
        scene: view.scene
        sceneSession: view.sceneSession
        anchors.right: parent.right
        anchors.rightMargin: 45
        anchors.top: parent.top
        anchors.topMargin: 50
    }
}

Key Features:
- NodesScene: Provides the scrollable canvas for gates
- SideMenu: Allows users to add new gates to the circuit
- SceneSession: Manages view state and interactions

Step 8: Create Main Application

8.1 main.cpp

Create main.cpp:

#include <QtGui/QGuiApplication>
#include <QQmlApplicationEngine>
#include <QQuickStyle>

int main(int argc, char* argv[])
{
    QGuiApplication app(argc, argv);
    QQmlApplicationEngine engine;

    QQuickStyle::setStyle("Material");
    engine.addImportPath(":/");

    const QUrl url(u"qrc:/LogicCircuit/main.qml"_qs);
    QObject::connect(&engine, &QQmlApplicationEngine::objectCreated,
                     &app, [url](QObject *obj, const QUrl &objUrl) {
        if (!obj && url == objUrl)
            QCoreApplication::exit(-1);
    }, Qt::QueuedConnection);
    engine.load(url);

    return app.exec();
}

8.2 main.qml

Create main.qml:

import QtQuick
import QtQuick.Dialogs
import QtQuick.Controls

import QtQuickStream
import NodeLink
import LogicCircuit

Window {
    id: window
    property LogicCircuitScene scene: null

    width: 1280
    height: 960
    visible: true
    title: qsTr("Logic Circuit Example")
    color: "#1e1e1e"

    Material.theme: Material.Dark
    Material.accent: "#4890e2"

    Component.onCompleted: {
        NLCore.defaultRepo = NLCore.createDefaultRepo(["QtQuickStream", "LogicCircuit"])
        NLCore.defaultRepo.initRootObject("LogicCircuitScene");
        window.scene = Qt.binding(function() {
            return NLCore.defaultRepo.qsRootObject;
        });
    }

    // Load Font Awesome fonts
    FontLoader { source: "qrc:/LogicCircuit/resources/fonts/Font Awesome 6 Pro-Thin-100.otf" }
    FontLoader { source: "qrc:/LogicCircuit/resources/fonts/Font Awesome 6 Pro-Solid-900.otf" }
    FontLoader { source: "qrc:/LogicCircuit/resources/fonts/Font Awesome 6 Pro-Regular-400.otf" }
    FontLoader { source: "qrc:/LogicCircuit/resources/fonts/Font Awesome 6 Pro-Light-300.otf" }

    // Main view
    LogicCircuitView {
        id: view
        scene: window.scene
        anchors.fill: parent
    }
}

Key Features:
- Dark Theme: Material Dark theme with custom accent color
- Scene Initialization: Creates the LogicCircuitScene using QtQuickStream
- Full-Screen View: LogicCircuitView fills the window

Step 9: Build and Run

9.1 Configure Build

1. Create a build directory:
   bash mkdir build cd build

2. Configure with CMake:
   bash cmake .. -DCMAKE_PREFIX_PATH=<Qt_Install_Path>

3. Build the project:
   bash cmake --build .

9.2 Run the Application

Run the executable:

./LogicCircuit  # Linux/Mac
LogicCircuit.exe  # Windows

Step 10: Using the Logic Circuit

Basic Usage

1. Add Nodes:
   1. Click the side menu to add gates
   2. You'll need: Input nodes, Logic gates (AND/OR/NOT), Output nodes
2. Connect Gates:
   1. Click and drag from an output port (right side)
   2. Release on an input port (left side)
   3. A link will be created if the connection is valid
3. Toggle Inputs:
   1. Click on Input nodes to toggle between ON and OFF
   2. The circuit updates automatically
4. Observe Outputs:
   1. Output nodes show the result:
      • Green = ON (true)
      • Red = OFF (false)
      • Gray = UNDEFINED (not connected or invalid)

Example: Simple AND Circuit

Setup:
1. Add two Input nodes
2. Add one AND gate
3. Add one Output node

Connections:
- Input 1 → AND (input A)
- Input 2 → AND (input B)
- AND → Output

Test:
- Both Inputs ON → Output: Green (ON)
- One Input OFF → Output: Red (OFF)
- Both Inputs OFF → Output: Red (OFF)

Example: OR Circuit

Setup:
1. Add two Input nodes
2. Add one OR gate
3. Add one Output node

Connections:
- Input 1 → OR (input A)
- Input 2 → OR (input B)
- OR → Output

Test:
- At least one Input ON → Output: Green (ON)
- Both Inputs OFF → Output: Red (OFF)

Example: NOT Circuit

Setup:
1. Add one Input node
2. Add one NOT gate
3. Add one Output node

Connections:
- Input → NOT
- NOT → Output

Test:
- Input ON → Output: Red (OFF) - inverted
- Input OFF → Output: Green (ON) - inverted

Example: Complex Circuit (A AND (B OR C))

Setup:
1. Add three Input nodes (A, B, C)
2. Add one OR gate
3. Add one AND gate
4. Add one Output node

Connections:
- Input B → OR (input A)
- Input C → OR (input B)
- Input A → AND (input A)
- OR → AND (input B)
- AND → Output

Test:
- A=ON, B=ON, C=OFF → Output: Green (ON)
- A=ON, B=OFF, C=ON → Output: Green (ON)
- A=OFF, B=ON, C=ON → Output: Red (OFF)
- A=ON, B=OFF, C=OFF → Output: Red (OFF)

Architecture Overview

Component Hierarchy

LogicCircuitScene (I_Scene)
├── NodeRegistry (defines gate types)
├── SelectionModel (manages selection)
├── UndoCore (undo/redo support)
└── Nodes & Links
    ├── InputNode (toggle switches)
    ├── Logic Gates (AND, OR, NOT)
    └── OutputNode (visual indicators)

LogicCircuitView
├── NodesScene (canvas)
│   └── NodesRect (renders gates)
│       └── LogicCircuitNodeView (custom gate UI)
└── SideMenu (add gates)

Signal Propagation

The circuit uses an iterative propagation algorithm:

1. Reset Phase: All gate inputs/outputs are reset to null
2. Propagation Phase:
   1. For each link, if upstream has output, set downstream input
   2. Update downstream gate if all inputs are ready
   3. Repeat until no more changes occur
3. Update Phase: All gates calculate their outputs based on inputs

This ensures signals propagate correctly through the circuit, even with complex topologies.

Key Concepts

Boolean Logic

The circuit implements fundamental boolean operations:

• AND: Output is true only when both inputs are true
• OR: Output is true when at least one input is true
• NOT: Output is the inverse of the input

Signal Propagation

Signals flow from Input nodes through gates to Output nodes:
- Input nodes provide boolean values (true/false)
- Gates process inputs and produce outputs
- Output nodes display the final result

Gate Symbols

Gates are rendered using standard digital circuit symbols:
- AND: Flat left side, curved right side
- OR: Curved on both sides
- NOT: Triangle with bubble on output

Connection Rules

• Each input port can only have one connection
• Output ports can connect to multiple inputs
• Cannot create cycles (prevents infinite loops)
• Cannot connect a node to itself

Extending the Logic Circuit

Adding New Gates

To add a new gate (e.g., NAND, NOR, XOR):

1. Add to LSpecs.qml:
   qml enum NodeType { // ... existing NAND = 5, NOR = 6, XOR = 7 }
2. Create NandNode.qml:
   

   import QtQuick
   import NodeLink
   import LogicCircuit
   
   LogicNode {
       nodeType: LSpecs.NodeType.NAND
   
       function updateData() {
           if (nodeData.inputA !== null && nodeData.inputB !== null) {
               nodeData.output = !(nodeData.inputA && nodeData.inputB);
           } else {
               nodeData.output = null;
           }
       }
   }
   

3. Add Canvas Component in LogicCircuitNodeView.qml for the symbol
4. Register in LogicCircuitScene.qml

Customizing Gate Appearance

• Modify Canvas drawing code in LogicCircuitNodeView.qml
• Change colors in OutputNode.qml
• Adjust sizes in LogicNode.qml guiConfig

Adding Truth Table Display

Create a component that shows the truth table for selected gates:
- Display all input combinations
- Show corresponding outputs
- Update in real-time as inputs change

Troubleshooting

Common Issues

1. Output Shows UNDEFINED:
   1. Check that all inputs are connected
   2. Verify gates have all required inputs
   3. Ensure Input nodes are toggled ON/OFF
2. Signals Not Propagating:
   1. Check for cycles in the circuit
   2. Verify connections are valid
   3. Ensure gates have all inputs connected
3. Gate Not Updating:
   1. Toggle an Input node to trigger update
   2. Check that connections are properly established
   3. Verify gate has all required inputs
4. Visual Issues:
   1. Gate symbols not rendering: Check Canvas code
   2. Colors not updating: Verify statusColor property
   3. Ports not visible: Check port creation code

Debug Tips

• Enable console logging in LogicCircuitScene.qml
• Check node data: console.log(node.nodeData.output)
• Verify connections: console.log(link.inputPort, link.outputPort)
• Monitor signal propagation: Add logs in updateLogic()

Truth Tables Reference

AND Gate

OR Gate

NOT Gate

Common Combinations

NAND (NOT AND): !(A && B)
| A | B | Output |
|---|---|--------|
| 0 | 0 | 1 |
| 0 | 1 | 1 |
| 1 | 0 | 1 |
| 1 | 1 | 0 |

NOR (NOT OR): !(A || B)
| A | B | Output |
|---|---|--------|
| 0 | 0 | 1 |
| 0 | 1 | 0 |
| 1 | 0 | 0 |
| 1 | 1 | 0 |

XOR (Exclusive OR): (A && !B) || (!A && B)
| A | B | Output |
|---|---|--------|
| 0 | 0 | 0 |
| 0 | 1 | 1 |
| 1 | 0 | 1 |
| 1 | 1 | 0 |

Conclusion

The Logic Circuit Example demonstrates how to build an interactive digital logic simulator using NodeLink. Key takeaways:

• Visual Circuit Design: Create logic circuits without writing code
• Real-Time Simulation: See signal propagation instantly
• Standard Symbols: Use industry-standard gate symbols
• Educational Value: Learn digital logic concepts visually
• Extensible Design: Easy to add new gates and features

This example serves as a foundation for building more sophisticated circuit simulators, such as:
- Sequential logic circuits (flip-flops, registers)
- Arithmetic circuits (adders, multipliers)
- Memory circuits
- Complex digital systems

For more examples, see the other examples in the NodeLink repository.

Chatbot Example

Overview

The Chatbot Example demonstrates how to build an interactive chatbot application using NodeLink's visual node-based programming system. Unlike traditional chatbots that rely on hardcoded logic, this example shows how to create a rule-based chatbot using regular expressions (Regex) and visual node connections. Users can define conversation patterns visually by connecting nodes, making it easy to design and modify chatbot behavior without writing complex code.

a. Purpose and Use Cases

Purpose

The Chatbot Example demonstrates:

1. Visual Rule-Based Chatbots: Shows how to create chatbots using visual node graphs instead of traditional programming approaches.

2. Pattern Matching with Regex: Illustrates how to use regular expressions to match user input and trigger appropriate responses.

3. Conditional Response Logic: Demonstrates branching logic where different responses are triggered based on pattern matching results.

4. Interactive User Interface: Combines a node-based editor with a real-time chat interface, allowing users to see their chatbot in action.

5. Real-Time Data Flow: Shows how user input flows through the node graph, gets processed, and generates responses in real-time.

6. Dual Output Nodes: Demonstrates nodes with multiple output ports for conditional branching (true/false paths).

Use Cases

• Educational Tool: Learn how to build rule-based chatbots and understand pattern matching concepts
• Prototyping: Quickly prototype chatbot logic and test conversation flows
• Visual Bot Builder: Create chatbots without writing code, ideal for non-programmers
• Pattern Testing: Test regular expressions and see their effects immediately
• Framework Demonstration: Showcase NodeLink's capabilities for building interactive applications
• Custom Application Foundation: Use as a starting point for building more complex conversational interfaces

Example Scenarios

• Simple Greeting Bot: Respond to greetings like "hello", "hi", "hey" with friendly messages
• Keyword-Based Responses: Trigger responses based on specific keywords in user messages
• Pattern Recognition: Match complex patterns like email addresses, phone numbers, or custom formats
• Multi-Path Conversations: Create branching conversations that respond differently based on input patterns
• Interactive Testing: Test chatbot behavior in real-time while building the node graph

Real-World Applications

• Customer Support Bots: Create simple rule-based support chatbots
• FAQ Systems: Build question-answering systems based on pattern matching
• Form Validation: Use regex patterns to validate user input
• Content Filtering: Filter or categorize messages based on patterns
• Educational Games: Create interactive learning experiences with pattern-based responses

b. Node Types Explained

The Chatbot Example implements four distinct node types, each serving a specific role in the chatbot's decision-making process.

1. Source Node (SourceNode)

Purpose: Receives and stores user input messages from the chat interface.

Type ID: CSpecs.NodeType.Source (0)

Properties:
- Contains a single output port named "value"
- Receives text input from the chat interface
- Acts as the entry point for all user messages
- Can be manually edited for testing purposes

Ports:
- Output Port: "value" (Right side) - Emits the user's message text

Behavior:
- Automatically receives messages when users type in the chat box
- The message text is stored in nodeData.data
- When data changes, it triggers the scene's updateData() function
- Can be manually edited by clicking on the node and typing

Visual Appearance:
- Icon: Document/Text icon (Font Awesome)
- Color: Gray (#444)
- Size: 150x100 pixels

Usage Example:
- User types "hello world" in chat → Source node receives "hello world"
- Source node outputs "hello world" to connected nodes

2. Regex Node (RegexNode)

Purpose: Matches user input against a regular expression pattern and routes the result through two different output ports.

Type ID: CSpecs.NodeType.Regex (1)

Properties:
- Has one input port and two output ports
- Contains a regular expression pattern in nodeData.data
- Performs case-insensitive pattern matching
- Routes results through "output 1" (match found) or "output 2" (no match)

Ports:
- Input Port: "input" (Left side) - Receives text to match against the pattern
- Output Port 1: "output 1" (Right side) - Emits when pattern matches (FOUND)
- Output Port 2: "output 2" (Right side) - Emits when pattern doesn't match (NOT_FOUND)

Properties:
- inputFirst: Stores the input text to match
- matchedPattern: Contains "FOUND" or "NOT_FOUND" based on match result
- nodeData.data: Contains the regular expression pattern (e.g., "hello|hi|hey")

Behavior:
1. Receives input text from the connected upstream node
2. Creates a case-insensitive RegExp from nodeData.data
3. Tests the input against the pattern
4. Sets matchedPattern to "FOUND" or "NOT_FOUND"
5. Routes the result through the appropriate output port

Regular Expression Examples:
- "hello|hi|hey" - Matches any of these greetings
- "\\d+" - Matches one or more digits
- "[a-zA-Z]+" - Matches one or more letters
- "^hello" - Matches "hello" at the start of the string
- "world$" - Matches "world" at the end of the string

Visual Appearance:
- Icon: Search icon (Font Awesome \uf002)
- Color: Brown/Tan (#C69C6D)
- Size: 150x100 pixels

Usage Example:
- Pattern: "hello|hi"
- Input: "hello world" → Matches → matchedPattern = "FOUND" → Routes to output 1
- Input: "goodbye" → No match → matchedPattern = "NOT_FOUND" → Routes to output 2

Code Implementation:

function updataData() {
  if (!inputFirst) {
  return
  }
  var re = new RegExp(nodeData.data, "i")  // 'i' flag for case-insensitive
  var found = re.test(inputFirst)
  matchedPattern = found ? "FOUND" : "NOT_FOUND"
}

3. Result True Node (ResultTrueNode)

Purpose: Displays a response message when a pattern match is found (FOUND).

Type ID: CSpecs.NodeType.ResultTrue (2)

Properties:
- Contains a single input port
- Displays response text when triggered
- Automatically sends the response to the chat interface
- Read-only (cannot be edited directly)

Ports:
- Input Port: "value" (Left side) - Receives data from Regex node's output 1

Behavior:
- Should be connected to Regex node's "output 1" port
- When triggered, checks if the upstream Regex node has matchedPattern === "FOUND"
- If true, sets nodeData.data to "HI ..." (or custom response)
- Emits botResponse signal to display the message in the chat box
- If the pattern didn't match, sets data to empty string

Visual Appearance:
- Icon: Checkmark/Circle icon (Font Awesome \uf058)
- Color: Green (#4caf50) - indicates positive/successful match
- Size: 150x100 pixels

Usage Example:
- Regex node matches "hello" → Routes to ResultTrue node
- ResultTrue node displays "HI ..." in chat
- User sees the bot's response

Code Implementation:

// In ChatbotScene.qml
  case CSpecs.NodeType.ResultTrue: {
  downStreamNode.nodeData.data = (upstreamNode.matchedPattern === "FOUND") ? "HI ..." : "";
  botResponse(downStreamNode.nodeData.data)
} break;

4. Result False Node (ResultFalseNode)

Purpose: Displays a response message when a pattern match is not found (NOT_FOUND).

Type ID: CSpecs.NodeType.ResultFalse (3)

Properties:
- Contains a single input port
- Displays response text when no pattern matches
- Automatically sends the response to the chat interface
- Read-only (cannot be edited directly)

Ports:
- Input Port: "value" (Left side) - Receives data from Regex node's output 2

Behavior:
- Should be connected to Regex node's "output 2" port
- When triggered, checks if the upstream Regex node has matchedPattern === "NOT_FOUND"
- If true, sets nodeData.data to " :( " (or custom response)
- Emits botResponse signal to display the message in the chat box
- If the pattern matched, sets data to empty string

Visual Appearance:
- Icon: X-mark/Circle icon (Font Awesome \uf057)
- Color: Red (#f44336) - indicates no match/failure
- Size: 150x100 pixels

Usage Example:
- Regex node doesn't match user input → Routes to ResultFalse node
- ResultFalse node displays " :( " in chat
- User sees the bot's "I don't understand" response

Code Implementation:

// In ChatbotScene.qml
  case CSpecs.NodeType.ResultFalse: {
  downStreamNode.nodeData.data = (upstreamNode.matchedPattern === "NOT_FOUND") ? " :( " : "";
  botResponse(downStreamNode.nodeData.data)
} break;

Node Type Summary Table

Data Flow Architecture

The chatbot follows a simple but powerful data flow pattern:

User Input (Chat Box)
    ↓
  Source Node (stores message)
    ↓
  Regex Node (pattern matching)
    ├─→ [Match Found] → ResultTrue Node → Chat Response ("HI ...")
    └─→ [No Match] → ResultFalse Node → Chat Response (" :( ")