API Reference


The NodeWidget class provides the main entry point to the nodeworks library. The class provides a QWidget that can be inserted into Qt based applications. The NodeWidget contains methods for adding/removing Nodes and Connections as well as saving, loading, exporting, and solving the network.

class nodeworks.nodewidget.NodeWidget(parent=None, parentNode=None, showtoolbar=True, onlypositivecoords=False, threaded=False, prompt=True)[source]

Main widget for the displaying and editing a Node Chart.

addConnection(from_, to, controlpoints=None)[source]

Add a new connection

addNode(path=[], pos=None, geometry=None, uniquename=None, node=None)[source]

Add a node to the scene.


Process dependencies of Nodes, determine order.


Copy the currently selected Nodes


Copies and designates the currently selected Nodes for deletion


Delete all Nodes.


Delete the cut Nodes.


Delete the currently selected Nodes.


Deselect Everything


Run the nodes.

keyboardPress(key, data)[source]

Handle keyboard press events from the view. Only lets control modified keys through, except for delete.

keyboardSearch(pos, text=None)[source]

Display a Node search tool when typing.


Everytime a new connection is made, or widget value changes, run this code.

open(event=None, path=None, nodeDict=None, customParams=None)[source]

Open a node chart or nodeDict


Paste the currently copied Nodes.


Delete items from scene

save(event=None, path=None, customParams=None)[source]

Save the node chart


Select Everything


Stop the run


Sort the dependency tree. Inspired by: http://code.activestate.com/recipes/578272-topological-sort/

static uniqueName(name, namelist, lower=True)[source]

Given a name and a name list, return a unique name.

NodeWidget Support

class nodeworks.nodewidget.GraphicsScene(parent=None)[source]

Custom QGraphicsScene.

class nodeworks.nodewidget.StructureScene(parent=None)[source]

Custom QGraphicsScene for structures.

class nodeworks.nodewidget.GraphicsView(scene, parent=None)[source]

Custom QGraphicsScene.


Handle key press events


Catch mouse events.


Handle zooming with the mouse wheel.

class nodeworks.nodewidget.PreviewView(scene, parent=None, view=None)[source]

Custom QGraphicsScene.

class nodeworks.nodewidget.SearchNodeWidget(parent=None, nodelist=[])[source]

Provide a search interface for the nodes

class nodeworks.nodewidget.WorkerThread(function, parent=None)[source]


The Node provides the top-level methods for a node.

class nodeworks.node.Node(parent=None, style={})[source]

Main class for a Node.

parent (QObject):
parent of the node, typically nodeworks.nodewidget.NodeWidget (defualt None)
style (dict):
a dictionary describing the style of the node

This method is called when options for a terminal exist in the state however, the terminal does not exist in the Node. This method is meant to be overridden.

terminal (dict):
a dictionary of options
addTerminal(name, opts={}, insert=None)[source]

Add a terminal to the Node.

name (str):
the name of the Terminal, and the index of the Terminal in terminals
opts (dict):
a dictionary of Terminal options (default dict())
insert (int):
the position to insert the Terminal at.
term (Terminal):
the created terminal
addWidget(widget, insert=None)[source]

Add an arbitrary widget to the Node.

widget (QWidget):
the widget to be added to the node. Can be any QtWidgets.QWidget based class such as QtWidgets.QLineEdit, QtWidgets.QPushButton, etc.
insert (int):
the position to insert the wiget at.

Clear the Node’s error state, allow to run.


Set the Node is not running.


Collect and return the dependencies of the Node

depSet (set):
a set nodes that this node depends on

Have the dependencies of the Node been processed

are the dependencies finished

Overide this function with code to check for errors.


Loop over terminals and flip them to/from left and right


This method is called when users select options that need to hide or show terminals based on selected options within the Node. This method is meant to be overwridden.


Overide this function with the code to be called when the Node is executed.


Remove all terminals from the Node.


Remove all connections from the Node.


Remove the terminal from the Node.

name (str):
name of the terminal to be removed

Run the node. This function updates connections, clears any errors, checks for errors, finally if there are no errors and the input values have changed, calls the process method

ran (bool):
False if process was not called (error) else True

Set the Node in an error state, will not let Node execute.

message (str):
an error message to be displayed for user information

Set the Node is running.

setState(state, customParams=None)[source]

Set the state. The uniquename, position, and connections are set through the addNode method of NodeWidget.

state (dict):
a dictionary containing information to set the terminal values

Set the style of the Node, as well as the terminals

style (dict):
a dictionary describing the style

Set the unique name of the node. This name is used in NodeWidget.nodeDict.

name (str):
the unique name

Display the help documentation


Programatically determine if the node has connections at terminals and show or hide them. On hide, hides any terminals that do not have a connection. On show, shows all terminals.

hide (bool):
a boolean that determines if the terminals should be hidden

The current state of the node (position, values, connections, path)

stateDict (dict):
a JSON encodable dictionary

