ThTreeNode

Represents a logical node in a tree structure, used to store hierarchical data in memory.
Manages child, sibling, and parent relationships, and supports recursive operations, sorting, and traversal.
Designed as the foundation for both generic trees and domain-specific extensions like ERP bill-of-materials.

Hidden

Indicates whether this node should be hidden from visual representation or processing.
This flag can be used by UI or filtering logic to skip rendering or handling the node.
Hidden: Boolean;

Selected_Update_Childs

Controls whether selecting this node should automatically update the selection state of its child nodes.
When set to True, selecting or deselecting this node will propagate the same state recursively to all its children.
Selected_Update_Childs: Boolean;

Clear_Child_Nodes

Removes all child nodes from the current node. Optionally includes nodes that were manually inserted by the end user.
Procedure Clear_Child_Nodes(Including_Inserted_By_End_User: Boolean = True);

Parameters

  • Including_Inserted_By_End_User: Boolean; If True, also removes user-inserted nodes. If False, keeps them intact.

ChildCount

Returns the number of immediate child nodes under this node.
Function ChildCount: Cardinal;

Return Value

The number of child nodes associated with this node.

Child

Retrieves a specific child node by its index.
Function Child(Index: Cardinal): ThTreeNode;

Parameters

  • Index: Cardinal; The zero-based index of the child node to retrieve.

Return Value

Returns the child node at the specified index.

Add_Child_Node

Creates and appends a new child node with the specified caption and glyph. Can optionally mark the new node as hidden.
Function Add_Child_Node(_Caption: String; _Glyph: AnsiString; _Hidden: Boolean = False): ThTreeNode;

Parameters

  • _Caption: String; The text caption for the new child node.
  • _Glyph: AnsiString; The glyph or icon identifier to associate with the node.
  • _Hidden: Boolean; If True, the new node will be initially hidden.

Return Value

Returns the newly created ThTreeNode instance.

Expand_Or_Collapse_All_Child_Nodes

Expands or collapses all direct and nested child nodes of the current node. The operation is recursive and applies the same state to all descendants.
Procedure Expand_Or_Collapse_All_Child_Nodes(Expand: Boolean);

Parameters

  • Expand: Boolean; If True, all nodes will be expanded. If False, all nodes will be collapsed.

IS_Node_Exists

Checks whether a given node exists within the children of the current node.
The check is recursive and includes all descendants.
Function IS_Node_Exists(Node: ThTreeNode): Boolean;

Parameters

  • Node: ThTreeNode; The node to search for in the subtree.

Return Value

Returns True if the node exists in the subtree.
Returns False otherwise.

Find_Node_By_Caption

Searches for a child node with the specified caption. Supports a specified matching algorithm and optional recursion into sub-branches.
Function Find_Node_By_Caption(FindCaption: String; Algo: ThTreeNodeFindAlgo; Recurse: Boolean): ThTreeNode;

Parameters

  • FindCaption: String; The caption to search for.
  • Algo: ThTreeNodeFindAlgo; Defines the comparison strategy (e.g., exact match, partial match).
    • ThTreeNodeFindAlgo = (he_SameString, he_ContString, he_StartingWith);
  • Recurse: Boolean; If True, search includes nested children recursively.

Return Value

Returns the first node matching the criteria, or nil if no match is found.

Find_Node_ML

Performs a multi-level search for a node based on an array of captions. Each caption represents a level in the hierarchy to follow.
Search is non-recursive and stops at the first failed step.
Function Find_Node_ML(FindCaption: Array OF String): ThTreeNode;

Parameters

  • FindCaption: Array of String; Sequence of captions representing the path from root to target node.

Return Value

Returns the matching node if the entire path is resolved, or nil if any segment is not found.

Find_Node_ML_ST1

Searches for a multi-level path and returns the caption of the matching final node as a flat string.
The search is not recursive and fails if any level is missing.
Function Find_Node_ML_ST1(FindCaption: Array OF String): String;

