#include <customgui_itemtree.h>

Inheritance diagram for ItemTreeData:

Detailed Description

Stores and manages the hierarchical data displayed by an item tree custom GUI.

Maintains item nodes, their hierarchy, associated object links, selection state, and application-defined data. The tree uses an internal sentinel root; regular items begin at

Note: In a description, configure the custom GUI through the resource and dynamic description data in NodeData::GetDDescription(). In a dialog, create the custom GUI settings container directly in GeDialog::CreateLayout() and handle its BFM_ACTION messages in the dialog.

See also: The objectdata_objecttree example in the SDK demonstrates how to use the item tree custom GUI.

Public Member Functions
ItemTreeNode *	AddItem (Int32 id, const maxon::String &name, BaseList2D *bl, const GeData &data, UInt32 flags, Bool aslast=true)

ItemTreeNode *	AddNode (Int32 id, const maxon::String &name, BaseList2D bl, const GeData &data, UInt32 flags, ItemTreeNode parent, ItemTreeNode *prev, Bool aslast=true)

Bool	AddHierarchy (BaseList2D node, ItemTreeNode parent, const maxon::ValueReceiver< ItemTreeNode * > &receiver, UInt32 flags=(0))

ItemTreeNodeData *	GetNodeData (ItemTreeNode *node)

const ItemTreeNodeData *	GetNodeData (const ItemTreeNode *node) const

ItemTreeNode *	GetiNext (ItemTreeNode node, ItemTreeNode topnode=nullptr)

const ItemTreeNode *	GetiNext (const ItemTreeNode node, const ItemTreeNode topnode=nullptr) const

ItemTreeNode *	GetNext (ItemTreeNode *node)

const ItemTreeNode *	GetNext (const ItemTreeNode *node) const

ItemTreeNode *	GetPrev (ItemTreeNode *node)

ItemTreeNode *	GetUp (ItemTreeNode *node)

const ItemTreeNode *	GetUp (const ItemTreeNode *node) const

ItemTreeNode *	GetDown (ItemTreeNode *node)

const ItemTreeNode *	GetDown (const ItemTreeNode *node) const

ItemTreeNode *	GetRoot ()

ItemTreeNode *	GetFirst ()

const ItemTreeNode *	GetFirst () const

void	Remove (ItemTreeNode *node)

void	FreeNode (ItemTreeNode *&node)

void	Insert (ItemTreeNode node, ItemTreeNode parent, ItemTreeNode *prev, Bool aslast=true)

void	SetOwner (BaseList2D *bl)

BaseContainer *	GetUserData ()

Int32	GetSelected (ItemTreeNode ***table, Bool children=true)

ItemTreeNode *	Find (UInt64 guid, ItemTreeNode *node=nullptr)

ItemTreeNode *	Find (UInt64 guid, Int32 id, Bool child=true, ItemTreeNode *node=nullptr)

const ItemTreeNode *	Find (UInt64 guid, const ItemTreeNode *node=nullptr) const

const ItemTreeNode *	Find (UInt64 guid, Int32 id, Bool child=true, const ItemTreeNode *node=nullptr) const

void	ClearSelection ()

UInt64	GetSelectedID ()

void	SetSelectedID (UInt64 guid)

void	SetSelected (ItemTreeNode *node)

ItemTreeNode *	GetFirstSelected ()

const ItemTreeNode *	GetFirstSelected () const

void	AddToSelected (ItemTreeNode *node)

void	Reset ()

ItemTreeNodeIndex *	BuildIndexTable (Int32 &tcnt, Bool sorted)

Int32	GetClipCount ()

ItemTreeNode **	GetClipArray ()

Int32	GetNodeTable (ItemTreeNode ***table)

void	RemoveSelected ()

UInt64	GetChecksum () const

maxon::HashInt	GetHashCode (Bool onlyGuid) const

void	SortNames (BaseDocument *doc)

void	Validate (BaseDocument *doc)

Bool	CopyFrom (ItemTreeData *src)

maxon::Result< void >	PrepareIndex ()

void	ClearIndex ()

Static Public Member Functions
static ItemTreeData *	Alloc ()

static void	Free (ItemTreeData *&data)

Private Member Functions
	ItemTreeData ()

	~ItemTreeData ()

Additional Inherited Members
Static Public Attributes inherited from CustomDataTypeT< 1024869 >
static constexpr Int32	DATATYPEID

