API Reference

NodeWidget

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 = None, parentNode: None = None, showtoolbar: bool = True, onlypositivecoords: bool = False, threaded: bool = False, prompt: bool = True)

Main widget for the displaying and editing a Node Chart.

addConnection(from_, to, controlpoints=None)

Add a new connection

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

Add a node to the scene.

buildRunOrder()

Process dependencies of Nodes, determine order.

copyNodes(recursive=False)

Copy the currently selected Nodes

cutNodes()

Copies and designates the currently selected Nodes for deletion

deleteAllNodes(confirm=True)

Delete all Nodes.

deleteCopyNodes()

Delete the cut Nodes.

deleteNodes()

Delete the currently selected Nodes.

deselectAll()

Deselect Everything

executeThreaded()

Run the nodes.

keyboardPress(key, data)

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

keyboardSearch(pos, text=None)

Display a Node search tool when typing.

networkChanged(args=None)

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

open(event=None, path=None, nodeDict=None, customParams=None)

Open a node chart or nodeDict

pasteNodes(recursive=False)

Paste the currently copied Nodes.

remove(items)

Delete items from scene

resizeEvent(self, a0: Optional[QResizeEvent])

save(event=None, path=None, customParams=None, save_connected_value=False, save_non_widget_value=True)

Save the node chart

selectAll()

Select Everything

stopRun()

Stop the run

topologicalSort()

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

NodeWidget Support

class nodeworks.nodewidget.GraphicsScene(parent=None)

Custom QGraphicsScene.

focusInEvent(self, event: Optional[QFocusEvent])

focusOutEvent(self, event: Optional[QFocusEvent])

mousePressEvent(self, event: Optional[QGraphicsSceneMouseEvent])

mouseReleaseEvent(self, event: Optional[QGraphicsSceneMouseEvent])

class nodeworks.nodewidget.StructureScene(parent=None)

Custom QGraphicsScene for structures.

class nodeworks.nodewidget.GraphicsView(scene: GraphicsScene, parent: None = None)

Custom QGraphicsScene.

keyPressEvent(event)

Handle key press events

leaveEvent(self, a0: Optional[QEvent])

mouseMoveEvent(self, event: Optional[QMouseEvent])

mousePressEvent(event: QMouseEvent)

Catch mouse events.

mouseReleaseEvent(self, event: Optional[QMouseEvent])

save_to_image(fname, scale=1)

Save the image to a file.

wheelEvent(event)

Handle zooming with the mouse wheel.

class nodeworks.nodewidget.PreviewView(scene: GraphicsScene, parent: NodeWidget | None = None, view: GraphicsView | None = None)

Custom QGraphicsScene.

mouseDoubleClickEvent(self, event: Optional[QMouseEvent])

mouseMoveEvent(self, event: Optional[QMouseEvent])

mousePressEvent(self, event: Optional[QMouseEvent])

mouseReleaseEvent(self, event: Optional[QMouseEvent])

resizeEvent(self, event: Optional[QResizeEvent])

class nodeworks.nodewidget.SearchNodeWidget(parent: NodeWidget | None = None, nodelist: List[Any] = [])

Provide a search interface for the nodes

hide(self)

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

run(self)

Node

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

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

Main class for a Node.

Parameters

parent (QObject):

parent of the node, typically nodeworks.nodewidget.NodeWidget (default None)

style (dict):

a dictionary describing the style of the node

addMissingTerminal(terminal)

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.

Parameters

terminal (dict):

a dictionary of options

addTerminal(name, opts={}, insert=None)

Add a terminal to the Node.

Parameters

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.

Returns

term (Terminal):

the created terminal

addWidget(widget, insert=None)

Add an arbitrary widget to the Node.

Parameters

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.

clearError()

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

clearRunning()

Set the Node is not running.

collapse(hide=None)

Collapse/expand the node down to only the connected terminals.

Parameters

hide (bool):

a boolean that determines if the terminals should be hidden

dependencies()

Collect and return the dependencies of the Node

Returns

depSet (set):

a set nodes that this node depends on

depsFinished()

Have the dependencies of the Node been processed

Returns

(bool):

are the dependencies finished

errorCheck()

Override this function with code to check for errors.

flipTerminals()

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

manageTerminals()

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 overridden.

manual_process()

Call this method to run the self.process method threaded.

process()

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

removeAllTerminals(inout=None)

Remove all terminals from the Node.

removeConnections()

Remove all connections from the Node.

removeTerminal(name)

Remove the terminal from the Node.

Parameters

name (str):

name of the terminal to be removed

runNode()

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

Returns

ran (bool):

False if process was not called (error) else True

setError(message='None', terminal=None)

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

Parameters

message (str):

an error message to be displayed for user information

terminal (str):

name of the terminal to highlight in red

setRunning()

Set the Node is running.

setState(state, customParams=None)

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

Parameters

state (dict):

a dictionary containing information to set the terminal values

