ThVisualTree

The ThVisualTree class is a custom UI control that visually represents a hierarchical structure of ThTreeNode and its extensions.
It provides interactive display, navigation, editing, and rendering for trees such as product structures, BOMs, or task hierarchies.
The control supports mouse and keyboard interaction, selection tracking, expansion states, and theme-aware drawing.
It is derived from TSYE_Control and is designed to bridge current VCL use with future FMX compatibility.

Assign_Base

Sets the root node for the visual tree and optionally releases the previously assigned base node.
This establishes the data structure that the control will display and interact with.
procedure Assign_Base(NewBase: ThTreeNode; FreePrevBase: Boolean);

Parameters

  • NewBase: ThTreeNode; The new root node to be displayed in the visual tree.
  • FreePrevBase: Boolean; If True, the previously assigned base node will be freed from memory.

Calc_Tree_Height

Calculates the required pixel height to render a specific number of visible tree items.
Used for autosizing parent containers such as ThApplication_Title or panels.
function Calc_Tree_Height(Visible_Items_Count: Word): Cardinal;

Parameters

  • Visible_Items_Count: Word; Number of tree items expected to be visible.

Return Value

Returns the calculated height in pixels needed to display the given number of items.

Refresh

Rebuilds the internal visual representation of the tree structure, recalculating visible nodes and layout height.
Optionally scrolls or focuses on a specific node after refreshing.
procedure Refresh(GotoNode: ThTreeNode = NIL);

Parameters

  • GotoNode: ThTreeNode; Optional node to scroll to or highlight after refresh. If NIL, no navigation occurs.

View_Json_Tree

Displays a JSON tree structure by converting ThJsonNode data into the internal tree format.
This allows JSON content to be browsed visually within the tree control.
procedure View_Json_Tree(Json_Base: ThJsonNode);

Parameters

  • Json_Base: ThJsonNode; The root JSON node to be displayed as a visual tree.

Base

Returns the root node assigned to the visual tree.
This is the starting point of the displayed hierarchy and source for all rendered nodes.
property Base: ThTreeNode;

CursorNode

Returns the node currently focused or selected by the user.
This node typically represents the UI cursor position for keyboard or mouse interaction.
property CursorNode: ThTreeNode;

Visible_Nodes_Count

Returns the number of nodes currently visible in the visual tree.
This value reflects the current expand/collapse state and filtering if applicable.
property Visible_Nodes_Count: Cardinal;

TabOrder

Specifies the tab order of the visual tree within its parent form or container.
This determines the navigation sequence when pressing the Tab key.
property TabOrder: TTabOrder;

Always_Expanded

Controls whether all nodes should always be visually expanded regardless of their internal state.
When set to True, the control ignores individual expand/collapse flags.
property Always_Expanded: Boolean;

Check_Boxes

Defines the checkbox interaction mode for nodes in the visual tree.
Controls whether checkboxes are shown, selectable, or disabled entirely.
property Check_Boxes: ThVisualTreeCheckbox;

    ThVisualTreeCheckbox

    The ThVisualTreeCheckbox enumeration defines the checkbox behavior mode for nodes in the visual tree.
    Each mode affects how selection logic is applied to parent and child nodes.
    ValueDescription
    he_No_SelectionDisables checkboxes completely — no visual checkbox and no selection state stored.
    he_Parent_Select_ChildrenEnables checkboxes with hierarchical logic — selecting a parent automatically selects all its children.
    he_Stand_AloneEnables independent checkboxes — each node's selection is handled individually without affecting others.

Execute_Node_Single_Click

Specifies whether node execution (e.g. double-click action) should also occur on a single click.
When enabled, clicking a node once may trigger its default behavior or command.
property Execute_Node_Single_Click: Boolean;

Usage_Notes

Stores optional notes or comments about how the visual tree is used or customized in context.
Can be displayed in tooltips or used for debugging/documentation.
property Usage_Notes: String;

Minimal_Row_Height

Specifies the minimum pixel height (default 26) of each tree row in the visual layout.
Used to control vertical spacing and accommodate custom content or scaling.
property Minimal_Row_Height: Word;

Execute_Node

Triggered when a node is executed — typically via double-click or Enter key.
Used to perform actions based on the selected node’s context.
property Execute_Node: ThVisualTreeEvent;

    ThVisualTreeEvent

    The ThVisualTreeEvent type defines a method pointer used for visual tree event handlers.
    It receives a reference to the affected ThTreeNode when triggered by user or programmatic interaction.
    Used in events such as Execute_Node, Cursor_Moved, and others.
    ThVisualTreeEvent = procedure (Node: ThTreeNode) of object;

    Parameters

    • Node: ThTreeNode; The node involved in the triggered event.