Constructor & Destructor Documentation

◆ ItemTreeData()

ItemTreeData ( )

private

◆ ~ItemTreeData()

~ItemTreeData ( )

private

Member Function Documentation

◆ Alloc()

static ItemTreeData* Alloc ( )

static

Allocates an empty item tree data container.

Returns: The allocated tree, or nullptr if allocation or initialization fails.

◆ Free()

static void Free ( ItemTreeData *& data )

static

Releases an item tree data container and clears the caller's pointer.

Parameters

[in,out] data The tree to release.

◆ AddItem()

ItemTreeNode* AddItem	(	Int32	id,
		const maxon::String &	name,
		BaseList2D *	bl,
		const GeData &	data,
		UInt32	flags,
		Bool	aslast = `true`
	)

Adds a top-level item to the tree.

Inserts the item below the internal root and initializes its identifier, name, link, data, and flags. Set aslast to false to insert it before the existing top-level items.

Parameters

[in]	id	The application-defined item identifier.
[in]	name	The item name.
[in]	bl	The object linked to the item, or `nullptr`.
[in]	data	The application-defined data stored by the item.
[in]	flags	The item flags.
[in]	aslast	Places the item last when `true`; otherwise places it first.

Returns: The new item, or nullptr if it cannot be allocated or initialized.

◆ AddNode()

ItemTreeNode* AddNode	(	Int32	id,
		const maxon::String &	name,
		BaseList2D *	bl,
		const GeData &	data,
		UInt32	flags,
		ItemTreeNode *	parent,
		ItemTreeNode *	prev,
		Bool	aslast = `true`
	)

Adds an item at a specified position in the hierarchy.

Inserts the item below parent or at the top level when parent is nullptr. When prev is provided, the item is inserted after that sibling; otherwise aslast controls its position among siblings.

Parameters

[in]	id	The application-defined item identifier.
[in]	name	The item name.
[in]	bl	The object linked to the item, or `nullptr`.
[in]	data	The application-defined data stored by the item.
[in]	flags	The item flags.
[in]	parent	The parent item, or `nullptr` for the top level.
[in]	prev	The previous sibling, or `nullptr`.
[in]	aslast	Places the item last among siblings when `true`.

Returns: The new item, or nullptr if it cannot be allocated or initialized.

◆ AddHierarchy()

Bool AddHierarchy	(	BaseList2D *	node,
		ItemTreeNode *	parent,
		const maxon::ValueReceiver< ItemTreeNode * > &	receiver,
		UInt32	flags = `(0)`
	)

Adds an object and all its descendants to the tree.

The object and every descendant are added as linked tree nodes in depth-first order. The receiver is called immediately after each node is added and can initialize its data or register notifications. Returning false from the receiver skips traversal of that node's descendants while continuing with its siblings.

Parameters

[in]	node	The root object to add together with its descendants.
[in]	parent	The tree parent for the added hierarchy, or nullptr for the tree root.
[in]	receiver	Receives every added node in depth-first order. Return `true` to visit descendants.
[in]	flags	The flags assigned to each added node.

Returns: true on success, or false if a node cannot be added or the receiver reports an error.

◆ GetNodeData() [1/2]

ItemTreeNodeData* GetNodeData ( ItemTreeNode * node )

Returns mutable data stored in a node.

Parameters

[in] node The node whose data to return.

Returns: The node data, or nullptr when node is nullptr.

◆ GetNodeData() [2/2]

const ItemTreeNodeData* GetNodeData ( const ItemTreeNode * node ) const

Returns read-only data stored in a node.

Parameters

[in] node The node whose data to return.

Returns: The node data, or nullptr when node is nullptr.

◆ GetiNext() [1/2]

ItemTreeNode* GetiNext	(	ItemTreeNode *	node,
		ItemTreeNode *	topnode = `nullptr`
	)

Returns the next node in depth-first tree order.

Starts with the child or following sibling of node and walks up through parents as needed. Traversal stops when it reaches topnode; pass nullptr to traverse the complete tree.

Parameters

[in]	node	The current node.
[in]	topnode	The traversal boundary, or `nullptr`.

Returns: The next node, or nullptr when the traversal is complete.

◆ GetiNext() [2/2]

const ItemTreeNode* GetiNext	(	const ItemTreeNode *	node,
		const ItemTreeNode *	topnode = `nullptr`
	)		const

Returns the next node in depth-first tree order without modifying the tree.

