TTreeView

│ English (en) │ español (es) │ suomi (fi) │ français (fr) │ magyar (hu) │ русский (ru) │

A TTreeView is a graphical control element that presents a hierarchical view of information. Each item can have a number of subitems.

An item can be expanded to reveal subitems, if any exist, and collapsed to hide subitems.

A Short example of using TTreeview

Here is a simple example:

• Create a new application.
• Add an empty treeview to the form, a button1 with caption "Add Child" and a button2 with caption "Delete"
• Assign the following code to the buttons' OnClick events. Compile and run.

procedure TForm1.Button1Click(Sender: TObject);
var 
  n: integer;
  s: string;
begin
  // If there are no nodes, create a root node with a parent of nil
  if TreeView1.Items.Count = 0 then
  begin
    Treeview1.Items.Add(nil,'Root Node');
    exit;
  end;
 
  // Set up a simple text for each new node - "Node1", "Node2" etc
  n := Treeview1.Items.Count;
  s := 'Node ' + IntToStr(n);

  // Add a new node to the currently selected node
  if TreeView1.Selected <> nil then
    Treeview1.Items.AddChild(Treeview1.Selected, s);
end;
 
procedure TForm1.Button2Click(Sender: TObject);

  // A procedure to recursively delete nodes
  procedure DeleteNode(ANode: TTreeNode);
  begin
    while ANode.HasChildren do 
      DeleteNode(ANode.GetLastChild);
    TreeView1.Items.Delete(ANode);
  end;
 
begin
  if TreeView1.Selected = nil then 
    exit;
  
  // If the selected node has child nodes, first ask for confirmation
  if Treeview1.Selected.HasChildren then
    if MessageDlg('Delete node and all children?', mtConfirmation, [mbYes,mbNo], 0 ) <> mrYes then 
      exit;
  DeleteNode(TreeView1.Selected);
end;

When running, the treeview is empty. If you click "Add Child", a root node is created. After that a child will be added to any selected node by clicking "Add Child" again.

The "Delete" button will delete the currently selected node. If it doesn't have children, it will delete it immediately, but if it has children, it will first ask.

Adding a new item in code

To add a sibling node to pre-existing node, use TTreeView.ITems.Add.

TreeView1.Items.Add(ATreeNode, 'Added node');

To add the first node, it becomes:

TreeView1.Items.Add(nil, 'First node');

Use TTreeView.Items.AddChild or AddChildObject to add child node.

TreeView1.Items.AddChild(ATreeNode, 'Child node');

Creating a TreeView which loads items only when expanding

To add the expansion symbol to a node without subitems use:

MyNode.HasChildren := True;

And then set an event handler for the OnExpanding event. In this even you should return if the expansion can actually be made or not and when yes, you should add subitems to the node. If the expansion cannot be done, the expansion symbol will be automatically removed even if you have previously set HasChildren to true.

How to move a node in TTreeview

Assuming you have UP and Down buttons to move the selected node in the TTreeview, these procedures will achieve moving the selected node.

procedure TForm1.UpBtnClick(Sender: TObject);
begin
  // Ensure a node is selected 
  if(Treeview1.Selected <> nil) then
    // Ensure there is a previous sibling node
    if Treeview1.Selected.GetPrevSibling <> nil then
      // If we have made it this far, move it UP
      Treeview1.Selected.MoveTo(Treeview1.Selected.GetPrevSibling, naInsert);
end;

procedure TForm1.DownBtnClick(Sender: TObject);
begin
  // Ensure a node is selected 
  if(Treeview1.Selected <> nil) then
    // Ensure there is a next sibling node
    if Treeview1.Selected.GetNextSibling <> nil then
      // If we have made it this far, move it DOWN
      Treeview1.Selected.MoveTo(Treeview1.Selected.GetNextSibling, naInsertBehind);
end;

Note: These procedures will only move nodes which are at the same level in the TTreeview.

Table of attachment mode of Nodes
Mode	Effect
naAdd	add as last sibling of target node
naAddFirst	add as first sibling of target node
naAddChild	add as last child of target node
naAddChildFirst	add as first child of target node
naInsert	insert in front of target node
naInsertBehind	insert behind target node

