#include <nodesystem.h>

Inheritance diagram for MutableRoot:

[legend]

Detailed Description

MutableRoot is a subclass of MutableNode and used for root nodes of node systems with write access. Such a node is returned by NodeSystem::BeginModifications(). The difference to MutableNode is that MutableRoot allows to add children, because this is only possible at the root level, and that MutableRoot holds a strong reference on the node system. You have to ensure that this reference is the only reference during the modification.

See also: $ref usernodes_modifications

Public Member Functions
void	Reset ()

MutableRoot &	operator= (std::nullptr_t)

	MutableRoot ()=default

	~MutableRoot ()

	MutableRoot (MutableRoot &&src)

	MAXON_OPERATOR_MOVE_ASSIGNMENT (MutableRoot)

	MAXON_DISALLOW_COPY_AND_ASSIGN (MutableRoot)

Result< void >	CopyFrom (const MutableRoot &src)

Result< MutableNode >	AddChild (const Id &childId, const Result< NodeSystem > &base, Opt< ChangeList & > list={}) const

Result< MutableNode >	AddChild (const Id &childId, const Result< NodeTemplate > &templ, const TemplateArguments &args=maxon::NullValue< const TemplateArguments & >(), const AssetRepositoryRef &lookup=maxon::NullValue< const AssetRepositoryRef & >(), Opt< ChangeList & > list={}) const

Result< ChangeList >	ReplaceBase (const NodeSystem &base, Opt< ChangeList & > list={}) const

Result< ChangeList >	ReplaceChild (const InternedId &childId, const NodeSystem &base, Opt< ChangeList & > list={}) const

Result< MutableNode >	MoveToGroup (MutableRoot &groupRoot, const Id &groupId, const Block< const InternedId > &selection, Opt< ChangeList & > list={}) const

Result< HomogenousTupleType< 3, HashMap< InternedId, InternedId > > >	Merge (const NodeSystem &other, Opt< ChangeList & > list={}) const

Result< void >	AddBase (const NodeSystem &other) const

Result< void >	ValidateTopology () const

Result< void >	ValidatePorts (Opt< ChangeList & > list={}) const

Result< void >	Validate (Opt< ChangeList & > list={}) const

Result< NodeSystem >	EndModification (Opt< ChangeList & > list={}, NodeSystem::FINALIZE_FLAGS finalize=NodeSystem::FINALIZE_FLAGS::CLEANUP)

Result< void >	SetTemplate (const InstantiationTrace &trace, const NodeTemplate &templ, const TemplateArguments &args) const

Result< void >	SetDerivationHandler (const NodeSystemDerivationHandler &handler) const

Result< ChangeList >	Apply (const ChangeList &toApply, Bool inverse, Opt< ChangeList & > track={}) const

const MutableNode &	ToNode () const

const String &	ToString (const FormatStatement *fs=nullptr) const

Bool	operator== (const MutableRoot &other) const

Bool	operator!= (const MutableRoot &other) const

Static Public Member Functions
static const MutableRoot &	NullValue ()

Private Member Functions
	MutableRoot (NodeSystem &&system)

Private Member Functions inherited from MutableNode
const Node &	ToImmutable () const

Result< HashMap< InternedId, InternedId > >	Ungroup (Opt< ChangeList & > list={})

Result< NodeSystem >	MoveToNodeSystem (Opt< ChangeList & > list={})

Private Member Functions inherited from NodeFunctions< MutableGNodeBase >
Result< NodeSelector< MutableGNodeBase ::MUTABLE > >	GetParent () const

Result< NodeSelector< MutableGNodeBase ::MUTABLE > >	FindChild (const InternedId &name) const

Result< NodeSelector< MutableGNodeBase ::MUTABLE > >	FindChild (const Id &name) const

Result< typename NODE::template Selector< MutableGNodeBase ::MUTABLE > >	FindInnerNode (const NODE &baseInner) const

Result< PortListSelector< MutableGNodeBase ::MUTABLE > >	GetPortList (PORT_DIR dir) const

Result< PortListSelector< MutableGNodeBase ::MUTABLE > >	GetInputs () const

