maxon.frameworks.graph.GraphModelInterface

Description

GraphModelInterface is an abstraction of a hierarchical graph.

The root node and any other node may have an arbitrary number of child nodes.

Each node may have a number of input ports and output ports.
Those ports may have nested ports, too.

Nodes and ports of a graph can be arranged in a single tree, for example:
  • Root (NODE_KIND::NODE)
    • N1 (NODE_KIND::NODE)
      • N2 (NODE_KIND::NODE)
        • Inputs (NODE_KIND::INPUTS)
          • PortA (NODE_KIND::INPORT)
            • PortB (NODE_KIND::INPORT)

          • PortC (NODE_KIND::INPORT)

        • Outputs (NODE_KIND::OUTPUTS)
          • PortD (NODE_KIND::OUTPORT)

      • Inputs (NODE_KIND::INPUTS)
        • PortE (NODE_KIND::INPORT)

      • Outputs (NODE_KIND::OUTPUTS)
        • PortF (NODE_KIND::OUTPORT)
          • PortG (NODE_KIND::OUTPORT)

    • N3 (NODE_KIND::NODE)
      • Inputs (NODE_KIND::INPUTS)
        • PortH (NODE_KIND::INPORT)

      • Outputs (NODE_KIND::OUTPUTS)
        • PortI (NODE_KIND::OUTPORT)

To distinguish between the different kinds of a maxon.frameworks.graph.GraphNode, a value of type maxon.frameworks.graph.NODE_KIND is returned by maxon.frameworks.graph.GraphNode.GetKind().
The example tree shows the possible kinds in parentheses:
  • NODE_KIND.NODE stands for true nodes.

  • NODE_KIND.INPUTS/NODE_KIND.OUTPUTS represent the lists of top-level input/output ports of a node.

  • NODE_KIND.INPORT/NODE_KIND.OUTPORT represent input/output ports.

It is not required for an implementation of maxon.frameworks.graph.GraphModelInterface to support arbitrary nestings.
For example, the implementation for nodes supports arbitrarily nested ports, but depending on its filter settings it doesn’t support nodes nested within other nodes.
In addition to the tree of nodes and ports, a hierarchical graph also has a number of connections between ports.
They are represented by maxon.frameworks.graph.GraphConnection.
Typically a connection goes from an output port to an input port, but this is not always the case.
The following connections are allowed:
  • An output port of a node may have a connection to an input port of a sibling node (so both nodes must have the same direct parent).

  • An input port of a child node may have a connection from an input port of its direct parent node.

  • An output port of a child node may have a connection to an output port of its direct parent node.

  • An input port of a node may have a connection to an output port of that same node (so the connections just tunnels the value through the node).

In all cases it doesn’t matter if the ports are top-level ports or nested ports.

Each node may have attributes.
An attribute is identified by an maxon.InternedId, typically this id is defined together with the type of the attribute value by maxon.MAXON_ATTRIBUTE().

Inheritance diagram

Inheritance

Parent Class:

Children Classes:

Methods Signature

AddChild(childId, nodeId[, args])

Adds an instance of the node given by the identifier nodeId as child of the root node to this graph.

AddPorts()

Apply()

Applies the given change list to the node system of this manager.

BeginTransaction([userData])

Begins a new transaction within which modifications can be made.

BeginTransactionImpl()

CommitImpl(userData, nesting[, validate])

CreateCopyOfSelection(selection)

Returns a new graph model which is a copy of the subgraph given by the selection.

DeSelectAll(kind)

Deselect all node based on the maxon.frameworks.graph.NODE_KIND passed as parameter.

DeselectNode(node)

Deselects a node or a port.

DeselectPort(port)

Deselects the Port passed as an argument.

DeselectTrueNode(node)

Deselects the True Node passed as an argument.

DeselectWire(src, dst)

Deselects the Wire between two Ports.

GetChangeList()

Returns the change list to which this graph model currently logs its modifications.

GetGraphAttribute(attr)

Returns the maxon.frameworks.graph.GraphAttribute which this graph model uses for the attribute identified by attr.

GetGraphAttributeFlags(attr)

Returns the maxon.frameworks.graph.GraphAttributeInterface.FLAGS to use for the attribute identified by attr.

GetModificationStamp()

Returns a time stamp of this graph which can be used to test for modifications.

GetModificationsSince(stamp[, receiver])

Reports all modifications which have been made since the given stamp to receiver.

GetNode(path[, filtered])