Starts with the child or following sibling of node and stops at topnode; pass nullptr to traverse the complete tree.

Parameters

[in]	node	The current node.
[in]	topnode	The traversal boundary, or `nullptr`.

Returns: The next node, or nullptr when the traversal is complete.

◆ GetNext() [1/2]

ItemTreeNode* GetNext ( ItemTreeNode * node )

Returns the next sibling of a node.

Parameters

[in] node The node whose sibling to return.

Returns: The next sibling, or nullptr when node is nullptr or has no next sibling.

◆ GetNext() [2/2]

const ItemTreeNode* GetNext ( const ItemTreeNode * node ) const

Returns the next sibling of a node without modifying the tree.

Parameters

[in] node The node whose sibling to return.

Returns: The next sibling, or nullptr when node is nullptr or has no next sibling.

◆ GetPrev()

ItemTreeNode* GetPrev ( ItemTreeNode * node )

Returns the previous sibling of a node.

Parameters

[in] node The node whose sibling to return.

Returns: The previous sibling, or nullptr when node is nullptr or has no previous sibling.

◆ GetUp() [1/2]

ItemTreeNode* GetUp ( ItemTreeNode * node )

Returns the parent of a node.

Parameters

[in] node The node whose parent to return.

Returns: The parent node, or nullptr when node is nullptr or has no parent.

◆ GetUp() [2/2]

const ItemTreeNode* GetUp ( const ItemTreeNode * node ) const

Returns the parent of a node without modifying the tree.

Parameters

[in] node The node whose parent to return.

Returns: The parent node, or nullptr when node is nullptr or has no parent.

◆ GetDown() [1/2]

ItemTreeNode* GetDown ( ItemTreeNode * node )

Returns the first child of a node.

Parameters

[in] node The node whose child to return.

Returns: The first child, or nullptr when node is nullptr or has no children.

◆ GetDown() [2/2]

const ItemTreeNode* GetDown ( const ItemTreeNode * node ) const

Returns the first child of a node without modifying the tree.

Parameters

[in] node The node whose child to return.

Returns: The first child, or nullptr when node is nullptr or has no children.

◆ GetRoot()

ItemTreeNode* GetRoot ( )

Returns the internal sentinel root node.

The root does not contain regular item data. Use GetFirst to access the first top-level item.

Returns: The internal root node.

◆ GetFirst() [1/2]

ItemTreeNode* GetFirst ( )

Returns the first top-level item.

Returns: The first item, or nullptr when the tree is empty.

◆ GetFirst() [2/2]

const ItemTreeNode* GetFirst ( ) const

Returns the first top-level item without modifying the tree.

Returns: The first item, or nullptr when the tree is empty.

◆ Remove()

void Remove ( ItemTreeNode * node )

Detaches a node and its descendants from the tree without releasing them.

Parameters

[in] node The node to detach.

◆ FreeNode()

void FreeNode ( ItemTreeNode *& node )

Releases a node and its descendants, then clears the caller's pointer.

Parameters

[in,out] node The node to release.

◆ Insert()

void Insert	(	ItemTreeNode *	node,
		ItemTreeNode *	parent,
		ItemTreeNode *	prev,
		Bool	aslast = `true`
	)

Inserts an existing node at a specified position in the tree.

Parameters

[in]	node	The detached node to insert.
[in]	parent	The parent item, or `nullptr` for the top level.
[in]	prev	The previous sibling, or `nullptr`.
[in]	aslast	Places the node last among siblings when `true`.

◆ SetOwner()

void SetOwner ( BaseList2D * bl )

Associates an owning object with the tree.

Stores a link to bl and tracks whether the link must be resolved through a document.

Parameters

[in] bl The owning object, or nullptr to clear the owner.

◆ GetUserData()

BaseContainer* GetUserData ( )

Returns the user data container associated with the tree.

Returns: The mutable user data container.

◆ GetSelected()

Int32 GetSelected	(	ItemTreeNode ***	table,
		Bool	children = `true`
	)

Returns the selected nodes in a newly allocated array.

Pass nullptr for table to retrieve only the count. When an array is returned, the caller owns its memory and must release it with DeleteMem. Set children to false to stop descending below selected nodes.

Parameters

[out]	table	Receives the allocated node array, or `nullptr`.
[in]	children	Includes descendants when `true`.

Returns: The number of selected nodes, or NOTOK if array allocation fails.