Result< PortListSelector< MutableGNodeBase ::MUTABLE > >	GetOutputs () const

Result< Iterator >	GetChildren () const

Result< void >	InitFromPath (typename maxon::nodes::details::NodeFunctionsSuper< MutableGNodeBase >::NodeSystemCtorParam system, const NodePath &path)

Friends
class	NodeSystemImpl

class	NodeSystemInterface

Additional Inherited Members
Private Types inherited from MutableNode
using	Super = MutableNodeFunctions< MutableGNodeBase >

Private Types inherited from MutableNodeFunctions< MutableGNodeBase >
using	ResultFunctions = MutableNodeFunctions< maxon::nodes::details::GNodeResultBase< SUPER > >

using	Super = NodeFunctions< MutableGNodeBase >

Private Types inherited from NodeFunctions< MutableGNodeBase >
using	Iterator = GNodeIterator< NodeSelector< MutableGNodeBase ::MUTABLE > >

using	ResultFunctions = NodeFunctions< maxon::nodes::details::GNodeResultBase< SUPER > >

using	Super = maxon::nodes::details::NodeFunctionsSuper< MutableGNodeBase >

Static Private Member Functions inherited from MutableNode
static const MutableNode &	NullValue ()

Constructor & Destructor Documentation

◆ MutableRoot() [1/3]

MutableRoot ( )

default

Constructs a null node reference.

◆ ~MutableRoot()

~MutableRoot ( )

◆ MutableRoot() [2/3]

MutableRoot ( MutableRoot && src )

◆ MutableRoot() [3/3]

MutableRoot ( NodeSystem && system )

explicitprivate

Member Function Documentation

◆ Reset()

void Reset ( )

Resets this @CLASS to the state it has right after default construction. This includes freeing all resources held by this @CLASS.

◆ operator=()

MutableRoot& operator= ( std::nullptr_t )

Resets this reference to a null reference.

◆ MAXON_OPERATOR_MOVE_ASSIGNMENT()

MAXON_OPERATOR_MOVE_ASSIGNMENT ( MutableRoot )

◆ MAXON_DISALLOW_COPY_AND_ASSIGN()

MAXON_DISALLOW_COPY_AND_ASSIGN ( MutableRoot )

◆ CopyFrom()

Result<void> CopyFrom ( const MutableRoot & src )

◆ AddChild() [1/2]

Result<MutableNode> AddChild	(	const Id &	childId,
		const Result< NodeSystem > &	base,
		Opt< ChangeList & >	list = `{}`
	)		const

Adds an instance of a node system as child to this root node. 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]	base	Node system to add as an instance.
[in]	list	An optional ChangeList to track the changes.

Returns: Reference to the added child.

◆ AddChild() [2/2]

Result<MutableNode> AddChild	(	const Id &	childId,
		const Result< NodeTemplate > &	templ,
		const TemplateArguments &	args = `maxon::NullValue< const TemplateArguments & >()`,
		const AssetRepositoryRef &	lookup = `maxon::NullValue< const AssetRepositoryRef & >()`,
		Opt< ChangeList & >	list = `{}`
	)		const

Adds an instance of a node system as child to this root node. 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]	templ	NodeTemplate of which an instantiation shall be added as an instance to this root node.
[in]	args	Template arguments for templ.
[in]	lookup	The asset repository to use for lookup of assets within the instantiation of templ. If this is a null reference (the default), then the repository of templ will be used.
[in]	list	An optional ChangeList to track the changes.

Returns: Reference to the added child.

◆ ReplaceBase()

Result<ChangeList> ReplaceBase	(	const NodeSystem &	base,
		Opt< ChangeList & >	list = `{}`
	)		const

Replaces the base of the current node system.

Parameters

[in]	base	The new base node system.
[in]	list	An optional ChangeList to track the changes.

Returns: A new change list which contains those parts of the original node system. which couldn't be restored for the new base.

◆ ReplaceChild()

Result<ChangeList> ReplaceChild	(	const InternedId &	childId,
		const NodeSystem &	base,
		Opt< ChangeList & >	list = `{}`
	)		const

Replaces the base of an existing child of this root node.

