Tree Nodes

Understanding TTreeNodeShape and the node hierarchy in TeeTree

The TTreeNodeShape class is the fundamental building block of TeeTree. Each node is a full standalone component with comprehensive properties, methods, and events.

Overview

Unlike traditional tree controls where nodes are simple data items, TeeTree nodes are complete visual components with rich formatting capabilities.

// Creating a node
var
  Node: TTreeNodeShape;
begin
  Node := Tree.Shapes.Add('My Node');
  Node.Color := clYellow;
  Node.Border.Width := 2;
end;

Every node in TeeTree is a TTreeNodeShape instance derived from TCustomTreeElement, which provides core functionality shared with connections.

Node Properties

Position and Size

Nodes have explicit position and size properties:

// Position (top-left corner)
Node.X0 := 100;  // or Node.Left := 100;
Node.Y0 := 50;   // or Node.Top := 50;

// Size (bottom-right corner)
Node.X1 := 200;
Node.Y1 := 100;

// Alternative: Width and Height
Node.Width := 100;
Node.Height := 50;

Left and Top are aliases for X0 and Y0 respectively. Use whichever is more intuitive for your code.

Visual Appearance

Colors and Brushes

// Background color
Node.Color := clWhite;        // Default white
Node.Brush.Color := clYellow; // Alternative way

// Border
Node.Border.Color := clBlack;
Node.Border.Width := 1;
Node.Border.Style := psSolid;

// Transparency
Node.Transparency := 50;  // 0-100%
Node.Transparent := True; // No interior fill

Gradients

// Apply gradient fill
with Node.Gradient do
begin
  Visible := True;
  StartColor := clWhite;
  EndColor := clBlue;
  Direction := gdTopBottom;
end;

// Gradient clipping
Node.GradientClip := True;  // Clip to shape bounds

Shadows

with Node.Shadow do
begin
  Visible := True;
  Size := 5;
  Color := clGray;
  Transparency := 50;
end;

Node Styles

Nodes support various visual styles:

type
  TTreeShapeStyle = (
    tssRectangle,        // Default
    tssCircle,
    tssVertLine,
    tssHorizLine,
    tssLine,
    tssInvertLine,
    tssDiamond,
    tssTriangleTop,
    tssTriangleBottom,
    tssTriangleLeft,
    tssTriangleRight,
    tssRoundRectangle,
    tssCustom,
    tssChamfer
  );

// Apply style
Node.Style := tssRoundRectangle;
Node.RoundSize := 10;  // Corner radius

When using tssCustom style, you’ll need to override the GetShapePoints method to define your custom shape.

Text Properties

Nodes have sophisticated text handling:

// Simple text assignment
Node.SimpleText := 'Hello World';

// Multi-line text
Node.Text.Clear;
Node.Text.Add('Line 1');
Node.Text.Add('Line 2');

// Text formatting
Node.Text.HorizAlign := htaCenter;  // htaLeft, htaRight
Node.Text.VertAlign := vtaCenter;   // vtaTop, vtaBottom
Node.Text.Angle := 45;              // 0..360 degrees
Node.Text.ClipText := False;        // Allow text outside bounds

// Font
Node.Font.Name := 'Arial';
Node.Font.Size := 12;
Node.Font.Style := [fsBold];
Node.Font.Color := clBlack;

AutoSize

Nodes can automatically size themselves based on content:

Node.AutoSize := True;  // Default
Node.SimpleText := 'This text determines the node size';

// Disable for manual sizing
Node.AutoSize := False;
Node.Width := 200;
Node.Height := 100;

When AutoSize is enabled, the node calculates its size based on text and image dimensions plus margins.

Images

Nodes can display images in various positions:

// Using stock images
Node.ImageIndex := tiFolderClose;
Node.Expanded := False;

// Using custom image
Node.Image.LoadFromFile('myimage.png');

// Image alignment
Node.ImageAlignment := iaLeft;  // iaAutomatic, iaLeftTop, iaRight, etc.

// Custom image size
Node.ImageWidth := 32;
Node.ImageHeight := 32;

// Using ImageList
Node.ImageListIndex := 0;  // Index in Tree.Images

Image Alignment Options

type
  TTreeImageAlignment = (
    iaAutomatic,    // Smart positioning
    iaLeftTop,
    iaRightBottom,
    iaLeftBottom,
    iaRightTop,
    iaLeft,
    iaTop,
    iaRight,
    iaBottom,
    iaCenter
  );

Parent-Child Relationships

Nodes form hierarchies through parent-child relationships:

// Create hierarchy
var
  Parent, Child1, Child2: TTreeNodeShape;
begin
  Parent := Tree.Shapes.Add('Parent');
  Child1 := Parent.AddChild('Child 1');
  Child2 := Parent.AddChild('Child 2');
  
  // Alternative: Set parent explicitly
  Child1.Parent := Parent;
end;

