QNodeEditor.node.Node#

class QNodeEditor.node.Node(title: str = 'Node')#

Bases: QObject

Node container holding inputs, outputs, widgets, and various utility methods.

This class is abstract and cannot be used by itself. To define nodes for the node editor, inherit from this class and implement (some of) the following functions:

create(): To add entries to the node and set properties such as its title
evaluate(): To use the inputs and static widgets of the node to determine its outputs
save(): To save any variables that are needed to restore the node state
load(): To use any saved variables to restore the node to its desired state

From these, only the py:meth:create method is strictly required.

Examples

To define a node that takes two number inputs and uses their sum as the output:

class MyNode(Node):
    code = 1  # Unique to MyNode

    def create(self):
        self.title = 'Add'  # Set the title of the node

        self.add_label_output('Output')  # Add a labeled output 'Output'
        self.add_value_input('Value 1')  # Add a number input 'Value 1'
        self.add_value_input('Value 2')  # Add another input 'Value 2'

    def evaluate(self, values):
        result = values['Value 1'] + values['Value 2']  # Calculate sum of Value 1 and 2
        self.set_output_value('Output', result)         # Set 'Output' value

Here, the create() method is called when the node is created. The evaluate() function is called when the node scene is evaluated (and the node is somehow connected to the output). It receives as its argument values. This is a dictionary of the values for each entry in the node. In this case, values would look like this:

values = {
    'Output': None,
    'Value 1': 10.0,  # some number
    'Value 2': 5.0    # another number
}

For MyNode, we do not need to implement the save() or load() function, since the value inputs are automatically saved. In case you implement custom entries, you can use these functions to store variables. The save() function should return a dictionary and can contain any data you want to save (as long as it is JSON-parsable). Whatever you choose to save will be provided back in the load() function, so you can restore the state of your node.

graphics#

Graphics object that is shown in the scene representing this edge

Type:: NodeGraphics

entries#

List of the entries in the node. List order is the same as vertical order of entries.

Type:: list[Entry]

output#

Cached output of the node (do not use)

Type:: dict[str, Any] or None

Properties

`evaluated`()	Signal that is emitted when the node is evaluated
`output`	Get or set the cached output for this node.
`scene`	Get or set the scene this node is part of
`title`	Get or set the title of the node
`code`	Unique code that only one derived Node class can use

Methods

`__init__`	Create a new node.
`add_combo_box_entry`	Add a new combo box entry to the node.
`add_entries`	Add multiple entries to this node.
`add_entry`	Add an entry to this node.
`add_label_entry`	Add a new labeled entry to the node.
`add_label_input`	Add a new labeled input to the node.
`add_label_output`	Add a new labeled output to the node.
`add_text_entry`	Add a new text box entry to the node.
`add_text_input`	Add a new text box input to the node.
`add_text_output`	Add a new text box output to the node.
`add_value_entry`	Add a new value box entry to the node.
`add_value_input`	Add a new value box input to the node.
`add_value_output`	Add a new value box output to the node.
`connect_signals`	Connect signals from all entries to the scene
`create`	Override this method to add elements to the node and set its properties.
`disconnect_signals`	Disconnect signals from all entries from the scene
`entry_names`	Get the names of all entries in the node.
`evaluate`	Override this method to use the inputs of the node to determine the outputs of the node.
`get_entry`	Get an entry object by its name.
`get_state`	Get the state of this node as a (JSON-safe) dictionary.
`index`	Get the index of the specified entry.
`insert_entries`	Insert multiple entries into this node at a specific index.
`insert_entry`	Insert an entry into this node at a specific index.
`load`	Override this method to load the saved additional values and restore the node state.
`remove`	Remove this node from the scene.
`remove_all_entries`	Remove all entries from the node.
`remove_entry`	Remove an entry from the node.
`save`	Override this method to save any additional values to the node state.
`set_output_value`	Set the value of an output entry.
`set_state`	Set ths state of this node from a state dictionary.
`sockets`	Get a list of all sockets in this node.
`update_entries`	Update the geometry of all entries in the node.

__init__(title: str = 'Node')#

