TcxCustomTreeList Class

The base class for Tree List controls.

Declaration

TcxCustomTreeList = class(
    TcxExtEditingControl,
    IcxNavigator,
    IcxStoredParent,
    IcxStoredObject,
    IcxTreeListDesignTimeOperations,
    IcxTreeListDesignTimeOperations2,
    IdxSkinSupport,
    IcxDataControllerConditionalFormattingProviderOwner,
    IcxFilterControl,
    IcxFilterControlEx
)

Remarks

A VCL Tree List (a TcxCustomTreeList descendant) is a hybrid control that allows you to display data in a grid, arrange a tree-like hierarchy, or display a combination of both.

VCL Tree List: A Tree List UI Example

Nodes and Columns

Tree List content is arranged into nodes and columns. Nodes correspond to data rows with values displayed in columns. Each node can include multiple expandable nested nodes.

VCL Tree List: A Tree List Column

In-Place Editors

A tree list column can use any editor shipped with the ExpressEditors Library as an in-place editor for cell edit operations. An in-place editor instance exists (and, therefore, has its own WinAPI handle) only when a column cell is being edited. Otherwise, the column displays a static editor image for resource usage optimization.

VCL Tree List: An In-Place Date Editor

To switch between all available in-place editors for a column, use the column’s PropertiesClass property. Use the Properties property to configure the in-place editor associated with the column.

Bands

Bands are additional headers designed to group columns. Each band can display a caption with support for BBCode-inspired formatting. Users can hide, display, and reorder bands and columns within bands.

VCL Tree List: Tree List Bands

Main API Members

The list below outlines key members of the TcxCustomTreeList class.

Appearance Settings

BorderStyle: Specifies if the skin-dependent border is visible.
FormattedText: Allow you to modify the appearance and behavior formatted text ranges defined in Tree List column and band captions that support BBCode-inspired markup.
LookAndFeel: Allows you to override global skin and palette settings at the Tree List control level.
OnCustomDrawBackgroundCell | OnCustomDrawBandCell | OnCustomDrawBandHeaderCell | OnCustomDrawIndentCell | OnCustomDrawIndicatorCell | OnCustomDrawPreviewCell: Allow you to override or complement individual Tree List draw routines.
OptionsView: Provides access to general appearance settings.
StateImages: Specifies the image source for Tree List node states.
Styles: Allows you to configure individual UI element appearance.

Built-in UI Element Management

FilterBox: Provides access to Filter Box settings.
FindCriteria: Provides access to search criteria and related settings that affect the Find Panel.
FindPanel: Provides access to Find Panel settings.
HideFindPanel | ShowFindPanel | IsFindPanelVisible: Manage Find Panel visibility.
Navigator: Provides access to data navigator settings.
PopupMenus: Provides access to context menu settings.
Preview: Allows you to display Microsoft Outlook-inspired preview sections and configure their settings.

User Interaction Options

Automation: Provides access to [UI Automation] and accessibility-related settings.

Tip
Use Automation.Name and Automation.Description, and other API members to specify information visible to third-party assistive tools as UIA node properties.
OptionsBehavior: Provides access to general Tree List behavior settings.
OptionsCustomizing: Provides access to end-user UI customization permissions.
OptionsSelection: Provides access to node and cell selection-related settings.
StoreDataViewState | RestoreDataViewState: Store/restore the user interaction state to/from memory during the same session.
StoreDataViewStateToStream | RestoreDataViewStateFromStream: Allow you to store the user interaction state between sessions.

CancelEdit: Closes the active in-place cell editor and discards pending changes.
HideEdit: Closes the active in-place cell editor and applies pending changes.
OnEdited: Allows you to execute custom code in response to in-place editor deactivation.
OnEditing: Allows you to prevent users from editing individual cells.
ShowEdit | ShowEditByKey | ShowEditByMouse: Activate an in-place editor for the focused cell.

Find | FindNodeByText: Search a Tree List node according to specified criteria.
FindNext: Navigates to the next or previous node that includes a match with the string assigned to the SearchingText property.
Searching: Identifies if an incremental search operation is underway.
SearchingText: Specifies the target search string for the FindNext function.

Node Structure Management