Returns the maxon.frameworks.graph.GraphNode corresponding to path.

GetRoot()

Returns the root node of this graph.

GetRootPath()

Returns the path of the root node of this graph.

GetSelectedNodes(callback, kind)

Retrieves all the selected ports or nodes on the graph depending on the NODE_KIND passed as argument.

GetSelectedPorts(callback)

Retrieves all the selected ports on the graph.

GetSelectedTrueNodes(callback)

Retrieves all the selected nodes on the graph.

GetSelectedWires(callback)

Retrieves all the selected wire on the graph.

GetTransactionCount()

GetUserState()

IsConnectable()

IsPortSelected(port)

Checks if the passed Port is selected.

IsReadOnly()

Checks if this graph is read-only.

IsTrueNodeSelected(node)

Checks if the passed True Node is selected.

IsWireSelected(src, dst)

Checks if a Wires between two port is selected.

ListAllNodes(callback, matchingData)

Retrieves all nodes having their stored data equals the ones in the passed DataDictionary.

Merge(other)

Merges the other graph into this graph.

RemovePorts()

ResetUserState(attr)

Removes all values for the given user state attribute attr from this graph (so from all of its nodes).

SelectNode(node)

Selects a node or a port.

SelectPort(port)

Retrieves all the selected ports on the graph.

SelectTrueNode(node)

Select the node passed as an argument.

SelectWire(src, dst)

Selects the Wire between two Ports.

StartNewChangeList()

Starts a new change list and returns the previous one.

Validate()

Validates the graph.

Methods Definition

GraphModelInterface.AddChild(childId, nodeId, args=)

Adds an instance of the node given by the identifier nodeId as child of the root node to this graph.

If childId is empty, a maxon.UUID will be chosen as identifier of the child, otherwise childId.
In the latter case it is an error if this root node already has a child with that identifier.
Parameters
  • childId (Union[str, maxon.Id]) – Identifier for the child node (if empty, a UUID is chosen).

  • nodeId (Union[str, maxon.Id]) – Identifier for the type of the node to add. How this is resolved to an actual node type is model-specific.

  • args (maxon.DataDictionary) – Arguments to use for the node creation. The exact meaning is model-specific.

Returns

A maxon.frameworks.graph.GraphNode referencing the added child.

Return type

maxon.frameworks.graph.GraphNode

GraphModelInterface.AddPorts()
GraphModelInterface.Apply()

Applies the given change list to the node system of this manager.

Parameters
  • list (maxon.frameworks.misc.ChangeList) – Change list to apply.

  • inverse (bool) – True if the inverse of the change list shall be applied (for an undo), False otherwise.

Returns

A new change list which contains those changes of list which couldn’t be applied, for example the change of an attribute value at a node which doesn’t exist in the node system.

Return type

maxon.frameworks.misc.ChangeList

GraphModelInterface.BeginTransaction(userData=None)
Begins a new transaction within which modifications can be made.

This is mandatory in order to modify the graph, modifications outside of transactions are not allowed (with the exception of changing user state attributes).

If there already is an active transaction, this will create a nested transaction.
Otherwise a non-nested transaction starts, only then the observable

Warning

It’s mandatory to use the with statement as unclosed Transaction could lead to a freeze.

# This will start a new transaction and RollBack the transaction once the scope is left
with graph.BeginTransaction() as transaction:
    # Do some modification like connecting two ports
    graph.Connect()

    # This will commit and perform the change to the graph
    transaction.Commit()

# transaction is not anymore accessible and it has been Rolled out to the previous Commit.
Parameters

userData (maxon.DataDictionary) –

User data to pass to the observers of GraphModelInterface::ObservableTransactionStarted.
Because nested transactions don’t trigger the observable, the user data of them is ignored.

Returns

A maxon.frameworks.graph.GraphTransaction object to commit or rollback the transaction at a later point of time.

Return type

maxon.frameworks.graph.GraphTransaction

GraphModelInterface.BeginTransactionImpl()
GraphModelInterface.CommitImpl(userData, nesting, validate=None)
GraphModelInterface.CreateCopyOfSelection(selection)

Returns a new graph model which is a copy of the subgraph given by the selection.

Parameters

selection (list[maxon.frameworks.graph.GraphNode]) – A selection of nodes. Nodes which aren’t direct children of this graph are ignored.

Returns

A copy of the subgraph given by the selection.

Return type

maxon.frameworks.graph.GraphModelRef