A function that is called if a value is changed. This enables the node for processing

value (Object):
the value to emit with the valueChanged signal

Loop through terminals, updating inputs

Node Support

class nodeworks.node.NodeGraphic(node, parent=None, style={})[source]

This class handles all the graphics for a Node.

node (Node):
the Node that this NodeGraphic is part of
parent (QObject):
parent (default None)
style (dict):
dictionary containing options
rightClickEvent (QGraphicsEvent):
emits when a user right clicks on a node but not over a Terminal
addTerminal(opts, style={}, insert=None)[source]

Add a terminal to the Node.

opts (dict):
a dictionary with options to define the terminal
style (dict):
a dictinary descripting the style of the terminal
insert (int):
the position in the layout to insert the terminal at. Index starts at 0. Thfirst item in the layout is typical the label for the node (defualt None)
term (Terminal):
the Terminal that was just created
addTerminalPad(pos=None, connect=True, rect=None, name=None, inout=None, dtype=None, padtype='pass', load=False)[source]

Add an arbitrary terminal pad to the Node

pos (QtCore.QPoint):
position where to add the pad (default None)
connect (bool):
True to emit a new connection event (defualt True)
rect (QtCore.QRectF):
rectangle describing the geometry of the pad (default None)
name (str):
name of the pad (default None)
inout (str):
‘in’ for an input pad, ‘out’ for an output pad.
dtype (type):
dtype of the pad
padtype (str):
type of the pad either ‘pass’, ‘index’, or ‘shift’ for a pass through terminal, an indexed terminal, or a shifted terminal.
addWidget(widget, insert=None)[source]

Allows arbitray widgets to be added to a Node.

widget (QWidget):
the widget to be added
insert (int):
the position in the layout to insert the terminal at. Index starts at 0. Thfirst item in the layout is typical the label for the node (defualt None)

Create a QLineEdit to edit the Nodes name.


Delete the pad


Handle Drop Events


Capture double click event


Handle mouse move events.


Capture mouse press events and find where the mouse was pressed on the object.


Capture mouse Release events.


Move Node to position.

pos (QPointF):
position to move the NodeGraphic to.

Remove a terminal from the node.

term (Terminal):
the terminal object to remove from the NodeGraphic

Rename the node.

name (str):
string to change the node name to

Resize the NodeGraphic to the minimum size allowed by the widgets in the node.


calculates the upper left hand corner of a node regardless of layering of structures


Set a QWidget to act as an editor for renaming the node.

widget (QWidget):
A QWidget to be called when the user edits the node name. This widget must have a lostFocus signal that is emitted when the widget as a new name to set the Node name to.
showRightClickMenu(globalpos, otheractions=None)[source]

Creates, configures, and sets right click menu.

globalpos (QPoint):
the QPoint object that represents the position of the mouse when the function is called
otheractions (list):
a list of additional QAction items that should be added to the right click menu for the node

Update Connections


Update Connections


Update Connections

class nodeworks.node.Terminal(opts, node, style={})[source]

This class draws a terminal.

opts (dict):
a dictionary of options for a terminal
node (Node):
the Node that this terminal is a part of
style (dict):
a dictionary of termianl options (default {})
a signal that emits the the current value everytime that the value is changed
compare(value1, value2)[source]

Compare two values to see if they are the same. True means the values are NOT equal.


Remove all connections. Called at node delete event.


Remove a spcific connection. The connection should already be removed from the scene.

removeconnection (Connection):
the connection to be removed.

Set the current value.


If there is an input connection, update the value.


The current value.


The Connection provides connections between Terminals of Nodes

class nodeworks.node.Connection(nodeWidget=None, style=None, parent=None)[source]

This class draws connections between Terminals on Nodes.


Return the bounding rectange of the connection.


Generate a path following points

points (list):
a list of QtCore.QPoint points for the connection line to follow

Check if the connection has both a start and stop terminal. It it does, return True, else return False.


Capture the mouse press event

event ():
mouse event
paint(painter, *args)[source]

Paint the line.


Remove self from connected Nodes.


Remove the starting terminal


Remove the stop terminal


Set the starting terminal for a connection.


Set the starting terminal for a connection.


Calculate and return the shape of the connection. This shape is used for determining if the mouse is “over” the connection. This is used for mouseEvents and HoverEvents.


The current state of the node (position, values, connections, path)

stateDict (dict):
a JSON encodable dictionary

Update the line. If mousePos, use as missing point (start, stop).

mousePos (QtCore.QPoint):
a position to use as the missing point if


The NodeLibrary provides methods for building and maintaining a collection of Nodes that can be added to a network.

class nodeworks.nodelibrary.NodeLibrary[source]

Collection of Nodes

addNode(node, path)[source]

Add a Node to the library

addNodeLibrary(name, library)[source]

add a node library


build the default node library


Return the node at path

Base Widgets

Base widgets provide unified value and setValue methods as well as ValueChanged Signals for a collection of QWidgets.


A collection of helper functions.