maxon.GraphNode¶
Description¶
A maxon.GraphNode
represents a general node (g-node for short) in the hierarchy of a maxon.GraphModelInterface
.
There are five different kinds of such a node: It may be a true node, an input or output port or an input port list or output port list.
A node may have attributes, and if it is a port, it may be connected to other ports. For a general overview, see maxon.GraphModelInterface
.
Most functions of maxon.GraphNode
can be used for all node kinds, some functions are specific for certain kinds (such as GraphNode.Connect()
which is only supported for ports).
maxon.GraphNode
holds a strong maxon.GraphModelRef
reference on the graph, see GraphNode.GetGraph()
.
The node within the graph is referenced symbolically by a maxon.NodePath
, see GraphNode.GetPath()
.
Therefore it is guaranteed for the referenced graph that it exists as long as the maxon.GraphNode
, but not for the referenced node.
Namely, a maxon.GraphNode
can be in one of three states:
It may be a null value, then it doesn’t represent any node.
GraphNode.IsNull()
returns true in this state.It may be a valid node in a graph (
GraphNode.IsValid()
returns true).GraphNode.GetGraph()
returns the graph,GraphNode.GetPath()
the path of the node, and all supported functions can be called.It represents a node which doesn’t exist any longer.
GraphNode.IsValid()
returns false, butGraphNode.IsPopulated()
still returns true. AlsoGraphNode.GetGraph()
andGraphNode.GetPath()
return valid values, but you can’t call any functions which would require access to the node. Such a state can be used to identify deleted nodes. A transition between the cases 2 and 3 can happen without thismaxon.GraphNode
being directly involved, namely when the graph is modified through anothermaxon.GraphNode
and a node with the path of thismaxon.GraphNode
is added or removed.
Methods Signature¶
|
Adds a port to this node with the given id.
|
|
Adds a number of variadic port instances to this variadic port.
|
|
|
|
Sets a part of the value of #attr to #value for this node. |
|
Connect this node with another node port. |
|
Copies all connections of source to the port given by this
maxon.GraphNode . |
|
Copies all directly set attribute values of source to this node.
|
|
Finds the child of this node whose kind matches the given mask.
|
|
Finds the inner child of this node with the given relative path. |
|
Returns the closest ancestor node of this node (possibly this node itself) whose kind matches the given mask.
|
|
Reports all attribute modifications which have been made for this node since the given stamp to the receiver.
|
|
Returns the modification stamp of the given attribute for this node.
|
|
Gets all children of this node.
|
|
Returns the modification stamp of incoming/outgoing connections for this port.
|
|
Gets the value of the given attribute for the connection from this port to target.
|
|
Gets all attribute values of the connection from this port to target. |
|
Yields all connections of this port for the given direction dir.
|
Returns the constant value of this port.
|
|
Returns the default value of this port.
|
|
|
Returns the graph to which this node belongs. |
Returns the hash code of |
|
|
Returns the identifier of this node.
|
|
Yields all inner nodes of this node matching #mask in pre-order. |
Returns the input port list of this node.
|
|
|
Returns the kind of this node.
|
|
Returns the message flags of the given attribute at this node.
|
|
Yields the error or warning messages (if any) of the given attribute at this node to receiver. |
Returns the output port list of this node.
|
|
Returns the parent of this node. |
|
|
Returns the path of this node.
|
|
Returns the input or output port list of this node, depending on dir. |
|
Gets the current value of the given attribute for this node, REGARDLESS of whether it is valid or not.
|
|
Gets the value of the given attribute attr for this node.
|
|
Gets all attribute values of this node. |
|
Returns the Wires from this node to #target.
|
|
Restores the inherited state of the value for attr.
|
|
Checks if this
maxon.GraphNode belongs to an inner node of the graph. |
Checks whether this
maxon.GraphNode has graph and path references. |
|
|
Checks whether this GraphNode points to a valid node.
|
|
Removes this node from the graph.
|
|
Removes all connections of this port in the given direction which match the given mask. |
|
Removes a number of variadic port instances from this variadic port.
|
|
Removes an attribute value from this node.
|
|
Resets this
maxon.GraphNode to the state it has right after default construction. |
|
Sets the value of attr to value for the connection from this port to target.
|
|
Sets the value of the attribute
maxon.DESCRIPTION.DATA.BASE.DEFAULTVALUE (maxon.Id(“default”)) to value for this port. |
|
Sets the value of attr to value for this node. |
|
Marks the value of attr as modified without actually modifying it.
|
|
Checks if two nodes are representing the same node in a graph. |
|
Initializes a node from a graph. |
|
Checks if two nodes are not representing the same node in a graph. |
Methods Definition¶
-
GraphNode.
AddPort
(name)¶ - Adds a port to this node with the given id.This node has to be a port list or a port itself.
- Parameters
name (Union[str,
maxon.String
,maxon.Id
]) – The identifier for the new port.- Returns
The added port.
- Return type
-
GraphNode.
AddPorts
(index, count)¶ - Adds a number of variadic port instances to this variadic port.This is more efficient than a repeated call to
GraphNode.AddPort()
.Warning
It is an error if this GraphNode is no variadic port.
- Parameters
index (int) – The index within the current list of variadic port instances where the new instances shall be added.
count (int) – The number of instances to add.
- Returns
The newly added port instances as an array.
- Return type
-
GraphNode.
BeginTransactionImpl
(userData=None)¶
-
GraphNode.
ChangeValue
(attr, op, path, value)¶ Sets a part of the value of #attr to #value for this node.
- Parameters
attr (Union[str,
maxon.String
,maxon.Id
,maxon.InternedId
]) – The attribute whose value shall be set.op (
maxon.SubDataOperation
) – The SubDataOperation to use.path (
maxon.SubDataPathBlock
) – The path to the part of the attribute value which shall be changed.value (
maxon.Data
) – The new value for the part.
-
GraphNode.
Connect
(target, *args, **kwargs)¶ Connect this node with another node port.
Only one of this calls is allowed: - Connect(target, modes=WIRE_MODE.NORMAL, reverse=False) - Connect(target, portId)
- Parameters
target (
maxon.GraphNode
) – The node to connect tomodes (Union[
maxon.Wires
,maxon.WIRE_MODE
]) – The type to use for the connection.reverse (bool) – If true the direction is reversed (from target to this port).
portId (Union[
maxon.InternedId
,maxon.Id
]) – The port’s id to be found.
-
GraphNode.
CopyConnectionsFrom
(source, direction, includeInner)¶ - Copies all connections of source to the port given by this
maxon.GraphNode
.For each connection of source to a port in the given direction, a corresponding port in this graph is searched (based on the relative path) and, if it exists, a connection to that port is created.- Parameters
source (
maxon.GraphNode
) – Anothermaxon.GraphNode
port, may stem from a different graph.direction (
maxon.PORT_DIR
) – The direction of connections to copy.includeInner (bool) – If True, copies connections for all inner nodes, too.
-
GraphNode.
CopyValuesFrom
(source, includeInner)¶ - Copies all directly set attribute values of source to this node.This excludes derived attribute values as well as attribute values which are inherited from a base.
- Parameters
source (
maxon.GraphNode
) – Anothermaxon.GraphNode
, may stem from a different graph.includeInner (bool) – If True, copies attribute values for all inner nodes, too.
-
GraphNode.
FindChild
(idOrNodeKind)¶ - Finds the child of this node whose kind matches the given mask.If no such child can be found, a null node is returned.If there is more than one matching child, an error is returned.
- Parameters
idOrNodeKind (Union[str,
maxon.String
,maxon.InternedId
,maxon.Id
]) – A particual Id of a node or mask kind to look for.- Returns
A direct child of this node which matches the given mask, or a null node if no such child exists.
- Return type
-
GraphNode.
FindInnerNode
(relativePath)¶ Finds the inner child of this node with the given relative path.
Note
If no such child can be found, a null node is returned.
- Parameters
relativePath (Union[
maxon.NodePath
, str]) – The relative path of the child to find, starting at this node.- Returns
The inner child of this node with the given relativePath, or a null node if no such child exists.
- Return type
-
GraphNode.
GetAncestor
(mask)¶ - Returns the closest ancestor node of this node (possibly this node itself) whose kind matches the given mask.i.e., the function goes upwards in the hierarchy until it finds a matching node.
- Parameters
mask (
maxon.NODE_KIND
) – Mask for the kind of node to look for.- Returns
Closest ancestor of this node matching the given mask, may be this node itself or a null node.
- Return type
-
GraphNode.
GetAttributeModificationsSince
(stamp, receiver)¶ - Reports all attribute modifications which have been made for this node since the given stamp to the receiver.Only stored attributes will be reported, so to also check for new values of computed attributes you should use
GraphAttributeInterface.IsComputedFrom()
.- Parameters
stamp (
maxon.TimeStamp
) – A reference time stamp. Only modifications newer than this stamp are reported.receiver (Callable[[
maxon.InternedId
,maxon.Data
], bool]) – Modifications are reported to this receiver as a pair of the attribute identifier and the current value.
- Returns
False if the receiver cancelled further evaluation, True otherwise.
- Return type
bool
-
GraphNode.
GetAttributeStamp
(attr)¶ - Returns the modification stamp of the given attribute for this node.This is the value of the graph’s time stamp (see
GraphModelInterface.GetModificationStamp()
) at the time when the attribute value has been set last for this node, or a null value if it hasn’t been set at all.- Parameters
attr (Union[str,
maxon.String
,maxon.InternedId
]) – An attribute.- Returns
The modification stamp of the last change of the attribute value.
- Return type
maxon.TimeStamp
-
GraphNode.
GetChildren
(callback=None, mask=31)¶ - Gets all children of this node.For a true node this will be its child nodes as well as a single input port list and a single output port list.Otherwise, the children are ports.
- Parameters
callback (Union[None, list, Callable[[
maxon.GraphNode
], bool]]) – This callback will receive all children.mask (
maxon.NODE_KIND
) – Mask to filter the kind of node to look for.
- Returns
If callback is None or a list then a list of
maxon.GraphNode
otherwise False if callback cancelled further evaluation, True otherwise.- Return type
Union[list[
maxon.GraphNode
], bool]
-
GraphNode.
GetConnectionStamp
(direction)¶ - Returns the modification stamp of incoming/outgoing connections for this port.This is the value of the graph’s time stamp (see
GraphModelInterface.GetModificationStamp()
) at the time when connections in the given direction have been modified last for this port.- Parameters
direction (
maxon.PORT_DIR
) – The connection direction.- Returns
The modification stamp of the last connection change of the port.
- Return type
maxon.TimeStamp
-
GraphNode.
GetConnectionValue
(target, position, attr, expectedType=None, reverse=False)¶ - Gets the value of the given attribute for the connection from this port to target.If there is no such connection, the connection has no value for the attribute or the value doesn’t have the expected type, an empty
maxon.Data
is returned.- Parameters
target (
maxon.GraphNode
) – The other end of the connection.position (
maxon.CONNECTION_POSITION
) – The connection position at which the attribute’s value shall be obtained.attr (
maxon.InternedId
) – The attribute whose value shall be obtained.expectedType (
maxon.DataType
) – The expected type of the attribute value, may be nullptr if no check shall be done.reverse (bool) – True if the connection shall be from target to this port (also position is reversed in this case), False otherwise (the default).
- Returns
The attribute value of the connection, or a null
maxon.Data
.- Return type
-
GraphNode.
GetConnectionValues
(target, receiver)¶ Gets all attribute values of the connection from this port to target.
- Parameters
target – The other end of the connection.
receiver (Callable[[
maxon.CONNECTION_POSITION
,maxon.InternedId
,maxon.Data
], bool]) – All attribute values of the connection will be reported to the receiver.
- Returns
False if receiver cancelled further evaluation, True otherwise.
- Return type
bool
-
GraphNode.
GetConnections
(pDir, conns=None, mask=Wires - Value:63, Event:63, Dependency:63, Context:63, Hidden:63, Inhibit:63, Slink:63, Tlink:63, mode=1)¶ - Yields all connections of this port for the given direction dir.Depending on the graph model implementation, this may include implicit wires due to connections between enclosing ports.The latter are marked with
maxon.WIRE_MODE.IMPLICIT
.- Parameters
pDir (
maxon.PORT_DIR
) – Whether to yield incoming or outgoing connections.conns (Union[None, list, Callable[[
maxon.GraphNode
,maxon.Wires
], bool]]) – The receiver for the found connections.mask (
maxon.Wires
) – Only yield connections whose wires match this mask.mode (
maxon.WIRE_MODE
) – Mode for GetConnections.
- Returns
A list if conns is None or a list otherwise False if conns cancelled further evaluation, True otherwise.
- Return type
Union[list[tuple[
maxon.GraphNode
,maxon.Wires
]], bool]
-
GraphNode.
GetConstantValue
()¶ - Returns the constant value of this port.The constant value is set whenever the graph implementation is able to determine a constant value for the port, either because the default value has been set directly at the port, or because it is possible to compute the value from connected ports and nodes.
- Returns
The default value of this port.
- Returns
-
GraphNode.
GetDefaultValue
()¶ - Returns the default value of this port.This is the value of the DefaultValue attribute,which in turn is synthesized from
maxon.DESCRIPTION.DATA.BASE.DEFAULTVALUE
: (maxon.Id(“default”))Default values are derived from right to left along connections.- Returns
The default value of this port.
- Returns
-
GraphNode.
GetGraph
()¶ Returns the graph to which this node belongs.
- Returns
Owning graph of this node.
- Return type
-
GraphNode.
GetHashCode
()¶ Returns the hash code of
maxon.GraphNode
.- Returns
Hash code.
- Return type
int
-
GraphNode.
GetId
()¶ - Returns the identifier of this node.This is the last part of the
GraphNode.GetPath()
“path”, so it’s unique within the siblings of this node, but not within the whole graph.- Returns
Identifier of this node.
- Return type
-
GraphNode.
GetInnerNodes
(mask, includeThis, receiver=None)¶ Yields all inner nodes of this node matching #mask in pre-order. The recursive traversal stops at nodes which don’t match mask.
- Parameters
mask (
maxon.NODE_KIND
) –Mask to filter the tree traversal.Only nodes matching this mask are considered.The node on which GetInnerNodes is called isn’t checked for mask.includeThis (bool) – If True, the node on which GetInnerNodes is called is yielded to receiver too.
receiver (Union[Callable[[
maxon.GraphNode
], bool], list, None]) – Inner nodes are reported to this value receiver.
- Returns
- If None or a list, a list with all the inner
maxon.GraphNode
False* if receiver cancelled further evaluation, True otherwise. - Return type
Union[list[
maxon.GraphNode
], bool]
-
GraphNode.
GetInputs
()¶ - Returns the input port list of this node.All top-level input ports of a node can be found as children of its input port list.
- Returns
Input port list of this node.
- Return type
-
GraphNode.
GetKind
()¶ - Returns the kind of this node.This can be used to check whether this node is a true node, a port or a port list, see
maxon.NODE_KIND
andmaxon.GraphModelInterface
.- Returns
-
GraphNode.
GetMessageFlags
(attr)¶ - Returns the message flags of the given attribute at this node.You have to call this method if you want to check if an attribute has a message (an error or a warning) for this node.
- Parameters
attr (Union[str,
maxon.String
,maxon.Id
,maxon.InternedId
]) – The attribute which shall be asked.- Returns
Message flags (GraphAttribute.FLAGS.WARNING, GraphAttribute.FLAGS.ERROR) of attr at this node.
- Return type
maxon.GraphAttribute.FLAGS
-
GraphNode.
GetMessages
(attr, receiver)¶ Yields the error or warning messages (if any) of the given attribute at this node to receiver.
- Parameters
attr (Union[str,
maxon.String
,maxon.Id
,maxon.InternedId
]) – The attribute which shall be asked.receiver (Callable[[
maxon.GraphMessage
], bool]) – All messages are reported to this receiver.
- Returns
False if the receiver cancelled further evaluation, True otherwise.
- Return type
bool
-
GraphNode.
GetOutputs
()¶ - Returns the output port list of this node.All top-level output ports of a node can be found as children of its output port list.
- Returns
Output port list of this node.
- Return type
-
GraphNode.
GetParent
()¶ Returns the parent of this node.
- Returns
Parent node of this node, or a null node if this node is the root node.
- Return type
-
GraphNode.
GetPath
()¶ - Returns the path of this node.
Note
It is not guaranteed that a node with that path still exists in the graph, to check this use
NodePath.IsValid()
.- Returns
Path of this node.
- Return type
-
GraphNode.
GetPortList
(dir)¶ Returns the input or output port list of this node, depending on dir.
- Parameters
dir (
maxon.PORT_DIR.INPUT
ormaxon.PORT_DIR.OUTPUT
.) – PORT_DIR.INPUT to return the input port list, PORT_DIR.OUTPUT to return the output port list.- Returns
Port list of this node.
- Return type
-
GraphNode.
GetStoredValue
(attr, expectedType=None)¶ - Gets the current value of the given attribute for this node, REGARDLESS of whether it is valid or not.If using lazy updates then this may be out of date.If NOT using lazy updates then this should always match GetValue().If this node doesn’t have a value for the attribute of the correct type, an empty Opt is returned.
- Parameters
attr (Union[str,
maxon.String
,maxon.Id
,maxon.InternedId
]) – The attribute whose value shall be obtained.expectedType (
maxon.DataType
) – The expected type of the attribute value, may be None if no check shall be done.
- Returns
The attribute value of this node.
- Return type
-
GraphNode.
GetValue
(attr, expectedType=None)¶ - Gets the value of the given attribute attr for this node.If this node doesn’t have a value for the attribute of the correct type, an empty
maxon.Data
is returned.- Parameters
attr (Union[str,
maxon.String
,maxon.Id
,maxon.InternedId
]) – The attribute whose value shall be obtained.expectedType (
maxon.DataType
) – The expected type of the attribute value, may be None if no check shall be done.
- Returns
The attribute value of this node
- Return type
-
GraphNode.
GetValues
(mask, graphAttrMap)¶ Gets all attribute values of this node.
- Parameters
mask (
maxon.GraphAttributeInterface.FLAGS
) – All attribute values of this node will be added to map.graphAttrMap (
maxon.HashMap
[maxon.InternedId
,maxon.Data
]) –
-
GraphNode.
GetWires
(target)¶ - Returns the Wires from this node to #target.Depending on the graph model implementation, this may include implicit wires due to connections between enclosing nodes.The latter are marked with
maxon.WIRE_MODE.IMPLICIT
.- Parameters
target (
maxon.GraphNode
) – Another graph node.- Returns
Wires between from this node to target.
- Return type
-
GraphNode.
InheritValue
(attr)¶ - Restores the inherited state of the value for attr.This removes any value which has been set directly in this graph.
- Parameters
attr (Union[str,
maxon.String
,maxon.Id
,maxon.InternedId
]) – The attribute whose value shall be removed from this node.- Returns
True if the value has been inherited.
- Return type
bool
-
GraphNode.
IsInner
()¶ - Checks if this
maxon.GraphNode
belongs to an inner node of the graph.The root node and its port lists and ports aren’t inner nodes, all other nodes are.- Returns
True if this
maxon.GraphNode
is an inner node of the graph.- Return type
bool
-
GraphNode.
IsPopulated
()¶ - Checks whether this
maxon.GraphNode
has graph and path references.This is not the same asGraphNode.IsValid()
, becauseGraphNode.IsPopulated()
just checks if graph and path are set, but not if the graph really contains a node with the path, seeGraphNode.IsValid()
.Therefore we also don’t have anGraphNode.IsEmpty()
counterpart, because it would hide that there are two different functions to check the content of amaxon.GraphNode
.- Returns
True if this GraphNode has graph and path set, False otherwise.
- Return type
bool
-
GraphNode.
IsValid
()¶ - Checks whether this GraphNode points to a valid node.This is not the same as
GraphNode.IsPopulated()
:GraphNode.IsValid()
return true if the node is a valid, existing node in the graph.GraphNode.IsPopulated()
also returns true for graph nodes which point to non-existing (deleted) nodes.They have a valid graph and path to identify the node, but you can’t call any functionwhich would require access to the node.
- Returns
- True if this
maxon.GraphNode
points to a valid node,False if it is a null node or a reference to a deleted node. - Return type
bool
-
GraphNode.
Remove
()¶ - Removes this node from the graph.This will also remove all nested nodes as well as connections of this node and its nested ports.
-
GraphNode.
RemoveConnections
(pDir, mask)¶ Removes all connections of this port in the given direction which match the given mask.
- Parameters
pDir (
maxon.PORT_DIR
) – Connection direction.mask (
maxon.Wires
) – Mask for the connections to remove.
-
GraphNode.
RemovePorts
(ports)¶ - Removes a number of variadic port instances from this variadic port.This is more efficient than a repeated call to
GraphNode.Remove()
on each of the instances.Warning
It is an error if this GraphNode is no variadic port.
- Parameters
ports (Union[list[str,
maxon.InternedId
]]) – The identifiers of the port instances which shall be removed.- Returns
-
GraphNode.
RemoveValue
(attr)¶ - Removes an attribute value from this node.Nothing happens if this node doesn’t have a value for the given attribute.
- Parameters
attr (Union[str,
maxon.String
,maxon.Id
,maxon.InternedId
]) – The attribute whose value shall be removed from this node.- Returns
True if the value has been changed.
- Return type
bool
-
GraphNode.
Reset
()¶ - Resets this
maxon.GraphNode
to the state it has right after default construction.This includes freeing all resources held by thismaxon.GraphNode
.
-
GraphNode.
SetConnectionValue
(target, position, attr, value)¶ - Sets the value of attr to value for the connection from this port to target.This will override any previously existing value.
- Parameters
target (
maxon.GraphNode
) – The other end of the connection.position (
maxon.CONNECTION_POSITION
) – The connection position at which the attribute’s value shall be set.attr (
maxon.InternedId
) – The attribute whose value shall be set.value (
maxon.Data
) – The value for the attribute.
- Returns
True if the value has been changed.
- Return type
bool
-
GraphNode.
SetDefaultValue
(value)¶ - Sets the value of the attribute
maxon.DESCRIPTION.DATA.BASE.DEFAULTVALUE
(maxon.Id(“default”)) to value for this port.This will override any values which would otherwise be inherited from a base port.- Parameters
value (
maxon.Data
) – The value for the DefaultValue attribute.- Returns
True if the value has been changed.
- Return type
bool
-
GraphNode.
SetValue
(attr, value, checkAndInvalidate=True)¶ Sets the value of attr to value for this node.
Note
This will override any previously existing value.
- Parameters
attr (Union[str,
maxon.String
,maxon.Id
,maxon.InternedId
]) – The attribute whose value shall be set.value (
maxon.Data
) – The value for the attribute.checkAndInvalidate (bool) – Validate the node once the value is set.
- Returns
True if the value has been changed.
- Return type
bool
-
GraphNode.
TouchValue
(attr)¶ - Marks the value of attr as modified without actually modifying it.Use this if the value points to some external data which has changed without knowledge of the graph (for example a
maxon.Url
for a file which has been modified).If there is no value yet for attr, an IllegalStateError is returned.- Parameters
attr (Union[str,
maxon.String
,maxon.Id
,maxon.InternedId
]) – The attribute whose value shall be set.
-
GraphNode.
__eq__
(other)¶ Checks if two nodes are representing the same node in a graph.
- Parameters
other (
maxon.GraphNode
) – The other node.- Return type
bool
- Returns
True if both node are equal.
-
GraphNode.
__init__
(src=None)¶ Initializes a node from a graph.
- Parameters
src (Optional[
maxon.GraphNode
]) – Another node to re-use.
-
GraphNode.
__ne__
(other)¶ Checks if two nodes are not representing the same node in a graph.
- Parameters
other (
maxon.GraphNode
) – The other node.- Return type
bool
- Returns
True if both node are not equal.