Parameters

[in]	childId	Identifier for the child node.
[in]	base	The new base node system for the child node.
[in]	list	An optional ChangeList to track the changes.

Returns: A new change list which contains those parts of the original node system. which couldn't be restored for the new base.

◆ MoveToGroup()

Result<MutableNode> MoveToGroup	(	MutableRoot &	groupRoot,
		const Id &	groupId,
		const Block< const InternedId > &	selection,
		Opt< ChangeList & >	list = `{}`
	)		const

Groups the selection of direct child nodes of this node system into a new group node. groupRoot is used to set up the new group node, usually you provide an empty new node system for groupRoot. All selected nodes are moved to the group using their original identifiers, including inner connections. Afterwards the group is finalized and an instance of the group is added to this node system using the given groupId. Connections which leave the group are kept by adding ports to the group node as needed, and connecting them correspondingly. If the used group node already has ports, these will be used where identifiers mach.

Parameters

[in]	groupRoot	The MutableRoot of another (usually empty) node system which will become the group. The function will clear this reference after successful creation of the group.
[in]	groupId	Identifier for the new group within this node system (if empty, a UUID is chosen).
[in]	selection	A selection of nodes, namely children of the root node. Identifiers for which no root child node exists are ignored.
[in]	list	An optional ChangeList to track the changes.

Returns: Reference to the added group node.

See also: MutableNode::Ungroup

◆ Merge()

Result<HomogenousTupleType<3, HashMap<InternedId, InternedId> > > Merge	(	const NodeSystem &	other,
		Opt< ChangeList & >	list = `{}`
	)		const

Merges the other node system into this node system. Top-level nodes and ports are added into this node system 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 node system to merge into this node system.
[in]	list	An optional ChangeList to track the changes.

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.

◆ AddBase()

Result<void> AddBase ( const NodeSystem & other ) const

Adds the other node system as an additional base of this node system. This merges the other node system into this node system, port identifiers are kept (unlike for Merge).

Parameters

[in] other Another node system to add as base and merge into this node system.

◆ ValidateTopology()

Result<void> ValidateTopology ( ) const

Validates the topology of the node system. This checks for cycles in the node graph and sets up the topological ordering. Usually you don't have to call this as it gets called implicitly by ValidatePorts, Validate or EndModification.

Returns: OK on success. If there is a cycle, an IllegalStateError is returned.

◆ ValidatePorts()

Result<void> ValidatePorts ( Opt< ChangeList & > list = {} ) const

Validates the ports of the node system after a sequence of modifications. You should invoke this function whenever you have applied several modifications to the node system which affect derived ports and want them to be up-to-date. For example a new connection between two ports #a, #b might induce derived nested ports at #b if #a has nested ports.

ValidatePorts() does the following steps:

The topology of the node system is checked (see ValidateTopology). If cycles are detected, an IllegalStateError is returned.
Nested ports are derived:
1. Nested ports are derived from sources to targets of connections.
2. After this has been done for the complete node system, nested ports are derived from targets to sources of connections.

See also: $ref usernodes_modifications; $ref usernodes_derivation; Validate() which validates ports and derived attributes.

Parameters

[in] list An optional ChangeList to track the changes.

◆ Validate()

Result<void> Validate ( Opt< ChangeList & > list = {} ) const

Completely validates the node system after a sequence of modifications. This includes the validation which happens as part of ValidatePorts(), but afterwards usernodes_attributes_derived are validated, too. So you should invoke this function whenever you have applied several modifications to the node system which affect derived attributes and want the values of derived attributes to be up-to-date.

See also: $ref usernodes_modifications; $ref usernodes_derivation

Parameters

[in] list An optional ChangeList to track the changes.

◆ EndModification()

Result<NodeSystem> EndModification	(	Opt< ChangeList & >	list = `{}`,
		NodeSystem::FINALIZE_FLAGS	finalize = `NodeSystem::FINALIZE_FLAGS::CLEANUP`
	)

Ends a sequence of modifications of this MutableRoot. You have to call this at the end of a sequence of modifications which has been started with NodeSystem::BeginModification, see there for an example. This MutableRoot reference is cleared by this function.