Parameters

  • FindCaption: Array of String; The multi-level caption sequence to follow.

Return Value

Returns the caption of the found node if the path is fully matched. Returns an empty string if not found.

Setup_Selection_IF_All_Children_Are_Selected

Marks the current node as selected if all of its immediate child nodes are already selected.
This is used to reflect consistent hierarchical selection status upward in the tree structure.
procedure Setup_Selection_IF_All_Children_Are_Selected;

Sort_Childs

Sorts the current node’s child nodes using the specified sorting strategy.
Sorting affects their visual and logical order within the tree.
procedure Sort_Childs(SortWay: ThTreeNodeSortAlgo);

Parameters

  • SortWay: ThTreeNodeSortAlgo; Defines the sorting algorithm to apply, such as by caption or insertion order.
    • ThTreeNodeSortAlgo = (he_CaptionString, he_ExtEvent, he_Node_ETag1, he_Node_STag1);

Move_Node_As_Child

Attempts to move a given node under the current node, making it one of its children.
The move is rejected if it causes a circular structure or is otherwise invalid.
function Move_Node_As_Child(MoveNode: ThTreeNode): Boolean;

Parameters

  • MoveNode: ThTreeNode; The node that will be moved to become a child of the current node.

Return Value

Returns True if the move succeeded and the node was reparented.
Returns False if the operation was blocked (e.g., self-move, circular parenting).

Get_Selected_Nodes_Into_Array_Of_Pointers

Collects all selected child nodes into an array of pointers.
Optionally limits the collection to only the first-level children of the current node.
function Get_Selected_Nodes_Into_Array_Of_Pointers(Only_First_Level: Boolean): ThNodes_List;

Parameters

  • Only_First_Level: Boolean; If True, only immediate child nodes are checked for selection. If False, the search is recursive.

Return Value

Returns a ThNodes_List containing pointers to all selected nodes according to the specified depth level.
ThNodes_List = Array OF ThTreeNode;

Reset_Selection_Recurse

Recursively updates the selection state of the current node and all its descendants.
This clears or sets the selection status tree-wide starting from the current node.
procedure Reset_Selection_Recurse(NewValue: Boolean = False);

Parameters

  • NewValue: Boolean; If True, marks all nodes as selected. If False, clears selection.

IS_Node_Selected

Checks whether the current node is selected.
Selection may be based on external UI interactions or logical operations.
function IS_Node_Selected: Boolean;

Return Value

Returns True if the node is marked as selected.
Returns False if it is not selected.

Get_Parent_Nodes_Into_Array_Of_Pointers

Creates an array containing pointers to all parent nodes of the current node, up to the root.
This is useful for navigation, path tracing, or hierarchy reconstruction.
function Get_Parent_Nodes_Into_Array_Of_Pointers: ThNodes_List;

Return Value

Returns a ThNodes_List containing pointers to all parent nodes in reverse order (from child to root).

Copy_Tree_Data_To_This_Node

Copies the content of a source node into the current node, optionally including children and overriding the current node's data.
This is used for deep or partial duplication of tree branches.
procedure Copy_Tree_Data_To_This_Node(CONST Source: ThTreeNode; CONST Override_Self: Boolean = True;
                                      CONST Copy_Children: Boolean = True);

Parameters

  • Source: ThTreeNode; The node whose data and children will be copied.
  • Override_Self: Boolean; If True, replaces the current node's fields with the source's values.
  • Copy_Children: Boolean; If True, includes recursive copying of all child nodes from the source.

Copy_Children_Recurse_Filter

Recursively copies child nodes from a source node to the current node, only including nodes that match the filter string.
This supports selective subtree extraction based on captions or custom logic.
procedure Copy_Children_Recurse_Filter(CONST Source: ThTreeNode; CONST Filter: String);