Create a new node.

Defines an empty node and a graphics object to represent it in the scene.

Parameters:: title (str, default='Node') – Title of the node (can be accessed through title)

add_combo_box_entry(name: str, items: Iterable[str] = None) → None#

Add a new combo box entry to the node.

Adds a new entry to the node containing a combo box widget. This entry can only be static.

Parameters:

name (str) – Name of this entry
items (Iterable[str] or dict[str, Any]) –
Possible values of the combo box.

Can be a list of strings used as the name of each option.

Can be a dictionary of (name, data) pairs.

If a dictionary is used, the values argument for the evaluate() method will contain the data for the selected option. Otherwise, it will contain the name.

Return type:

None

add_entries(entries: Iterable[Entry]) → None#

Add multiple entries to this node.

Append multiple new entries to the node content. The entries will be placed at the end (bottom) of the node.

See also

add_entry(): Add a single entry
insert_entry(): Add an entry at a specific index
insert_entries(): Add multiple entries at a specific index

Parameters:: entries (Iterable[Entry]) – Iterable of entries to add to the node
Return type:: None

add_entry(entry: Entry) → None#

Add an entry to this node.

Append a new entry to the node content. The entry will be placed as the last entry (bottom) of the node.

See also

add_entries(): Add multiple entries
insert_entry(): Add an entry at a specific index
insert_entries(): Add multiple entries at a specific index

Parameters:: entry (Entry) – Entry to add to the node
Return type:: None

add_label_entry(name: str, entry_type: int = 0) → None#

Add a new labeled entry to the node.

Adds a new entry to the node containing only a label with the entry name.

Parameters:

name (str) – Name of this entry
entry_type (int) – Type of entry (TYPE_STATIC, TYPE_INPUT , or TYPE_OUTPUT)

Return type:

None

add_label_input(name: str) → None#

Add a new labeled input to the node.

Adds a new entry to the node containing only a label with the entry name. The entry has an input socket.

Parameters:: name (str) – Name of this entry
Return type:: None

add_label_output(name: str) → None#

Add a new labeled output to the node.

Adds a new entry to the node containing only a label with the entry name. The entry has an output socket.

Parameters:: name (str) – Name of this entry
Return type:: None

add_text_entry(name: str, entry_type: int = 0, value: str = '', max_length: int = 32767, show_clear_button: bool = False, input_mask: str = '', completer: QCompleter | None = None, validator: QValidator | None = None) → None#

Add a new text box entry to the node.

Adds a new entry to the node containing a TextBox widget.

By default, the entry is static (no inputs/outputs).

Parameters:

name (str) – Name of this entry
entry_type (int) – Type of entry (TYPE_STATIC, TYPE_INPUT , or TYPE_OUTPUT)
value (str, optional) – Initial value of the TextBox
max_length (int, optional) – Maximum length of the string in the text box
show_clear_button (bool, optional) – Show a clear button in the text box when the string is not empty
input_mask (str, optional) – Input mask to use for text box (see QLineEdit input mask)
completer (Optional[QCompleter], optional) – Auto-completer to use for the text box
validator (Optional[QValidator], optional) – Validator to use for the text box

Return type:

None

add_text_input(name: str, value: str = '', max_length: int = 32767, show_clear_button: bool = False, input_mask: str = '', completer: QCompleter | None = None, validator: QValidator | None = None) → None#

Add a new text box input to the node.

Adds a new entry to the node containing a TextBox widget. The entry has an input socket.

Parameters:

name (str) – Name of this entry
value (str, optional) – Initial value of the TextBox
max_length (int, optional) – Maximum length of the string in the text box
show_clear_button (bool, optional) – Show a clear button in the text box when the string is not empty
input_mask (str, optional) – Input mask to use for text box (see QLineEdit input mask)
completer (Optional[QCompleter], optional) – Auto-completer to use for the text box
validator (Optional[QValidator], optional) – Validator to use for the text box

Return type:

None

add_text_output(name: str, value: str = '', max_length: int = 32767, show_clear_button: bool = False, input_mask: str = '', completer: QCompleter | None = None, validator: QValidator | None = None) → None#