◆ Find() [1/4]

ItemTreeNode* Find	(	UInt64	guid,
		ItemTreeNode *	node = `nullptr`
	)

Finds a node by its GUID.

Searches the complete tree when node is nullptr; otherwise searches the subtree rooted at node.

Parameters

[in]	guid	The node GUID.
[in]	node	The subtree root, or `nullptr` for the complete tree.

Returns: The matching node, or nullptr when no node matches.

◆ Find() [2/4]

ItemTreeNode* Find	(	UInt64	guid,
		Int32	id,
		Bool	child = `true`,
		ItemTreeNode *	node = `nullptr`
	)

Finds a node by its item identifier and optionally its GUID.

A guid of CRC64_NEGL matches any GUID. Set child to false to search only the specified level. When node is nullptr, the top level is searched.

Parameters

[in]	guid	The node GUID, or `CRC64_NEGL` to ignore the GUID.
[in]	id	The application-defined item identifier.
[in]	child	Searches descendants when `true`.
[in]	node	The level to search, or `nullptr` for the top level.

Returns: The matching node, or nullptr when no node matches.

◆ Find() [3/4]

const ItemTreeNode* Find	(	UInt64	guid,
		const ItemTreeNode *	node = `nullptr`
	)		const

Finds a node by its GUID without modifying the tree.

Searches the complete tree when node is nullptr; otherwise searches the subtree rooted at node.

Parameters

[in]	guid	The node GUID.
[in]	node	The subtree root, or `nullptr` for the complete tree.

Returns: The matching node, or nullptr when no node matches.

◆ Find() [4/4]

const ItemTreeNode* Find	(	UInt64	guid,
		Int32	id,
		Bool	child = `true`,
		const ItemTreeNode *	node = `nullptr`
	)		const

Finds a node by its item identifier and optionally its GUID without modifying the tree.

A guid of CRC64_NEGL matches any GUID. Set child to false to search only the specified level. When node is nullptr, the top level is searched.

Parameters

[in]	guid	The node GUID, or `CRC64_NEGL` to ignore the GUID.
[in]	id	The application-defined item identifier.
[in]	child	Searches descendants when `true`.
[in]	node	The level to search, or `nullptr` for the top level.

Returns: The matching node, or nullptr when no node matches.

◆ ClearSelection()

void ClearSelection ( )

Clears the selection state of every node in the tree.

◆ GetSelectedID()

UInt64 GetSelectedID ( )

Returns the GUID of the first selected node.

Returns: The selected node GUID, or CRC64_NEGL when no node is selected.

◆ SetSelectedID()

void SetSelectedID ( UInt64 guid )

Selects a node by GUID and clears the previous selection.

Parameters

[in] guid The GUID of the node to select.

◆ SetSelected()

void SetSelected ( ItemTreeNode * node )

Selects a node and clears the previous selection.

Parameters

[in] node The node to select, or nullptr to clear the selection.

◆ GetFirstSelected() [1/2]

ItemTreeNode* GetFirstSelected ( )

Returns the first selected node in depth-first order.

Returns: The first selected node, or nullptr when no node is selected.

◆ GetFirstSelected() [2/2]

const ItemTreeNode* GetFirstSelected ( ) const

Returns the first selected node in depth-first order without modifying the tree.

Returns: The first selected node, or nullptr when no node is selected.

◆ AddToSelected()

void AddToSelected ( ItemTreeNode * node )

Adds a node to the current selection without clearing other selected nodes.

Parameters

[in] node The node to select, or nullptr.

◆ Reset()

void Reset ( )

Removes all nodes and resets the tree to its initial empty state.

◆ BuildIndexTable()

ItemTreeNodeIndex* BuildIndexTable	(	Int32 &	tcnt,
		Bool	sorted
	)

Builds a flat table containing every node in depth-first order.

The caller owns the returned array and must release it with DeleteMem. When sorted is true, the entries are sorted by GUID. The table becomes invalid when the tree is modified.

Parameters

[out]	tcnt	Receives the number of entries in the returned table.
[in]	sorted	Sorts entries by GUID when `true`.

Returns: The allocated index table, or nullptr when the tree is empty or allocation fails.

◆ GetClipCount()

Int32 GetClipCount ( )

Returns the number of nodes in the global item-tree clipboard.

Returns: The clipboard node count, or zero when no clipboard exists.

◆ GetClipArray()

