Tree Component

Understanding the TTree component and its role in TeeTree

The TTree component is the central visual control in TeeTree. It maintains a network-hierarchy of nodes, similar to Microsoft’s TreeView control, but with significantly more power and flexibility.

Overview

TTree is a visual component that manages a collection of nodes and their relationships. Unlike traditional tree controls, every node in TeeTree is a full standalone component with its own properties, methods, and events.

// Creating a basic tree
var
  Tree: TTree;
begin
  Tree := TTree.Create(Self);
  Tree.Parent := Self;
end;

Key Features

Node Management

Maintains a network-hierarchy of nodes with parent-child relationships

Visual Connections

Links nodes using connection components with customizable styles

Auto-Positioning

Automatic layout management through child manager classes

Rich Formatting

Full control over colors, borders, fonts, gradients, and more

Component Architecture

TeeTree follows a component-based architecture where the Tree acts as a container:

TCustomTree (Base Class)
  ├── TCustomTreeElement (Base for nodes and connections)
  │   ├── TTreeNodeShape (Individual nodes)
  │   └── TTreeConnection (Links between nodes)
  └── Child Managers (Layout algorithms)

The TCustomTree class is the base class, while TTree is the published component you’ll typically use in your applications.

Global Configuration

Global Variables

TeeTree provides several global variables for fine-tuning behavior:

var
  TeeTreeAnimatedScroll  : Boolean = True;
  TeeLineClickTolerance  : Integer = 3;
  TeeConnectionCursor    : TCursor = crHandPoint;
  TreeListCapacity       : Integer = 100;

These global variables might be removed or replaced in future versions. Use with caution.

Performance Tuning

Adjust list capacities for better performance:

// Minimize memory usage
TreeListCapacity := 0;
TreeShapeListCapacity := 0;

// Optimize for large trees (1000+ nodes)
TreeListCapacity := 1000;
TreeShapeListCapacity := 1000;

Working with Roots

The Tree maintains a collection of root nodes (nodes without parents):

// Add root nodes
var
  RootNode: TTreeNodeShape;
begin
  RootNode := Tree.Shapes.Add('Root 1');
  RootNode.X0 := 10;
  RootNode.Y0 := 10;
end;

// Access all root nodes
for i := 0 to Tree.Roots.Count - 1 do
  ShowMessage(Tree.Roots[i].SimpleText);

Root nodes are automatically positioned based on the Tree’s GlobalFormat.ChildManager when their AutoPosition property is enabled.

Layout Management

The Tree’s layout is controlled by the GlobalFormat.ChildManager object:

// Use Explorer-style layout (default)
Tree.GlobalFormat.ChildManager := TTreeExplorerAlignChild.Create;

// Use circular layout
Tree.GlobalFormat.ChildManager := TTreeCircularAlignChild.Create;

// Use top-to-bottom layout
Tree.GlobalFormat.ChildManager := TTreeTopBottomAlignChild.Create;

Child managers determine how parent and children nodes are arranged on screen when nodes are auto-positioned. See Child Managers for details.

Selection Management

TTree provides a built-in selection system:

// Select a node
Tree.Selected.Add(MyNode);

// Select multiple nodes
Tree.Selected.ShiftState := [ssShift];  // Enable multi-select

// Access selected nodes
for i := 0 to Tree.Selected.Count - 1 do
  ProcessNode(Tree.Selected[i]);

// Clear selection
Tree.Selected.Clear;

CrossBox (Expand/Collapse)

The CrossBox is the visual indicator (+/-) for expanding and collapsing nodes:

// Configure CrossBox appearance
with Tree.CrossBox do
begin
  Size := 15;
  Style := cbsSquare;     // Square, Diamond, or Circle
  SignStyle := cssCross;  // Cross or Triangle
  Border.Color := clGray;
  Brush.Color := clWhite;
end;

VCL vs FireMonkey

TeeTree supports both VCL and FireMonkey frameworks:

• VCL: Uses TeeTree.pas unit
• FireMonkey: Uses FMXTee.Tree.pas unit

The API is consistent across both frameworks, with minor platform-specific differences in rendering and events.

Common Patterns

Creating a Simple Hierarchy

var
  Root, Child1, Child2: TTreeNodeShape;
begin
  Root := Tree.Shapes.Add('Root');
  Child1 := Root.AddChild('Child 1');
  Child2 := Root.AddChild('Child 2');
  
  Root.Expanded := True;
end;

Iterating All Nodes

// Iterate through all shapes
for i := 0 to Tree.Shapes.Count - 1 do
begin
  Node := Tree.Shapes[i];
  // Process node
end;

Finding Nodes

// Find by text
Node := Tree.Shapes.Find('Search Text');

// Find by partial match
Node := Tree.Shapes.Find('Search', True);

// Find by object reference
Node := Tree.Shapes.FindObject(MyDataObject);

Best Practices

Use AutoPosition

Enable AutoPosition for automatic layout management instead of manually positioning every node

Set List Capacity

Pre-allocate list capacity for better performance when adding many nodes

Batch Updates

Use BeginUpdate/EndUpdate when making multiple changes to prevent flickering

Choose Right ChildManager

Select the appropriate child manager for your tree’s visual structure

Next Steps

Nodes

Learn about TTreeNodeShape and node hierarchy

Connections

Understand how to link nodes with connections

Child Managers

Explore layout management options