Add a new text box output to the node.

Adds a new entry to the node containing a TextBox widget. The entry has an output socket.

Parameters:

name (str) – Name of this entry
value (str, optional) – Initial value of the TextBox
max_length (int, optional) – Maximum length of the string in the text box
show_clear_button (bool, optional) – Show a clear button in the text box when the string is not empty
input_mask (str, optional) – Input mask to use for text box (see QLineEdit input mask)
completer (Optional[QCompleter], optional) – Auto-completer to use for the text box
validator (Optional[QValidator], optional) – Validator to use for the text box

Return type:

None

add_value_entry(name: str, entry_type: int = 0, value: int = 0, minimum: int = -100, maximum: int = 100, value_type: ~typing.Type[int] = <class 'float'>) → None#

Add a new value box entry to the node.

Adds a new entry to the node containing a ValueBox widget.

By default, the entry is static (no inputs/outputs).

Parameters:

name (str) – Name of this entry
entry_type (int) – Type of entry (TYPE_STATIC, TYPE_INPUT , or TYPE_OUTPUT)
value (int or float) – Initial value of the ValueBox
minimum (int or float) – Minimum value of the ValueBox
maximum (int or float) – Maximum value of the ValueBox
value_type (Type[int] or Type[float]) – Type of ValueBox (float or int)

Return type:

None

add_value_input(name: str, value: int = 0, minimum: int = -100, maximum: int = 100, value_type: ~typing.Type[int] = <class 'float'>) → None#

Add a new value box input to the node.

Adds a new entry to the node containing a ValueBox widget. The entry has an input socket.

Parameters:

name (str) – Name of this entry
value (int or float) – Initial value of the ValueBox
minimum (int or float) – Minimum value of the ValueBox
maximum (int or float) – Maximum value of the ValueBox
value_type (Type[int] or Type[float]) – Type of ValueBox (float or int)

Return type:

None

add_value_output(name: str, value: int = 0, minimum: int = -100, maximum: int = 100, value_type: ~typing.Type[int] = <class 'float'>) → None#

Add a new value box output to the node.

Adds a new entry to the node containing a ValueBox widget. The entry has an output socket.

Parameters:

name (str) – Name of this entry
value (int or float) – Initial value of the ValueBox
minimum (int or float) – Minimum value of the ValueBox
maximum (int or float) – Maximum value of the ValueBox
value_type (Type[int] or Type[float]) – Type of ValueBox (float or int)

Return type:

None

connect_signals() → None#

Connect signals from all entries to the scene

Return type:: None

abstract create() → None#

Override this method to add elements to the node and set its properties.

Return type:: None

disconnect_signals() → None#

Disconnect signals from all entries from the scene

Return type:: None

entry_names() → list[str]#

Get the names of all entries in the node.

The result of this function is a list of names. Entry names within a node are unique.

Return type:: None

evaluate(entry_values: dict[str, Any]) → None#

Override this method to use the inputs of the node to determine the outputs of the node.

Use the set_output_value() method to set output values of the node.

By default, the entry outputs are set using the corresponding widget value.

Parameters:: entry_values (dict[str, Any]) – Dictionary with (name, value) pairs for each entry in this node.
Return type:: None

get_entry(name: str) → Entry#

Get an entry object by its name.

Parameters:: name (str) – Name of the entry to retrieve.
Returns:: The entry with the specified name.
Return type:: Entry
Raises:: KeyError – If no entry with the specified name exists.

get_state() → dict#

Get the state of this node as a (JSON-safe) dictionary.

The dictionary contains:

code: the unique code assigned to this node type
title: Title of the node
pos_x: X-location of the node in the scene
pos_y: Y-location of the node in the scene
entries: list of states for each entry
custom: additional values saved through the save() method

Returns:: JSON-safe dictionary representing the node state
Return type:: dict

index(entry: str) → int#

Get the index of the specified entry.

Finds the entry (optionally by name) and returns its index (0 being the top-most entry).

Parameters:: entry (str or Entry) – The (name of the) entry to get the index of
Returns:: Index of the specified entry
Return type:: int
Raises:: KeyError – If the entry could not be found in the node