Cursor_Moved

Fires when the cursor or selection focus moves from one node to another.
Useful for updating UI elements or syncing other controls with the active node.
property Cursor_Moved: ThVisualTreeEvent;

Selection_Changed

Occurs when the node selection state changes due to user input or programmatic modification.
Used to react to selection updates, such as enabling buttons or displaying details.
property Selection_Changed: TNotifyEvent;

RightClick_Event

Triggered when the user performs a right-click on any tree node.
Commonly used to show context menus or display node-specific actions.
property RightClick_Event: TNotifyEvent;

Node_Freed_Alert

Triggered just before a node is destroyed or removed from memory.
Allows cleanup or logging of associated data tied to the node.
property Node_Freed_Alert: ThVisualTreeEvent;

Lost_Focus

Fires when the control loses keyboard focus to another UI element.
Useful for committing edits or hiding overlays tied to the visual tree.
property Lost_Focus: TNotifyEvent;

Sort_Compare

Custom comparison event used when sorting child nodes.
Allows application-specific logic for comparing two nodes beyond built-in sort options.
property Sort_Compare: ThTreeNode_SortEvent;

    ThTreeNode_SortEvent

    The ThTreeNode_SortEvent type defines a method used for custom sorting of tree nodes.
    It compares two nodes and determines whether the first node should appear before the second.
    Used in the Sort_Compare property of ThVisualTree to override default sort logic.
    ThTreeNode_SortEvent = procedure (Node1, Node2: ThTreeNode; var Node1_Before_Node2: Boolean) of object;

    Parameters

    • Node1: ThTreeNode; The first node to compare.
    • Node2: ThTreeNode; The second node to compare.
    • Node1_Before_Node2: Boolean; Set to True if Node1 should come before Node2, otherwise set to False.

OnKeyDown

Standard VCL event triggered when a key is pressed down while the control has focus.
Can be used to intercept keyboard commands or custom shortcuts.
property OnKeyDown;

OnKeyPress

Standard VCL event triggered when a character key is typed.
Useful for capturing text input or filtering keystrokes in the tree context.
property OnKeyPress;

ThBOM_VisualTree

The ThBOM_VisualTree class is a specialized visual tree control designed for displaying and interacting with ThBillOfMaterial structures.
It extends ThVisualTree with logic specific to BOM data, including dimension columns, pricing, part numbers, and quantities.
This control is tailored for ERP-style applications where multi-level assemblies, nested materials, and manufacturing hierarchies must be visualized and edited.
It supports custom rendering, column layouts, field highlighting, and BOM-specific event handling.

BOM_Add_Child

Triggered when the control requests to add a new child node to a BOM entry.
Used to delegate the creation logic to external handlers such as editors or rules engines.
property BOM_Add_Child: ThBOMevent_Add_Child;

    ThBOMevent_Add_Child

    The ThBOMevent_Add_Child event is triggered when the system requests to create a new child node in the BOM structure.
    It provides the target node reference and the required dimensions and quantity per parent.
    This delegate is used in the BOM_Add_Child property of ThBOM_VisualTree.
    ThBOMevent_Add_Child = procedure (NewNode: ThTreeNode; Catalogic_Number: String; Quantity_Per_Parent, Width, Height, Depth: Double) of object;

    Parameters

    • NewNode: ThTreeNode; A reference to the node that is about to be initialized as a child.
    • Catalogic_Number: String; The catalogic number or code for the child item.
    • Quantity_Per_Parent: Double; The required quantity of the child per parent unit.
    • Width: Double; Physical width of the child item in millimeters.
    • Height: Double; Physical height of the child item in millimeters.
    • Depth: Double; Physical depth of the child item in millimeters.

BOM_Run_Phantom

Invoked when the UI requests to generate a phantom structure under a BOM node.
Allows dynamic sub-assembly creation based on rules or catalog data.
property BOM_Run_Phantom: ThBOMevent_Run_Phantom;

    ThBOMevent_Run_Phantom

    The ThBOMevent_Run_Phantom event is triggered when the control requests to build a phantom structure under a given node.
    This is typically used to generate dynamic or temporary subassemblies based on a catalog number.
    ThBOMevent_Run_Phantom = procedure (NewNode: ThTreeNode; Phantom_Cat_Num: String) of object;

    Parameters

    • NewNode: ThTreeNode; The node where the phantom structure should be added.
    • Phantom_Cat_Num: String; The catalog number representing the phantom structure template.

BOM_Init_Field_Value