Using multiple node selection

To allow multiple selection, you need to set the tvoAllowMultiSelect flag of the Options property. This will allow you to select additional nodes by Ctrl+Mouse click.

To get a list of selected nodes from code, you can use the TreeView1.Selections property:

procedure TForm1.Button1Click(Sender: TObject);
var
  i: integer;
begin
  Memo1.Lines.Clear;
  for i := 0 to TreeView1.SelectionCount - 1 do
    Memo1.Lines.Add(TreeView1.Selections[i].GetTextPath);
end;

Freeing TreeNode Data

Use the TreeView's OnDeletion event to free your object.

procedure TForm1.TreeView1Deletion(Sender: TObject; Node: TTreeNode);
begin
  TMyObject(Node.Data).Free;
  Node.Data := nil;
end;

Using Drag and Drop in a TreeView

If you want to allow a drag and drop function in your treeview, you need to :

1. Set to DmAutomatic, the property "Drag Mode" of your treeview
2. Create events for onDragDrop and OnDragOver:

...

Var
  Node: TTreeNode;

...

procedure TForm1.TreeView1DragDrop(Sender, Source: TObject; X, Y: Integer);
begin
  Treeview1 := TTreeView(Sender);    { Sender is TreeView where the data is being dropped  }
  Node := Treeview1.GetNodeAt(x,y);  { x,y are drop coordinates (relative to the Sender)   }
                                     {   since Sender is TreeView we can evaluate          }
                                     {   a tree at the X,Y coordinates                     }
  if Source = Sender then            { drop is happening within a TreeView   }
    begin
      if Assigned(Treeview1.Selected) and     {  check if any node has been selected  }
        (Node <> Treeview1.Selected) then     {   and we're dropping to another node  }
          begin
            if Node <> nil then
              Treeview1.Selected.MoveTo(Node, naAddChild) { complete drop, by moving selected node }
            else
              Treeview1.Selected.MoveTo(Node, naAdd);     { complete drop, by moving selected node in root }
          end;
    end;
end;

procedure TForm1.TreeView1DragOver(Sender, Source: TObject; X, Y: Integer; State: TDragState; var Accept: Boolean);
begin
  Accept := true;
end;

Comments on Events

Event handlers are convenient places for developing LCL applications. There are some peculiar events for TTreeview.

When selected node is changed

procedure TForm1.TreeView1Change(Sender: TObject; Node: TTreeNode);

The OnChange event is fired when another node is selected. It can be used in a program to update some data.

procedure TForm1.TreeView1Changing(Sender: TObject; Node: TTreeNode; var AllowChange: Boolean);

The OnChanging event is called before OnChange, which allows you to prevent node selection under certain conditions. To do this, just set AllowChange to false. It is not necessary to set to true as this is the default value.

Please note that in Delphi the Node variable points to the node that leaves the selection. In Lazarus, the Node variable points to the node receiving the selection, but you can use the Selected property to find out the "previous" node.

In both events, the Node and Selected can be equal to nil (if there was no selection or it is being removed).

When a node is inserted

When a new node is inserted, related events occur in the following order.

      1) OnNodeChanged
      2) (OnChanging): This is called if there was a previously selected node.
      3) OnSelectionChanged
      4) OnChange

When deleting a node

When the selected node is deleted, the following events occur.

     1) OnDelete
     2) OnChanging
     3) SelectionChanged
     4) OnChange :  This is called because when you delete a node, another node is selected. 

If an unselected node is deleted, e.g. programmatically, then only the OnDelete event handler is called.

When Form is Closed

OnChanging event occurs, as the selected node is "de"selected. But OnChanging eventhander is executed AFTER the form is closed. This means that you cannot access the form's other data (other controls, other variables, etc.) within the OnChanging event handler procedure.

When Drag&Drop is done

When you drag a node to another node and drop, the following events occur.

     1) OnSelectionChanged
     2) OnNodeChanged
     3) OnChange

See also

• Drag and Drop sample
• TTreeView doc
• TListView
• VirtualTreeview