insert_entries(entries: Iterable[Entry], index: int) → None#

Insert multiple entries into this node at a specific index.

Inserts new entries into the node content. The position of the entries is determined by the index (0 being the top-most entry).

See also

add_entry(): Add a single entry at the end
add_entries(): Add multiple entries at the end
insert_entry(): Add a single entry at a specific index

Parameters:

entries (Iterable[Entry]) – Iterable of entries to add to the node
index (int) – Index at which to insert the entries

Return type:

None

insert_entry(entry: Entry, index: int) → None#

Insert an entry into this node at a specific index.

Inserts a new entry into the node content. The position of the entry is determined by the index (0 being the first (top) element).

See also

add_entry(): Add a single entry at the end
add_entries(): Add multiple entries at the end
insert_entries(): Add multiple entries at a specific index

Parameters:

entry (Entry) – Entry to add to the node
index (int) – Index at which to insert the entry

Return type:

None

load(state: dict) → bool#

Override this method to load the saved additional values and restore the node state.

The received state is the same as the dictionary returned by the save() method (an empty dictionary if not overridden).

Use this method to use the saved values to restore the node to the desired state.

Parameters:: state (dict) – Saved additional values by save()
Returns:: Whether the method executed successfully
Return type:: bool

remove() → None#

Remove this node from the scene.

The node will be removed from the scene. Any edges connected to the node are removed as well.

Return type:: None

remove_all_entries() → None#

Remove all entries from the node.

This methods clears all of the content from the node. Since all entries are removed, any edges connected to inputs/outputs are also removed.

Return type:: None

remove_entry(name: str)#

remove_entry(entry: QNodeEditor.entry.Entry)

remove_entry(entry) → None

Remove an entry from the node.

Finds and removes the specified entry from the node. The node is automatically resized to fit the remaining content.

Parameters:: entry (str or Entry) – The (name of the) entry to remove.
Return type:: None
Raises:: TypeError – If the entry argument is not a string or Entry

save() → dict#

Override this method to save any additional values to the node state.

The dictionary returned by this function is saved along with the rest of the node state. It is provided back to the load() method when the node is loaded again.

Use this method to add any variables to the node state that are needed to restore the node to the desired state when the node is loaded.

Returns:

dict – Additional values to save (key, value) pairs.

Must be JSON-safe.
:meta abstract:

set_output_value(entry: str, value: Any) → None#

Set the value of an output entry.

Use this function in the evaluate() method in derived classes. The outputs can then be used by any nodes connected to them.

Parameters:

entry (str or .entry.Entry) – The (name of the) output entry to set the output value for
value (Any) – The value to give the output

Return type:

None

set_state(state: dict, restore_id: bool = True) → bool#

Set ths state of this node from a state dictionary.

The dictionary contains:

code: the unique code assigned to this node type
title: Title of the node
pos_x: X-location of the node in the scene
pos_y: Y-location of the node in the scene
entries: list of states for each entry
custom: additional values saved through the save() method

Parameters:

state (dict) – Dictionary representation of the desired node state
restore_id (bool) –
Whether to restore the internal IDs of the node sockets (used to reconnect saved edges)

Is set to False for copy-paste operations (sockets take on new unique ID)

Returns:

Whether setting the node state succeeded

Return type:

bool

Raises:

ValueError – If the number of entry states in the state argument does not match the number of entries in the node after running the create() method. If this occurs, the node does not have the same entries as when it was saved. Use the save() and load() methods to save and restore additional values such that the node ends up with the same entries.

sockets() → list[Socket]#

Get a list of all sockets in this node.

Goes through each entry and collects its socket (if it has one)

Returns:: List of Socket objects that are in this node
Return type:: list[Socket]

code: int#

Unique code that only one derived Node class can use

Type:: int

evaluated: Signal#

Signal that is emitted when the node is evaluated

Type:: Signal

property scene: NodeScene | None#: Get or set the scene this node is part of

property title: str#: Get or set the title of the node

Table of Contents

QNodeEditor.node.Node#