Provides a hook for initializing the value of a custom or dynamic BOM field.
This is typically used during node creation or field refresh operations.
property BOM_Init_Field_Value: ThBOMevent_Init_Field_Value;

    ThBOMevent_Init_Field_Value

    The ThBOMevent_Init_Field_Value event is called when initializing the value of a dynamic field in a BOM node.
    It allows external logic to assign default or computed values based on field name and type.
    ThBOMevent_Init_Field_Value = procedure (Node: ThTreeNode; PropName: RawByteString; Kind: ThtpKindType; var Value: Variant) of object;

    Parameters

    • Node: ThTreeNode; The BOM node for which the field value is being initialized.
    • PropName: RawByteString; Internal name of the field whose value is being initialized.
    • Kind: ThtpKindType; Data type of the field.
    • Value: Variant; Output parameter where the initialized value should be assigned.

BOM_Get_ValuesList

Called when a field in the BOM tree requires a list of selectable values (e.g. dropdown or suggestion menu).
Enables integration with external sources or predefined dictionaries.
property BOM_Get_ValuesList: ThBOMevent_Get_ValuesList;

    ThBOMevent_Get_ValuesList

    The ThBOMevent_Get_ValuesList event is triggered when a field with a selection menu requires its list of values.
    It allows external code to supply valid choices dynamically, based on the menu ID.
    ThBOMevent_Get_ValuesList = procedure (SelectFromMenuID: Integer; var ValuesList: String) of object;

    Parameters

    • SelectFromMenuID: Integer; Identifier of the menu associated with the requested field.
    • ValuesList: String; Output parameter containing the list of selectable values (comma-separated or custom format).

BOM_Add_ProtoChild

Triggered when a prototype child node should be added to the BOM.
Used for templated BOM expansions or reusable subassemblies.
property BOM_Add_ProtoChild: ThBOMevent_Add_ProtoChild;

    ThBOMevent_Add_ProtoChild

    The ThBOMevent_Add_ProtoChild event is used to add a new child node based on a prototype definition.
    It provides the prototype index and associated dimensional and quantity values.
    This event supports reusable BOM fragments or templated subassemblies.
    ThBOMevent_Add_ProtoChild = procedure (NewNode: ThTreeNode; ProtoTypeIndex: Word;
                                       Quantity_Per_Parent, Width, Height, Depth: Double) of object;

    Parameters

    • NewNode: ThTreeNode; The node being initialized as a prototype-based child.
    • ProtoTypeIndex: Word; The index of the prototype definition to apply.
    • Quantity_Per_Parent: Double; Quantity of the prototype per one unit of the parent node.
    • Width: Double; Width of the child node in millimeters.
    • Height: Double; Height of the child node in millimeters.
    • Depth: Double; Depth of the child node in millimeters.

BOM_Get_Value_From_Header

Fires when a field in the BOM requires a value derived from a header node (e.g. parent form or global context).
property BOM_Get_Value_From_Header: ThBOMevent_Get_Head_Value;

    ThBOMevent_Get_Head_Value

    The ThBOMevent_Get_Head_Value event is triggered when a BOM field needs to retrieve a value from the header or parent context.
    Used to propagate shared or inherited values into child nodes.
    ThBOMevent_Get_Head_Value = procedure (Node: ThTreeNode; PropName: RawByteString; var Value: Variant) of object;

    Parameters

    • Node: ThTreeNode; The current BOM node requesting a value.
    • PropName: RawByteString; The internal name of the requested field/property.
    • Value: Variant; Output parameter where the retrieved value should be stored.

BOM_Refresh_Node

Requests that a specific node be programmatically refreshed, typically after a data update or command execution.
property BOM_Refresh_Node: ThVisualTreeEvent;

BOM_String_Command

Handles string-based field operations within the BOM structure, such as expressions or assignment rules.
This supports flexible scripting or user-driven logic between fields.
property BOM_String_Command: ThBOMevent_String_Command;

    ThBOMevent_String_Command

    The ThBOMevent_String_Command event is triggered to perform a string-based command or operation on BOM fields.
    It enables external logic to process field-to-field assignments, expressions, or conditional operations dynamically.
    ThBOMevent_String_Command = procedure (Node: ThTreeNode; Command, PropName, AssignTo: RawByteString) of object;

    Parameters

    • Node: ThTreeNode; The BOM node where the command is executed.
    • Command: RawByteString; The name of the command to execute (e.g., 'assign', 'copy', 'add').
    • PropName: RawByteString; The source property or field name involved in the command.
    • AssignTo: RawByteString; The target property or field name where the result should be stored.