GraphModelInterface.DeSelectAll(kind)

Deselect all node based on the maxon.frameworks.graph.NODE_KIND passed as parameter.

Parameters

kind (maxon.frameworks.graph.NODE_KIND) – The GraphNode kind to check

GraphModelInterface.DeselectNode(node)

Deselects a node or a port.

Parameters

node (maxon.frameworks.graph.GraphNode) – The node or the port that have to be deselected.

GraphModelInterface.DeselectPort(port)

Deselects the Port passed as an argument.

Parameters

port (maxon.frameworks.graph.GraphNode) – The Port to deselect.

GraphModelInterface.DeselectTrueNode(node)

Deselects the True Node passed as an argument.

Parameters

node (maxon.frameworks.graph.GraphNode) – The True Node to deselect.

GraphModelInterface.DeselectWire(src, dst)

Deselects the Wire between two Ports.

Parameters
GraphModelInterface.GetChangeList()
Returns the change list to which this graph model currently logs its modifications.
A newly created graph model doesn’t automatically create a change list, so to start logging you need to call GraphModelInterface.StartNewChangeList() once.
The change list can be used to undo or redo the changes or even to apply them to a different graph, see GraphModelInterface.Apply().
Returns

Current change list, may be a null reference.

Return type

maxon.frameworks.misc.ChangeList

GraphModelInterface.GetGraphAttribute(attr)
Returns the maxon.frameworks.graph.GraphAttribute which this graph model uses for the attribute identified by attr.
The model may return a null reference if it doesn’t provide a maxon.frameworks.graph.GraphAttribute for attr.
This doesn’t mean that the attribute is unsupported, it just means that there is no need for special handling of the attribute (which would require a maxon.frameworks.graph.GraphAttribute).
Parameters

attr (maxon.InternedId) – The identifier of the attribute

Returns

The corresponding maxon.frameworks.graph.GraphAttribute, or a null reference if the graph model has no maxon.frameworks.graph.GraphAttribute for attr.

Return type

maxon.frameworks.graph.GraphAttribute

GraphModelInterface.GetGraphAttributeFlags(attr)
Returns the maxon.frameworks.graph.GraphAttributeInterface.FLAGS to use for the attribute identified by attr.
This allows the graph model to override the default flags of the attribute, for example to mark an attribute as meta attribute.
Parameters

attr (maxon.InternedId) – The identifier of the attribute.

Returns

The flags which this graph model uses for the attribute.

Return type

maxon.frameworks.graph.GraphAttributeInterface.FLAGS

GraphModelInterface.GetModificationStamp()
Returns a time stamp of this graph which can be used to test for modifications.
Each transaction or change of user state increments the stamp.
The time stamp is also needed for GraphModelInterface.GetModificationsSince() and GraphNode.GetAttributeModificationsSince() to get all modifications which have happened since then.
Returns

Modification time stamp of the graph.

Return type

maxon.TimeStamp

GraphModelInterface.GetModificationsSince(stamp, receiver=None)
Reports all modifications which have been made since the given stamp to receiver.
If receiver is None only flags will be returned.
Parameters
Returns

Combination of flags to indicate the kinds of changes that have happened.

GraphModelInterface.GetNode(path, filtered=True)

Returns the maxon.frameworks.graph.GraphNode corresponding to path.

Note

If no such node exists in the graph, an empty node is returned.

Parameters
  • path (maxon.frameworks.graph.NodePath) –

    A node path.
    This has to be an absolute path, so if the current graph is view of a nested part of an enclosing graph.
    The path has to be the full path starting at the root of the enclosing graph.

  • filtered

    With the default value of True the filter settings (if any) of this graph will be used.
    When False this is disabled, then you’ll get a valid maxon.frameworks.graph.GraphNode even for paths which don’t belong to this graph, but e.g. to nested graphs which are hidden by the filter settings.

Return type

maxon.frameworks.graph.GraphNode

Returns

The maxon.frameworks.graph.GraphNode corresponding to the path.
This is empty when there is no such node in the graph.

GraphModelInterface.GetRoot()
Returns the root node of this graph.
The whole graph can be traversed starting from the root node.
Return type

GraphNode

Returns

The root node of this graph.

GraphModelInterface.GetRootPath()
Returns the path of the root node of this graph.
Usually this is an empty path, but a graph model may be a view of a nested part of an enclosing graph.
In the latter case the path points to the root node of the nested part.
Return type

NodePath