AbsoluteCount: Returns the total number of Tree List nodes (available using the AbsoluteItems property).
AbsoluteItems: Provides indexed access to all Tree List nodes (at all hierarchy levels).
AbsoluteVisibleCount: Returns the number of visible Tree List nodes (available using the AbsoluteVisibleItems property).
AbsoluteVisibleItems: Provides indexed access to all visible Tree List nodes (regardless of hierarchy levels).
AddNode: Adds a new Tree List node to the Tree List structure.
Count: Returns the number of Tree List nodes at the root level (nodes available using the Items property).
Clear: Deletes all nodes.
DeleteSelection: Deletes selected nodes.
Items: Provides indexed access to Tree List nodes at the root level.
Root: Provides access to the root node.
TopNode: Provides access to the first node.

Node Selection Management

ClearSelection: Deselects all selected nodes.
Deselect: Deselects an individual node.
OnCanSelectNode: Allows you to prevent users from selecting individual nodes.
OnSelectionChanged: Allows you to respond to node selection state changes.
Select: Selects specified nodes.
SelectAll: Selects all node if the OptionsSelection.MultiSelect setting is enabled.
SelectionCount: Returns the number of selected nodes accessible using the Selections property.
Selections: Provides indexed access to selected nodes.

Node State Management

OnExpanded | OnCollapsed: Allow you to execute custom code in response to node expand and collapse operations.
OnExpanding | OnCollapsing: Allow you to prevent users from expanding or collapsing nodes that meet specific criteria.
FullExpand | FullCollapse: Expand and collapse all nodes.

Column Management

Bands: Provides access to the bands collection.
CreateColumn: Creates a new Tree List column.
ColumnByName: Provides access to a Tree List column by name.
ColumnCount: Returns the number of Tree List columns available using the Columns property.
Columns: Provides indexed access to all Tree List columns.
DeleteAllColumns: Deletes all Tree List columns.
VisibleColumnCount: Returns the number of visible Tree List columns accessible using the VisibleColumns property.
VisibleColumns: Provides indexed access to visible columns.

Data Management

OptionsData: Provides access to general data-related settings.
OnDataChanged: Allows you to execute custom code in response to data post operations.
Post: Posts data changes to the underlying data storage.

Data Shaping & Analysis

ConditionalFormatting: Allows you to apply custom formatting to cells that meet certain criteria.
OnCompare: Allows you to implement custom sorting algorithms.
OnSorting | OnSorted: Allow you to execute custom code in response to sort operations.
Filter: Allows you to manage filter criteria.
Filtering: Provides access to filtering settings.
Sorted: Specifies if data is sorted by one or multiple columns.
SortedColumnCount: Returns the number of sorted columns accessible using the SortedColumns property.
SortedColumns: Provides indexed access to sorted columns.
Summary: Allows you to define group and footer summaries.

FocusedColumn | FocusedNode: Allow you to identify the focused column/node and move focus between columns/nodes.
OnCanFocusNode: Allows you to prevent users from moving focus to individual nodes.
OnFocusedColumnChanged | OnFocusedNodeChanged: Allow you to execute custom code in response to focus movement.
GotoBOF | GotoEOF: Move focus to the first or last node.
GotoNext | GotoPrev: Move focus between two adjacent nodes.
GotoNextPage | GotoPrevPage: Move focus and scroll content by one page down or up. A page includes the number of rows that fit into the Tree List client area.
ScrollbarAnnotations: Allows you to add and display scrollbar annotations that help users to quickly locate important entries and navigate between them using a vertical scrollbar.
SetFocusedNode: Moves focus to the target node.
TopVisibleNode | LastVisibleNode: Scroll content to display the specified node at the top or bottom border of the Tree List client area.

Data Layout/State Import & Export Options

StoreToIniFile | RestoreFromIniFile: Store/restore Tree List structure/data layout and user interaction states to/from an INI file.
StoreToRegistry | RestoreFromRegistry: Store/restore Tree List structure/data layout and user interaction states to/from the system registry.
StoreToStream | RestoreFromStream: Store/restore Tree List structure/data layout and user interaction states to/from a stream.

Tip

To export Tree List content to different target formats, use dedicated global export procedures declared in the cxTLExportLink unit. Refer to the following section for a complete list of available options: Tree List Content Export Functionality.

General-Purpose API Members

BeginUpdate | EndUpdate | CancelUpdate: Allow you to avoid excessive redraw operations during batch content and appearance changes.
FullRefresh: Updates the Tree List.

Tree List Content Export Functionality

Call the following global procedures to export Tree List content in corresponding formats:

