#include <graph.h>
Detailed Description
GraphModelInterface is an abstraction of a hierarchical graph. A GraphModelInterface has a single root node (see GetRoot()). The root node and any other node may have an arbitrary number of child nodes. Also each node may have a number of input ports and output ports, and those ports may have nested ports, too. So 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)
- PortA (NODE_KIND::INPORT)
- Outputs (NODE_KIND::OUTPUTS)
- PortD (NODE_KIND::OUTPORT)
- Inputs (NODE_KIND::INPUTS)
- Inputs (NODE_KIND::INPUTS)
- PortE (NODE_KIND::INPORT)
- Outputs (NODE_KIND::OUTPUTS)
- PortF (NODE_KIND::OUTPORT)
- PortG (NODE_KIND::OUTPORT)
- PortF (NODE_KIND::OUTPORT)
- N2 (NODE_KIND::NODE)
- N3 (NODE_KIND::NODE)
- Inputs (NODE_KIND::INPUTS)
- PortH (NODE_KIND::INPORT)
- Outputs (NODE_KIND::OUTPUTS)
- PortI (NODE_KIND::OUTPORT)
- Inputs (NODE_KIND::INPUTS)
- N1 (NODE_KIND::NODE)
In fact, GraphModelInterface represents nodes and ports by the same class GraphNode. To distinguish between the different kinds of a GraphNode, a value of type NODE_KIND is returned by GraphNode::GetKind(). The example tree shows the possible kinds in parentheses:
- NODE_KIND::NODE stands for true nodes.
- NODE_KIND::INPUTS/NODE_KINDOUTPUTS represent the lists of top-level input/output ports of a node.
- NODE_KIND::INPORT/NODE_KINDOUTPORT represent input/output ports.
It is not required for an implementation of 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 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. This is an example graph which shows all four cases: @graph +-Root-------------------------------------—+ | ,-------------—> p o | +-N------—+ / | | | p o -* | o x --> o x —> x o \ +-M--—+ | o y --> o y —> y o `--> o p q o --> q o | +--------—+ +----—+ | +------------------------------------------—+ @endgraph
Each node may have attributes. An attribute is identified by an InternedId, typically this id is defined together with the type of the attribute value by MAXON_ATTRIBUTE.
Public Types | |
| enum class | GET_CONNECTIONS_MODE { NONE , CONNECTIONS , INDUCED_DEPENDENCIES , DERIVATION_FILTER , EXTERNAL_CONNECTIONS , WITHOUT_INHIBITED , INCLUDE_HIDDEN , INTERNAL_CONNECTIONS , SKIP_REROUTER } |
| enum class | MODIFIED { NONE , COMPLETE , DIRECT_ATTRIBUTE , DIRECT_META_ATTRIBUTE , INHERITED_ATTRIBUTE , SYNTHESIZED_ATTRIBUTE , USER_STATE_ATTRIBUTE , NODE_ADDED , CHILD_REMOVED , INPUT_CONNECTION , OUTPUT_CONNECTION , SPECIAL0 , SPECIAL1 , SPECIAL_NAME , ALL_MASK , DERIVED_ATTRIBUTE_MASK , DIRECT_ATTRIBUTE_MASK , DATA_ATTRIBUTE_MASK , ATTRIBUTE_MASK , CONNECTION_MASK , NODE_MASK , STRUCTURE_MASK } |
Private Member Functions | |
| MAXON_INTERFACE (GraphModelInterface, MAXON_REFERENCE_NORMAL, "net.maxon.graph.interface.graphmodel", MAXON_IMPLEMENTATION_MODULE("net.maxon.nodes")) | |
Friends | |
| class | GraphNode |
| class | GraphTransaction |
| template<typename BASE > | |
| class | GraphNodeFunctions |
Member Enumeration Documentation
◆ GET_CONNECTIONS_MODE
|
strong |
This enum is needed for GraphNode::GetConnections to control which connections shall be reported. At least one of CONNECTIONS or INDUCED_DEPENDENCIES has to be set.
| Enumerator | |
|---|---|
| NONE | No flags. |
| CONNECTIONS | Report normal connections, the default. |
| INDUCED_DEPENDENCIES | Report induced dependencies (due to loop dependencies or sequencing). |
| DERIVATION_FILTER | Apply the derivation filter. |
| EXTERNAL_CONNECTIONS | Only report connections which leave the node to which the port belongs (so they are external to the node). |
| WITHOUT_INHIBITED | Don't report inhibited connections (those where Wires::inhibit is present). |
| INCLUDE_HIDDEN | Report connections where the hidden flag is set or which go to hidden ports. |
| INTERNAL_CONNECTIONS | Only report connections which don't leave the node to which the port belongs (so they are internal to the node). |
| SKIP_REROUTER | Hop over rerouter nodes. |
◆ MODIFIED
|
strong |
These flags are reported by GetModificationsSince() to tell which properties of the node have changed.
| Enumerator | |
|---|---|
| NONE | No flag. |
| COMPLETE | The graph has changed completely. This is only reported for the root node. |
| DIRECT_ATTRIBUTE | Direct non-meta attributes of the node have changed. |
| DIRECT_META_ATTRIBUTE | Direct meta attributes of the node have changed (see GraphAttributeInterface::FLAGS::META). |
| INHERITED_ATTRIBUTE | Inherited attributes (derived from left to right) of the node have changed. |
| SYNTHESIZED_ATTRIBUTE | Synthesized attributes (derived from right to left) of the node have changed. |
| USER_STATE_ATTRIBUTE | User state attributes of the node have changed (see GraphAttributeInterface::FLAGS::USER_STATE). |
| NODE_ADDED | The node has been added. |
| CHILD_REMOVED | Children of the node have been removed. |
| INPUT_CONNECTION | Input connections of the port have changed. |
| OUTPUT_CONNECTION | Output connections of the port have changed. |
| SPECIAL0 | This is set to indicate a special change, the exact meaning is graph-specific. |
| SPECIAL1 | This is set to indicate a special change, the exact meaning is graph-specific. |
| SPECIAL_NAME | This is set to indicate a change which affects names of nodes or ports. |
| ALL_MASK | A mask containing all possible MODIFIED bits. |
| DERIVED_ATTRIBUTE_MASK | Derived attributes of the node have changed. |
| DIRECT_ATTRIBUTE_MASK | Mask to test for changes to direct attributes (whether meta or non-meta). |
| DATA_ATTRIBUTE_MASK | Mask to test for changes to attributes belonging to the data model of the graph (non-meta, non-user-state attributes). |
| ATTRIBUTE_MASK | Mask to test for attribute changes. |
| CONNECTION_MASK | Mask to test for connection changes of ports. |
| NODE_MASK | Mask to test for added or removed nodes. |
| STRUCTURE_MASK | Mask to test for any structural change (changed connections, added or removed nodes). |
Member Function Documentation
◆ MAXON_INTERFACE()
|
private |
◆ MAXON_ENUM_FLAGS_CLASS() [1/2]
| enum maxon::GraphModelInterface::GET_CONNECTIONS_MODE MAXON_ENUM_FLAGS_CLASS | ( | GET_CONNECTIONS_MODE | ) |
◆ GetRootPath()
| MAXON_METHOD const NodePath& GetRootPath | ( | ) |
Returns the current view path of the model. This can be an empty path, meaning the model is currently editing or viewing the root of the graph. Or it can be a path to a node in the graph which an editor currently uses to show the content of the node at this path. Deprecated. Use GetViewRootPath() instead.
- Returns
- The view root path of this model.
◆ GetRoot()
| MAXON_METHOD GraphNode GetRoot | ( | ) |
Returns the node at GetViewRootPath.
- See also
- GetViewRootPath. Deprecated. Use GetViewRoot() instead.
- Returns
- The view root node of this model.
◆ IsReadOnly()
| MAXON_METHOD Bool IsReadOnly | ( | ) |
Checks if this graph is read-only. You can't modify read-only graphs.
- Returns
- true if this graph is read-only, otherwise false.
◆ GetNode() [1/2]
| MAXON_METHOD GraphNode GetNode | ( | const NodePath & | path, |
| Bool | filtered = true |
||
| ) |
Returns the GraphNode corresponding to path. If no such node exists in the graph, an empty node is returned.
- Parameters
-
[in] path 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. [in] 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 GraphNode even for paths which don't belong to this graph, but e.g. to nested graphs which are hidden by the filter settings.
- Returns
- The GraphNode corresponding to the path. This is empty when there is no such node in the graph.
◆ GetNode() [2/2]
| MAXON_METHOD Result<GraphNode> GetNode | ( | const PathBlock & | path, |
| Bool | filtered = true |
||
| ) |
Returns the GraphNode corresponding to path. If no such node exists in the graph, an empty node is returned.
- Parameters
-
[in] path 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. [in] 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 GraphNode even for paths which don't belong to this graph, but e.g. to nested graphs which are hidden by the filter settings.
- Returns
- The GraphNode corresponding to the path. This is empty when there is no such node in the graph.
◆ Validate()
| MAXON_METHOD Result<void> Validate | ( | ) |
Validates the graph. 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 GraphModelInterface for nodes may update the type of an output port of a polymorphic node based on the types of the input ports.
◆ ResetUserState()
| MAXON_METHOD void ResetUserState | ( | const InternedId & | attr | ) |
Removes all values for the given user state attribute attr from this graph (so from all of its nodes).
- Parameters
-
[in] attr A user state attribute.
◆ GetGraphAttribute()
| MAXON_METHOD const GraphAttribute& GetGraphAttribute | ( | const InternedId & | attr | ) |
Returns the 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 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 GraphAttribute).
- Parameters
-
[in] attr The identifier of the attribute.
- Returns
- The corresponding GraphAttribute, or a null reference if the graph model has no GraphAttribute for attr.
- See also
- GetGraphAttributeFlags
◆ GetGraphAttributeFlags()
| MAXON_METHOD GraphAttribute::FLAGS GetGraphAttributeFlags | ( | const InternedId & | attr | ) |
Returns the GraphAttribute::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
-
[in] attr The identifier of the attribute.
- Returns
- The flags which this graph model uses for the attribute.
- See also
- GetGraphAttribute @MAXON_ANNOTATION{default=GraphAttributeInterface::FLAGS::DIRECT}
◆ BeginTransaction()
| MAXON_FUNCTION Result<GraphTransaction> BeginTransaction | ( | const DataDictionary & | userData = GetPtrSizedZeroRef< DataDictionary >() | ) |
Begins a new transaction within which modifications can be made. You have to do this 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 GraphModelInterface::ObservableTransactionStarted informs its observers about the start of a transaction.
- Parameters
-
[in] userData 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 GraphTransaction object to commit or rollback the transaction at a later point of time.
◆ GetTransactionCount()
| MAXON_METHOD Int GetTransactionCount | ( | ) |
Returns the number of active transactions. Transactions can be nested, so the transaction count is the current nesting depth.
- Returns
- Number of active transactions, 0 if there's no active transaction at all.
◆ AddChild()
| MAXON_METHOD Result<GraphNode> AddChild | ( | const Id & | childId, |
| const Id & | nodeId, | ||
| const DataDictionary & | args = DataDictionary::DefaultValue() |
||
| ) |
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 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
-
[in] childId Identifier for the child node (if empty, a UUID is chosen). [in] nodeId Identifier for the type of the node to add. How this is resolved to an actual node type is model-specific. [in] args Arguments to use for the node creation. The exact meaning is model-specific.
- Returns
- A GraphNode referencing the added child.
◆ MAXON_OBSERVABLE() [1/3]
| MAXON_OBSERVABLE | ( | void | , |
| ObservableTransactionStarted | , | ||
| (const GraphModelRef &graph, const DataDictionary &userData) | , | ||
| ObservableCombinerRunAllComponent | |||
| ) |
Informs about the start of a transaction. This is called during BeginTransaction(), but only for outmost transactions (which aren't nested within other transactions).
- Parameters
-
[in] graph The graph at which the observer was registered. [in] userData The user data given to GraphModelRef::BeginTransaction(). In case of nested transactions, this is the user data of the outmost (i.e. first) invocation.
◆ MAXON_OBSERVABLE() [2/3]
| MAXON_OBSERVABLE | ( | void | , |
| ObservableTransactionCommitted | , | ||
| (const GraphModelRef &graph, const DataDictionary &userData) | , | ||
| ObservableCombinerRunAllComponent | |||
| ) |
Informs about the commit of a transaction. This is called during GraphTransaction::Commit(), but only for outmost transactions (which aren't nested within other transactions).
- Parameters
-
[in] graph The graph at which the observer was registered. [in] userData The user data given to GraphTransaction::Commit(). In case of nested transactions, this is the merger of the user datas given to all commits.
◆ MAXON_OBSERVABLE() [3/3]
| MAXON_OBSERVABLE | ( | void | , |
| ObservableTransactionRolledBack | , | ||
| (const GraphModelRef &graph) | , | ||
| ObservableCombinerRunAllComponent | |||
| ) |
Informs about the rollback of a transaction. This is called during GraphTransaction::Rollback(), but only for outmost transactions (which aren't nested within other transactions).
- Parameters
-
[in] graph The graph at which the observer was registered.
◆ GetModificationStamp()
| MAXON_METHOD TimeStamp 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 GetModificationsSince and GraphNodeFunctions::GetAttributeModificationsSince to get all modifications which have happened since then.
- Returns
- Modification time stamp of the graph.
◆ MAXON_ENUM_FLAGS_CLASS() [2/2]
| enum maxon::GraphModelInterface::MODIFIED MAXON_ENUM_FLAGS_CLASS | ( | MODIFIED | ) |
◆ GetModificationsSince() [1/2]
| MAXON_METHOD Result<Bool> GetModificationsSince | ( | TimeStamp | stamp, |
| const ValueReceiver< const GraphNode &, MODIFIED > & | receiver, | ||
| Bool | filtered = true |
||
| ) |
Reports all modifications which have been made since the given stamp to the receiver. A typical usage is
- Parameters
-
[in] stamp A reference time stamp. Only modifications newer than this stamp are reported. [in] receiver Modifications are reported to this receiver. [in] filtered With the default value of true the filter settings (if any) of this graph will be used, so modifications to nodes which don't pass the filter aren't reported.
- Returns
- false if the receiver cancelled further evaluation, true otherwise.
◆ GetModificationsSince() [2/2]
| MAXON_METHOD MODIFIED GetModificationsSince | ( | TimeStamp | stamp | ) |
Returns flags which tell which kinds of changes have happened since the given time stamp. From the returned value you can't tell exactly which nodes or ports are affected, but you can tell for example if only attributes have changed or also the structure.
- Parameters
-
[in] stamp A reference time stamp. Only modifications newer than this stamp are reported.
- Returns
- Combination of flags to indicate the kinds of changes that have happened.
◆ GetChangeList()
| MAXON_METHOD const ChangeList& 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 StartNewChangeList() once. The change list can be used to undo or redo the changes or even to apply them to a different graph, see Apply().
- Returns
- Current change list, may be a null reference.
◆ StartNewChangeList()
| MAXON_METHOD Result<ChangeList> StartNewChangeList | ( | ) |
Starts a new change list and returns the previous one. Afterwards the graph will log all modifications to the newly created change list. The new change list can be obtained with GetChangeList() or as the result of the next call to StartNewChangeList(). The returned change list contains all modifications which have been made since the previous call to StartNewChangeList(). You can pass it to Apply() to undo or redo the changes or apply them to a different graph.
- Returns
- Change list which contains the modifications since the previous call to StartNewChangeList().
◆ Apply()
| MAXON_METHOD Result<ChangeList> Apply | ( | const ChangeList & | list, |
| Bool | inverse | ||
| ) |
Applies the given change list to this graph. For an undo set inverse to true, for a redo or if you want to apply the change list to a different graph use false.
- Parameters
-
[in] list Change list to apply. [in] inverse Use 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 this graph.
◆ CreateCopyOfSelection()
| MAXON_METHOD Result<GraphModelRef> CreateCopyOfSelection | ( | const Block< const GraphNode > & | selection | ) |
Returns a new graph model which is a copy of the subgraph given by the selection.
- Parameters
-
[in] selection 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.
◆ Merge()
| MAXON_METHOD Result<HomogenousTupleType<3, HashMap<InternedId, InternedId> > > Merge | ( | const GraphModelRef & | 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
-
[in] other Another graph to merge into this graph.
- Returns
- The mapping from original identifiers of other to the identifiers used for the merge:
- first contains the mapping of top-level nodes.
- second contains the mapping of top-level input ports.
- third contains the mapping of top-level output ports.
◆ Duplicate()
| MAXON_METHOD Result<HomogenousTupleType<3, HashMap<InternedId, InternedId> > > Duplicate | ( | const Block< const GraphNode > & | selection, |
| Bool | withConnections | ||
| ) |
Duplicates the subgraph given by the selection within this graph. The nodes and ports of the subgraph are added into this graph using new unique identifiers. The mapping from the original identifiers to the new ones is returned.
- Parameters
-
[in] selection A selection of nodes and ports. Nodes/ports which aren't direct children of this graph are ignored. [in] withConnections True if incoming connections shall be duplicated as well, false otherwise.
- Returns
- The mapping from original identifiers to the identifiers used for the merge:
- first contains the mapping of top-level nodes.
- second contains the mapping of top-level input ports.
- third contains the mapping of top-level output ports.
◆ GetUserState()
| MAXON_METHOD const Data* GetUserState | ( | const NodePath & | path, |
| const InternedId & | attr | ||
| ) |
◆ GetKind()
|
protected |
◆ GetPath()
|
protected |
◆ GetChildren()
|
protected |
◆ GetParent()
|
protected |
◆ GetAncestor()
|
protected |
◆ FindChild()
|
protected |
◆ FindInnerNode()
|
protected |
◆ GetInnerNodes()
|
protected |
◆ Remove()
|
protected |
◆ RemovePorts()
|
protected |
◆ AddPort()
|
protected |
◆ AddPorts()
|
protected |
◆ GetConnections()
|
protected |
◆ PrivateGetConnections()
|
protected |
◆ GetWires()
|
protected |
◆ Connect()
|
protected |
◆ RemoveConnections()
|
protected |
◆ CopyConnectionsFrom()
|
protected |
◆ GetConnectionValues()
|
protected |
◆ GetConnectionValue()
|
protected |
◆ SetConnectionValue()
|
protected |
◆ GetValues()
|
protected |
◆ GetValue()
|
protected |
◆ GetStoredValue()
|
protected |
◆ GetBaseValues()
|
protected |
◆ SetValue()
|
protected |
◆ TouchValue()
|
protected |
◆ ChangeValue()
|
protected |
◆ RemoveValue()
|
protected |
◆ InheritValue()
|
protected |
◆ CopyValuesFrom()
|
protected |
◆ GetMessageFlags()
|
protected |
◆ GetMessages()
|
protected |
◆ GetAttributeModificationsSince()
|
protected |
◆ GetAttributeStamp()
|
protected |
◆ GetConnectionStamp()
|
protected |
◆ BeginTransactionImpl()
|
protected |
◆ CommitImpl()
|
protected |
◆ RollbackImpl()
|
protected |
◆ CopyConstruct()
|
protected |
◆ Destruct()
|
protected |
◆ IsValid()
|
protected |
◆ IsSame()
|
protected |
◆ NodeToString()
|
protected |
◆ IsConnectable()
|
protected |
◆ IsRoot()
| MAXON_METHOD Bool IsRoot | ( | const GraphNode & | node | ) |
◆ GetViewRootPath()
| MAXON_FUNCTION const NodePath& GetViewRootPath | ( | ) |
Returns the current view path of the model. This can be an empty path, meaning the model is currently editing or viewing the root of the graph. Or it can be a path to a node in the graph which an editor currently uses to show the content of the node at this path.
- Returns
- The view root path of this model.
◆ GetViewRoot()
| MAXON_FUNCTION GraphNode GetViewRoot | ( | ) |
Returns the node at GetViewRootPath.
- See also
- GetViewRootPath. Deprecated. Use GetViewRoot() instead.
- Returns
- The view root node of this model.
Friends And Related Function Documentation
◆ GraphNode
|
friend |
◆ GraphTransaction
|
friend |
◆ GraphNodeFunctions
|
friend |