Returns

The path of the root node of this graph.

GraphModelInterface.GetSelectedNodes(callback, kind)

Retrieves all the selected ports or nodes on the graph depending on the NODE_KIND passed as argument.

Parameters
GraphModelInterface.GetSelectedPorts(callback)

Retrieves all the selected ports on the graph.

Parameters

callback (Union[[maxon.frameworks.graph.GraphNode], Callable(maxon.frameworks.graph.GraphNode)]) – This callback will receive all selected ports.

GraphModelInterface.GetSelectedTrueNodes(callback)

Retrieves all the selected nodes on the graph.

Parameters

callback (Union[[maxon.frameworks.graph.GraphNode], Callable[maxon.frameworks.graph.GraphNode]]) – This callback will receive all selected nodes.

GraphModelInterface.GetSelectedWires(callback)

Retrieves all the selected wire on the graph.

Parameters

callback (Union[[maxon.frameworks.graph.Wires], Callable(maxon.frameworks.graph.Wires)]) – This callback will receive all selected wires.

GraphModelInterface.GetTransactionCount()
GraphModelInterface.GetUserState()
GraphModelInterface.IsConnectable()
GraphModelInterface.IsPortSelected(port)

Checks if the passed Port is selected.

Parameters

port (maxon.frameworks.graph.GraphNode) – The port to check

Returns

true if this maxon.frameworks.graph.GraphNode is a port and is selected, otherwise false.

Return type

bool

GraphModelInterface.IsReadOnly()

Checks if this graph is read-only.

Note

You can’t modify read-only graphs.

Return type

bool

Returns

True if this graph is read-only otherwise False.

GraphModelInterface.IsTrueNodeSelected(node)

Checks if the passed True Node is selected.

Parameters

node (maxon.frameworks.graph.GraphNode) – The True Node to check

Returns

true if this maxon.frameworks.graph.GraphNode is a True Node and is selected, otherwise false.

Return type

bool

GraphModelInterface.IsWireSelected(src, dst)

Checks if a Wires between two port is selected. (GraphNode will be converted to nodePath)

Parameters
Returns

true if the wire is selected, otherwise false.

Return type

bool

GraphModelInterface.ListAllNodes(callback, matchingData)

Retrieves all nodes having their stored data equals the ones in the passed DataDictionary.

Parameters
GraphModelInterface.Merge(other)
Merges the other graph into this graph.
Top-level nodes and ports are added into this graph using new unique identifiers to prevent naming conflicts.
The mapping from the original identifiers of other to the new ones is returned.
Parameters

other (maxon.frameworks.graph.GraphModelRef) – Another graph to merge into this graph.

Returns

Return type

GraphModelInterface.RemovePorts()
GraphModelInterface.ResetUserState(attr)

Removes all values for the given user state attribute attr from this graph (so from all of its nodes).

Parameters

attr (maxon.InternedId) – A user state attribute

GraphModelInterface.SelectNode(node)

Selects a node or a port.

Parameters

node (maxon.frameworks.graph.GraphNode) – The node or the port that have to be selected.

GraphModelInterface.SelectPort(port)

Retrieves all the selected ports on the graph.

Parameters

port (maxon.frameworks.graph.GraphNode) – The port to select.

GraphModelInterface.SelectTrueNode(node)

Select the node passed as an argument.

Parameters

node (maxon.frameworks.graph.GraphNode) – The node to select.

GraphModelInterface.SelectWire(src, dst)

Selects the Wire between two Ports.

Parameters
GraphModelInterface.StartNewChangeList()
Starts a new change list and returns the previous one.
Afterwards this manager will log all modifications to the newly created change list.

The new change list can be obtained with GraphModelInterface.GetChangeList() or as the result of the next call to GraphModelInterface.StartNewChangeList().

The returned change list contains all modifications which have been made since the previous call to GraphModelInterface.StartNewChangeList().
You can pass it to GraphModelInterface.Apply() to undo or redo the changes.
Returns

Change list which contains the modifications since the previous call to GraphModelInterface.StartNewChangeList.

Return type

maxon.frameworks.misc.ChangeList

GraphModelInterface.Validate()
Validates the graph.

Note

This is an implementation-specific operation and should be invoked when a batch of changes has been applied to the graph and the graph should be brought into a valid state again.

For example, the implementation of maxon.frameworks.graph.GraphModelInterface for nodes may update the type of an output port of a polymorphic node based on the types of the input ports.