ItemTreeNode** GetClipArray ( )

Returns the global item-tree clipboard array.

Returns: The clipboard node array, or nullptr when no clipboard exists.

◆ GetNodeTable()

Int32 GetNodeTable ( ItemTreeNode *** table )

Returns all non-folder nodes in a newly allocated array.

The result includes the internal sentinel root and all non-folder nodes. Pass nullptr for table to retrieve only the count. When an array is returned, the caller owns its memory and must release it with DeleteMem.

Parameters

[out] table Receives the allocated node array, or nullptr.

Returns: The number of nodes, or NOTOK if array allocation fails.

◆ RemoveSelected()

void RemoveSelected ( )

Removes every selected node and its descendants from the tree.

◆ GetChecksum()

UInt64 GetChecksum ( ) const

Calculates a CRC checksum for the complete tree content.

Includes node identifiers, flags, names, stored data, and the memory markers of linked objects.

Returns: The tree checksum.

◆ GetHashCode()

maxon::HashInt GetHashCode ( Bool onlyGuid ) const

Calculates a hash code for the complete tree content.

Set onlyGuid to true to hash only node GUIDs; otherwise node identifiers, flags, names, stored data, and linked objects also contribute to the result.

Parameters

[in] onlyGuid Hashes only node GUIDs when true.

Returns: The tree hash code.

◆ SortNames()

void SortNames ( BaseDocument * doc )

Sorts sibling nodes by the names of their linked objects.

Recursively sorts every sibling level. Only nodes with a resolvable linked object participate in the comparison; nodes without one are excluded from sorting and retain their relative order.

Parameters

[in] doc The document used to resolve object links, or nullptr to use the active document.

◆ Validate()

void Validate ( BaseDocument * doc )

Removes nodes whose linked objects can no longer be resolved.

Only nodes with a link are checked. Nodes marked with ITEMTREE_FLAG_NULLLINK or ITEMTREE_FLAG_NOLINK are exempt from removal.

Parameters

[in] doc The document used to resolve object links.

◆ CopyFrom()

Bool CopyFrom ( ItemTreeData * src )

Copies the complete contents of another item tree.

Replaces the current node hierarchy with a copy of src, including its node data and linked object data. The destination's user data and owner link are not changed.

Parameters

[in] src The source tree to copy.

Returns: true on success; otherwise false.

◆ PrepareIndex()

maxon::Result<void> PrepareIndex ( )

Builds an internal index for repeated item identifier and GUID lookups.

Populates exact (id, guid) entries and wildcard-GUID entries used by Find. Call this before repeated lookups; tree changes require the index to be rebuilt or cleared.

Returns: OK on success; otherwise an error result.

◆ ClearIndex()

void ClearIndex ( )

Clears the internal lookup index and disables indexed lookup.

Detailed Description

Public Member Functions

Static Public Member Functions

Private Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

◆ ItemTreeData()

◆ ~ItemTreeData()

Member Function Documentation

◆ Alloc()

◆ Free()

◆ AddItem()

◆ AddNode()

◆ AddHierarchy()

◆ GetNodeData() [1/2]

◆ GetNodeData() [2/2]

◆ GetiNext() [1/2]

◆ GetiNext() [2/2]

◆ GetNext() [1/2]

◆ GetNext() [2/2]

◆ GetPrev()

◆ GetUp() [1/2]

◆ GetUp() [2/2]

◆ GetDown() [1/2]

◆ GetDown() [2/2]

◆ GetRoot()

◆ GetFirst() [1/2]

◆ GetFirst() [2/2]

◆ Remove()

◆ FreeNode()

◆ Insert()

◆ SetOwner()

◆ GetUserData()

◆ GetSelected()

◆ Find() [1/4]

◆ Find() [2/4]

◆ Find() [3/4]

◆ Find() [4/4]

◆ ClearSelection()

◆ GetSelectedID()

◆ SetSelectedID()

◆ SetSelected()

◆ GetFirstSelected() [1/2]

◆ GetFirstSelected() [2/2]

◆ AddToSelected()

◆ Reset()

◆ BuildIndexTable()

◆ GetClipCount()

◆ GetClipArray()

◆ GetNodeTable()

◆ RemoveSelected()

◆ GetChecksum()

◆ GetHashCode()

◆ SortNames()

◆ Validate()

◆ CopyFrom()

◆ PrepareIndex()

◆ ClearIndex()