cxExportTLToCSV | cxExportTLToCSVStream: Export Tree List content to a file or stream in the Comma-Separated Values (CSV) format.
cxExportTLToExcel | cxExportTLToExcelStream: Export Tree List content to a file or stream in the Microsoft Excel® binary (XLS) format.
cxExportTLToHTML | cxExportTLToHTMLStream: Export Tree List content to a file or stream in the HyperText Markup Language (HTML) format.
cxExportTLToText | cxExportTLToTextStream: Export Tree List content to a file or stream as plain text.
cxExportTLToXLSX | cxExportTLToXLSXStream: Export Tree List content to a file or stream in the Office OpenXML Spreadsheet (XLSX) format.
cxExportTLToXML: Exports Tree List content to a file in the Extensible Markup Language (XML) format.

Code Examples

Create and Populate Unbound Tree List Controls

The following code example creates a TcxTreeList control with three columns and populates it with nodes arranged into a tree-like hierarchy (in unbound mode):

Delphi
C++

uses
  cxTL;  // Declares the TcxTreeList control and related types
// ...

var
  ATreeList: TcxTreeList;
  ABand: TcxTreeListBand;
  AColumn: TcxTreeListColumn;
  ARootNode, ANode, AChildNode: TcxTreeListNode;
begin
  ATreeList := TcxTreeList.Create(Self);  // Creates a TcxTreeList control
  ATreeList.Parent := Self;  // Associates the created control with the parent form
  ATreeList.BeginUpdate;  // Initiates the following batch operation
  try
    ATreeList.Align := alClient;
    // Create a band and three columns
    ABand := ATreeList.Bands.Add;
    ABand.Caption.Text := 'General Information';
    AColumn := ATreeList.CreateColumn(ABand);
    AColumn.Caption.Text := 'Name';
    AColumn := ATreeList.CreateColumn(ABand);
    AColumn.Caption.Text := 'Distance (000km)';
    AColumn := ATreeList.CreateColumn(ABand);
    AColumn.Caption.Text := 'Period (days)';
    // Create all nodes and assign values
    ARootNode := ATreeList.Add;
    ARootNode.Values[0] := 'Sun';
    ANode := ATreeList.AddNode(nil, ARootNode, nil, tlamAddChild);
    ANode.Values[0] := 'Mercury';
    ANode.Values[1] := 57910;
    ANode.Values[2] := 87.97;
    ANode := ATreeList.AddNode(nil, ARootNode, nil, tlamAddChild);
    ANode.Values[0] := 'Venus';
    ANode.Values[1] := 108200;
    ANode.Values[2] := 224.7;
    ANode := ATreeList.AddNode(nil, ARootNode, nil, tlamAddChild);
    ANode.Values[0] := 'Earth';
    ANode.Values[1] := 149600;
    ANode.Values[2] := 365.26;
    AChildNode := ANode.AddChild;
    AChildNode.Values[0] := 'Moon';
    AChildNode.Values[1] := 384;
    AChildNode.Values[2] := 27.32;
    ARootNode.Expand(True);  // Expands all nodes starting from the root level
  finally
    ATreeList.EndUpdate;  // Calls EndUpdate regardless of the batch operation's success
  end;
  ATreeList.ApplyBestFit;  // Adjusts column width to fit all captions and content in full
end;

#include "cxTL.hpp"  // Declares the TcxTreeList control and related types