// Access children
for i := 0 to Parent.Children.Count - 1 do
  ProcessChild(Parent.Children[i]);

// Check if node has children
if Node.HasChildren then
  Node.Expanded := True;

When a parent node is destroyed, all its children are automatically freed.

Child Management Methods

// Add children
Child := Node.AddChild('New Child');          // Add at end
Child := Node.AddChildFirst('First Child');   // Add at beginning
Child := Node.Insert(1, 'Insert at Index 1'); // Insert at position

// Add with data
Child := Node.AddChildObject('Child', MyDataPointer);

// Add sibling
Brother := Node.AddBrother('Sibling Node');

// Node count
Count := Node.Count;  // Number of direct children

Expand and Collapse

Nodes can be expanded or collapsed to show/hide children:

// Expand/Collapse
Node.Expanded := True;
Node.Expanded := False;

// Toggle
Node.Toggle;

// Collapse recursively
Node.Collapse(True);  // Collapse this and all descendants

// Show CrossBox
Node.ShowCross := scAuto;    // scAuto, scAlways, scNever

CrossBox Styles

type
  TTreeNodeShapeShowCross = (
    scAuto,    // Show only when node has children
    scAlways,  // Always show
    scNever    // Never show
  );

AutoPosition

Control automatic positioning of nodes:

// Enable both Left and Top auto-positioning
Node.AutoPosition.Left := True;   // Default
Node.AutoPosition.Top := True;    // Default

// Manual X position, automatic Y
Node.AutoPosition.Left := False;
Node.AutoPosition.Top := True;
Node.X0 := 100;  // Fixed X position

The ChildManager class calculates positions for nodes with AutoPosition enabled. See Child Managers for details.

Selection and Interaction

// Select a node
Node.Selected := True;

// Check if selected
if Node.Selected then
  ShowMessage('Node is selected');

// Add to tree selection
Tree.Selected.Add(Node);

// Events
Node.OnClick := NodeClickHandler;
Node.OnDblClick := NodeDblClickHandler;
Node.OnMouseEnter := NodeMouseEnterHandler;
Node.OnMouseLeave := NodeMouseLeaveHandler;

Event Handlers

procedure TForm1.NodeClickHandler(Sender: TTreeNodeShape;
  Button: TMouseButton; Shift: TShiftState; X, Y: Integer);
begin
  ShowMessage('Clicked: ' + Sender.SimpleText);
end;

Node Navigation

// Access parent and siblings
ParentNode := Node.Parent;
RootNode := Node.Root;
PreviousNode := Node.PreviousBrother;

// Get node level (depth in tree)
Level := Node.Level;  // 0 for root nodes

// Brother index (position among siblings)
Index := Node.BrotherIndex;
Node.BrotherIndex := 0;  // Move to first position

Visibility Control

// Show/Hide
Node.Visible := True;
Node.Show;
Node.Hide;

// Check if inside tree bounds
if Node.InsideTreeBounds then
  ProcessNode(Node);

Data Association

// Store custom data
Node.Data := MyDataPointer;
Node.TagObject := MyObject;
Node.Tag := 123;

// Retrieve data
MyData := PMyDataType(Node.Data);
MyObj := Node.TagObject as TMyClass;

The Data property is a raw pointer. Ensure proper memory management. TagObject provides automatic reference counting on supported platforms.

Advanced Features

Checkboxes

// Use checkbox images
Node.ImageIndex := tiUnChecked;
Node.Checked := False;

// Toggle checkbox
Node.ToggleCheck;
Node.Checked := True;  // Now shows tiChecked

// Check all selected
Tree.Selected.ToggleCheck;

Custom Drawing

// Override DrawShapeCanvas for custom rendering
type
  TMyNode = class(TTreeNodeShape)
  protected
    procedure DrawShapeCanvas(const ACanvas: TCanvas3D;
      const R: TRect); override;
  end;

Z-Order

// Control drawing order
Node.BringToFront;
Node.SendToBack;

Utility Methods

// Geometry
CenterX := Node.XCenter;
CenterY := Node.YCenter;
Bounds := Node.Bounds;  // TRect
Adjusted := Node.AdjustedRectangle;  // Includes image

// Sorting children
Node.SortChildsText(True, False);  // Ascending, case-sensitive

// Select all children
Node.SelectChilds;

// Move node
Node.MoveRelative(10, 20, True);  // DeltaX, DeltaY, MoveChildren

// Resize
Node.Resize(rcRightBottom, 10, 10);  // Corner, DeltaX, DeltaY

Best Practices

Use AutoSize

Let nodes automatically size themselves based on content for consistent appearance

Leverage Parent-Child

Use parent-child relationships instead of manual positioning when possible

Cache References

Store node references in data structures for quick access instead of searching

Handle Events

Use node events for interactive features rather than polling

Next Steps

Connections

Learn how to link nodes together

Child Managers

Understand automatic layout management

Styling Guide

Master visual customization