This function executes several steps:

The node system is validated.
The node system is finalized according to the given flags.
The (exclusive) strong reference to the node system is moved from this MutableRoot to the returned NodeSystem.

Parameters

[in]	list	An optional ChangeList to track the changes.
[in]	finalize	The flags to pass to NodeSystemClass::FinalizeModification.

Returns: Strong reference to the node system, this is moved from the MutableRoot to the return value.

◆ SetTemplate()

Result<void> SetTemplate	(	const InstantiationTrace &	trace,
		const NodeTemplate &	templ,
		const TemplateArguments &	args
	)		const

Sets template and arguments for the current node system if it is an instantiation of a NodeTemplate. This method has to be called within NodeTemplate::Instantiate to have a back reference to the arguments of the instantiation.

Parameters

[in]	trace	The instantiation trace.
[in]	templ	The NodeTemplate which instantiated the current node system.
[in]	args	The template arguments used for the instantiation.

◆ SetDerivationHandler()

Result<void> SetDerivationHandler ( const NodeSystemDerivationHandler & handler ) const

Sets the derivation handler for the current node system. Only NodeTemplates are allowed to change the derivation handler within their InstantiateImpl method, and they have to do so immediately after the creation of the new node system.

Parameters

[in] handler The derivation handler to use for the current node system.

◆ Apply()

Result<ChangeList> Apply	(	const ChangeList &	toApply,
		Bool	inverse,
		Opt< ChangeList & >	track = `{}`
	)		const

Applies the given change list to this node system. 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]	toApply	Change list to apply.
[in]	inverse	Use true if the inverse of the change list shall be applied (for an undo), false otherwise.
[in]	track	An optional ChangeList to track the changes.

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

◆ NullValue()

static const MutableRoot& NullValue ( )

static

◆ ToNode()

const MutableNode& ToNode ( ) const

Upcasts this MutableRoot to a MutableNode.

Returns: This MutableRoot as a MutableNode.

◆ ToString()

const String& ToString ( const FormatStatement * fs = nullptr ) const

Returns a String representation of this @CLASS.

Parameters

[in] formatStatement Nullptr or additional formatting instruction.

Returns: String representation of this @CLASS.

◆ operator==()

Bool operator== ( const MutableRoot & other ) const

Checks if this MutableRoot is the same object as #other. Note that a MutableRoot has to be the exclusive owner of its NodeSystem, so two different MutableRoots will always point to different node systems.

Parameters

[in] other Another MutableRoot.

Returns: True if this is the same as #other, false otherwise.

◆ operator!=()

Bool operator!= ( const MutableRoot & other ) const

Checks if this MutableRoot is a different object as #other.

Parameters

[in] other Another MutableRoot.

Returns: True if this and other are different MutableRoots, false otherwise.

Friends And Related Function Documentation

◆ NodeSystemImpl

friend class NodeSystemImpl

friend

◆ NodeSystemInterface

friend class NodeSystemInterface

friend

Detailed Description

Public Member Functions

Static Public Member Functions

Private Member Functions

Friends

Additional Inherited Members

Constructor & Destructor Documentation

◆ MutableRoot() [1/3]

◆ ~MutableRoot()

◆ MutableRoot() [2/3]

◆ MutableRoot() [3/3]

Member Function Documentation

◆ Reset()

◆ operator=()

◆ MAXON_OPERATOR_MOVE_ASSIGNMENT()

◆ MAXON_DISALLOW_COPY_AND_ASSIGN()

◆ CopyFrom()

◆ AddChild() [1/2]

◆ AddChild() [2/2]

◆ ReplaceBase()

◆ ReplaceChild()

◆ MoveToGroup()

◆ Merge()

◆ AddBase()

◆ ValidateTopology()

◆ ValidatePorts()

◆ Validate()

◆ EndModification()

◆ SetTemplate()

◆ SetDerivationHandler()

◆ Apply()

◆ NullValue()

◆ ToNode()

◆ ToString()

◆ operator==()

◆ operator!=()

Friends And Related Function Documentation

◆ NodeSystemImpl

◆ NodeSystemInterface