// Add the following linker directives to the corresponding CPP source file
#pragma link "cxTL" // Required to use cxTL.hpp declarations
// ...

  TcxTreeList *ATreeList;
  TcxTreeListBand *ABand;
  TcxTreeListColumn *AColumn;
  TcxTreeListNode *ARootNode, *ANode, *AChildNode;
  // ...

  ATreeList = new TcxTreeList(this);  // Creates a TcxTreeList control
  ATreeList->Parent = this;  // Associates the created control with the parent form
  ATreeList->BeginUpdate();  // Initiates the following batch operation
  try
  {
    ATreeList->Align = alClient;
    // Create a band and three columns
    ABand = ATreeList->Bands->Add();
    ABand->Caption->Text = "General Information";
    AColumn = ATreeList->CreateColumn(ABand);
    AColumn->Caption->Text = "Name";
    AColumn = ATreeList->CreateColumn(ABand);
    AColumn->Caption->Text = "Distance (000km)";
    AColumn = ATreeList->CreateColumn(ABand);
    AColumn->Caption->Text = "Period (days)";
    // Create nodes and assign values
    ARootNode = ATreeList->Add();
    ARootNode->Values[0] = "Sun";
    ANode = ATreeList->AddNode(nullptr, ARootNode, nullptr, tlamAddChild);
    ANode->Values[0] = "Mercury";
    ANode->Values[1] = 57190;
    ANode->Values[2] = 87.97;
    ANode = ATreeList->AddNode(nullptr, ARootNode, nullptr, tlamAddChild);
    ANode->Values[0] = "Venus";
    ANode->Values[1] = 108200;
    ANode->Values[2] = 224.7;
    ANode = ATreeList->AddNode(nullptr, ARootNode, nullptr, tlamAddChild);
    ANode->Values[0] = "Earth";
    ANode->Values[1] = 149600;
    ANode->Values[2] = 365.26;
    AChildNode = ANode->AddChild();
    AChildNode->Values[0] = "Moon";
    AChildNode->Values[1] = 384;
    AChildNode->Values[2] = 27.32;
    ARootNode->Expand(True);  // Expands all nodes starting from the root level
  }
  __finally
  {
    ATreeList->EndUpdate();  // Calls EndUpdate regardless of the batch operation's success
  }
  ATreeList->ApplyBestFit();  // Adjusts column width to fit both captions and content in full

VCL Tree List: Populate a Tree List with Nodes in Unbound Mode

Store Tree List State Between Sessions

The code example in this section demonstrates form OnDestroy and OnCreate event handlers. These handlers call StoreToStream and RestoreFromStream procedures to save and restore user interaction states (selection, focus, scroll position, etc.) in addition to the Tree List structure/data layout.

Delphi
C++

uses
  System.SysUtils,  // Declares the FileExists function
  cxTL,  // Declares TcxTreeList, TcxCustomTreeList, and related types
// ...

procedure TMyForm.FormCreate(Sender: TObject);
var
  AFileStream: TFileStream;
begin
  if FileExists('TreeListConfig.dat') then
  begin
    AFileStream := TFileStream.Create('TreeListConfig.dat', fmOpenReadWrite);
    try
      cxTreeList1.RestoreFromStream(AFileStream, True, False, '', cxTreeListStoreAllDataViewStates);
    finally
      AFileStream.Free;
    end;
  end;
end;

procedure TMyForm.FormDestroy(Sender: TObject);
var
  AFileStream: TFileStream;
begin
  AFileStream := TFileStream.Create('TreeListConfig.dat', fmCreate or fmOpenReadWrite);
  try
    cxTreeList1.StoreToStream(AFileStream, '', cxTreeListStoreAllDataViewStates);
  finally
    AFileStream.Free;
  end;
end;

#include "System.SysUtils.hpp"  // Declares the FileExists function
#include "cxTL.hpp"  // Declares TcxTreeList, TcxCustomTreeList, and related types

// Add the following linker directive to the corresponding CPP source file:
#pragma link "cxTL"  // Required to use cxTL.hpp declarations

void __fastcall TMyForm::FormCreate(TObject *Sender)
{
  TFileStream *AFileStream;
  if(FileExists("TreeListConfig.dat"))
  {
    AFileStream = new TFileStream("TreeListConfig.dat", fmOpenReadWrite);
    try
    {
      cxTreeList1->RestoreFromStream(AFileStream, true, false, "", cxTreeListStoreAllDataViewStates);
    }
    __finally
    {
      delete AFileStream;
    }
  }
}

void __fastcall TMyForm::FormDestroy(TObject *Sender)
{
  TFileStream *AFileStream = new TFileStream("TreeListConfig.dat", fmCreate | fmOpenReadWrite);
  try
  {
    cxTreeList1->StoreToStream(AFileStream, "", cxTreeListStoreAllDataViewStates);
  }
  __finally
  {
    delete AFileStream;
  }
}

Export Tree List Content to XLSX File

VCL Tree List: A Source Tree List Example

The following code example exports Tree List content to a file in the XLSX format:

Delphi
C++

uses
  cxTLExportLink,   // Declares global export procedures
  dxSplashForms,    // Declares the TdxSplashFormManager class and related types
  cxTL;             // Declares the TcxTreeList component
// ...

procedure TMyForm.cxButtonExportToXLSXClick(Sender: TObject);
var
  AStream: TMemoryStream;