Parameters

  • Source: ThTreeNode; The node from which children will be filtered and copied.
  • Filter: String; A substring condition used to determine which nodes to include (typically on caption).

Write_To_MS

Serializes the current node and optionally its children into a memory stream.
Used for temporary or persistent binary storage of a tree structure.
procedure Write_To_MS(CONST MS: ThMemoryStream; Limit_MS_Size: Integer = 0);

Parameters

  • MS: ThMemoryStream; The destination stream to which the node data will be written.
  • Limit_MS_Size: Integer; Optional size limit to prevent writing excessive data (0 = no limit).

Debug_Write_To_Log

Outputs internal data of the current node and its hierarchy to the application log for debugging purposes.
This helps trace values and structural issues during development or inspection.
procedure Debug_Write_To_Log;

Child_Index

Indicates the position of the current node within its parent's child list.
The value is automatically managed and reflects the node's visual/logical order.
property Child_Index: Integer;

Parent

Returns a reference to the parent node of the current node.
If the node is the root, this property returns nil.
property Parent: ThTreeNode;

Level

Returns the depth level of the current node in the tree hierarchy.
The root node has level 0, and each child increases the level by 1.
property Level: Word;

BOM

Provides access to the ThBillOfMaterial instance associated with this node, if any.
Used when the node represents a structured ERP item with quantity and dependencies.
property BOM: ThBillOfMaterial;

Expanded

Indicates whether the child nodes of this node are currently expanded in the UI.
Used for rendering and user interaction in the visual tree.
property Expanded: Boolean;

Flat Functions

TagStr_To_ThNumeric

Converts a string tag value into a ThNumeric type used for internal node identification.
Useful when parsing external references or clipboard content containing encoded numeric tags.
function TagStr_To_ThNumeric(TagValue: String): ThNumeric;

Parameters

  • TagValue: String; A string containing the numeric tag value to convert.

Return Value

Returns a ThNumeric representing the converted numeric identifier.

Load_Tree_From_File

Loads a tree structure from the specified file and populates the given base node.
Used to restore saved data or import BOM trees from external sources.
function Load_Tree_From_File(Base: ThTreeNode; FileName: String): Boolean;

Parameters

  • Base: ThTreeNode; The root node where the loaded structure will be attached.
  • FileName: String; Path to the file containing the serialized tree data.

Return Value

Returns True if the tree was successfully loaded and assigned to the base node.
Returns False if the file was missing, invalid, or caused an error during parsing.

Save_Tree_To_File

Saves the tree structure starting from the given base node into a file.
Used for backups, exports, or persistent storage of BOM or tree data.
procedure Save_Tree_To_File(Base: ThTreeNode; FileName: String);

Parameters

  • Base: ThTreeNode; The root node of the tree to serialize and save.
  • FileName: String; Path where the output file will be written.

Copy_Tree_Into_Clipboard

Copies the full structure of the tree rooted at the specified node into the system clipboard.
Used to support copy-paste of entire BOM sections between sessions or applications.
procedure Copy_Tree_Into_Clipboard(Base: ThTreeNode);

Parameters

  • Base: ThTreeNode; The node whose subtree will be serialized and placed in the clipboard.

Paste_Tree_From_Clipboard

Reads a tree structure from the system clipboard and attaches it under the specified base node.
Supports importing nodes copied from other visual trees or sources.
function Paste_Tree_From_Clipboard(Base: ThTreeNode): Boolean;

Parameters

  • Base: ThTreeNode; The destination node where the pasted tree will be inserted.

Return Value

Returns True if a valid tree was pasted from the clipboard and attached.
Returns False if the clipboard did not contain valid tree data.

Write_TREE_Into_Log_FileA

Outputs the entire tree structure to the application log file in a readable format.
Used for debugging, traceability, and audit purposes.
procedure Write_TREE_Into_Log_FileA(Base: ThTreeNode);

Parameters

  • Base: ThTreeNode; The root node of the tree to be logged.