setStyle(style=None)

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

Parameters

style (dict):

a dictionary describing the style

setUniqueName(name)

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

Parameters

name (str):

the unique name

showHelpDoc()

Display the help documentation

state(customParams=None, save_connected_value=False, save_non_widget_value=True)

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

Returns

stateDict (dict):

a JSON encodable dictionary

terminalChanged(value)

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

Parameters

value (Object):

the value to emit with the valueChanged signal

updateInputs()

Loop through terminals, updating inputs

Node Support

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

This class handles all the graphics for a Node.

Parameters

node (Node):

the Node that this NodeGraphic is part of

parent (QObject):

parent (default None)

style (dict):

dictionary containing options

Signals

rightClickEvent (QGraphicsEvent):

emits when a user right clicks on a node but not over a Terminal

addTerminal(opts, style={}, insert=None)

Add a terminal to the Node.

Parameters

opts (dict):

a dictionary with options to define the terminal

style (dict):

a dictionary 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 (default None)

Returns

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)

Add an arbitrary terminal pad to the Node

Parameters

pos (QtCore.QPoint):

position where to add the pad (default None)

connect (bool):

True to emit a new connection event (default 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)

Allows arbitrary widgets to be added to a Node.

Parameters

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 (default None)

buildLabelEditWidget()

Create a QLineEdit to edit the Nodes name.

deletePad(pad)

Delete the pad

dropConnectionEvent(scenePos)

Handle Drop Events

hoverEnterEvent(self, event: Optional[QGraphicsSceneHoverEvent])

hoverLeaveEvent(self, event: Optional[QGraphicsSceneHoverEvent])

hoverMoveEvent(self, event: Optional[QGraphicsSceneHoverEvent])

itemChange(self, change: QGraphicsItem.GraphicsItemChange, value: Any) → Any

keyPressEvent(self, event: Optional[QKeyEvent])

mouseDoubleClickEvent(event)

Capture double click event

mouseMoveEvent(event)

Handle mouse move events.

mousePressEvent(event)

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

mouseReleaseEvent(event)

Capture mouse Release events.

moveTo(pos)

Move Node to position.

Parameters

pos (QPointF):

position to move the NodeGraphic to.

paint(self, painter: Optional[QPainter], option: Optional[QStyleOptionGraphicsItem], widget: Optional[QWidget])

removeTerminal(term)

Remove a terminal from the node.

Parameters

term (Terminal):

the terminal object to remove from the NodeGraphic

rename(name)

Rename the node.

Parameters

name (str):

string to change the node name to

resizeToMinimum()

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

screenPos()

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

setLabelEditWidget(widget)

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

Parameters

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.

setStyle(self, style: Optional[QStyle])

showRightClickMenu(globalpos, otheractions=None)

Creates, configures, and sets right click menu.

Parameters

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(self, rect: QRectF = QRectF())

update(self, ax: float, ay: float, width: float, height: float) → None

updateConnections()

Update Connections

updateTerminalValues()

Update Connections

updateTerminals()

Update Connections

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

This class draws a terminal.

Parameters

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 terminal options (default {})

Signals

valueChanged(value)

a signal that emits the the current value every time that the value is changed

compare(value1, value2)

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

hide(self)

paintEvent(self, a0: Optional[QPaintEvent])

removeAllConnections()

Remove all connections. Called at node delete event.

removeConnection(removeconnection)

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

Parameters

removeconnection (Connection):

the connection to be removed.

setStyle(self, a0: Optional[QStyle])

setValue(value, trigger_update=False)

Set the current value.

show(self)

updateInput()

If there is an input connection, update the value.

property value

The current value.

Connection

The Connection provides connections between Terminals of Nodes

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

This class draws connections between Terminals on Nodes.

boundingRect()

Return the bounding rectangle of the connection.

generatePath(points)

Generate a path following points

Parameters

points (list):

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

isConnected()

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

mouseDoubleClickEvent(self, event: Optional[QGraphicsSceneMouseEvent])

mousePressEvent(event)

Capture the mouse press event

Parameters

event ():

mouse event

paint(painter, *args)

Paint the line.

removeConnections()

Remove self from connected Nodes.

removeStartTerm()

Remove the starting terminal

removeStopTerm()

Remove the stop terminal

setStartTerminal(startTerm)

Set the starting terminal for a connection.

setStopTerminal(stopTerm)

Set the starting terminal for a connection.

shape()

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.

state(customParams=None, save_connected_value=False, save_non_widget_value=True)

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

Returns

stateDict (dict):

a JSON encodable dictionary

updateLine(mousePos=None)

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

Parameters

mousePos (QtCore.QPoint):

a position to use as the missing point if

NodeLibrary

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

class nodeworks.nodelibrary.NodeLibrary

Collection of Nodes

addNode(node, path)

Add a Node to the library

build_default_library()

build the default node library

getNode(path)

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.

Tools

A collection of helper functions.