begin
  AStream := TMemoryStream.Create;              // Creates a memory stream
  TdxSplashFormManager.WaitForm.Show(self);     // Displays a Wait Form before the export operation
  try
    // Export Tree List content to the created memory stream in the XLSX format
    cxExportTLToXLSXStream(AStream, cxTreeList1);
    AStream.SaveToFile('Departments.xlsx');    // Saves the resulting file
  finally
    AStream.Free;                               // Releases the memory stream
    TdxSplashFormManager.WaitForm.Hide;         // Hides the Wait Form once the operation is complete
  end;
end;

#include "cxTLExportLink.hpp"   // Declares global export procedures
#include "dxSplashForms.hpp"    // Declares the TdxSplashFormManager class and related types
#include "cxTL.hpp"             // Declares the TcxTreeList component

// Add the following linker directives to the corresponding CPP source file:
#pragma link "cxTLExportLink"   // Required to use cxTLExportLink declarations
#pragma link "cxTL"             // Required to use cxTL.hpp declarations
// ...

void __fastcall TMyForm::cxButtonExportToXLSXClick(TObject *Sender)
{
  TMemoryStream *AStream = new TMemoryStream();    // Creates a memory stream
  TdxSplashFormManager::WaitForm()->Show(this);    // Displays a Wait Form before the export operation
  try
  {
    // Export Tree List content to the created memory stream in the XLSX format
    cxExportTLToXLSXStream(AStream, cxTreeList1);
    AStream->SaveToFile("Departments.xlsx");     // Saves the resulting file
  }
  __finally
  {
    delete AStream;                               // Releases the memory stream
    TdxSplashFormManager::WaitForm()->Hide();     // Hides the Wait Form once the operation is complete
  }
}

The following image demonstrates exported content:

VCL Tree List: Exported Tree List Data in XLSX Format

To see the VCL Tree List in action, run the TreeView-Grid Hybrid demo in the VCL Demo Center installed with compiled DevExpress VCL demos. Click different items in the sidebar on the left to switch between demo features.

Download: Compiled VCL Demos

Compiled DevExpress demos ship with source code installed in the Public Documents folder (%PUBLIC%) for all users (default). You can find all project and source code files for the TreeView-Grid Hybrid demo in the following folder:

Default Installation Path

%PUBLIC%\Documents\DevExpress VCL Demos\MegaDemos\Product Demos\ExpressQuantumTreeList\

Terminal TcxCustomTreeList Class Descendants

Do not use the TcxCustomTreeList class directly. Use one of the following descendants that implement corresponding data access modes:

TcxDBTreeList: A data-aware Tree List control.
TcxTreeList: An unbound Tree List control.
TcxVirtualTreeList: A TreeList control used in provider mode.

Implements

IcxNavigator

IcxStoredParent

IcxStoredObject

IcxTreeListDesignTimeOperations

IcxTreeListDesignTimeOperations2

IdxSkinSupport

IcxDataControllerConditionalFormattingProviderOwner

IcxFilterControl

Inheritance

Show 11 items

TcxCustomTreeList

Controls

FREE UTILITIES

Controls and Extensions

FREE UTILITIES

.NET

Java

Controls

FREE UTILITIES

Controls and Extensions

FREE UTILITIES

.NET

Java

TcxCustomTreeList Class

Declaration

Remarks

Nodes and Columns

In-Place Editors

Bands

Main API Members

Appearance Settings

Built-in UI Element Management

User Interaction Options

Node Structure Management

Node Selection Management

Node State Management

Column Management

Data Management

Data Shaping & Analysis

Navigation & Focus Management

Data Layout/State Import & Export Options

General-Purpose API Members

Tree List Content Export Functionality

Code Examples

Create and Populate Unbound Tree List Controls

Store Tree List State Between Sessions

Export Tree List Content to XLSX File

Terminal TcxCustomTreeList Class Descendants

Implements

Inheritance

TcxCustomTreeList Class

Declaration

Remarks

Nodes and Columns

In-Place Editors

Bands

Main API Members

Appearance Settings

Built-in UI Element Management

User Interaction Options

In-Place Editor-Related APIs

Search-Related APIs

Node Structure Management

Node Selection Management

Node State Management

Column Management

Data Management

Data Shaping & Analysis

Navigation & Focus Management

Data Layout/State Import & Export Options

General-Purpose API Members

Tree List Content Export Functionality

Code Examples

Create and Populate Unbound Tree List Controls

Store Tree List State Between Sessions

Export Tree List Content to XLSX File

Related Compiled Demo

Terminal TcxCustomTreeList Class Descendants

Implements

Inheritance