Sunteți pe pagina 1din 1199

Introduction

Getting Started   Known Issues and Important Changes List   Built-in Touch Support   Built-in Per-Monitor DPI Awareness

The ExpressQuantumTreeList is a powerful control that can display information as a tree, a grid, or a combination of both – in
bound, unbound or virtual mode. This unique synergy between a traditional grid and a traditional treeview allows you to create
cutting-edge and visually appealing application interfaces for your end-users. With the ExpressQuantumTreeList, you can
create function-rich and responsive applications without having to write a single line of code.

Use the following links to find more information on the ExpressQuantumTreeList control:
Concepts
Feature Center
Visual Elements
Design-Time Features
End-User Capabilities
Task-Based Help

Page 1 of 1199
Getting Started
This topic describes the basics of a tree list and the fastest way for beginners to get started with the TreeList control.
The tree list is a list of data organized into a tree structure. In other words, it's a collection of hierarchically nested rows. To build
up the tree's structure it's essential to have dependencies between two fields in the rows. One field contains the current row's
unique identifier and the other the identifier of the row's parent. As shown in the image below, the ID field holds the current row's
identifier and the ParentID – an identifier of the parent row.

Every row in the tree list is called a node. The parent node may have an unlimited number of child nodes while the child node has
only one parent. To facilitate an end-user working with the tree list every parent node can be expanded or collapsed.

To learn how to prepare the control in the most simple way for using in your application refer to the Bind to a Data Source help
topic.

Concepts

l Concepts

Page 2 of 1199
Known Issues and Important Changes List
Overview

The following list groups all known issues and breaking changes associated with ExpressQuantumTreeList Suite releases by Builds
in descending order.

Build 46
Breaking Change – Previously, when using the StoreTo~/RestoreFrom~ methods, columns were restored within incorrect bands if
bands were moved after storing. This issue has now been fixed.

Build 45
Breaking Change – Previously, if the node height specified via the TreeList control's DefaultRowHeight property and a node did not
display its contents in their entirety, the specified property value was ignored. This validation has now been removed.

Build 44
1. Breaking Change – The report link unit compatible with the ExpressQuantumTreeList v5 is dxPScxTL5Lnk. To update your
projects from v4 to v5, you need to manually replace all dxPScxTLLnk entries with dxPScxTL5Lnk.

2. Breaking Change – The Sender parameter of most TreeList events represents a TcxCustomTreeList object (or
TcxCustomDBTreeList in bound tree lists). So, there is no need to explicitly cast this parameter to TcxCustomTreeList (or
TcxCustomDBTreeList) within your event handlers. To make them compilable, you need to replace TObject with TcxCustomTreeList or
TcxCustomDBTreeList in your event handlers.

3. Breaking Change – Now a column displays its footer cells by default (the TcxTreeListColumnOptions.Footer property is True by
default). To hide a column's footer cells, set the column's Options.Footer property to False.

4. Breaking Change – Now the TreeList control's OptionsBehavior.CellHints property enables hints for data cells only. To enable hints
for band and column headers and footer and group footer cells, use the OptionsBehavior.HeaderHints and
OptionsBehavior.FooterHints properties introduced in v5. By default, hints are disabled within the TreeList control.

5. Breaking Change – Now, end-users can nest bands by default. To disable this behavior for backward compatibility, set the
OptionsCustomizing.NestedBands property to False.

6. Breaking Change – Now, if the TreeList control's OptionsCustomizing.RowSizing option is enabled, end-users need only vertically
resize the first visible node to change the node height within the entire TreeList control. To allow end-users to resize individual nodes,
enable the OptionsCustomizing.NodeSizing option introduced in v5.

7. Breaking Change – Now, you should explicitly cast a TcxDBTreeList.Columns collection item to TcxDBTreeListColumn, to properly
access its data-aware properties.

8. Breaking Change – Now, to export the tree list, replace the cxExportTL4Link unit in the 'uses' clause with cxTLExportLink and
replace the cxExportTL4ToExcel, cxExportTL4ToHTML, cxExportTL4ToText, and cxExportTL4ToXML method calls with
cxExportTLToExcel, cxExportTLToHTML, cxExportTLToText, and cxExportTLToXML, respectively.

9. Breaking Change – Now, the TcxDBTreeListDataController inherits from the TcxDataTreeListDataController. The former
TcxDBTreeListDataController's parent – the TcxDBDataController – is no longer in the data controller inheritance hierarchy. Refer to
the TcxDBDataController description to learn about its members that are now not the part of the data-aware tree list's data controller
API.

10. Breaking Change – The tree list's BufferedPaint property has been made read only.

11. Breaking Change – Now, the tree list's HitTest.HitAtBand property determines the band background.
Page 3 of 1199
The tables below list classes, class members, and member parameters that have been renamed, replaced or removed in
ExpressQuantumTreeList v5.

Classes

v4 v5

TcxCustomTreeListControl TcxCustomTreeList

TcxTreeListDataNode TcxDBTreeListNode or
TcxVirtualTreeListNode

TcxTreeListFooterItemViewInfo TcxTreeListFooterCellViewInfo (the


AViewInfo parameter's type of the
OnCustomDrawFooterCell event)

TcxTreeListHeaderViewInfo TcxTreeListHeaderCellViewInfo (the


AViewInfo parameter's type of the
OnCustomDrawHeaderCell event)

TcxTreeListIndentViewInfo TcxTreeListIndentCellViewInfo (the


AViewInfo parameter's type of the
OnCustomDrawIndentCell event)

TcxTreeListIndicatorViewInfo TcxTreeListIndicatorCellViewInfo (the


AViewInfo parameter's type of the
OnCustomDrawIndicatorCell event)

Note:   The TcxTreeListColumnSummaryFooter class has been removed. Now, to manage footer summaries, use a column's
Summary.FooterSummaryItems collection or the TreeList control's Summary.FooterSummaryItems collection instead of a column's
SummaryFooter option set. At design time, a column's SummaryFooter option set is automatically converted to an item within the
column's Summary.FooterSummaryItems collection.

Properties

v4 v5

TcxDBTreeListDataController.StateIndexFieldName TcxDBTreeListDataController.StateIndexField

TcxTreeListDataNode.KeyValue TcxDBTreeListNode.KeyValue

TcxTreeListDataNode.ParentValue TcxDBTreeListNode.ParentKeyValue

TcxTreeListOptionsBehavior.AutomateLeftMostIndent Now an expandable column's width is not


decreased when collapsing nodes, as if this
property was disabled.

Methods

v4 v5

TcxCustomDataTreeList.FindNodeByKeyValue TcxCustomDBTreeList.FindNodeByKeyValue

TcxTreeListCustomizing.MakeBandSheetVisible TcxTreeListCustomizing.MakeBandPageVisible

TcxTreeListCustomizing.MakeColumnSheetVisible TcxTreeListCustomizing.MakeColumnPageVisible

Events

Page 4 of 1199
v4 v5
TcxCustomTreeListControl.OnAfterSorting TcxCustomTreeList.OnSorted

TcxCustomTreeListControl.OnCustomDrawBackground TcxCustomTreeList.OnCustomDrawBackgroundCell

TcxCustomTreeListControl.OnCustomDrawBandHeader TcxCustomTreeList.OnCustomDrawBandHeaderCell

TcxCustomTreeListControl.OnCustomDrawCell TcxCustomTreeList.OnCustomDrawDataCell

TcxCustomTreeListControl.OnCustomDrawPreview TcxCustomTreeList.OnCustomDrawPreviewCell

TcxCustomTreeListControl.OnCustomizationFormVisibleChanged TcxCustomTreeList.OnCustomizationVisibleChanged

TcxDBTreeList.OnGetUniqueKeyValue TcxCustomDBTreeList.OnGetUniqueKeyValue

Parameters and parameter types

API Member Parameter

v4 v5

TcxCustomDBTreeList.OnInitInsertingRecord Sender The Sender parameter's type has


been changed to
TcxCustomDBTreeList.

  AFocusedNode The AFocusedNode parameter's


type has been changed to
TcxDBTreeListNode.

TcxDBTreeList.OnGetUniqueKeyValue Sender The Sender parameter's type has


been changed to
TcxCustomDBTreeList.

TcxTreeListColumn.Values and Index ANode


TcxTreeListColumn.DisplayTexts

TcxTreeListNode.Create AOwner The AOwner parameter's type has


been changed to
TcxCustomTreeList.

TcxTreeListNode.GetNextChild, Value ANode


TcxTreeListNode.GetPrevChild,
TcxTreeListNode.HasAsParent, and
TcxTreeListNode.IndexOf

TcxTreeListStyles.OnGetContentStyle Sender The Sender parameter's type has


been changed to
TcxCustomTreeList.

  AItem AColumn
The parameter's type has been
changed to TcxTreeListColumn.

The following table contains API members that have been removed in the new release:

Removed API Member Substitute API Member in v5

cxTreeListDefBandHeaderLineCount 1

cxTreeListDefBands False

cxTreeListDefFooter False

cxTreeListDefColumnHeaders True

cxTreeListDefColumnAutoWidth False
Page 5 of 1199
cxTreeListDefWaitExpandTime 500

cxTreeListDefPreviewIndent 5

cxTreeListDefPreviewMaxLineCount 3

TcxCustomTreeListControl.BandPanelHeight –

TcxCustomTreeListControl.FooterPanelHeight –

TcxCustomTreeListControl.HeaderHeight –

TcxCustomTreeListControl.HeaderPanelHeight –

TcxCustomTreeListControl.InplaceColumnIndex –

TcxCustomTreeListControl.LevelIndentWidth –

TcxCustomTreeListControl.Nodes TcxCustomTreeList.AbsoluteItems

TcxCustomTreeListControl.TopVisibleIndex –

TcxCustomTreeListControl.VisibleBandCount TcxTreeListBandRows.VisibleItemCount

TcxCustomTreeListControl.VisibleBands TcxTreeListBandRows.VisibleItems

TcxCustomTreeListControl.Subselect TcxCustomTreeList.Select

TcxCustomTreeListControl.OnCustomDrawCellsGroup TcxCustomTreeList.OnCustomDrawBandCell

TcxCustomTreeListControl.OnCustomDrawFooter TcxCustomTreeList.OnCustomDrawFooterCell

TcxCustomTreeListControl.OnCustomDrawHeader TcxCustomTreeList.OnCustomDrawHeaderCell

TcxTreeListBands.GetAbsoluteIndex TcxTreeListBands.VisibleItems

TcxTreeListBands.GetVisibleIndex TcxTreeListBands.VisibleIndexOf

TcxTreeListColumn.IsLeftMost and TcxTreeListColumn.Position.VisibleColIndex


TcxTreeListColumn.IsRightMost

TcxTreeListColumn.OwnerBand TcxTreeListColumn.Position.Band

TcxTreeListColumn.OwnerBandRow TcxTreeListColumn.Position.Row

TcxTreeListColumn.RealMinWidth TcxTreeListColumn.IndentWidth +
TcxTreeListColumn.MinWidth

TcxTreeListColumn.RealWidth TcxTreeListColumn.DisplayWidth

TcxTreeListColumn.Visibility TcxTreeListColumn.ActuallyVisible

TcxTreeListColumn.VisibleIndexAtBand TcxTreeListColumn.Position.VisibleColIndex

TcxTreeListNode.Owner –

TcxTreeListNode.RecordIndex –

TcxTreeListNode.GetIsFirstVisible TcxTreeListNode.GetFirstChildVisible

TcxTreeListNode.GetIsLastVisible TcxTreeListNode.GetLastChildVisible

TcxTreeListNodes –

TcxTreeListOptionsView.BandLineCount Use the TcxTreeListOptionsView.BandLineHeight


property to specify the exact band height in pixels.

TcxTreeListOptionsView.HeaderSingleLine To emulate the removed functionality, set the


Position.LineCount property to 1 and the
Position.RowIndex property to 0 for all columns. To
prohibit end-users from vertically resizing column
headers, set the TreeList control's
OptionsCustomizing.ColumnVertSizing property to
Page 6 of 1199
False. To prohibit end-users from stacking columns,
OptionsCustomizing.StackedColumns property to
False.

Related Information

l TcxCustomTreeList.RestoreFromRegistry
l TcxCustomTreeList.RestoreFromStream
l TcxCustomTreeList.StoreToRegistry
l TcxCustomTreeList.StoreToStream

Page 7 of 1199
Data Loading Modes
The following data modes are provided in a tree list:

l Bound Mode
A tree list is connected to the TDataSource via the TcxDBDataController. The TcxDBTreeList control is used in this mode.
To learn how to link a tree list to the data source, refer to the Connecting to Data help topic.

l Provider Mode
The data is retrieved from a custom-structured data source. The TcxVirtualTreeList control is used in this mode.
To learn how to use a tree list in provider mode, refer to the Example: TreeList Provider Mode help topic.

l Unbound Mode
The data is not obtained from any data source, and is populated programmatically. The TcxTreeList control is used in this mode.
To learn how to use a tree list in unbound mode, refer to the Unbound Mode help topic.

Concepts

l Concepts

Page 8 of 1199
Options
ExpressQuantumTreeList has many features making it a very powerful and flexible data-aware control. Most of these features
are accessed via option sets. These options control the functionality and appearance of almost all of the TreeList elements.
Sometimes ExpressQuantumTreeList options affect other option sets, even if connections between them are not obvious.

The option sets available within the TreeList control include:


l OptionsBehavior, defining the TreeList's response to user actions via the mouse and keyboard.
l OptionsCustomizing, determining the runtime functionality of TreeList items and bands. These options determine whether
the end-user can move and resize TreeList columns and bands. These option settings can be overridden via code.
l OptionsData, controlling data manipulation in the TreeList control. These options control editing, inserting, deleting
records, etc.
l OptionsSelection, managing selection within the TreeList control. These options determine the visibility and appearance of
the selection bar, whether multiple nodes can be selected, whether individual cells can be focused instead of nodes, etc.
The OptionsSelection.CellSelect property affects the editing capability of the TreeList control. If this property value is
False, editing can only be implemented programmatically.
l OptionsView, controlling the appearance of the TreeList control. This option set defines the visibility, color, width and other
appearance settings of control elements.
l FindPanel, controlling the Find Panel's look & feel.
l Navigator, controlling the visibility and appearance of the navigator within the TreeList control. These options specify the
visibility of the navigator and its elements.
l Preview, managing the preview section of the TreeList control. These options specify the preview section visibility, the
column whose values are displayed within the preview section, the preview text position, etc.

TreeList elements (columns and bands) have their own option sets. These option sets are similar to the TreeList control's
OptionsCustomizing options and are used to override the TreeList settings for certain control elements. For instance, a user can
allow all TreeList columns to be moved via an appropriate option from the OptionsCustomizing set and prevent a particular
column from being moved via the column's Options.Moving property.

Concepts

l Concepts

Page 9 of 1199
Self-Referenced Dataset
A data-aware TreeList control is able to connect to any VCL dataset, however only self-referenced datasets are suitable for
ExpressQuantumTreeList. In other cases, the TreeList control will not be able to build a tree.
A self-referenced dataset is a dataset that has at least two fields: the Key field and the Parent field.
KeyField values uniquely identify records. The ParentField property designates the dataset field whose values define the record
position within a tree structure. The values of the ParentField specify the KeyField value of a record (node in the tree structure),
owning the current record (node).
If a record has a ParentField value without a corresponding key field value within the dataset, the record is displayed at the root of
the tree structure. Records with the same ParentField value are displayed as child records (nodes) of the record (node), whose
KeyField value matches the appropriate ParentField value.
The Key and Parent fields have to be of the same type. Here is an example of a self-referenced dataset and the data-aware
TreeList bound to this dataset:

Parent Key Name

-1 1 Corporate Headquarters

1 2 Sales and Marketing

2 3 Field Office: Canada

2 4 Field Office: East Coast

2 5 Field Office: East Coast

5 6 Field Office: Singapore

5 7 Field Office: Japan

2 8 Marketing

2 9 Finance

1 10 Engineering

Concepts

l Concepts

Page 10 of 1199
Feature Center
Section Navigator

The topics in the following sections provide detailed information related to specific features in the ExpressQuantumTreeList
control:
l Data Exchange
l Bind to a Data Source
l Copy Data to the Clipboard
l Export Data
l Print Data

l Data-Related Features
l Cell Value Formatting
l Footer Summaries
l Group Summaries
l In-place Editors
l Sorting Data
l Source Data Persistence

l Layout Features
l Categorized Columns
l Customization Form
l Expandable Bands
l Fixed Bands
l Multi-Line Cells
l Nested Bands
l Save and Restore Layout
l Stacked Columns

l Focus and Selection


l Navigation and Scrolling
l Selection

l Appearance
l Custom Draw
l Style Customization

Page 11 of 1199
Data Exchange
Feature Center

The topics in this section describe the ways in which you can supply data for the ExpressQuantumTreeList control, export its
data to a file in various formats, print its contents, etc.

The following topics are available:


l Bind to a Data Source
l Copy Data to the Clipboard
l Export Data
l Print Data

Page 12 of 1199
Bind to a Data Source
Feature Center   Data Exchange

To begin working with the TreeList control, consider an example for the TcxDBTreeList data-aware TreeList control (located on
the Dev Express page).
If the TreeList control is a data-aware control, it can be populated by hierarchically organized data if the underlying dataset contains
two fields that relate to each other as parent-child. These fields should be defined using the same type. A dataset containing these
types of fields is called a self-referenced dataset. The following image shows the structure of the DEPARTMENTS.DB table which
was created in Paradox® format:

The ID and ParentID fields are related fields. To inform the data-aware TreeList control which fields in a dataset are responsible for
building the tree structure in the control use the TcxDBTreeListDataController.KeyField and TcxDBTreeListDataController.ParentField
properties. At design time in the Object Inspector, bind the TcxDBTreeListDataController.KeyField property to the ID field and the
TcxDBTreeListDataController.ParentField property to the ParentID field, as demonstrated in the image below:

To create the tree structure in the control and populate it with data from the dataset, double-click the TreeList control to invoke the
Component Editor. In this editor, click the Columns tab and then click the Create all fields button:

Page 13 of 1199
You can also use the context menu as an alternative way of populating the control. To perform this operation, right-click the TreeList
control and select the Create all columns menu item from the pop-up menu.
For details on how to set up a connection to the database using the BDE or ADO data service please refer to the Connecting to Data
help topic.
This is the result when the application runs:

Concepts
Data Loading Modes
Columns
Refresh Data

Member Table
Member Table: Bind to a Data Source

Page 14 of 1199
Copy Data to the Clipboard
Feature Center   Data Exchange

A tree list is capable of transferring data to other applications using the system clipboard. It provides the following methods used
to programmatically perform basic clipboard operations:
l TcxCustomTreeList.CopyAllToClipboard – Copies all nodes to the clipboard as text.
l TcxCustomTreeList.CopySelectedToClipboard – Copies selected nodes to the clipboard as text.

Page 15 of 1199
Export Data
Feature Center   Data Exchange

The ExpressQuantumTreeList allows you to export its display data to a file in CSV, HTML, XML, TXT, XLSX (Microsoft Excel
2007 or later) or XLS (Microsoft Excel 97-2003) format. When exporting, you copy data from the tree list into a new file to be used
in another application. Note that the results of custom drawing and images cannot be exported.

To export data, add the cxExport and cxTLExportLink units to the 'uses' clause, and call an appropriate export procedure.

The following code snippet shows how to export the tree list's content to an XLSX file.

[Delphi]
uses
//...
..., cxExport, cxTLExportLink;
//...
cxExportTLToXLSX('c:\export', TreeListControl);

[C++ Builder]
//...
#pragma link "cxExport"
#pragma link "cxTLExportLink"
//...
cxExportTLToXLSX("c:\export", TreeListControl);

Member Table
Member Table: Export Data

Page 16 of 1199
Related Information

l cxExportTLToExcel Procedure
l cxExportTLToHTML Procedure
l cxExportTLToText Procedure
l cxExportTLToXLSX Procedure
l cxExportTLToXML Procedure

Page 17 of 1199
Print Data
Feature Center   Data Exchange

All Developer Express VCL controls can be printed by means of our advanced ExpressPrinting System. All you need to do is to
create an appropriate report link for a control, and use it to adjust print settings and call the printing routine. Moreover, the
ExpressPrinting System allows end-users to fine-tune reports via an easy-to-use runtime interface loaded with a number of
options.

Note:   The ExpressPrinting System must be installed separately.

To print the ExpressQuantumTreeList control, add the dxPScxTL5Lnk unit to the 'uses' clause and create a report link that
corresponds to the control.

Task-Based Help
How to Display Print Preview and Print the Tree List

Page 18 of 1199
Data-Related Features
Feature Center

The topics in this section describe the data-related features that are provided by the ExpressQuantumTreeList. These include
in-place editors, value formatting, sorting data, using summaries, etc.

The following topics are available:


l Cell Value Formatting
l Footer Summaries
l Group Summaries
l In-place Editors
l Sorting Data
l Source Data Persistence

Page 19 of 1199
Cell Value Formatting
Feature Center   Data-Related Features

The ExpressQuantumTreeList control allows you to format the display text of its data, footer, and group footer cells before they
are displayed onscreen.

For data cells, you can use a column's in-place editor, which provides value formatting options according to the editor type.
Alternatively, you can implement a custom format by handling the column's OnGetDisplayText event.
For footer and group footer cells, you can specify the formatting pattern via a summary's Format property. A custom format can
be implemented by handling the summary's OnGetText event.

Concepts
In-place Editors

Page 20 of 1199
Footer Summaries
Feature Center   Data-Related Features

Footer summaries represent summaries that are calculated against all nodes and displayed within footer cells. They are specified
via a column's Summary.FooterSummaryItems collection.

You can use built-in functions or manually calculate summary values by handling the TreeList control's OnSummary event. You
can opt to include all nodes for the calculation base or calculate using only the root level nodes. End-users can specify the
required summary types and adjust summary options via the footer context menu.

End-User Capabilities
Calculating Summaries

Task-Based Help
Creating Summaries

Member Table
Member Table: Footer Summaries

Page 21 of 1199
Group Summaries
Feature Center   Data-Related Features

Group summaries represent summaries that are calculated against groups of nodes with the same parent. Summary values are
displayed within the parent's group footer cells. Use a column's Summary.GroupFooterSummaryItems collection to specify these
summaries.

You can use built-in functions or manually calculate summary values by handling the TreeList control's OnSummary event. You
can opt to include all child nodes for the calculation base or calculate using only the immediate child nodes. End-users can
specify the required summary types and adjust summary options via the group footer context menu.

End-User Capabilities
Calculating Summaries

Task-Based Help
Creating Summaries

Member Table
Member Table: Group Summaries

Page 22 of 1199
In-place Editors
Feature Center   Data-Related Features

The TreeList control provides the ability to use different editors to edit column values. There are a number of editors that can be
used for this purpose.

When a column is bound to a data source field, an editor corresponding to the bound field type is assigned to the column. For
instance, if a column is bound to a Boolean field, a check box (TcxCheckBox) is used to edit column values. The
correspondence of field types to default editors is presented in the cxEditDBRegisteredRepositoryItems unit. You can change
the default editors via the DBRepositoryItemClasses array declared in this unit.

If the default editor does not suit your needs, you can assign an appropriate editor explicitly to columns. The assignment of a
specific editor to an item can be done in two ways: via the repository or by using an editor's properties class.

Repository
A repository (TcxEditRepository) represents storage of repository items each of which defines properties specific to the
corresponding editor. There is a repository item for every editor in the ExpressEditors Library.

Page 23 of 1199
After you have added a repository item, you can adjust its properties in the Object Inspector.

To assign an editor to a column, you have to set the column's RepositoryItem property.

Page 24 of 1199
The advantage of using repository items is that you can assign a single one to several columns, thus providing the same
behavior.

The Editor Properties Class


Every column has a Properties property and this can be used to assign a particular editor to a column. After setting Properties,
you can access and modify the editor's properties via the Properties object's sub-properties.

At design time, you can use the Object Inspector to assign the editor's properties. The column's Properties property provides a
drop-down list containing all available editors.

Selecting an item from this list initializes the PropertiesClass property with the corresponding editor's properties class. For
instance, the TcxTimeEditProperties class holds the properties necessary for time edit fields.

To customize the properties of the assigned editor, expand the Properties entry in the Object Inspector:

Page 25 of 1199
When both Properties and RepositoryItem are assigned, the editor is determined by the RepositoryItem object.

Multi-Editor Cells
You can dynamically specify a cell's in-place editor type by handling a column's OnGetEditingProperties event. To dynamically
specify a cell's display value formatting editor type, handle a column's OnGetEditProperties event.

Sizing Modes in Multi-Line Editors


Use the EditAutoHeight property to switch the sizing mode for multi-line in-place editors.

Related Information

l TcxTreeListOptionsBehavior.EditAutoHeight

Page 26 of 1199
Sorting Data
Feature Center   Data-Related Features

To preserve the tree-like structure of data displayed within the TreeList control, nodes are sorted with respect to their nesting levels. F
nodes are sorted. Then, the tree list sorts the immediate child nodes of each root level node. This process is repeated recursively until
hierarchy has been sorted. The order in which sorting is performed is specified by a column's SortOrder property, and is indicated by a
displayed within the column's header.

The image below displays the original data within the TreeList control and its arrangement after sorting by a column's values in ascend

The ExpressQuantumTreeList allows you to sort data by the values of multiple columns. If two or more columns are involved in sortin
sorted sequentially as specified by a column's SortIndex property. First, data is sorted by the values of the first column, as described a
second column only affects sorting for nodes belonging to the same parent node (group) with identical values within the first column.

The following image shows how the second column affects the node order. The Budget column is initially sorted. However, it contains i
within one group. Thus, including the Vacation column in sorting changes the node order.

You can disable sorting within the TreeList control and sorting by multiple columns or by individual columns via the control's OptionsB
and OptionsBehavior.MultiSort property or a column's Options.Sorting property

You can also provide custom sorting logic for nodes by handling the TreeList control's OnCompare event or calling a node's CustomSo

The TreeList control uses multi-threaded algorithms to improve performance when sorting nodes. Refer to the Multi-Threaded Data Pro
to learn more.

End-User Capabilities
Sorting Nodes
Page 27 of 1199
Source Data Persistence
Feature Center   Data-Related Features

You can persist an unbound TreeList control's source data across multiple work sessions. To accomplish this, you can call the
control's SaveToFile or SaveToStream method to store its data to a file or stream. To load stored data from a file or stream to the
control, call its LoadFromFile or LoadFromStream methods. You can load source data to any unbound TreeList control, provided
that its structure matches the structure of the data source being loaded (i.e. column data types and ItemIndex property values
match).

Related Information

l TcxTreeListColumn.DataBinding

Page 28 of 1199
Layout Features
Feature Center

The topics in this section describe the ways in which you can manage the layout of the ExpressQuantumTreeList. These
include changing the layout of columns, bands, and data cells, saving and restoring the TreeList control's overall layout, etc.

The following topics are available:


l Categorized Columns
l Customization Form
l Expandable Bands
l Fixed Bands
l Multi-Line Cells
l Nested Bands
l Save and Restore Layout
l Stacked Columns

Page 29 of 1199
Categorized Columns
Feature Center   Layout Features

A categorized column is a column that provides category values for group nodes. Only one categorized column can be specified
at a time.
The following image shows a TreeList control with its Editor Name column set as a categorized column:

Member Table
Member Table: Categorized Columns

Page 30 of 1199
Customization Form
Feature Center   Layout Features

The customization form allows end-users to change the visibility of a band or column using drag-and-drop operations. The
headers of hidden bands and columns are contained in the customization form in the associated tabs. Headers in tabs are
displayed in alphabetical order.

To hide a band or a column, drag its header to the customization form. While dragging, a corresponding tab (Bands or Columns)
is automatically activated for the header being dragged.
The customization form can be invoked by end-users using the column header context menu.

The table below lists the main properties that relate to the customization form.

Window Instance The tree list's Customizing property.

Visibility The tree list's Customizing.Visible property. The OnCustomizationVisibleChanged event is


fired after the form's visibility has been changed.

Bounds The tree list's Customizing.RowCount property.

Contents The tree list's OptionsView.SimpleCustomizeBox and OptionsView.Bands properties.


The Options.Hidden property of a column or band.

Localization The scxCustomizeCaption, scxColumnsCaption, and scxBandsCaption resource strings.

End-User Capabilities
Controlling the Visibility of Bands and Columns

Related Information

l Column Header
l TcxTreeListColumnOptions.Hidden

Page 31 of 1199
Expandable Bands
Feature Center   Layout Features

A band that displays node expand buttons is called an expandable band. The column in which node expand buttons are
displayed is called an expandable column.
You can specify whether a band is expandable via its Expandable property.

If none of the visible bands are set as expandable, expand buttons are not displayed in the tree list. In this instance, end-users
can expand or collapse nodes by double-clicking nodes or node indicator cells.

End-User Capabilities
Expanding and Collapsing Nodes

Member Table
Member Table: Expandable Bands

Page 32 of 1199
Fixed Bands
Feature Center   Layout Features

You can anchor a band to the left or right side of the TreeList control so that the band's header, child bands, and columns don't
take part in horizontal scrolling. Scrollable content is separated from fixed bands using fixed band separators.

Once fixed, a band cannot be freely moved within the control – it can only be repositioned within bands that are anchored to the
same side. Use a band's FixedKind property to specify the TreeList control's side to which the band is anchored. You can
anchor any number of bands in this manner.

Concepts
Navigation and Scrolling

End-User Capabilities
Navigating Through Cells

Member Table
Member Table: Fixed Bands

Page 33 of 1199
Multi-Line Cells
Feature Center   Layout Features

You can make a column's cells span across multiple lines. To adjust a cell's height, use a column's Position.LineCount property.
As a result, the height of data, footer, and group footer cells and the column header panel is adjusted accordingly.

Alternatively, you can enable the TreeList control's OptionsView.CellAutoHeight option to allow the height of data cells to be
automatically adjusted to fit their contents.

End-User Capabilities
Resizing Bands and Columns

Related Information

l Footer Cell
l Group Footer Cell
l ExpressPivotGrid: Data Cell

Page 34 of 1199
Nested Bands
Feature Center   Layout Features

Each band can own a collection of child bands, thus building a hierarchical band structure. Moving a band within the hierarchy or
changing its visibility affects all its child bands and their columns. This allows users to easily customize band/column layout,
while keeping related bands and columns together.

In a nested band layout, only bottom bands contain columns. Moving a bottom band higher within a hierarchy automatically
moves its columns to the first visible child bottom band.

Use a band's Position.BandIndex property to specify the parent band. End-users can change band nesting by moving band
headers using drag and drop. To prohibit these operations, set the TreeList control's OptionsCustomizing.NestedBands property
to False.

End-User Capabilities
Reordering Bands and Columns

Member Table
Member Table: Nested Bands

Page 35 of 1199
Save and Restore Layout
Feature Center   Layout Features

The ExpressQuantumTreeList control's layout information contains the following attributes of its bands and columns:
l Position
l Width
l Caption
l Visibility
l Height (for columns only)
l Sort index (for columns only).
Layout information can be saved and then re-applied to this tree list later. This allows you to reset the tree list's layout to its
default at any time.

You can customize the manner in which layout attributes are saved for the tree list and individual columns and bands, by
handling the OnGetStoredProperties, OnGetStoredPropertyValue, OnGetStoredPropertyValue, and OnInitStoredObject events.

Member Table
Member Table: Save and Restore Layout

Related Information

l TcxTreeListBand.OnGetStoredProperties
l TcxTreeListBand.OnGetStoredPropertyValue
l TcxTreeListBand.OnSetStoredPropertyValue
l TcxTreeListBand.Width
l TcxTreeListColumn.Caption
l TcxTreeListColumn.MinWidth
l TcxTreeListColumn.OnGetStoredProperties
l TcxTreeListColumn.OnGetStoredPropertyValue
l TcxTreeListColumn.OnSetStoredPropertyValue
l TcxTreeListColumn.Position
l TcxTreeListColumn.Visible
l TcxTreeListColumn.Width

Page 36 of 1199
Stacked Columns
Feature Center   Layout Features

Columns can be arranged in rows (stacked). To accomplish this in code, you can assign a column's Position.RowIndex property
or call its Position.SetPositionEx method. End-users can stack columns by vertically repositioning their headers within the
column header panel, using drag and drop. Data cell layout will be updated accordingly.

To prohibit end-users from stacking columns, set the TreeList control's OptionsCustomizing.StackedColumns property to False.

End-User Capabilities
Reordering Bands and Columns

Member Table
Member Table: Stacked Columns

Page 37 of 1199
Focus and Selection (Overview)
Feature Center

The topics in this section provide information on moving focus between cells, scrolling the TreeList control's contents, and
selecting data cells via code.

The following topics are available:


l Navigation and Scrolling
l Selection

Page 38 of 1199
Navigation and Scrolling
Feature Center   Focus and Selection

A tree list provides members that allow you to perform focus navigation between nodes and data cells.
Navigation can also be performed without moving focus. For this purpose, use a node's or column's MakeVisible method. If
called, the method only scrolls the View in order to display a node or a column if they are beyond the View's boundaries.

End-User Capabilities
Focusing and Selecting Nodes
Navigating Through Cells

Member Table
Member Table: Navigation and Scrolling

Related Information

l TcxTreeListNode.MakeVisible

Page 39 of 1199
Selection
Feature Center   Focus and Selection

A tree list provides a set of members that allow you to perform selection operations on the nodes when the multi-select feature is
enabled (the tree list's OptionsSelection.MultiSelect option is active).

End-User Capabilities
Focusing and Selecting Nodes

Member Table
Member Table: Selection

Page 40 of 1199
Appearance
Feature Center

The ExpressQuantumTreeList provides a number of ways to customize its appearance. These include:
l Styles – you can apply a common style for a group of identical visual elements at once, or specify an individual style for
each element.
l Custom Drawing – every element in the view can be painted manually.
l Style Sheets – provides a set of predefined style schemes for all visual elements of the TreeList control (see the
Styles.StyleSheet property). In addition to the predefined styles, you can specify your own style scheme and save it in the
style repository (see the TcxPropertiesStore) for further use across different applications.

l The TcxLookAndFeelController component – allows you to apply the overall painting scheme for the entire TreeList
control, as well as for other proprietary controls.

Page 41 of 1199
Custom Draw
Feature Center   Appearance

This topic describes custom draw events used to manually paint the tree list's visual elements.
The following image shows the tree list's content:

All events provide a unified parameter list to facilitate coding. This includes:
Sender – specifies the tree list.
ViewInfo – provides the ViewInfo information used to paint elements. Generally, you will only need to use a few properties of
ViewInfo. The other properties are used by the control for internal purposes.
The most frequently used ViewInfo properties include:
l BoundsRect – provides the coordinates of the element's bounding rectangle.
l ViewParams – specifies the style settings.

ACanvas – specifies the drawing surface on which a tree list element is painted. Since this parameter specifies the control's
canvas, use the AViewInfo.BoundsRect property instead, to determine the element's bounding rectangle.
ADone – specifies whether default painting is required. If ADone is True, the default code is not executed.

Member Tables
Member Table: Appearance
Page 42 of 1199
Task-Based Help
l How to Custom Paint the Tree List Background
l How to Custom Paint Band Backgrounds
l How to Custom Paint Band Headers
l How to Custom Paint Column Headers
l How to Custom Paint Data Cells
l How to Custom Paint Footer Cells
l How to Custom Paint Indent Cells
l How to Custom Paint Node Indicators
l How to Custom Paint Previews

Page 43 of 1199
Style Customization
Feature Center   Appearance

A tree list provides two ways of painting with styles:


l Style settings – allow you to customize the appearance of a group of identical visual elements.
l Style events – allow you to paint each element individually.

The following priority rules are applied to style settings:


l Style settings of child elements override style settings of their containers all the way up the container hierarchy.
l Style events take priority over style settings.

Member Tables
Member Table: Appearance

Page 44 of 1199
Visual Elements
Section Navigator

The topics in this section describe the TreeList control's elements that you see on screen. Each topic contains a screenshot
that outlines the described element, and a brief overview of the element's purpose. Additionally, each topic contains the list of
settings that specify the element's visibility, content, behavior, and appearance. For general information on these elements, refer
to the TreeList Elements Review topic.

The following topics are available:


Band
Band Header
Band Header Panel
Column
Column Header
Column Header Panel
Data Cell
Expand Button
Find Panel
Fixed Band Separator
Footer
Footer Cell
Grid Line
Group Footer
Group Footer Cell
Header Panel
Indent Cell
Navigator
Node
Node Indicator
Preview
Quick Band Customization Button
Quick Column Customization Button
Tree Line

Page 45 of 1199
Band
Visual Elements

The ExpressQuantumTreeList allows end-users to combine columns into bands. A band represents a logical group that can
contain any number of related columns.

All the end-user operations with a band can be carried out using its header.

For more information regarding band functionality, please refer to the following topics:
l Nested Bands
l Fixed Bands
l Expandable Bands

The table below lists the main properties that relate to bands.

Visibility A band's Visible property.

Appearance The TreeList control's Styles.BandBackground, Styles.BandContent and


Styles.BandHeader properties, or a band's Styles property.
To dynamically customize these style settings, handle the TreeList control's
Styles.OnGetBandBackgroundStyle, Styles.OnGetBandContentStyle, and
Styles.OnGetBandHeaderStyle events.

Page 46 of 1199
Custom Draw Event The TreeList control's OnCustomDrawBandCell and OnCustomDrawBandHeaderCell
events.

Contents A band's Caption, ChildBands, and Columns properties.

Behavior The TreeList control's OptionsCustomizing.BandCustomizing,


OptionsCustomizing.BandHiding, OptionsCustomizing.BandHorzSizing,
OptionsCustomizing.BandMoving, OptionsCustomizing.BandsQuickCustomization,
OptionsCustomizing.BandVertSizing, and OptionsCustomizing.NestedBands properties.
A band's Options, FixedKind, and Expandable properties.

HitTest Information The TreeList control's HitTest.HitAtBand property.

Page 47 of 1199
Band Header
Visual Elements

Band headers identify bands in the tree list. All band headers are located in the band header panel.

Bands can be moved within the tree list by dragging their headers and can be resized by dragging header edges. Moving and
sizing a band's header or changing its visibility affects all its columns and child bands and automatically adjusts the band header
panel's height. You can prohibit bands from being resized or moved within the tree list.

The table below lists the main properties that relate to band headers.

Visibility The TreeList control's OptionsView.Bands property.

Position A band's Position property.

Appearance The TreeList control's Styles.BandHeader or a band's Styles.Header property.


To dynamically customize these style settings, handle the TreeList control's
Styles.OnGetBandHeaderStyle event.
Use the TreeList control's OptionsView.ExtPaintStyle property to customize the appearance
of band headers when the UltraFlat style is applied to the TreeList control.

Custom Draw Event The TreeList control's OnCustomDrawBandHeaderCell event.

Contents A band's Caption property.

Behavior The TreeList control's OptionsCustomizing.BandCustomizing,


OptionsCustomizing.BandHiding, OptionsCustomizing.BandHorzSizing,
OptionsCustomizing.BandMoving, OptionsCustomizing.BandsQuickCustomization,
OptionsCustomizing.BandVertSizing, and OptionsCustomizing.NestedBands properties.
A band's Options, FixedKind, and Expandable properties.

Size The TreeList control's OptionsView.BandLineHeight property.


A band's Width property.

Hints The TreeList control's OptionsBehavior.HeaderHints property.

HitTest Information The TreeList control's HitTest.HitAtBandHeader property.

Page 48 of 1199
Band Header Panel
Visual Elements

The band header panel displays the headers of visible bands. The band header panel and the column header panel comprise the
header panel.

The table below lists the main properties that relate to the band header panel.

Visibility The TreeList control's OptionsView.Bands property.

Appearance The TreeList control's Styles.BandHeader or a band's Styles.Header property.


To dynamically customize these style settings, handle the TreeList control's
Styles.OnGetBandHeaderStyle event.

Custom Draw Event The TreeList control's OnCustomDrawBandHeaderCell event.

Size The TreeList control's OptionsView.BandLineHeight property.

HitTest Information The TreeList control's HitTest.HitAtBandHeader property.

Page 49 of 1199
Column
Visual Elements

A column corresponds to a data source field that provides data for:


l Data cells and preview sections.
l Footer and group summaries.

The column layout determines the position and size of data cells within a node.

All the end-user operations with a column (such as layout customization, sorting data, etc.) can be carried out using its header.

Visible columns are always associated with a certain band. If a column is not associated with any band, it's hidden within the
TreeList control.

To learn more about column functionality, please refer to the following topics:
l Categorized Columns
l Stacked Columns

Sorting
You can sort nodes against column values via a column's SortOrder property. End-users can add or remove columns used for
sorting by clicking column headers while holding down the Shift or Ctrl key.

Page 50 of 1199
The table below lists the main properties that relate to columns.

Visibility The TreeList control's OptionsView.Headers property or a column's Visible property.

Appearance The TreeList control's Styles.ColumnHeader property, or a column's Styles.Header


property.
To dynamically customize style settings, handle the TreeList control's
Styles.OnGetColumnHeaderStyle event.
Use the TreeList control's OptionsView.ExtPaintStyle property to customize the appearance
of column headers when the UltraFlat style is applied to the control.

Custom Draw Event The TreeList control's OnCustomDrawHeaderCell event.

Contents A column's Properties, DataBinding, Options.ShowEditButtons, and


Options.CellEndEllipsis properties and OnGetDisplayText event.
The TreeList control's OptionsView.CellEndEllipsis and OptionsView.ShowEditButtons
properties.

Sort Order The TreeList control's SortedColumns property.


A column's SortOrder property.

Summaries The TreeList control's Summary.FooterSummaryItems and


Summary.GroupFooterSummaryItems properties.
A column's Summary.FooterSummaryItems and Summary.GroupFooterSummaryItems
properties.

Behavior The TreeList control's OptionsCustomizing.ColumnCustomizing,


OptionsCustomizing.ColumnHiding, OptionsCustomizing.ColumnHorzSizing,
OptionsCustomizing.ColumnMoving, OptionsCustomizing.StackedColumns,
OptionsCustomizing.ColumnsQuickCustomization,
OptionsCustomizing.ColumnVertSizing, OptionsBehavior.Sorting, and
OptionsBehavior.MultiSort, properties.
A column's Options property.
A band's Options.OnlyOwnColumns property.

HitTest Information The TreeList control's HitTest.HitAtColumn property.

Related Information

l TcxTreeListColumn.DataBinding

Page 51 of 1199
Column Header
Visual Elements

Column headers identify columns in the tree list. All column headers are located in the column header panel.

A column header contains:


l A caption string that identifies the column's content.
l A caption glyph that provides graphical information about the column's content.
l A sort glyph that identifies the sort order applied to the column's values.

Columns can be moved within the tree list by dragging their headers, and can be resized by dragging header edges. Moving and
sizing a column's header or changing its visibility affects all data and summary cells that correspond to this column and
automatically adjusts the column header panel's height. You can prohibit columns from being resized or moved within the tree
list, as well as prohibit bands from accepting columns of other bands.

The table below lists the main properties that relate to column headers.

Visibility The TreeList control's OptionsView.Headers property.

Position A column's Position property.

Appearance The TreeList control's Styles.ColumnHeader property, or a column's Styles.Header


property.
To dynamically customize style settings, handle the TreeList control's
Styles.OnGetColumnHeaderStyle event.
Use the TreeList control's OptionsView.ExtPaintStyle property to customize the appearance
of column headers when the UltraFlat style is applied to the control.

Custom Draw Event The TreeList control's OnCustomDrawHeaderCell event.

Contents A column's Caption.Text, Caption.Glyph, and SortOrder properties.

Behavior The TreeList control's OptionsCustomizing.ColumnCustomizing,


OptionsCustomizing.ColumnHiding, OptionsCustomizing.ColumnHorzSizing,
OptionsCustomizing.ColumnMoving, OptionsCustomizing.StackedColumns,
OptionsCustomizing.ColumnsQuickCustomization,
OptionsCustomizing.ColumnVertSizing, OptionsBehavior.Sorting, and
OptionsBehavior.MultiSort properties.
 
A column's Options property.

Size The TreeList control's OptionsView.ColumnAutoWidth and OptionsView.HeaderAutoHeight


properties.
Page 52 of 1199
properties.
A column's Position.LineCount and Width property.

Context Menu Refer to the Column Header Context Menu topic.

Hints The TreeList control's OptionsBehavior.HeaderHints property.


A column's StatusHint property.

HitTest Information The TreeList control's HitTest.HitAtColumnHeader property.

Related Information

l Group Footer Cell

Page 53 of 1199
Column Header Panel
Visual Elements

The column header panel is located below the band header panel. The column header panel displays the headers of visible
columns. The band header panel and the column header panel comprise the header panel.

The table below lists the main properties that relate to the column header panel.

Visibility The TreeList control's OptionsView.Headers property.

Appearance The TreeList control's Styles.BandBackground property.


To dynamically customize these style settings, handle the TreeList control's
Styles.OnGetBandBackgroundStyle event.

Custom Draw Event The TreeList control's OnCustomDrawBandCell event.

HitTest Information The TreeList control's HitTest.HitAtBandContainer property.

Page 54 of 1199
Data Cell
Visual Elements

A node's data cells display values of the data store record that the node represents. In editable data cells (see the tree list's
OptionsData.Editing property), values can be modified using associated in-place editors.

The position and size of the data, footer, and group footer cells are determined by the column header layout. End-users can
adjust a cell's width, and make it span across multiple lines.
In group nodes, a categorized column's cell occupies the entire node (spans all the columns). The number of visible data cells
varies in ordinary nodes, and is dependent upon the visibility of the containing columns.

The table below lists the main properties that relate to data cells.

Appearance The TreeList control's Styles.ContentEven, Styles.ContentOdd, Styles.UseOddEvenStyles,


Styles.HotTrack, and Styles.IncSearch properties.
To dynamically customize style settings, handle the TreeList control's
Styles.OnGetContentStyle event.
The TreeList control's OptionsView.PaintStyle property.

Custom Draw Event The TreeList control's OnCustomDrawDataCell event.

Contents A node's Values and Texts properties.

HitTest Information The TreeList control's HitTest.HitAtNode property.

Page 55 of 1199
Expand Button
Visual Elements

A node expand button (located in node indents) shows a node's expanded state and enables end-users to change the state by
clicking this button.
By default, the expand button occupies the leftmost position in a node. You can change this position by specifying the
expandable band in which the expand button will reside.

The table below lists the main properties that relate to expand buttons.

Visibility For root level nodes, the TreeList control's OptionsView.ShowRoot property.
To hide all expand buttons, set the TreeList control's OptionsView.Buttons property to
False. Alternatively, you can assign tlbeNotExpandable to the Expandable property of all
visible bands.

Position A band's Expandable property. The expand button's location can only be changed in the
banded layout.

Appearance Handle the TreeList control's Styles.OnGetNodeIndentStyle event to dynamically customize


the expand button's style settings.

Custom Draw Event The TreeList control's OnCustomDrawIndentCell event.

HitTest Information The TreeList control's HitTest.HitAtButton, HitTest.HitAtIndent, and HitTest.HitAtNode


properties.

Page 56 of 1199
Find Panel
Visual Elements

The Find Panel enables end-users to type search queries into the panel's Find box to filter nodes and highlight search strings in
the results.

Use the TreeList control's FindPanel property to customize the Find Panel's look & feel.

The table below lists the main members that relate to the Find Panel.

Visibility The TreeList control's FindPanel.DisplayMode property.


The TreeList control's ShowFindPanel and HideFindPanel procedures.

Position The TreeList control's FindPanel.Position property.

Appearance The TreeList control's Styles.FindPanel and Styles.SearchResultHighlight properties.

Contents The TreeList control's FindPanel.ShowClearButton, FindPanel.ShowCloseButton, and


FindPanel.ShowFindButton properties.
The TreeList control's ApplyFindFilterText and ClearFindFilterText procedures.

Behavior The TreeList control's FindPanel.HighlightSearchResults, FindPanel.UseExtendedSyntax,


FindPanel.UseDelayedFind, FindPanel.FocusContentOnApplyFilter, and
FindPanel.ClearFindFilterTextOnClose properties.

HitTest Information The TreeList control's HitTest.HitAtFindPanel property.

Page 57 of 1199
Fixed Band Separator
Visual Elements

Vertical lines that separate fixed band contents from scrollable bands are called fixed band separators.

The table below lists the main properties that relate to fixed band separators.

Visibility A band's FixedKind property.

Appearance The TreeList control's OptionsView.FixedSeparatorColor property.

Custom Draw Event The TreeList control's OnCustomDrawBandCell event.

Size The TreeList control's OptionsView.FixedSeparatorWidth property.

HitTest Information The TreeList control's HitTest.HitAtSeparator property.

Page 58 of 1199
Footer
Visual Elements

The footer is a non-scrollable area displayed at the bottom of the TreeList control. Commonly, the footer's cells are used to
display total summaries. Additionally, you can display any custom information within the footer or its cells.

The table below lists the main properties that relate to the footer.

Visibility The TreeList control's OptionsView.Footer property.


End-users can change the visibility of the footer via the column header context menu.

Appearance The TreeList control's Styles.Footer property.


Use a band's Styles.Footer property to specify style settings for the band's footer.

Custom Draw Event The TreeList control's OnCustomDrawBandCell event.

Contents The TreeList control's Summary.FooterSummaryItems property or a column's


Summary.FooterSummaryItems property.
End-users can customize footer summary options via the footer context menu.

Context Menu Refer to the Footer Context Menu topic.

HitTest Information The TreeList control's HitTest.HitAtFooter property.

Page 59 of 1199
Footer Cell
Visual Elements

A footer cell displays a total summary calculated against a column's values.

Normally, one footer cell is displayed per each summary item specified for a column. In a stacked column layout, a single footer
cell is shown per column, and the cell displays all summaries separated by a character specified via the ListSeparator global
variable.

The position and size of footer, data, and group footer cells are determined by the column header layout. Users can adjust a
cell's width and make it span across multiple lines.

Footer cells are similar to group footer cells, except for its position and HitTest information.

The table below lists the main properties that relate to footer cells.

Visibility The TreeList control's OptionsView.Footer property or a column's Options.Footer property.


End-users can change the visibility of individual footer cells via the footer context menu.

Appearance The TreeList control's Styles.Footer and Styles.ColumnFooter properties.


Use a band's Styles.Footer property to specify style settings for the band's footer cells.
Use a column's Styles.Footer property to specify style settings for the column's footer cells.

Custom Draw Event The TreeList control's OnCustomDrawFooterCell event.

Contents The TreeList control's Summary.FooterSummaryItems property or a column's


Summary.FooterSummaryItems property.
Page 60 of 1199
Summary.FooterSummaryItems property.
End-users can customize footer summary options via the footer context menu.

Context Menu Refer to the Footer Context Menu topic.

Hints The TreeList control's OptionsBehavior.FooterHints property.

HitTest Information The TreeList control's HitTest.HitAtFooterItem property.

Page 61 of 1199
Grid Line
Visual Elements

The table below lists the main properties that relate to grid lines.

Visibility The TreeList control's OptionsView.GridLines property.

Appearance The TreeList control's OptionsView.GridLineColor property.

Custom Draw Event The TreeList control's OnCustomDrawDataCell event.

Page 62 of 1199
Group Footer
Visual Elements

The group footer is an area displayed under a node's last immediate child node. Commonly, a node's group footer cells display
group summaries calculated for a certain column within this node. Additionally, you can display any custom information within
group footers or their cells.

The table below lists the main properties that relate to group footers.

Visibility The TreeList control's OptionsView.GroupFooters property.


End-users can change the visibility of group footers via the column header context menu.

Appearance The TreeList control's Styles.Footer property.


Use a band's Styles.Footer property to specify style settings for the band's group footers.

Custom Draw Event The TreeList control's OnCustomDrawBandCell event.

Contents The TreeList control's Summary.GroupFooterSummaryItems property or a column's


Summary.GroupFooterSummaryItems property.
End-users can customize group footer summary options via the group footer context menu.

Context Menu Refer to the Group Footer Context Menu topic.

HitTest Information The TreeList control's HitTest.HitAtGroupFooter property.

Page 63 of 1199
Group Footer Cell
Visual Elements

A node's group footer cell displays a group summary calculated against a column's values corresponding to this node.

Normally, one group footer cell is displayed per each summary item specified for a column. In a stacked column layout, a single
group footer cell is shown per column, and the cell displays all summaries separated by a character specified via the
ListSeparator global variable.

The position and size of group, footer, and data cells are determined by the column header layout. Users can adjust a cell's width
and make it span across multiple lines.

Group footer cells are similar to footer cells, except for the position and HitTest information.

The table below lists the main properties that relate to group footer cells.

Visibility The TreeList control's OptionsView.GroupFooters property or a column's


Options.GroupFooter property.
End-users can change the visibility of individual group footer cells via the group footer
context menu.

Appearance The TreeList control's Styles.Footer and Styles.ColumnFooter properties.


Use a band's Styles.Footer property to specify style settings for the band's group footer
cells.
Use a column's Styles.Footer property to specify style settings for the column's group footer
cells.
Page 64 of 1199
Custom Draw Event The TreeList control's OnCustomDrawFooterCell event.

Contents The TreeList control's Summary.GroupFooterSummaryItems property or a column's


Summary.GroupFooterSummaryItems property.
End-users can customize group footer summary options via the group footer context menu.

Context Menu Refer to the Group Footer Context Menu topic.

Hints The TreeList control's OptionsBehavior.FooterHints property.

HitTest Information The TreeList control's HitTest.HitAtGroupFooterItem property.

Page 65 of 1199
Header Panel
Visual Elements

The header panel is an area at the top of a tree list that is comprised of the band and column header panels.

Refer to the Band Header Panel and Column Header Panel topics, to learn about the main properties that affect the header
panel's appearance.

Page 66 of 1199
Indent Cell
Visual Elements

The node indent shifts nodes right, visualizing the node subordination.
The node indent contains the following visual elements (from left to right): a level area (includes the expand button), a check box
(radio button), a state image (for indicating a node of the specific type), and a select image (for indicating a selected node).

The table below lists the main properties that relate to indent cells.

Appearance To dynamically customize style settings, handle the TreeList control's


Styles.OnGetNodeIndentStyle event.

Custom Draw Event The TreeList control's OnCustomDrawIndentCell event.

HitTest Information The TreeList control's HitTest.HitAtIndent, HitAtCheckButton and HitTest.HitAtNode


properties.

Page 67 of 1199
Navigator
Visual Elements

The navigator enables end-users to navigate through nodes, add and delete them, and control the data cell editing process.

The table below lists the main properties that relate to the navigator.

Visibility The TreeList control's Navigator.Visible property.

Position The TreeList control's OptionsView.NavigatorOffset property.

Appearance The TreeList control's Styles.Navigator and Styles.NavigatorInfoPanel properties.

Contents The TreeList control's Navigator.Buttons and Navigator.InfoPanel properties.

Behavior The enabled state of navigator buttons depends upon the currently focused and selected
node(s), the current state of a data editing operation, and the data operations enabled via
the TreeList control's OptionsData option set.

Size The navigator is automatically sized to include all its elements (buttons and the information
panel) that are made visible via the TreeList control's Navigator.Buttons and
Navigator.InfoPanel.Visible properties.

Hints The TreeList control's OptionsBehavior.NavigatorHints property.


The Hint property of individual buttons.

HitTest Information The TreeList control's HitTest.HitAtNavigator property.

Related Information

l TcxCustomTreeList.OptionsData

Page 68 of 1199
Node
Visual Elements

A node visualizes a single data store record. Each node contains data cells used for displaying the record's values. In group
nodes, a data cell that belongs to the categorized column is spanned over the entire node.
A hierarchy of nodes reflects the self-referencing relationship of the persistent data.
A tree list provides different ways to build up the View with nodes:
l The TcxDBTreeList control can be populated with nodes programmatically or automatically. To learn how to prepare the
control for automatic loading of nodes, refer to the Connecting to Data help topic.
l The TcxVirtualTreeList control is populated with nodes programmatically.
l For the TcxDBTreeList and TcxTreeList controls, nodes can also be specified manually at design time using the Items
Editor.

Along with the data cells, the node also contains the following visual elements (from left to right):

Element Description

Node Indicator Informs an end-user about focused and selected nodes. It allows an end-
user to focus or select nodes, expand or collapse nodes, and also move
nodes in the same nesting level.

Expand Button It is used to expand or collapse parent nodes.

Check Box (Radio Optional element. It is used to check or uncheck nodes.


Button)

State Image Optional element. Informs about specific node states.

Select Image Optional element. Informs whether the node is selected or not.

Preview Optional element. Displays large chunks of non-editable information.

Drop Indicator Optional element. Suggests the resulting drop position for a node being
dragged, relative to a node under the mouse pointer.

In code, each node is represented by an instance of one of the following classes:


l The base class (TcxTreeListNode).
l The class that corresponds to a certain data loading mode (TcxUnboundTreeListNode, TcxDBTreeListNode, or
TcxVirtualTreeListNode).

The table below lists the main properties that relate to nodes.

Page 69 of 1199
Visibility The node's Visible property.

Appearance The TreeList control's Styles.ContentEven, Styles.ContentOdd, Styles.UseOddEvenStyles,


Styles.Preview, Styles.HotTrack, and Styles.IncSearch properties.
To dynamically customize style settings, handle the TreeList control's
Styles.OnGetNodeIndentStyle, Styles.OnGetContentStyle, Styles.OnGetPreviewStyle and
Styles.OnGetHotTrackStyle events.

Custom Draw Event The TreeList control's OnCustomDrawIndentCell, OnCustomDrawDataCell and


OnCustomDrawPreviewCell events.

HitTest Information The TreeList control's HitTest.HitAtNode property.

Contents The node's Values property.

Bounds The node's DisplayRect method.

Page 70 of 1199
Node Indicator
Visual Elements

The node indicator is an area displayed between the View's left boundary and nodes. Nodes divide this area into cells that
indicate the focused and selected state of corresponding nodes. Indicator cells at the intersection of the band header panel and
column header panel provide space for the Quick Band Customization button and Quick Column Customization button.

Indicator cells allow end-users to:


l Focus nodes.
l Change the selected and expanded states of nodes.
l Move nodes within their nesting level.

The table below lists the main properties that relate to the node indicator and its cells.

Visibility The TreeList control's OptionsView.Indicator,


OptionsCustomizing.BandsQuickCustomization, and
OptionsCustomizing.ColumnsQuickCustomization properties.

Appearance The TreeList control's Styles.Indicator property.

Custom Draw Event The TreeList control's OnCustomDrawIndicatorCell event.

HitTest Information The TreeList control's HitTest.HitAtIndicator and HitTest.HitAtNode properties.

Bounds The TreeList control's OptionsView.IndicatorWidth property.

Page 71 of 1199
Preview
Visual Elements

A node preview section is a non-editable area that enables end-users to view large pieces of information provided by a node.

The table below lists the main properties that relate to preview sections.

Visibility The TreeList control's Preview.Visible property.

Appearance The TreeList control's Styles.Preview property.


To dynamically customize style settings, handle the TreeList control's
Styles.OnGetPreviewStyle event.

Custom Draw Event The TreeList control's OnCustomDrawPreviewCell event.

Layout The TreeList control's Preview.Place, Preview.LeftIndent, and Preview.RightIndent


properties.

Contents The TreeList control's Preview.Column, Preview.MaxLineCount and Preview.AutoHeight


properties.

HitTest Information The TreeList control's HitTest.HitAtNodePreview and HitTest.HitAtNode properties.

Page 72 of 1199
Quick Band Customization Button
Visual Elements

The Quick Band Customization button is displayed at the intersection of the band header panel and the node indicator. Clicking
this button invokes the Quick Band Customization dropdown that displays band captions in a checklist. Clicking band captions
allows users to change the visible state of corresponding bands without using the Customization Form at runtime, or the Object
Inspector or Component Editor at design time.

The table below lists the main properties that relate to the Quick Band Customization button.

Visibility The TreeList control's OptionsCustomizing.BandsQuickCustomization property.

Appearance The Quick Band Customization button is an indicator cell. Refer to the Node Indicator topic
for information on customizing indicator cells' appearance.

Dropdown List's The dropdown list displays all bands whose Options.Hidden property value is False.
Content Use the TreeList control's
OptionsCustomizing.BandsQuickCustomizationShowCommands property to switch the
visibility of the (All) and (Sorted) check boxes.

Dropdown List's Layout Use the TreeList control's


OptionsCustomizing.BandsQuickCustomizationMaxDropDownCount property to constrain
the dropdown's height.

HitTest Information The TreeList control's HitTest.HitAtBandCustomizing property.

Localization Use the scxQuickCustomizationAllCommandCaption and


scxQuickCustomizationSortedCommandCaption resource strings declared in the
cxLibraryStrs unit to localize the captions of the (All) and (Sorted) check boxes.

Page 73 of 1199
Quick Column Customization Button
Visual Elements

The Quick Column Customization button is displayed at the intersection of the column header panel and the node indicator.
Clicking this button invokes the Quick Column Customization dropdown that displays column names in a checklist. Clicking
column names allows users to change the visible state of columns without using the Customization Form at runtime, or the
Object Inspector or Component Editor at design time.

The table below lists the main properties that relate to the Quick Column Customization button.

Visibility The TreeList control's OptionsCustomizing.ColumnsQuickCustomization property.

Appearance The Quick Column Customization button is an indicator cell. Refer to the Node Indicator
topic for information on customizing indicator cells' appearance.

Dropdown List's The dropdown list displays all columns whose Options.Hidden property is set to False.
Content Use the TreeList control's
OptionsCustomizing.ColumnsQuickCustomizationShowCommands property to switch the
visibility of the (All) and (Sorted) check boxes.

Dropdown List's Layout Use the TreeList control's


OptionsCustomizing.ColumnsQuickCustomizationMaxDropDownCount property to
constrain the dropdown's height.

HitTest Information The TreeList control's HitTest.HitAtColumnCustomizing property.

Localization Use the scxQuickCustomizationAllCommandCaption and


scxQuickCustomizationSortedCommandCaption resource strings declared in the
cxLibraryStrs unit to localize the captions of the (All) and (Sorted) check boxes.

Page 74 of 1199
Tree Line
Visual Elements

Tree lines link expand buttons and nodes, emphasizing levels in a tree structure.

The table below lists the main properties that relate to tree lines.

Visibility The TreeList control's OptionsView.TreeLineStyle property.


For root level nodes, the TreeList control's OptionsView.ShowRoot property.

Appearance The TreeList control's OptionsView.TreeLineStyle and OptionsView.TreeLineColor


properties.

Custom Draw Event The TreeList control's OnCustomDrawIndentCell event.

HitTest Information The TreeList control's HitTest.HitAtIndent and HitTest.HitAtNode property.

Page 75 of 1199
Design-Time Features
Section Navigator

The topics in this section describe the ways in which you can customize the ExpressQuantumTreeList at design time.

The following topics are available:


l Component Editor
l Items Editor
l On-Form Object Access

Page 76 of 1199
Component Editor
Design-Time Features

The ExpressQuantumTreeList control provides an advanced Component Editor, which allows you to customize bands and
columns at design time.

To invoke the Component Editor, click the Bands… or Columns… item in the control's context menu or double-click the
control.

Bands page

This page allows you to:


l Create and delete bands.
l Reposition bands within the TreeList control.
l Access individual bands and display their properties in the Object Inspector. This is useful for hidden fields, since all the
Page 77 of 1199
l
visible bands can be accessed via on-form object access provided by the ExpressQuantumTreeList.

The list within this page displays the bands contained within the TreeList control's Bands collection. Each band in the list is
identified by its Caption.Text property value. You can customize the settings for multiple selected bands simultaneously. Hold
down the Shift or Ctrl keys while clicking bands to modify the selection. The settings of the currently selected band(s) can be
accessed and changed via the Object Inspector.

The following table lists all the buttons available within the Bands page, along with descriptions of their purpose.

Button Description

Add Adds a new band. This band is automatically selected within the list.

Delete Removes the selected band from the list and the Bands collection. This doesn't remove the
band's columns or child bands.

Move Up Moves the selected band to the top of the list. This decrements the band's Index property
value.

Move Down Moves the selected band to the bottom of the list. This increments the band's Index property
value.

Restore Defaults Restores the selected band's default option settings and width. Clicking this button calls the
band's RestoreDefaults method.

Restore Widths Restores the selected band's default width. Clicking this button calls the band's
RestoreWidths method.

Columns page

This page allows you to:


l Create and delete columns.
l Reposition columns within the TreeList control.
l Access individual columns and display their properties in the Object Inspector.
l Automatically create columns for all the fields in a bound data source.

The list within this page displays the columns contained within the TreeList control's Columns collection. Each column in the list
is identified by its Name property value and the parent band's caption. As with bands, you can customize the settings for multiple
Page 78 of 1199
selected columns simultaneously. Hold down the Shift or Ctrl keys while clicking columns to modify the selection. The settings
of the currently selected column(s) will be displayed in the Object Inspector.

The following table lists all the buttons available within the Columns page along with descriptions of their purpose.

Button Description

Add Adds a new column to the first visible band. This column is automatically selected within the
list.

Delete Removes the selected column from the list and the Columns collection.

Move Up Moves the selected column to the top of the list. This decrements the column's ItemIndex
property value.

Move Down Moves the selected band to the bottom of the list. This increments the column's ItemIndex
property value.

Restore Defaults Restores the selected column's default option settings and width. Clicking this button calls
the column's RestoreDefaults method.

Restore Widths Restores the selected column's default width. Clicking this button calls the column's
RestoreWidths method.

Create all fields Available only for data-aware TreeList controls.


Creates columns for all the fields in a bound data source. The created columns are
positioned within the first visible band. The names of the created columns are assigned
automatically.

The Bands or Columns list's context menu items provide the same functionality as buttons on corresponding pages, and allow
you to select all items within the list.

Page 79 of 1199
Items Editor
Design-Time Features

The ExpressQuantumTreeList control provides a design-time Items Editor, which allows you to do the following within unbound
TreeList controls:
l Create or remove nodes and edit data cell values.
l Assign node images.
l Specify a node's check group type.
l Specify whether end-users can change a node's check state.
l Customize the tree list's layout.

To invoke the Items Editor, click the Items editor… item in the control's context menu.

The following table lists all the UI elements available within the Items Editor, along with descriptions of their purpose.

Element Description

TreeList control Used as a pattern for the resulting TreeList control. Initially, it represents a copy of the
control at the moment the Items Editor is invoked. You can edit data cell values and
customize the layout as needed.

New Item Adds a node at the nesting level of the focused node. If no node is focused, a root level node
is created.

New SubItem Adds a child node to the focused node. If no node is focused, a root level node is created.

Delete Removes the currently focused node.

Page 80 of 1199
Image Indexes Editors within the Current column allow you to specify the ImageIndex, SelectedIndex,
section StateIndex, OverlayIndex, and OverlayStateIndex properties for the focused node. Editors
within the Default column allow you to specify the default values of these properties for all
new nodes created within the Items Editor.

Check Group Allows you to assign the CheckGroupType property for the parent of the focused node.
Type Combo Box This combo box is enabled only if the TreeList control's OptionsView.CheckGroups property
is set to True .

Enabled Check Allows you to assign the Enabled property for the focused node.
Box This check box is enabled only if the TreeList control's OptionsView.CheckGroups property
is set to True.

Customize Invokes the customization form. You can use this form to customize the tree list's layout.

Ok Applies all pending changes to the tree list's data and layout and closes the Items Editor.

Cancel Discards all pending changes to the tree list and closes the Items Editor.

The tree list's context menu provides the same functionality as the New Item, New SubItem, Delete, and Customize buttons.

Related Information

l TcxTreeListNode.OverlayIndex
l TcxTreeListNode.OverlayStateIndex
l TcxTreeListNode.SelectedIndex
l TcxTreeListNode.StateIndex

Page 81 of 1199
On-Form Object Access
Design-Time Features

The Component Editor allows you to access all bands and columns created within the ExpressQuantumTreeList. It's also
possible to customize the visible bands and columns and their layout directly on-form, without having to invoke the Component
Editor.

To access a band or column and display its properties in the Object Inspector, simply click its header in the control. Note that
multiple elements can be selected at one time while holding down the Shift key.

At design time, you can reposition individual band or column headers via drag and drop. You can also adjust their size as
needed, by dragging the sizing edges.

You can also access the properties of a footer or group summary. To accomplish this, click its cell in the control.

Related Information

l Column Header
l Group Footer Cell
l Reordering Bands and Columns
l Resizing Bands and Columns

Page 82 of 1199
End-User Capabilities
Section Navigator

The topics in this section describe the operations available to end-users of the ExpressQuantumTreeList.

The following topics are available:


l Calculating Summaries
l Controlling the Visibility of Bands and Columns
l Data Editing
l Expanding and Collapsing Nodes
l Focusing and Selecting Nodes
l Incremental Search
l Navigating Through Cells
l Reordering Bands and Columns
l Reordering Nodes
l Resizing Bands and Columns
l Resizing Nodes
l Sorting Nodes

Page 83 of 1199
Calculating Summaries
End-User Capabilities

End-users can calculate footer and group summaries and adjust summary options via the built-in footer context menu and group
footer context menu.

      

These menus can be invoked only if the footer and group footers are visible within the TreeList control. End-users can use the
column header context menu to change the visibility of the footer and group footers.

Page 84 of 1199
Controlling the Visibility of Bands and Columns
End-User Capabilities

The following operations allow end-users to change the visibility of bands:

Action Effect

Clicking items within the Quick Band Customization Shows or hides corresponding bands.
dropdown.  

Dragging band headers to the customization form. Hides corresponding bands.


End-users can invoke the customization form via the column
header context menu.

Dragging band headers and dropping them outside Hides corresponding bands.
the band header panel. This action can be performed when the
OptionsCustomizing.BandHiding property is set to True or
the customization form is displayed.

Dragging band headers from the customization form Shows corresponding bands.
and dropping them within the band header panel.  

Note:   Use the TreeList control's OptionsCustomizing.BandCustomizing and OptionsCustomizing.BandMoving properties to


prohibit end-users from moving bands or customizing them using the customization form. Use a band's Options.Customizing and
Options.Moving properties to prohibit moving or customizing individual bands. To respond to end-user changes made to the
visibility of bands, handle the TreeList control's OnBandPosChanged event.

The following operations allow end-users to change the visibility of columns:

Action Effect

Clicking items within the Quick Column Shows or hides corresponding columns.
Customization dropdown.  

Dragging column headers to the customization form. Hides corresponding columns.


 

Dragging column headers and dropping them Hides corresponding columns.


outside the column header panel. This action can be performed when the
OptionsCustomizing.ColumnHiding property is set to True or
the customization form is displayed.

Dragging column headers from the customization Shows corresponding columns.


form and dropping them within the column header  
panel.

Clicking the 'Remove this Column' item within the Hides the column located under the mouse pointer.
column header context menu.  

Note:   Use the TreeList control's OptionsCustomizing.ColumnCustomizing and OptionsCustomizing.ColumnMoving properties


to prohibit end-users from moving columns or customizing them using the customization form. Use a column's
Options.Customizing and Options.Moving properties to prohibit moving or customizing individual columns. To respond to end-user
changes made to the visibility of columns, handle the TreeList control's OnColumnPosChanged event.

Page 85 of 1199
Data Editing
End-User Capabilities

For data entry, use the following keyboard shortcuts or mouse operations:

Keyboard Shortcut Enter, F2, typing any character in the focused cell (including the Spacebar key).

Mouse Action Click a data cell.

To finish editing, use the following keyboard shortcuts:

Keyboard Shortcut Enter (commits content changes), Esc (discards content changes).

Mouse Action Click outside of cell.

Alternatively, you can use data editing capabilities provided by the embedded navigator.

Notes
Data editing is enabled if the tree list's OptionsData.Editing option is active.
Use the EditAutoHeight property to switch the sizing mode for multi-line in-place editors.

Related Information

l TcxTreeListOptionsBehavior.EditAutoHeight

Page 86 of 1199
Expanding and Collapsing Nodes
End-User Capabilities

To expand a collapsed parent node, use the following keyboard shortcuts or mouse operations:

Keyboard Shortcut Result

Plus (+) Expands a node to show its immediate children.

Right Arrow Expands a node to show its immediate children in the


single-column View.

Asterisk (*) on the numeric keypad Recursively expands a subtree.

Mouse Action Result

Click an expand button, double-click a Expands a node to show its immediate children.
node, double-click a node indicator.

To collapse an expanded parent node, use the following keyboard shortcuts or mouse operations:

Keyboard Shortcut Result

Minus (–) Collapses an expanded node.

Left Arrow Collapses an expanded node in the single-column View.

Mouse Action Result

Click an expand button, double-click a Collapses an expanded node.


node, double-click a node indicator.

Notes
A parent node can be automatically expanded or collapsed when performing drag and drop. To enable this, activate the tree list's
OptionsBehavior.DragExpand and OptionsBehavior.DragCollapse options.
Automatic expansion can also be performed during an incremental search. For this purpose, activate the tree list's
OptionsBehavior.ExpandOnIncSearch option.
The Right Arrow and Left Arrow keys are used for node expansion and collapse when only one column is visible in the View. In
the multi-column View, these keys are used for data cell navigation.
Node expansion with a node or a node indicator double-click is allowed, if the tree list's OptionsBehavior.ExpandOnDblClick
option is active.

Page 87 of 1199
Focusing and Selecting Nodes
End-User Capabilities

To focus a particular node, click the node, its indicator, or use navigation capabilities provided by the embedded navigator. The
focused node is selected automatically. For the focused node, the node indicator displays a right arrow.
To select multiple nodes in a random order, hold down the Ctrl key, and click the nodes you want to select.
The image below shows non-adjacent selected nodes:

To select contiguous nodes, click the first node you want to select. Then, hold down the Shift key and click the last node.
The image below shows the TreeList control with the third to the twelfth nodes selected:

You can also select multiple series of nodes. First, select contiguous nodes, using the Shift key. Then, add single nodes to the
selection using the Ctrl key.

Page 88 of 1199
You can unselect all the selected nodes simultaneously by clicking on any unfocused node. To remove certain nodes from the
selection, hold down the Ctrl key, and click these nodes.

Notes
Node focusing is also performed in the navigation operations.
Nodes can be automatically focused when performing drag operations. To enable this capability, activate the tree list's
OptionsBehavior.DragFocusing option.
Multiple node selection is allowed if the tree list's OptionsSelection.MultiSelect option is active.

Page 89 of 1199
Incremental Search
End-User Capabilities

This feature allows end-users to locate nodes in the TreeList control by column values. To search a node by a column value,
focus a data cell within the appropriate column and type the search text. If the TreeList control contains a node whose column
value starts with the search text, the node is focused.

The image below shows the result of pressing the 're' characters. The first 'Requisitioning Development' value is located and the
node containing it is focused:

The 'l' character is pressed after typing 're' and focus is moved to the 'Reliability Analysis Section' record:

You can continue searching by the search text. To search forward and backward, press the Ctrl+Down Arrow and Ctrl+Up
Arrow keys respectively.

Notes
By default, incremental search is disabled. To enable it, activate the tree list's OptionsBehavior.IncSearch option.
While incremental search is enabled for the entire control, searching by a particular column can only be performed if the column's
Options.IncSearch option is active.
If the tree list's OptionsBehavior.IncSearchItem property is not specified, the search is performed by the currently focused
column.

Page 90 of 1199
Navigating Through Cells
End-User Capabilities

A tree list is capable of performing focus navigation through data cells, if cell navigation is enabled (the tree list's
OptionsSelection.CellSelect option is active).
To navigate through node data cells, use the following keyboard shortcuts:

Keyboard Shortcut Result

Right Arrow, Enter, Tab Moves focus one data cell to the right within the current node.

Left Arrow, Shift+Enter, Shift+Tab Moves focus one data cell to the left within the current node.

Home Moves focus to the first data cell of the current node.

End Moves focus to the last data cell of the current node.

Up Arrow Moves focus one node up.

Down Arrow Moves focus one node down.

PgUp Scrolls focus one page up.

PgDn Scrolls focus one page down.

Ctrl+Home Moves focus to the first data cell of the first node.

Ctrl+End Moves focus to the last data cell of the last node.

Notes
For the data cells that are beyond the View's boundaries, the tree list automatically scrolls the View in order to bring the focused
data cell into the View. However, there is a special case in which horizontal scrolling is not performed. If the View is split across
fixed bands and ordinary bands, in fixed bands the contents are not horizontally scrolled, unlike the ordinary bands.
Navigation with the Enter key is allowed if the tree list's OptionsBehavior.GoToNextCellOnEnter option is active.
Navigation with the Tab key is allowed if the tree list's OptionsBehavior.GoToNextCellOnTab option is active.
The Tab key cycles forward from the end of the current node to the beginning of the next node (the Shift+Tab key cycles in the
opposite direction) if the tree list's OptionsBehavior.FocusCellOnCycle option is active.
In the single-column View, the Right Arrow and Left Arrow keys can only be used for node expansion and collapse.

Page 91 of 1199
Reordering Bands and Columns
End-User Capabilities

The following operations can be performed by end-users to rearrange bands:

Action Effect

Dragging a band header and dropping it at a new Moves the band header to the new position.
position within the band header panel.  

Double-clicking a band header located within the Restores the band header within the band header panel at
customization form. the position specified by the band's Position property.

Note:   Use the TreeList control's OptionsCustomizing.BandMoving property to prohibit end-users from moving bands. Use a
band's Options.Moving property to prohibit moving this band. To prohibit end-users from nesting bands, set the TreeList control's
OptionsCustomizing.NestedBands property to False.
To respond to end-user changes made to the position of bands, handle the TreeList control's OnBandPosChanged event.

The following operations can be performed by end-users to rearrange columns:

Action Effect

Dragging a column header and dropping it at a new Moves the column header to the new position.
position within the column header panel.  

Double-clicking a column header located within the Restores the column header within the column header
customization form. panel at the position specified by the column's Position
property.

Note:   Use the TreeList control's OptionsCustomizing.ColumnMoving property to prohibit end-users from moving columns. Use
a column's Options.Moving property to prohibit moving this column. To prohibit end-users from stacking columns, set the
TreeList control's OptionsCustomizing.StackedColumns property to False.
To respond to end-user changes made to the position of columns, handle the TreeList control's OnColumnPosChanged event.

Page 92 of 1199
Reordering Nodes
End-User Capabilities

To reorder nodes in the View, drag the selected node or its indicator to the target position. You can also drag multiple nodes
simultaneously in this manner, if the multi-select feature is enabled (the tree list's OptionsSelection.MultiSelect option is active).
This type of reordering can only be performed within the same nesting level.

Notes
Node dragging is enabled if the tree list's OnDragOver event is handled (at least, an empty implementation of the event handler is
provided).

Task-Based Help
Implementing the Drag And Drop Functionality

Page 93 of 1199
Resizing Bands and Columns
End-User Capabilities

The following operations can be performed by end-users to resize bands:

Action Effect

Dragging the right edge of a band header. Changes the width of the current and related bands and
  their columns.
 

Dragging the bottom edge of a band header. Changes the height of all root bands.
  This action can be performed only when there are no nested
bands.
 

Double-clicking the right edge of a band header. Applies Best Fit to the band's visible columns and adjusts
  the band's width to match the combined width of these
columns.
 

Clicking the 'Best Fit (all columns)' item within the Applies Best Fit to all visible columns within the TreeList
column header context menu. control.
 

Note:   Use the TreeList control's OptionsCustomizing.BandHorzSizing and OptionsCustomizing.BandVertSizing properties to


prohibit end-users from resizing bands. Use a band's Options.Sizing and Options.VertSizing properties to prohibit sizing this
band.

The following operations can be performed by end-users to resize columns:

Action Effect

Dragging the right edge of a column header. Changes the width of the current and related columns.
   

Dragging the bottom edge of a column header. Changes the height of the column. End-users can perform
  this action to make the column's cells span across multiple
lines.
 

Double-clicking the right edge of a column header. Applies Best Fit to the column.
   

Clicking the 'Best Fit' item within the column header Applies Best Fit to the column located under the mouse
context menu. pointer.
 

Clicking the 'Best Fit (all columns)' item within the Applies Best Fit to all visible columns within the TreeList
column header context menu. control.
 

Note:   Use the TreeList control's OptionsCustomizing.ColumnHorzSizing and OptionsCustomizing.ColumnVertSizing properties


to prohibit end-users from resizing columns. Use a column's Options.Sizing and Options.VertSizing properties to prohibit sizing
this column.

Page 94 of 1199
Resizing Nodes
End-User Capabilities

To resize nodes, perform the following mouse operations:

Mouse Action Result

Drag a column header's bottom edge, or the Changes the height of all nodes.
node indicator's bottom edge of the top
visible node.

Drag the node indicator's bottom edge of a Changes the height of a particular node.
selected node.

Notes
Sizing of column headers is allowed if the tree list's OptionsCustomizing.ColumnVertSizing option is active.
Sizing of all nodes using the top node is allowed if the tree list's OptionsCustomizing.RowSizing option is active.
Sizing of a certain node is allowed if the tree list's OptionsCustomizing.NodeSizing option is active. The
OptionsCustomizing.NodeSizing and OptionsCustomizing.RowSizing options override each other.

Page 95 of 1199
Sorting Nodes
End-User Capabilities

To sort nodes against a column, click this column's header. To sort in reverse order, click the column header again.
To sort by multiple columns, hold down the Shift key and click column headers you want to use in sorting. To stop sorting
against a particular column, hold down the Ctrl key and click this column's header.
Sorting can also be performed using the column header's context menu. In the context menu, use the Sort Ascending and Sort
Descending menu items.

Notes
Sorting is allowed if the tree list's OptionsBehavior.Sorting option or the particular column's Sorting option is active.
Multiple sorting is allowed if the tree list's OptionsBehavior.MultiSort option is active.

Page 96 of 1199
Task-Based Help
Section Navigator

This section provides a list of the examples contained in this help. To get detailed information on specific features, browse the
Feature Center section.
l Bands
l Connecting To Data
l Creating And Deleting Columns
l Creating Summaries
l Deleting Nodes
l How to Custom Paint the Tree List Background
l How to Custom Paint Band Backgrounds
l How to Custom Paint Band Headers
l How to Custom Paint Column Headers
l How to Custom Paint Footer Cells
l How to Custom Paint Indent Cells
l How to Custom Paint Node Indicators
l How to Custom Paint Previews
l How to Display Print Preview and Print the Tree List
l How to Implement Sorting
l Implementing Drag-And-Drop Functionality
l Obtaining And Setting Cell Values
l Selecting Nodes
l Setting the TreeList appearance
l Using Lookup Column

Page 97 of 1199
Member Table: Appearance
Feature Center   Appearance   Style Customization

The following properties apply styles to a tree list, its bands and columns.

Member Description

TcxCustomTreeList.Styles and Apply style settings to tree list elements.


TcxTreeListStyles.StyleSheet

TcxTreeListBand.Styles Applies style settings to band elements.

TcxTreeListColumn.Styles Applies style settings to column elements.

The following properties specify styles for all elements of a particular type.

Member Description

TcxTreeListStyles.BandBackground Band backgrounds.

TcxTreeListStyles.BandContent Band contents.

TcxTreeListStyles.BandHeader Band headers.

TcxTreeListStyles.ColumnFooter Column footers.

TcxTreeListStyles.ColumnHeader Column headers.

TcxTreeListStyles.ContentEven Even nodes.

TcxTreeListStyles.ContentOdd Odd nodes.

TcxTreeListStyles.Footer Footer panel.

TcxTreeListStyles.HotTrack Hot-tracked nodes.

TcxTreeListStyles.IncSearch A data cell located by the incremental search.

TcxTreeListStyles.Indicator Indicator column.

TcxTreeListStyles.Preview Node previews.

The following events allow you to specify styles for individual elements.

Member Description

TcxTreeListStyles.OnGetBandBackgroundStyle Band backgrounds.

TcxTreeListStyles.OnGetBandContentStyle Band contents.

TcxTreeListStyles.OnGetBandFooterStyle Band footers.

TcxTreeListStyles.OnGetBandHeaderStyle Band headers.

TcxTreeListStyles.OnGetColumnFooterStyle Column footers.

TcxTreeListStyles.OnGetColumnHeaderStyle Column headers.

TcxTreeListStyles.OnGetContentStyle Data cells.

Page 98 of 1199
TcxTreeListStyles.OnGetHotTrackStyle Hot-tracked nodes.

TcxTreeListStyles.OnGetNodeIndentStyle Node indents.

TcxTreeListStyles.OnGetPreviewStyle Node previews.

The following events allow you to custom paint individual elements.

Member Description

TcxCustomTreeList.OnCustomDrawBackgroundCell Tree list background.

TcxCustomTreeList.OnCustomDrawBandCell Band backgrounds.

TcxCustomTreeList.OnCustomDrawBandHeaderCell Band headers.

TcxCustomTreeList.OnCustomDrawDataCell Data cells.

TcxCustomTreeList.OnCustomDrawFooterCell Column footers.

TcxCustomTreeList.OnCustomDrawHeaderCell Column headers.

TcxCustomTreeList.OnCustomDrawIndentCell Node indents.

TcxCustomTreeList.OnCustomDrawIndicatorCell Node indicators.

TcxCustomTreeList.OnCustomDrawPreviewCell Node previews.

Related Information

l TcxTreeList Object
l TcxVirtualTreeList Object

Page 99 of 1199
Member Table: Bind to a Data Source
Feature Center   Data Exchange   Bind to a Data Source

Member Description

TcxCustomDBTreeList.DataController Specifies the data controller.

TcxDBTreeListDataController.DataSource Specifies the data source used for binding the dataset to the tree
list.

TcxCustomTreeList.Columns Provides indexed access to columns.

TcxDBTreeListColumn.DataBinding Connects a column to a data field.

Page 100 of 1199


Member Table: Categorized Columns
Feature Center   Layout Features   Categorized Columns

Member Description

TcxTreeListOptionsView.PaintStyle Applies the categorized paint style to the tree list.


 

TcxTreeListOptionsView.CategorizedColumn Specifies a categorized column.


 

TcxTreeListNode.IsGroupNode Indicates whether a node is a group node, for which a specified


categorized column provides values.

TcxCustomTreeList.OnIsGroupNode Enables you to dynamically specify group nodes.


 

Page 101 of 1199


Member Table: Expandable Bands
Feature Center   Layout Features   Expandable Bands

Member Description

TcxTreeListBand.Expandable Specifies whether a band can display expand buttons in nodes.


 

TcxTreeListBand.ActuallyExpandable Determines whether a band or one of its child bands displays


expand buttons.
 

TcxTreeListBands.ExpandableBand Provides access to the band that displays expand buttons


(contains an expandable column).

Page 102 of 1199


Member Table: Export Data
Feature Center   Data Exchange   Export Data

Member Description

cxExportTLToCSV Exports the tree list's content to a CSV (comma-separated values)


file.
 

cxExportTLToExcel Exports the tree list's content to a file in Microsoft Excel 97-2003
format.
 

cxExportTLToHTML Exports the tree list's content to a file in HTML format.


 

cxExportTLToText Exports the tree list's content to a text file.


 

cxExportTLToXLSX Exports the tree list's content to a file in Microsoft Excel 2007 or
later format.
 

cxExportTLToXML Exports the tree list's content to a file in XML format.


 

Page 103 of 1199


Member Table: Fixed Bands
Feature Center   Layout Features   Fixed Bands

Member Description

TcxTreeListBand.FixedKind Specifies whether a band is involved in horizontal scrolling.


 

TcxTreeListBands.VisibleLeftFixedCount, Determine the number of bands anchored to a particular side of


TcxTreeListBands.VisibleRightFixedCount, the TreeList control.
TcxTreeListBands.VisibleRootLeftFixedCount, and  
TcxTreeListBands.VisibleRootRightFixedCount

TcxTreeListOptionsView.FixedSeparatorColor and Specify the color and width of fixed band separators.
TcxTreeListOptionsView.FixedSeparatorWidth

Page 104 of 1199


Member Table: Footer Summaries
Feature Center   Data-Related Features   Footer Summaries

Member Description

TcxTreeListColumnSummary.FooterSummaryItems and Specify a column's footer summary options.


TcxTreeListSummary.FooterSummaryItems  

TcxCustomDataSummaryItem.Kind and Specify a footer summary's type and the formatting


TcxCustomDataSummaryItem.Format pattern for footer summary values.

TcxTreeListNode.FooterSummaryValues, Provide access to the values and display values of footer


TcxTreeListSummary.FooterSummaryValues, summaries.
TcxTreeListNode.FooterSummaryTexts, and
TcxTreeListSummary.FooterSummaryTexts

TcxTreeListSummaryItem.AllNodes Specifies a footer summary's calculation base (all nodes


or root level nodes).
 

TcxTreeListSummaryItem.CalculatedColumn Specifies the column that provides values for a footer


summary.

TcxCustomTreeList.OnSummary Enables you to manually calculate footer summary


values.
 

TcxCustomTreeList.OnAfterSummary Enables you to perform specific actions after footer


summaries have been calculated.
 

Page 105 of 1199


Member Table: Group Summaries
Feature Center   Data-Related Features   Group Summaries

Member Description

TcxTreeListColumnSummary.GroupFooterSummaryItems and Specify a column's group summary options.


TcxTreeListSummary.GroupFooterSummaryItems  

TcxCustomDataSummaryItem.Kind and Specify a group summary's type and the formatting


TcxCustomDataSummaryItem.Format pattern for group summary values.

TcxTreeListNode.FooterSummaryValues, Provide access to the values and display values of


TcxTreeListSummary.GroupFooterSummaryValues, group summaries.
TcxTreeListNode.FooterSummaryTexts, and
TcxTreeListSummary.GroupFooterSummaryTexts

TcxTreeListSummaryItem.AllNodes Specifies a group summary's calculation base (all


child nodes or only immediate children).
 

TcxTreeListSummaryItem.CalculatedColumn Specifies the column that provides values for a


group summary.

TcxCustomTreeList.OnSummary Enables you to manually calculate group summary


values.
 

TcxCustomTreeList.OnAfterSummary Enables you to perform specific actions after


group summaries have been calculated.
 

Page 106 of 1199


Member Table: Navigation and Scrolling
Feature Center   Focus and Selection   Navigation and Scrolling

Member Description

TcxTreeListColumn.MakeVisible and Scrolls a specified column or node into view without moving
TcxTreeListNode.MakeVisible focus.

TcxCustomTreeList.GotoNext Moves focus one node down.

TcxTreeListNode.Focused and Specify the focused node.


TcxCustomTreeList.FocusedNode

TcxTreeListOptionsView.FocusRect Specifies the visibility of the focus rectangle.

TcxCustomTreeList.GotoNext Moves focus one node down.

TcxCustomTreeList.GotoPrev Moves focus one node up.

TcxCustomTreeList.GotoNextPage Scrolls focus one page down.

TcxCustomTreeList.GotoPrevPage Scrolls focus one page up.

TcxCustomTreeList.GotoBOF Focuses the first node.

TcxCustomTreeList.GotoEOF Focuses the last node.

TcxCustomTreeList.IsBOF Checks whether the first node is focused.

TcxCustomTreeList.IsEOF Checks whether the last node is focused.

TcxCustomTreeList.OnCanFocusNode Enables you to prohibit focusing of individual nodes.

TcxCustomTreeList.OnFocusedNodeChanged Enables you to respond to node focus changes.

TcxTreeListOptionsSelection.CellSelect Enables cell-to-cell navigation instead of entire nodes.

TcxCustomTreeList.FocusedColumn and Specifies the focused column.


TcxTreeListColumn.Focused

TcxCustomTreeList.VisibleColumnCount Returns the number of visible columns.

TcxCustomTreeList.VisibleColumns Provides indexed access to visible columns.

TcxCustomTreeList.OnLeftPosChanged Enables you to respond when the tree list is horizontally


scrolled.

Page 107 of 1199


Member Table: Nested Bands
Feature Center   Layout Features   Nested Bands

Member Description

TcxTreeListBandPosition.BandIndex and Nest a band within a specified band.


TcxTreeListBand.MoveBand  

TcxTreeListBand.ParentBand and Provide access to the band's immediate parent band.


TcxTreeListBandPosition.ParentBand

TcxTreeListBand.RootParentBand Provides access to a band's root parent band.


 

TcxTreeListBand.HasAsParent Determines whether a band is a child of a specified band.


 

TcxTreeListBand.ChildBands Provides indexed access to child bands.

TcxCustomTreeList.MakeDefaultLayout Removes all bands, creates a new band and moves all columns
to this band.

Page 108 of 1199


Member Table: Save and Restore Layout
Feature Center   Layout Features   Save and Restore Layout

Member Description

TcxCustomTreeList.StoreToIniFile, Save the tree list's layout in an INI file, registry, or stream.
TcxCustomTreeList.StoreToRegistry, and
TcxCustomTreeList.StoreToStream

TcxCustomTreeList.RestoreFromIniFile, Restore the tree list's layout from an INI file, registry, or stream.
TcxCustomTreeList.RestoreFromRegistry, and
TcxCustomTreeList.RestoreFromStream

TcxCustomTreeList.OnGetStoredProperties, Specify how to specify how tree list, band, and column
TcxCustomTreeList.OnGetStoredPropertyValue, properties are persisted to external data stores.
TcxCustomTreeList.OnSetStoredPropertyValue,
TcxCustomTreeList.OnInitStoredObject,
TcxTreeListBand.OnGetStoredProperties,
TcxTreeListBand.OnGetStoredPropertyValue,
TcxTreeListBand.OnSetStoredPropertyValue,
TcxTreeListColumn.OnGetStoredProperties,
TcxTreeListColumn.OnGetStoredPropertyValue, and
TcxTreeListColumn.OnSetStoredPropertyValue

Page 109 of 1199


Member Table: Selection
Feature Center   Focus and Selection   Selection

Member Description

TcxTreeListOptionsSelection.MultiSelect Specifies whether the multi-select feature is enabled.

TcxTreeListNode.Selected Specifies whether the node is selected.

TcxCustomTreeList.Select Selects specified nodes.

TcxCustomTreeList.SelectAll Selects all the nodes.

TcxCustomTreeList.Deselect Unselects a node.

TcxCustomTreeList.ClearSelection Unselects all the selected nodes.

TcxCustomTreeList.SelectionCount Returns the number of selected nodes.

TcxCustomTreeList.Selections Provides indexed access to the selected nodes.

TcxCustomTreeList.OnCanSelectNode Enables you to prohibit selection of individual nodes.

TcxCustomTreeList.OnSelectionChanged Enables you to respond to node selection changes.

Page 110 of 1199


Member Table: Sorting Data
Feature Center   Data-Related Features   Sorting Data

Member Description

TcxTreeListColumn.SortOrder Specifies whether a column is involved in sorting.

TcxTreeListColumn.SortIndex Specifies a column's position within sorted


columns.

TcxCustomTreeList.ClearSorting Stops sorting by all columns.

TcxTreeListNode.AlphaSort Sorts a node's child nodes.

TcxTreeListOptionsData.AnsiSort Specifies how string comparisons are carried out


when sorting string cell values.

TcxTreeListOptionsData.CaseInsensitive Specifies whether sorting is case-insensitive.

TcxTreeListOptionsData.MultiThreadedSorting Specifies whether or not nodes are sorted using


multi-threaded algorithms.

TcxCustomTreeList.Sorted Indicates whether columns are sorted.

TcxCustomTreeList.SortedColumns and Provides indexed access to columns involved in


TcxCustomTreeList.SortedColumnCount sorting and returns the number of these columns.

TcxTreeListOptionsBehavior.Sorting Specifies whether end-users can sort by clicking


column headers.

TcxTreeListOptionsBehavior.MultiSort Specifies whether end-users can sort by multiple


columns.

TcxCustomTreeList.OnSorting and Enables you to respond to sorting data.


TcxCustomTreeList.OnSorted

TcxCustomEditContainerItemOptions.Sorting Specifies whether end-users can sort by a certain


column by clicking its header.

TcxCustomTreeList.OnCompare and Enables you to provide custom sorting logic for


TcxTreeListNode.CustomSort nodes.

Page 111 of 1199


Member Table: Stacked Columns
Feature Center   Layout Features   Stacked Columns

Member Description

TcxTreeListColumnPosition.RowIndex Specifies the vertical position of a column within its band.

TcxTreeListColumnPosition.SetPositionEx Moves a column at a specific position in a specified band.

TcxTreeListColumnPosition.SetPosition Moves a column within its band.

TcxTreeListOptionsCustomizing.StackedColumns Specifies whether end-users can stack columns via drag


and drop.

Page 112 of 1199


ExpressQuantumTreeList: Resource Strings
Strings displayed in various message boxes, dialogs and control elements of Developer Express VCL products are stored as
resources. This allows you to easily substitute them with custom strings depending on your needs (for instance, with localized
versions).

Developer Express offers you a simple and complete mechanism of localizing the resource strings, which is common to all
Developer Express VCL products. You can use the TcxLocalizer component designed to simplify localization tasks, or manually
replace the default value of specific resource strings at runtime via the cxSetResourceString procedure calls. To learn more about
the TcxLocalizer component, please refer to the How To Localize an Application Using the TcxLocalizer help topic.

The cxSetResourceString procedure is used with the cxGetResourceString function used by Developer Express controls. When
the controls need a specific string to display, they call the cxGetResourceString function, which returns either the custom string
or the default string (if the resource string was not replaced).

The resource strings used by the ExpressQuantumTreeList Suite are declared in the cxTLStrs unit.

Example
The TreeList control displays the confirmation dialog when an end-user deletes a node by pressing the Ctrl+Del key
combination. The dialog's caption is addressed by the scxTreeListDeletingConfirmationCaption identifier. The following code
replaces the caption with its German equivalent:

[Delphi]
cxSetResourceString(@scxTreeListDeletingConfirmationCaption, 'Bestätigen');

[C++ Builder]
cxSetResourceString(&_scxTreeListDeletingConfirmationCaption, "Bestätigen");

The list of resource strings for ExpressQuantumTreeList with default values is given below:

Resource identifier Value Description

scxExportNotVisibleControl 'Control must be visible for The error message that appears when
  export' attempting to export an invisible TreeList
control. Read the Export Data topic for
more information on exporting the
TreeList control.

scxIndexOutOfBounds 'Index %d out of bounds' The error message that appears when
  accessing a non-existent child node via
the Node.Items property.

scxInvalidStreamFormat 'Invalid stream format' The error message that may appear
  during the TreeList.LoadFromStream
method execution.

scxMultiSelectRequired 'Multi select required' The error message that appears when
  attempting to select several nodes when
the OptionsSelection.MultiSelect option is
deactivated.

scxOperationNotSupported 'Operation not supported' Not used.


 

scxTreeListDeletingConfirmationCaption 'Confirm' Specifies the delete confirmation dialog


  caption. Read the
OptionsBehavior.ConfirmDelete topic for
more information.
Page 113 of 1199
scxTreeListDeletingFocusedConfirmationText 'Delete record(s)?' Specifies the delete confirmation dialog
  text. Read the
OptionsBehavior.ConfirmDelete topic for
more information.

Customization form resource strings

Resource identifier Value Description

scxBandsCaption ' Bands ' Specifies the caption of the Bands tab of the TreeList customization
  form.

scxColumnsCaption ' Columns ' Specifies the caption of the Columns tab of the TreeList customization
  form.

scxCustomizeCaption 'Customize' Specifies the caption of the TreeList customization form.


 

Column Header Context Menu resource strings

# Resource identifier Value

1 scxTreeListSortAscendingMenuItem '&Sort Ascending'

2 scxTreeListSortDescendingMenuItem 'S&ort Descending'

3 scxTreeListClearSortingMenuItem '&Clear Sorting'

4 scxTreeListFooterMenuItem '&Footer'

5 scxTreeListGroupFootersMenuItem '&Group Footers'

6 scxTreeListRemoveThisColumnMenuItem 'R&emove This Column'

7 scxTreeListFieldChooserMenuItem 'F&ield Chooser'

8 scxTreeListHorizontalAlignmentMenuItem 'Ho&rizontal Alignment'

9 scxTreeListVerticalAlignmentMenuItem 'Ver&tical Alignment'

10 scxTreeListBestFitMenuItem '&Best Fit'

11 scxTreeListBestFitAllColumnsMenuItem 'Bes&t Fit (all columns)'

Page 114 of 1199


Group Footers sub-menu resource strings

# Resource identifier Value

1 scxTreeListGroupFootersInvisibleMenuItem '&Hidden'

2 scxTreeListGroupFootersVisibleWhenExpandedMenuItem '&Visible When Expanded'

3 scxTreeListGroupFootersAlwaysVisibleMenuItem '&Always Visible'

Horizontal Alignment sub-menu resource strings

# Resource identifier Value

1 scxTreeListHorizontalAlignmentLeftMenuItem '&Left'

2 scxTreeListHorizontalAlignmentCenterMenuItem 'Ce&nter'

3 scxTreeListHorizontalAlignmentRightMenuItem '&Right'

Vertical Alignment sub-menu resource strings

Page 115 of 1199


# Resource identifier Value

1 scxTreeListVerticalAlignmentTopMenuItem '&Top'

2 scxTreeListVerticalAlignmentCenterMenuItem 'Ce&nter'

3 scxTreeListVerticalAlignmentBottomMenuItem '&Bottom'

Footer Context Menu and Group Footer Context Menu resource strings

# Resource identifier Value

1 scxTreeListSumMenuItem 'Sum'

2 scxTreeListMinMenuItem 'Min'

3 scxTreeListMaxMenuItem 'Max'

4 scxTreeListCountMenuItem 'Count'

5 scxTreeListAvgMenuItem 'Average'

6 scxTreeListNoneMenuItem 'None'

7 scxTreeListAllNodesMenuItem 'All Nodes'

Page 116 of 1199


TcxCustomTreeList Object
Hierarchy   Properties   Methods   Events

The base class for the TcxDBTreeList, TcxTreeList, and TcxVirtualTreeList controls.

Unit
cxTL

Syntax

TcxCustomTreeList = class(TcxExtEditingControl, , IcxNavigator, IcxStoredParent, IcxStoredOb

Description
The TcxCustomTreeList class defines the basic functionality for classes implementing a tree-like data representation. This display m

The main element of the tree-like data representation is a node. Each node can have one or more child nodes. Nodes contain actual da
belongs to a column.

Columns represent the second group of control elements. Each column has a caption that allows end-users to uniquely identify the co
caption. Columns can be hidden (see Visible). Visible columns are stored in the collection exposed via the VisibleColumns property. A

Bands are objects that logically and visually group columns. Each band can have as many columns as you wish. Like columns, bands
property. Thus, a column can be accessed at two levels: owner band level (see Columns) and at TreeList control level (see ItemIndex)
collection.

In addition, the TreeList control contains a footer located at the bottom and this is used to display summary values. Use the TreeList

The TreeList control has several option sets that control different aspects of its behavior and appearance. These include:
l OptionsBehavior, determining the control's response to end-user actions;
l OptionsCustomizing, controlling how end-users can manipulate view items at runtime;
l OptionsData, determining the functionality of a data-aware view;
l OptionsSelection, managing selection within the TreeList control;
l OptionsView, controlling the visibility, color, width and other appearance settings of control elements;
l Navigator, controlling the visibility and appearance of the embedded navigator;
l FindPanel, controlling the Find Panel's look & feel.

Additionally, you have an option to define the styles of most of the TreeList elements using the Styles property.

Related Information

l Visual Elements
l ExpressPivotGrid: Visual Elements

Page 117 of 1199


TcxCustomDataTreeList Object
Hierarchy   Properties   Methods   Events

The base class for data-aware tree lists (TcxDBTreeList and TcxVirtualTreeList).

Unit
cxTLData

Syntax

TcxCustomDataTreeList = class(TcxCustomTreeList)

Description
This class provides the common functionality used in bound and provider modes.

Do not use this class directly. Use its descendants instead.

Page 118 of 1199


TcxCustomDBTreeList Object
Hierarchy   Properties   Methods   Events

The base class for the data-aware tree list control (TcxDBTreeList class).

Unit
cxDBTL

Syntax

TcxCustomDBTreeList = class(TcxCustomDataTreeList)

Description
This class extends its ancestor class with the DataController property representing an object that manages the connection to a
data source. The DataController.DataSource property specifies the TDataSet or its descendant that provides data for the TreeList
control. The DataController.KeyField and DataController.ParentField properties identify dataset fields used for building the tree
structure. Key field values uniquely identify dataset records (nodes, in the tree structure). The parent field of a record contains the
key field value for the record (node), which is the parent of the record (node) within the tree structure.

Data-aware columns are represented by TcxDBTreeListColumn class instances. The TcxDBTreeListColumn class provides the
DataBinding property that manages the column's connection to a data source.

Related Information

l TcxCustomDBTreeList.DataController
l TcxDBItemDataBinding Object
l TcxDBItemDataBinding.FieldName
l TcxDBTreeList Object
l TcxDBTreeListColumn Object
l TcxDBTreeListColumn.DataBinding
l TcxDBTreeListDataController Object
l TcxDBTreeListDataController.KeyField
l TcxDBTreeListDataController.ParentField

Page 119 of 1199


TcxDBTreeList Object
Hierarchy   Properties   Methods   Events

A data-aware version of the TreeList control.

Unit
cxDBTL

Syntax

TcxDBTreeList = class(TcxCustomDBTreeList)

Description
The TcxDBTreeList control is capable of displaying data from a TDataSet or its descendants in a tree-like structure. The
connection between the dataset and the TreeList control is managed via the TcxDBTreeListDataController instance, which can
be accessed by using the DataController property. Use the DataController.DataSource property to bind a dataset to the
TcxDBTreeList control. This dataset must have the two fields required for building a tree structure. Key field values are used to
uniquely identify dataset records. The parent field value for a specific record (node in the tree structure) specifies the key field
value for a record (node), which is its parent.

See the following screenshot as an example:

The key field of the dataset is ID and the parent field is PARENTID. As you can see, nodes with key values 2, 3, 4, 6, 7 and 8 are
child nodes for the node with key value 1. The PARENTID field value for these nodes is 1. Nodes with keys 14, 24 and 43 are
child nodes of the node with key value 3, etc. Some records (nodes) can have a parent field value without a corresponding key
field value within the dataset. Such records (nodes) will be displayed at the root level of the tree structure (see the node with ID =
1 in the above screenshot). Read the Self-Referenced Dataset topic for more information.
The key field name for the dataset is specified via the DataController.KeyField and the parent field name is specified via the
DataController.ParentField property value.

The TcxDBTreeList control supports many display capabilities:


l Sorting data against multiple columns;
l Summaries calculation;
l Node preview;
l Grouping nodes;
l Formatting summary values;
l Specifying in-place editors for cell contents;
Page 120 of 1199
l Find Panel;
l etc.

The TcxDBTreeList control also has advanced styles support. You can customize the control's look & feel by assigning different
styles to the control's elements or by assigning a style sheet to the whole control. The custom draw feature gives you full control
over the TreeList control's appearance.

Related Information

l Group Summaries

Page 121 of 1199


TcxTreeList Object
Hierarchy   Properties   Methods   Events

A control that displays data in a tree-like manner.

Unit
cxTL

Syntax

TcxTreeList = class(TcxCustomTreeList)

Description
The base element of a tree-like structure is a node. Nodes contain actual data. You can use the Node.Values property of a node
to access its values, one for each column within the control.

The TreeList control supports node(s) selection. To select a node, an end-user should click it with the mouse. Additionally, the
control supports multiple node selection. An additional node can be selected by clicking the node holding down the Ctrl key. The
Ctrl key can also be used to exclude a node from the selection. Alternatively, the end-user can select a range of nodes by using
the Shift key. To select a range of nodes, the end-user should first select the initial node within the range, press the Shift key
and then click the final node for the range.

Each TreeList column has a caption that uniquely identifies the column among the other columns. Also, the end-user can use
the caption to resize the column and to move it to another location within the control.

Page 122 of 1199


The TreeList control supports sorting by column values. To sort, the end-user should click a column header. To change the sort
order, another click is required. To clear sorting by a column, the end-user should click the column header while holding down the
Ctrl key. The control supports the sorting of several columns at once. Use the OptionsBehavior.MultiSort property to enable this
feature. To sort on a second column, the end-user clicks on the column header while holding down the Shift key.

Columns are logically and visually arranged in bands. Each band can have a number of associated nodes. Like columns, bands
have captions that are used to identify the band uniquely, resize it and relocate it within the control. Bands can be fixed either to
the left or the right side of the control. Columns that belong to fixed bands are not involved in horizontal scrolling.

Bands and columns can be hidden at runtime using the customization form. This form is used to remove/restore bands and
columns temporarily. The end-user can move the desired bands or columns to the customization form, scroll to the desired
location within the control and restore them. To move a band or a column to the customization form, the end-user should drag the
desired band or column header to the form. A band or a column moved to the customization form is removed from the TreeList
control. To restore a band or a column from the customization form, the end-user should drag the band or column header back to
the control.

Page 123 of 1199


The TreeList control supports Developer Express styles technology. You can specify style settings for the control's various
visual elements at design and runtime. Support for style sheets means that styles can be assigned for all control elements at
once.

The TreeList control supports summary calculations. A developer can define summary items for each column within the control.
Summary results are displayed within the footer and group footers.

Page 124 of 1199


The TreeList control provides a huge number of properties, methods, and events that allow a developer to customize the control's
look and feel and behavior as required. Sets of properties dealing with similar functionality are arranged in groups and are
exposed by option objects. To learn about these objects, refer to the Options topic.

Related Information

l Group Summaries

Page 125 of 1199


TcxCustomVirtualTreeList Object
Hierarchy   Properties   Methods

The base class for the TcxVirtualTreeList control used in provider mode.

Unit
cxTLData

Syntax

TcxCustomVirtualTreeList = class(TcxCustomDataTreeList)

Description
This class extends the TcxCustomDataTreeList class with the capabilities to work with custom data structures. The
TcxCustomVirtualTreeList class declares the CustomDataSource property that allows you to bind the TreeList control to a
custom data source.

Do not use the TcxCustomVirtualTreeList class directly. Use its descendant instead.

Page 126 of 1199


TcxVirtualTreeList Object
Hierarchy   Properties   Methods   Events

A TreeList control used in provider mode.

Unit
cxTLData

Syntax

TcxVirtualTreeList = class(TcxCustomVirtualTreeList)

Description
The virtual TreeList control allows you to work with tree-like data structures of your own format. For detailed information, please
refer to the Introduction To Provider Mode help topic.

The TcxVirtualTreeList class does not introduce any new functionality, but instead publishes inherited members.

Page 127 of 1199


cxDBTL Unit
Classes
TcxCustomDBTreeList
TcxDBItemDataBinding
TcxDBTreeList
TcxDBTreeListColumn
TcxDBTreeListDataController
TcxDBTreeListNode
TcxDBTreeListOptionsData

Page 128 of 1199


cxTL Unit
Classes
TcxCustomTreeList
TcxTreeList
TcxTreeListBand
TcxTreeListBandCellViewInfo
TcxTreeListBandOptions
TcxTreeListBandRow
TcxTreeListBandRows
TcxTreeListBands
TcxTreeListBandStyles
TcxTreeListBuiltInMenu
TcxTreeListCaption
TcxTreeListColumn
TcxTreeListColumnHeaderPopupMenu
TcxTreeListColumnOptions
TcxTreeListColumnPosition
TcxTreeListColumnStyles
TcxTreeListColumnSummary
TcxTreeListCustomBuiltInMenu
TcxTreeListCustomCellViewInfo
TcxTreeListCustomHeaderCellViewInfo
TcxTreeListCustomizing
TcxTreeListCustomPopupMenu
TcxTreeListDataController
TcxTreeListEditCellViewInfo
TcxTreeListFooterCellViewInfo
TcxTreeListFooterPopupMenu
TcxTreeListGroupFooterPopupMenu
TcxTreeListHeaderCellViewInfo
TcxTreeListHitTest
TcxTreeListIndentCellViewInfo
TcxTreeListIndicatorCellViewInfo
TcxTreeListLikeParams
TcxTreeListNode
TcxTreeListOptionsBehavior
TcxTreeListOptionsCustomizing
TcxTreeListOptionsData
TcxTreeListOptionsSelection
TcxTreeListOptionsView

Page 129 of 1199


TcxTreeListPopupMenu
TcxTreeListPopupMenus
TcxTreeListPreview
TcxTreeListStyles
TcxTreeListStyleSheet
TcxTreeListSummary
TcxTreeListSummaryItem
TcxTreeListSummaryItems
TcxUnboundTreeListNode

Other Types
TcxTreeListBandExpandable
TcxTreeListBandPart
TcxTreeListBuiltInMenuItemType
TcxTreeListImageIndexType
TcxTreeListNodeAttachMode
TcxTreeListNodeCheckGroupType

Global Constants
cxTreeListDefMinWidth
cxTreeListDefWidth

Page 130 of 1199


cxTLData Unit
Classes
TcxCustomDataTreeList
TcxCustomVirtualTreeList
TcxDataTreeListDataController
TcxTreeListCustomDataSource
TcxVirtualTreeList
TcxVirtualTreeListNode
TcxVirtualTreeListOptionsData

Page 131 of 1199


cxTLExportLink Unit
Routines
cxExportTLToCSV
cxExportTLToExcel
cxExportTLToHTML
cxExportTLToText
cxExportTLToXLSX
cxExportTLToXML

Page 132 of 1199


TcxTreeListBand Object
Hierarchy   Properties   Methods   Events

A band within a TreeList control.

Unit
cxTL

Syntax

TcxTreeListBand = class(TcxInterfacedCollectionItem)

Description
This class extends its ancestor with members that allow you to:
l Change the band's visibility and caption (Visible and Caption);
l Adjust the band's position and size (Position, MoveBand, RootIndex, Width, and MinWidth);
l Customize the band's appearance and behavior options (Options and Styles);
l Fix the band to the TreeList control's left or right side (FixedKind);
l Specify whether the band displays expand buttons (Expandable);
l Automatically resize the band to the minimum required to completely display its column cell values (ApplyBestFit);
l Restore default appearance and layout band options (RestoreDefaults and RestoreWidths);
l Access columns associated with the band (Columns and VisibleColumns);
l Customize band layout persistence (OnGetStoredProperties, OnGetStoredPropertyValue, and OnSetStoredPropertyValue).

The TreeList control's Bands collection provides indexed access to all created bands. To access only the currently visible
bands, use the Bands.VisibleItems property.

Page 133 of 1199


TcxTreeListBands Object
Hierarchy   Properties   Methods

Represents a band collection.

Unit
cxTL

Syntax

TcxTreeListBands = class(TCollection)

Description
This class introduces members that allow you to do the following:
l Add bands to the collection (Add).
l Restore band widths and default values of band settings (RestoreWidths and RestoreDefaults).
l Access individual bands (BottomItems, Items, RootItems, FirstVisible, LastVisible, VisibleItems, and VisibleRootItems).
l Determine the number of:
l Bands at a certain level of the band hierarchy (BottomItemCount, RootItemCount, VisibleItemCount, and
VisibleRootItemCount).
l Bands that are fixed (VisibleLeftFixedCount, VisibleRightFixedCount, VisibleRootLeftFixedCount, and
VisibleRootRightFixedCount).
l Rows occupied by band and column headers (LineCount and ColumnLineCount).

The TcxTreeListBands object is referenced by the TreeList control's Bands property and a band's Bands property.

Page 134 of 1199


TcxTreeListBandOptions Object
Hierarchy   Properties

Represents band options.

Unit
cxTL

Syntax

TcxTreeListBandOptions = class(TcxOwnedPersistent)

Description
This class extends its ancestor class with members that allow you to:
l Specify the visibility of a band within the customization form (Hidden).
l Specify whether end-users can move a band (Moving).
l Specify whether end-users can move a band to the customization form (Customizing).
l Specify whether end-users can resize a band (Sizing and VertSizing).
l Specify whether a band can accept columns from other bands (OnlyOwnColumns).
l Restore band options to their default values (RestoreDefaults).

The TcxTreeListBandOptions object is referenced by a band's Options property.

Page 135 of 1199


TcxTreeListBandRow Object
Hierarchy   Properties   Methods

Represents a band's row displaying column headers.

Unit
cxTL

Syntax

TcxTreeListBandRow = class(TObject)

Description
In the TreeList control, columns can be arranged into multiple rows. Visually, a band's row is represented by a number of column
headers that correspond to the band's columns arranged within this row.

If a band is nested within the TreeList control, a band row is associated with this band only if the band is positioned at the
bottom of the band hierarchy.

Each band row represents a TcxTreeListBandRow instance that allows you to access the following information:
l Columns arranged within the row (Items, VisibleItems, First, and Last).
l Column position within the row (IndexOf).
l Band associated with the band row (Band).
l Band row collection that contains all rows associated with a certain band (BandRows).
l Band row's attributes:
l Position within the band row collection (Index, IsFirst, and IsLast).
l Vertical position within the column header panel (VisibleIndex and LineOffset).
l Current and minimum possible widths (Width and MinWidth).
l Height (LineCount).

Related Information

l TcxTreeListColumn Object

Page 136 of 1199


TcxTreeListBandRows Object
Hierarchy   Properties

Represents a collection of band rows associated with a certain band.

Unit
cxTL

Syntax

TcxTreeListBandRows = class(TObject)

Description
This class introduces the properties that allow you to access the following information:
l Rows contained within the collection (Items, VisibleItems, First, and Last).
l Band associated with band rows in the collection (Band).
l Combined row height and width of all band rows (LineCount, RowMinWidth, and RowMaxWidth).

The TcxTreeListBandRows object is referenced by a band's BandRows property and a band row's BandRows property.

Page 137 of 1199


TcxDBTreeListColumn Object
Hierarchy   Properties   Methods   Events

A column within a data-aware TreeList control.

Unit
cxDBTL

Syntax

TcxDBTreeListColumn = class(TcxTreeListColumn)

Description
The TcxDBTreeListColumn class extends its ancestor class with the DataBinding property, which allows you to bind a column
to a persistent field of the underlying data source.

The data-aware TreeList control's Columns collection provides indexes to all created columns. To access the columns that are
currently visible within the data-aware TreeList control, use its VisibleColumns collection.

Page 138 of 1199


TcxTreeListColumn Object
Hierarchy   Properties   Methods   Events

A column within an unbound or virtual TreeList control.

Unit
cxTL

Syntax

TcxTreeListColumn = class(TcxCustomInplaceEditContainer)

Description
This class publishes some properties inherited from its ancestor class, and also extends it with members that allow you to:
l Change the following column attributes:
l Visibility (Visible)
l Caption (Caption)
l Layout (Position, IsPreview, Width, and MinWidth).
l Adjust appearance and behavior options (Options and Styles).
l Specify sorting and summary options (SortOrder and Summary).
l Specify data binding settings (DataBinding).
l Dynamically provide cell display values and format them (OnGetDisplayText, OnGetEditProperties, and
OnGetEditingProperties).
l Access values and display values of the column's data cells (Values and DisplayTexts).
l Access the currently edited cell value (EditValue).
l Automatically adjust the column's width to the minimum required to completely display its cell values (ApplyBestFit and
BestFitMaxWidth).
l Restore default appearance and layout column options (RestoreDefaults and RestoreWidths).
l Customize column layout persistence (OnGetStoredProperties, OnGetStoredPropertyValue, and
OnSetStoredPropertyValue).

The unbound or virtual TreeList control's Columns collection provides indexed access to all created columns. To access the
columns that are currently visible within the unbound TreeList control, use its VisibleColumns collection.

Related Information

l TcxDBTreeListColumn Object

Page 139 of 1199


TcxTreeListColumnPosition Object
Hierarchy   Properties   Methods

Represents a set of options that determine the layout aspects of a column within the TreeList control.

Unit
cxTL

Syntax

TcxTreeListColumnPosition = class(TcxOwnedPersistent)

Description
This class introduces members that allow you to:
l Specify the band containing the column (BandIndex).
l Specify the column's horizontal and vertical positions within a band (ColIndex and RowIndex).
l Specify the column header's height in lines (LineCount).
l Simultaneously change multiple layout options (SetPosition and SetPositionEx).
l Access the band, column, and row properties (Band, Column, and Row).
l Determine the visible position of the column within the TreeList control (VisibleBandIndex, VisibleColIndex, and
VisibleRowIndex).

The TcxTreeListColumnPosition object is referenced by a column's Position property.

Page 140 of 1199


TcxTreeListColumnOptions Object
Hierarchy   Properties   Methods

Contains column options.

Unit
cxTL

Syntax

TcxTreeListColumnOptions = class(TcxCustomEditContainerItemOptions)

Description
This class extends its ancestor class with members that allow you to:
l Specify the visibility of an ellipsis in a column's data cells with truncated content (CellEndEllipsis).
l Specify the visibility of footer and group footer cells for a column (Footer and GroupFooter).
l Specify the visibility of a column within the customization form (Hidden).
l Specify whether end-users can resize a column (Sizing and VertSizing).
l Specify the sizing mode for a column's multi-line in-place editor (EditAutoHeight).
l Restore column options to their default values (RestoreDefaults).

The TcxTreeListColumnOptions object is referenced by a column's Options property.

Page 141 of 1199


TcxTreeListBuiltInMenu Object
Hierarchy   Properties

Represents a generic built-in context TreeList menu.

Unit
cxTL

Syntax

TcxTreeListBuiltInMenu = class(TcxTreeListCustomBuiltInMenu)

Description
This class extends its ancestor class with the PopupMenu property that provides access to a TPopupMenu object, representing
a built-in context menu.
The TcxTreeListBuiltInMenu class is referenced by a context menu's BuiltInMenu property.

Page 142 of 1199


TcxTreeListColumnHeaderPopupMenu Object
Hierarchy   Properties   Methods   Events

Represents the column header context menu.

Unit
cxTL

Syntax

TcxTreeListColumnHeaderPopupMenu = class(TcxTreeListPopupMenu)

Description
This class extends its ancestor class with the Items property that allows you to specify the visibility of specific menu items.
The TcxTreeListColumnHeaderPopupMenu object is referenced by the TreeList control's PopupMenus.ColumnHeaderMenu
property.

Page 143 of 1199


TcxTreeListCustomBuiltInMenu Object
Hierarchy   Properties

Represents the base class for TreeList built-in context menus.

Unit
cxTL

Syntax

TcxTreeListCustomBuiltInMenu = class(TcxTreeListCustomPopupMenu)

Description
This class doesn't introduce any new public members, but instead specifies the built-in menu's root item, and extends its
ancestor class with members that are common to all built-in context menus.

Related Information

l TcxTreeListBuiltInMenu Object

Page 144 of 1199


TcxTreeListCustomPopupMenu Object
Hierarchy   Properties

Represents the base class for TreeList context menus.

Unit
cxTL

Syntax

TcxTreeListCustomPopupMenu = class(TcxOwnedPersistent)

Description
This class introduces members that are common to all TreeList context menus:
l Root – provides access to the context menu's root item.
l TreeList – provides access to the TreeList control with which the context menu is associated.
l PopupMenu – specifies a TPopupMenu descendant that is used as the context menu.

Descendants of the TcxTreeListCustomPopupMenu class (TcxTreeListCustomBuiltInMenu and TcxTreeListPopupMenu)


declare additional menu specific members that correspond to built-in and custom context menus.

Page 145 of 1199


TcxTreeListFooterPopupMenu Object
Hierarchy   Properties   Methods   Events

Represents the footer context menu.

Unit
cxTL

Syntax

TcxTreeListFooterPopupMenu = class(TcxTreeListPopupMenu)

Description
This class extends its ancestor class with the Items property that allows you to specify the visibility of specific menu items.
The TcxTreeListFooterPopupMenu object is referenced by the TreeList control's PopupMenus.FooterMenu property.

Page 146 of 1199


TcxTreeListGroupFooterPopupMenu Object
Hierarchy   Properties   Methods   Events

Represents the group footer context menu.

Unit
cxTL

Syntax

TcxTreeListGroupFooterPopupMenu = class(TcxTreeListFooterPopupMenu)

Description
This class doesn't introduce any new members, but instead specifies the position suitable for invoking the group footer context
menu.
The TcxTreeListGroupFooterPopupMenu object is referenced by the TreeList control's PopupMenus.GroupFooterMenu
property.

Page 147 of 1199


TcxTreeListPopupMenu Object
Hierarchy   Properties   Methods   Events

Represents a TreeList's generic context menu.

Unit
cxTL

Syntax

TcxTreeListPopupMenu = class(TcxTreeListCustomPopupMenu)

Description
The TreeList control allows you to display either built-in or custom menus as context menus. The built-in menu is automatically
populated with predefined menu items, while a custom menu can be represented by any TMenu descendant. You can specify
which menu type is displayed and customize its contents using the TcxTreeListPopupMenu class members. These members
allow you to:
l Enable the built-in menu to be displayed as a context menu and access its items (UseBuiltInMenu and BuiltInMenu).
l Customize the contents of the context menu being invoked (OnPopup).
l Create custom menu items within the built-in menu and provide images for them (CreateMenuItem and UserImages).
l Respond to clicks on built-in menu items (OnClick).

Descendants of the TcxTreeListPopupMenu class (TcxTreeListFooterPopupMenu, TcxTreeListGroupFooterPopupMenu, and


TcxTreeListColumnHeaderPopupMenu) represent context menus for certain visual elements. The built-in menus associated with
these classes contain items that are specific to a corresponding visual element.

Page 148 of 1199


TcxTreeListPopupMenus Object
Hierarchy   Properties

Represents a set of context menus available within the TreeList control.

Unit
cxTL

Syntax

TcxTreeListPopupMenus = class(TcxOwnedPersistent)

Description
This class introduces properties that allow you to access the following menus:
l Column header context menu (ColumnHeaderMenu).
l Footer context menu (FooterMenu).
l Group footer context menu (GroupFooterMenu).
The TcxTreeListPopupMenus object is referenced by the TreeList control's PopupMenus property.

Page 149 of 1199


TcxDataTreeListDataController Object
Hierarchy   Properties

Manages interaction between the TcxVirtualTreeList control and the linked custom data source in provider mode.

Unit
cxTLData

Syntax

TcxDataTreeListDataController = class(TcxTreeListDataController)

Description
The TcxDataTreeListDataController inherits all its functionality from the TcxTreeListDataController and adds support for
custom data sources. The custom data source is used when working in provider mode.

The TcxDataTreeListDataController object is referenced by the tree list's DataController property.

Page 150 of 1199


TcxDBTreeListDataController Object
Hierarchy   Properties   Methods   Events

Represents an object managing the cxDBTreeList control's access to a dataset.

Unit
cxDBTL

Syntax

TcxDBTreeListDataController = class(TcxDataTreeListDataController)

Description
The cxDBTreeList control is bound to a data source via the DataController property. This property represents the
TcxDBTreeListDataController object that manages the connection to a dataset.
The dataset providing data for cxDBTreeList is specified via the DataController.DataSource property. This dataset should meet
certain requirements. Besides the key field, whose values uniquely identify dataset records, it must contain an additional field,
whose values specify the parent node (record) key field for the current node (record). The data source key field is identified via the
DataController.KeyField property. The name of the data source containing the parent node's key field values is specified via the
DataController.ParentField property.
To learn more on the hierarchical structure that must meet the tree list requirement, refer to the Self-Referenced Dataset help
topic.

The TcxDBTreeListDataController object is referenced by the tree list's DataController property.

Related Information

l TcxCustomTreeList.OptionsData
l TcxDBTreeList Object

Page 151 of 1199


TcxTreeListCustomDataSource Object
Hierarchy

A custom data source for the virtual TreeList control.

Unit
cxTLData

Syntax

TcxTreeListCustomDataSource = class(TcxCustomDataSource)

Description
This class provides the base functionality to implement a user-defined data source. You can inherit your own class from
TcxTreeListCustomDataSource to enable your control to display arbitrary data. As a rule, you have to implement your custom
data source when it is necessary to display information from an aggregate data structure within the control (for instance, a tree
structure, a cluster of linked objects, a list, etc.). To set a custom data source for the control, use the CustomDataSource
property. When a data controller retrieves data from a custom data source, it is operating in provider mode.
To learn how to implement a custom data source, refer to the Introduction To Provider Mode help topic.

The TcxTreeListCustomDataSource object is referenced by the TcxVirtualTreeList.CustomDataSource property, and by the


data controller's CustomDataSource property.

Page 152 of 1199


TcxTreeListDataController Object
Hierarchy

Represents the base class for the TcxDBTreeListDataController and TcxDataTreeListDataController used in bound and provider
modes.

Unit
cxTL

Syntax

TcxTreeListDataController = class(TcxControlDataController)

Description
Do not use this class directly. Use its descendants instead.

Page 153 of 1199


TcxDBItemDataBinding Object
Hierarchy   Properties

Represents an object associating a data-aware item with a dataset field.

Unit
cxDBTL

Syntax

TcxDBItemDataBinding = class(TcxCustomItemDataBinding)

Description
The TcxDBItemDataBinding object provides the connection of a data-aware item (column) to a cxDBTreeList data source.
When the cxDBTreeList control is bound to a data source, each TreeList item (column) is connected to a particular data source
field. This field is specified via the DataBinding.FieldName property. The DataBinding.Field property provides access to the
corresponding TField object.

The TcxDBItemDataBinding object is referenced by the column's DataBinding property.

Page 154 of 1199


TcxTreeListHitTest Object
Hierarchy   Properties   Methods

Contains the HitTest information about the tree list elements located at a specified test point.

Unit
cxTL

Syntax

TcxTreeListHitTest = class(TcxCustomHitTestController)

Description
This class provides the HitX, HitY, and HitPoint properties that allow you to specify the relative coordinates of the test point, in
pixels. Note that if you assign the HitX and HitY properties, you must call the ReCalculate method to update the hit test
information returned by other TcxTreeListHitTest class members.

After the test point is specified, you can use TcxTreeListHitTest properties to identify the tree list elements that contain this
test point. In addition, the TcxTreeListHitTest class provides the HitBand, HitColumn, and HitNode properties with which you
can access attributes of the elements that correspond to the test point.

The TcxTreeListHitTest instance is referenced by a TreeList control's HitTest property.

Note:   Do not create a TcxTreeListHitTest instance explicitly. It is created automatically on demand.

Page 155 of 1199


TcxDBTreeListNode Object
Hierarchy   Properties   Methods

A data-aware control's node.

Unit
cxDBTL

Syntax

TcxDBTreeListNode = class(TcxTreeListNode)

Description
This class introduces the KeyValue and ParentKeyValue properties that allow manual assignment of unique identifiers, if, for
some reason, the node's ID automatic generation is disabled (see the tree list's OptionsData.AutoCalcKeyValue property).

Page 156 of 1199


TcxTreeListNode Object
Hierarchy   Properties   Methods

The base class for nodes used in the TcxDBTreeList, TcxTreeList, and TcxVirtualTreeList controls.

Unit
cxTL

Syntax

TcxTreeListNode = class(TPersistent)

Description
Nodes are organized in a hierarchical structure using parent-child relationships. Every node can have child nodes and these are
defined by the Items collection.
Nodes can be expanded to display the next level of child nodes. Users can expand a node by pressing its plus (+) button if it is
displayed or can expand it by setting the Expanded property to True. Setting the property to False hides child nodes. The
TreeList control fires the following events in response to expanding/collapsing its nodes: OnExpanding, OnExpanded,
OnCollapsing, and OnCollapsed.
The HasChildren property specifies whether a node may have children. The number of child nodes is returned via the Count
property. You can manually set the property to True to display the plus (+) button for the node (ensure that the TreeList
control's OptionsView.Buttons property is set to True). An end-user can press it and thus generate the TreeList control's
OnExpanding event. This can be used to implement dynamic node loading.
The TreeList control allows you to display up to two images within nodes. You need to assign ImageList instances to the
TreeList control's Images and StateImages properties for this purpose. There are a number of ways to assign images to
individual nodes.
The TcxTreeListNode class provides several methods that can be used to navigate through the TreeList control. These
methods provide access to the next/previous visible, child and sibling nodes. See the GetNext, GetNextChild, getNextSibling,
GetNextSiblingVisible, GetNextVisible, GetPrev, GetPrevChild, getPrevSibling, GetPrevSiblingVisible, and GetPrevVisible method
descriptions. Note that using these methods improves performance during recursive navigation through the tree structure.
The TreeList control provides drag-and-drop functionality, which enables users to move nodes to another position, to another
TreeList control or even to a third-party control. If the TreeList control's DragMode property is set to dmAutomatic, dragging
occurs automatically. You can control drag-and-drop operations by handling the OnDragOver and OnDragDrop events.

Do not use this class directly. Use its descendants instead.

Related Information

l TreeList Elements Review

Page 157 of 1199


TcxUnboundTreeListNode Object
Hierarchy   Properties   Methods

Represents the TcxTreeList control's node.

Unit
cxTL

Syntax

TcxUnboundTreeListNode = class(TcxTreeListNode)

Description
The TcxUnboundTreeListNode class is derived from the TcxTreeListNode to provide persistence capability for the node in
unbound mode.

Page 158 of 1199


TcxVirtualTreeListNode Object
Hierarchy   Properties   Methods

Represents the TcxVirtualTreeList control's node.

Unit
cxTLData

Syntax

TcxVirtualTreeListNode = class(TcxTreeListNode)

Description
The TcxVirtualTreeListNode class is derived from the TcxTreeListNode to provide referential consistency between the node and
the corresponding custom data source's record.

Page 159 of 1199


TcxDBTreeListOptionsData Object
Hierarchy   Properties

Contains settings affecting the functionality of a data-aware TreeList control.

Unit
cxDBTL

Syntax

TcxDBTreeListOptionsData = class(TcxVirtualTreeListOptionsData)

Description
The options of the TcxDBTreeListOptionsData class define the functionality of a data-aware cxDBTreeList control. This class
inherits the basic data-aware functionality options from its ancestor – TcxVirtualTreeListOptionsData, whose properties determine
manage dataset access: insertion, editing and deletion of records.
The TcxDBTreeListOptionsData class extends the set of data-aware options. The AutoCalcKeyValue property determines
whether the key field value for the inserted node (record) is calculated automatically. The SmartRefresh option specifies whether
the TreeList data controller updates only changed records. The SyncMode property enables synchronization between the
TreeList control and the corresponding TDataSet.

The TcxDBTreeListOptionsData object is referenced by the TcxDBTreeList.OptionsData property.

Related Information

l TcxVirtualTreeListOptionsData Object
l TcxVirtualTreeListOptionsData.SmartLoad

Page 160 of 1199


TcxTreeListOptionsBehavior Object
Hierarchy   Properties

Stores the TreeList control's behavior and end-user functionality settings.

Unit
cxTL

Syntax

TcxTreeListOptionsBehavior = class(TcxControlOptionsBehavior)

Description
Options allow you to handle the following end-user actions:
l Drag and drop (AutoDragCopy, DragCollapse, DragExpand, DragFocusing, and WaitForExpandNodeTime);
l Sorting data (Sorting and MultiSort);
l Node expansion (ExpandOnDblClick and ExpandOnIncSearch);
l Node and in-place editor vertical sizing (EditAutoHeight);
l Node scrolling and hot-tracking (RecordScrollMode and HotTrack);
l Incremental searching (IncSearchItem);
l Displaying hints for visual elements with truncated content and navigator buttons (FooterHints, HeaderHints, and
NavigatorHints);
l Applying changes to the TreeList control (ChangeDelay, ConfirmDelete, and ShowHourGlass).

The TreeList control's OptionsBehavior property references a TcxTreeListOptionsBehavior object.

Page 161 of 1199


TcxTreeListOptionsCustomizing Object
Hierarchy   Properties

Represents a set of options, which determine how end-users can customize the TreeList control's layout.

Unit
cxTL

Syntax

TcxTreeListOptionsCustomizing = class(TcxOwnedPersistent)

Description
Options in the set allow you to control the following layout aspects:
l Band customization, moving, and resizing (BandCustomizing, BandMoving, BandHorzSizing, and BandVertSizing).
l Column customization, moving, and resizing (ColumnCustomizing, ColumnMoving, ColumnHorzSizing, and
ColumnVertSizing).
l Node height (RowSizing and NodeSizing).
l Instant visualization of band, column or node sizing (DynamicSizing).

The TcxTreeListOptionsCustomizing class is referenced by the TreeList control's OptionsCustomizing property.

Related Information

l TcxTreeListColumn Object

Page 162 of 1199


TcxTreeListOptionsData Object
Hierarchy   Properties

Represents a set of options specifying how data is managed within the TreeList control and which data management operations
are available to end-users.

Unit
cxTL

Syntax

TcxTreeListOptionsData = class(TcxControlOptionsData)

Description
Options in this set control the following operations:
l Appending, inserting, editing, and deleting nodes (Inserting, Editing, and Deleting).
l Sorting (MultiThreadedSorting, AnsiSort, and CaseInsensitive).
l Summary calculation (SummaryNullIgnore).

The TcxTreeListOptionsData class is referenced by the TreeList control's OptionsData property.

Page 163 of 1199


TcxTreeListOptionsSelection Object
Hierarchy   Properties

Represents selection settings for the TreeList control.

Unit
cxTL

Syntax

TcxTreeListOptionsSelection = class(TcxOwnedPersistent)

Description
This class provides a set of properties that allow:
l The choice of data cells to be selected by end-users (CellSelect).
l The selection of multiple data cells (MultiSelect).
l The selection highlighting for the focused node (InvertSelect).
l The drawing of highlighted and focus rectangles within the selected data cell when the TreeList control is not focused
(HideSelection and HideFocusRect).

The TcxTreeListOptionsSelection class is referenced by the TreeList control's OptionsSelection property.

Page 164 of 1199


TcxTreeListOptionsView Object
Hierarchy   Properties   Methods

Stores the TreeList control's appearance settings.

Unit
cxTL

Syntax

TcxTreeListOptionsView = class(TcxControlOptionsView)

Description
This class extends its ancestor with members that allow you to customize the visibility and appearance of the following TreeList
elements:
l Nodes (CategorizedColumn, PaintStyle, UseImageIndexForSelected, and UseNodeColorForIndent);
l Node indicator (Indicator, IndicatorWidth, ExtPaintStyle, and DropNodeIndicator);
l Node check groups (CheckGroups);
l Band headers (Bands and ExtPaintStyle);
l Band header panel (BandLineHeight);
l Column headers (ColumnAutoWidth, ExtPaintStyle, and HeaderAutoHeight);
l Footer (Footer);
l Group footers (GroupFooters);
l Fixed band separators (FixedSeparatorColor and FixedSeparatorWidth);
l Tree and grid lines (ShowRoot, TreeLineColor, TreeLineStyle, GridLines, and GridLineColor);
l Expand buttons (Buttons, ShowRoot, TreeLineColor, and TreeLineStyle);
l In-place editor in eahEditor sizing mode (EditAutoHeightBorderColor);
l Customization form (SimpleCustomizeBox).

You can restore the default TreeList control appearance settings by calling the RestoreDefaults procedure.

The TreeList control's OptionsView property references a TcxTreeListOptionsView object.

Page 165 of 1199


TcxVirtualTreeListOptionsData Object
Hierarchy   Properties

Contains settings used to control the data load behavior.

Unit
cxTLData

Syntax

TcxVirtualTreeListOptionsData = class(TcxTreeListOptionsData)

Description
In addition to the inherited members, the TcxVirtualTreeListOptionsData class introduces new properties:
l CheckHasChildren – enables checking for child nodes before the parent node is loaded.
l SmartLoad – enables partial data load from storage (if large data stores are used), for performance optimization.

The TcxVirtualTreeListOptionsData object is referenced by the TcxVirtualTreeList.OptionsData property.

Page 166 of 1199


TcxTreeListPreview Object
Hierarchy   Properties

Represents a set of appearance and behavior options of the TreeList control's preview section.

Unit
cxTL

Syntax

TcxTreeListPreview = class(TcxOwnedPersistent)

Description
Options in this set allow you to control the following preview aspects:
l Visibility (Visible).
l Content (Column).
l Position relative to a node (Place).
l Height (AutoHeight and MaxLineCount).
l Text margins (LeftIndent and RightIndent).

The TcxTreeListPreview object is referenced by the TreeList control's Preview property.

Page 167 of 1199


TcxTreeListBandStyles Object
Hierarchy   Properties

A collection of style links for the various band elements.

Unit
cxTL

Syntax

TcxTreeListBandStyles = class(TcxStyles)

Description
This class introduces properties that allow you to define the appearance of various band elements. The class is exposed via the
band's Styles property. Using properties of this class, you can define the styles of a band's content, footer and header.
Also, it is possible to define band styles using the following events: OnGetBandBackgroundStyle, OnGetBandContentStyle, and
OnGetBandHeaderStyle.

Page 168 of 1199


TcxTreeListColumnStyles Object
Hierarchy   Properties

Contains a column's style settings.

Unit
cxTL

Syntax

TcxTreeListColumnStyles = class(TcxEditContainerStyles)

Description
A TcxTreeListColumnStyles class instance is exposed via a column's Styles property. Use properties of this class to define
the style settings of the column header, content and footer.
You can also define the styles of the column header and footer by handling the OnGetColumnHeaderStyle and
OnGetColumnFooterStyle events.

Page 169 of 1199


TcxTreeListStyles Object
Hierarchy   Properties   Events

Contains settings controlling the style of the TreeList control's elements.

Unit
cxTL

Syntax

TcxTreeListStyles = class(TcxCustomControlStyles)

Description
This class declares properties allowing you to customize the appearance of the tree list elements. You can specify the style
settings for:
l The TreeList control (see Background) and its bands background (see BandBackground);
l Column headers (see ColumnHeader) and column footer cells (see ColumnFooter);
l The control's footer (see Footer);
l Preview sections (see Preview);
l Even and odd nodes (see ContentEven and ContentOdd);
l The control's navigator (Navigator and NavigatorInfoPanel);
l The control's Find Panel (FindPanel and SearchResultHighlight);
l etc.

Page 170 of 1199


TcxTreeListStyleSheet Object
Hierarchy   Properties

A style sheet for the TreeList control.

Unit
cxTL

Syntax

TcxTreeListStyleSheet = class(TcxCustomStyleSheet)

Description
A StyleSheet property contains a collection of styles that can be applied to the control, thus setting multiple styles in one step.
The TcxTreeListStyleSheet class provides a style sheet collection for the TreeList control.

Page 171 of 1199


TcxTreeListColumnSummary Object
Hierarchy   Properties

Represents column summaries.

Unit
cxTL

Syntax

TcxTreeListColumnSummary = class(TcxOwnedPersistent)

Description
This class introduces members that allow you to:
l Access a column's footer and group summary collections (FooterSummaryItems and GroupFooterSummaryItems).
l Obtain the number of collection summaries that are currently visible within the TreeList control (FooterVisibleCount and
GroupFooterVisibleCount).
l Access the column that displays summaries (Column).

The TcxTreeListColumnPosition object is referenced by a column's Summary property.

Page 172 of 1199


TcxTreeListSummary Object
Hierarchy   Properties   Methods

Represents summaries created within the TreeList control.

Unit
cxTL

Syntax

TcxTreeListSummary = class(TObject)

Description
This class introduces members that allow you to:
l Access individual footer and group summaries (FooterSummaryItems and GroupFooterSummaryItems).
l Access the value and display text of a certain summary (FooterSummaryValues, GroupFooterSummaryValues,
FooterSummaryTexts, and GroupFooterSummaryTexts).
l Obtain the number of summaries created in the TreeList control (FooterSummaryCount and GroupFooterSummaryCount).
l Recalculate all summaries (Recalculate).

The TcxTreeListSummary object is referenced by the TreeList control's Summary property.

Page 173 of 1199


TcxTreeListSummaryItem Object
Hierarchy   Properties   Events

A set of appearance and calculation options for a column's footer and group summaries.

Unit
cxTL

Syntax

TcxTreeListSummaryItem = class(TcxCustomDataSummaryItem)

Description
Options include:
l Summary calculation options (Kind, AllNodes, and CalculatedColumn).
l Summary cell visibility (Visible).
l Cell text formatting options (Format, MultiLine, and OnGetText).
l Cell text arrangement options (AlignHorz and AlignVert, and VisibleIndexInColumn).

At design time, you can access these options using the Object Inspector by clicking the corresponding footer and group footer
cells.

The TcxTreeListSummaryItem object is referenced by a column's Summary.FooterSummaryItems and


Summary.GroupFooterSummaryItems collections.

Related Information

l TcxCustomTreeList.Summary
l TcxTreeListColumn Object

Page 174 of 1199


TcxTreeListSummaryItems Object
Hierarchy   Properties   Methods

Represents a collection of column summaries.

Unit
cxTL

Syntax

TcxTreeListSummaryItems = class(TcxCollection)

Description
This class extends its ancestor class with members that allow you to:
l Add summaries to the collection (Add).
l Access individual summaries within the collection (Items and GetItemByKind).
l Obtain the number of collection summaries that are currently visible within the TreeList control (VisibleCount).
l Access the column that displays summaries stored in the collection (Column).

The TcxTreeListSummaryItem object represents:


l A footer summary collection referenced by the TreeList control's Summary.FooterSummaryItems and a column's
Summary.FooterSummaryItems properties.
l A group summary collection referenced by the TreeList control's Summary.GroupFooterSummaryItems and a column's
Summary.GroupFooterSummaryItems properties.

Related Information

l TcxTreeListColumn Object

Page 175 of 1199


TcxTreeListBandCellViewInfo Object
Hierarchy

Provides the ViewInfo information specific to the band background.

Unit
cxTL

Syntax

TcxTreeListBandCellViewInfo = class(TcxTreeListCustomCellViewInfo)

Description
In addition to the properties derived from its ancestor class (TcxTreeListBandCellViewInfo), the TcxTreeListBandCellViewInfo
class introduces the following properties:

Property Type Write Access Description

Band TcxTreeListBand Read Only Provides access to the band whose background is
about to be painted.

Part TcxTreeListBandPart Read Only Identifies the band's area whose background is about
to be painted. Refer to the How to Custom Paint Band
Backgrounds help topic to learn more.

The TcxTreeListBandCellViewInfo object is referenced by the OnCustomDrawBandCell's AViewInfo parameter.

Related Information

l Custom Draw

Page 176 of 1199


TcxTreeListCustomCellViewInfo Object
Hierarchy

The base class for the TcxTreeListBandCellViewInfo, TcxTreeListCustomHeaderCellViewInfo, TcxTreeListFooterCellViewInfo and


TcxTreeListIndentCellViewInfo classes that provide the ViewInfo information about tree list elements.

Unit
cxTL

Syntax

TcxTreeListCustomCellViewInfo = class(TcxCustomViewInfoItem)

Description
The TcxTreeListCustomCellViewInfo class contains the following properties:

Property Type Write Access Description

AttachNode TcxTreeListNode Read Only In the OnCustomDrawBandCell event, returns the


node visible on screen that belongs to the painted
band.
In the OnCustomDrawFooterCell event, returns
the node under which a footer or a group footer
cell is drawn.
This property is only exposed by the
TcxTreeListBandCellViewInfo and
TcxTreeListFooterCellViewInfo classes.

BorderColor TColor Read/Write Specifies the painted element's border color.

Borders TcxBorders Read Only Returns the painted element's borders.

ExtPaintStyle Boolean Read Only Returns True if borders of neighboring band and
column headers and node indicator cells are
displayed unconnected (see the tree list
OptionsView.ExtPaintStyle option).

Node TcxTreeListNode Read Only In the OnCustomDrawIndentCell event, returns


the parent node of a node to which the indent cell
belongs.
In the OnCustomDrawFooterCell event, returns
the node against which a summary is calculated.

TreeList TcxCustomTreeList Read Only Returns the tree list whose View element is
painted.

VisibleRect TRect Read Only Returns the bounding rectangle of a painted


element, in tree list coordinates.

Related Information

l Custom Draw

Page 177 of 1199


TcxTreeListCustomHeaderCellViewInfo Object
Hierarchy

The base class for the TcxTreeListHeaderCellViewInfo and TcxTreeListIndicatorCellViewInfo classes.

Unit
cxTL

Syntax

TcxTreeListCustomHeaderCellViewInfo = class(TcxTreeListCustomCellViewInfo)

Description
The TcxTreeListCustomHeaderCellViewInfo class contains the following properties:

Property Type Write Access Description

HotTrack Boolean Read/Write Set this property to True, to highlight the element.
In the OnCustomDrawHeaderCell event, if the
option is active, the column header is
highlighted.
In the OnCustomDrawIndicatorCell event, if the
option is active, the quick column customization
button is highlighted.

IsLast Boolean Read Only In the OnCustomDrawHeaderCell event, returns


True if the painted column header is the last
header in the column header panel.

MultiLine Boolean Read Only Returns True, if a column header's text can be
displayed in several lines (see the
TcxTreeListCaption.MultiLine property).

Neighbors TcxNeighbors Read Only Returns the positions of the neighboring


TcxNeighbor = (nLeft, nTop, homogeneous elements, relative to the painted
nRight, nBottom); element (available positions: to the left, top, right,
TcxNeighbors = set of or bottom of the element).
TcxNeighbor;

Pressed Boolean Read/Write Set this property to True to paint the element
pressed.

State TcxButtonState Read/Write Specifies the element's state. Refer to the


TcxButtonState type description to learn about
available states.

TextBounds TRect Read Only Returns the column header's text bounding
rectangle, in tree list coordinates.

Related Information

l Custom Draw

Page 178 of 1199


TcxTreeListEditCellViewInfo Object
Hierarchy

Provides the ViewInfo information specific to the data and preview cells.

Unit
cxTL

Syntax

TcxTreeListEditCellViewInfo = class(TcxEditCellViewInfo)

Description
The TcxTreeListEditCellViewInfo class contains the following properties:

Property Type Write Access Description

Band TcxTreeListBand Read Only Returns the band to which the painted data
cell belongs.

BorderColor TColor Read/Write Specifies the painted data cell's border color.

Column TcxTreeListColumn Read Only Returns the column to which the painted data
cell belongs.

Editing Boolean Read Only Returns True if the painted data cell is being
edited (see the TcxTreeListColumn.Editing
property).

EditRect TRect Read Only Returns the data cell edit container's
rectangle, in tree list coordinates.

Focused Boolean Read Only Returns True if the painted data cell is
focused.

HotTrack Boolean Read Only Returns True if the node is hot-tracked (see
the node's HotTrack and the tree list's
OptionsBehavior.HotTrack properties).

Node TcxTreeListNode Read Only Returns the node to which the painted data
cell belongs.

NodeViewData TcxTreeListNodeViewData Read Only Returns the ViewInfo information specific to


the node that owns the painted data cell.

OptionsView TcxTreeListOptionsView Read Only Returns the tree list appearance settings.

Selected Boolean Read Only Returns True if the painted data cell is
selected.

TreeList TcxCustomTreeList Read Only Returns the tree list that owns the painted
data cell.

The TcxTreeListEditCellViewInfo object is referenced by the AViewInfo parameter of the OnCustomDrawDataCell and
OnCustomDrawPreviewCell events, and by the OnGetCellHint event's ACell parameter.

Related Information

Page 179 of 1199


l Custom Draw

Page 180 of 1199


TcxTreeListFooterCellViewInfo Object
Hierarchy

Provides the ViewInfo information specific to the footer and group footer cells.

Unit
cxTL

Syntax

TcxTreeListFooterCellViewInfo = class(TcxTreeListCustomCellViewInfo)

Description
The TcxTreeListFooterCellViewInfo class contains the following properties:

Property Type Write Access Description

AlignHorz TAlignment Read Only Returns the horizontal alignment of a summary cell's
text (see the TcxTreeListSummaryItem.AlignHorz
property).

AlignVert TcxAlignmentVert Read Only Returns the vertical alignment of a summary cell's
text (see the TcxTreeListSummaryItem.AlignVert
property).

Column TcxTreeListColumn Read Only Returns the column that owns the current summary.

Hidden Boolean Read Only Returns True, if a summary is not specified for a
Column.

MultiLine Boolean Read Only Returns True, if a summary cell's text is displayed in
several lines (see the column's Position.LineCount
and TcxTreeListSummaryItem.MultiLine properties).

ShowEndEllipsis Boolean Read Only Returns True, if an ellipsis within a summary cell is
allowed (see the column's Options.CellEndEllipsis
property).

Text String Read Only Returns the summary cell's text.

The TcxTreeListFooterCellViewInfo object is referenced by the OnCustomDrawFooterCell's AViewInfo parameter, and by the
OnGetCellHint event's ACell parameter.

Related Information

l Custom Draw

Page 181 of 1199


TcxTreeListHeaderCellViewInfo Object
Hierarchy

Provides the ViewInfo information specific to the band and column headers.

Unit
cxTL

Syntax

TcxTreeListHeaderCellViewInfo = class(TcxTreeListCustomHeaderCellViewInfo)

Description
The TcxTreeListHeaderCellViewInfo class contains the following properties:

Member Type Write Access Description

AlignHorz TAlignment Read Only Returns the horizontal alignment of a caption's text
(see the TcxTreeListCaption.AlignHorz property).

AlignVert TcxAlignmentVert Read Only Returns the vertical alignment of a caption's text
(see the TcxTreeListCaption.AlignVert property).

Fixed Boolean Read Only Returns True, if the painted band is fixed (see the
band's FixedKind property). This property is only in
effect for the OnCustomDrawBandHeaderCell event.

Glyph TBitmap Read Only Returns the caption's image (see the
TcxTreeListCaption.Glyph property).

GlyphAlignHorz TAlignment Read Only Returns the horizontal alignment of a caption's


image (see the TcxTreeListCaption.GlyphAlignHorz
property).

GlyphAlignVert TcxAlignmentVert Read Only Returns the vertical alignment of a caption's image
(see the TcxTreeListCaption.GlyphAlignVert
property).

GlyphPosition TPoint Read Only Returns the upper-left corner of a caption's image,
in tree list coordinates.

ShowEndEllipsis Boolean Read Only Returns True if an ellipsis within a caption is


allowed (see the
TcxTreeListCaption.ShowEndEllipsis property).

SortMarkBounds TRect Read Only Returns the sorting mark's bounding rectangle, in
tree list coordinates.

SortOrder TcxDataSortOrder Read Only Returns the sort order of column values (see the
column's SortOrder property).

Text String Read Only Returns the caption's text.

The TcxTreeListHeaderCellViewInfo object is referenced by the AViewInfo parameter of the OnCustomDrawBandHeaderCell


and OnCustomDrawHeaderCell events, and by the OnGetCellHint event's ACell parameter.

Related Information

Page 182 of 1199


l Custom Draw
l TcxTreeListColumn.Caption

Page 183 of 1199


TcxTreeListIndentCellViewInfo Object
Hierarchy

Provides the ViewInfo information specific to the indent cell.

Unit
cxTL

Syntax

TcxTreeListIndentCellViewInfo = class(TcxTreeListCustomCellViewInfo)

Description
The TcxTreeListIndentCellViewInfo class contains the following properties:

Member Type Write Access Description

Button Boolean Read Only Returns True, if the expand button is


displayed.

CheckState TcxCheckBoxState Read Only Returns the node check box's state (see
the node's CheckState property and the
TcxCheckBoxState enumeration).

Fixed Boolean Read Only Returns True, if a band to which the


indent cell belongs is fixed (see the
band's FixedKind property).

GlyphRect TRect Read/Write Specifies the bounding rectangle of a


node image (see the node's ImageIndex
property), in tree list coordinates.

HasImage Boolean Read Only Returns True if a node image (overlay


image) is specified (see the tree list's
Images and the node's ImageIndex and
OverlayIndex properties).

HorzTreeLine TRect Read Only Returns the horizontal tree line's


bounding rectangle, in tree list
coordinates.

HotTrack Boolean Read Only Returns True, if a node that owns the
painted indent cell is hot-tracked (see
the node's HotTrack and the tree list's
OptionsBehavior.HotTrack properties).

ImageIndex Integer Read Only Returns the node image's index (see the
node's ImageIndex property).

Images TCustomImageList Read Only Returns the collection of node images


(see the tree list's Images property).

Index Integer Read Only Returns the owning node's level (see the
node's Level property)

IsExpanded Boolean Read Only Returns True, if a node is expanded


(see the node's Expanded property).

Kind TcxTreeListNodeIndentKind Read Only Returns the type of an indent cell's area
TcxTreeListNodeIndentKind = used for displaying a certain element

Page 184 of 1199


(nikLevel, nikImage, nikState, (level, node image, state image, check
nikCheck, nikFooter); box, summary cell).

LevelNode TcxTreeListNode Read Only Returns the node that owns the painted
indent cell.

Lines TcxTreeListIndentLines Read Only Returns the direction of the painted tree
TcxTreeListIndentLine = lines, relative to the node whose indent
(ilVertUp, ilVertDown, ilHorz); is painted (available directions: up, down
and horizontal).

OverlayIndex Integer Read Only Returns the overlay image's index (see
the node's OverlayIndex property).

VertTreeLine TRect Read Only Returns the vertical tree line's bounding
rectangle, in tree list coordinates.

The TcxTreeListIndentCellViewInfo object is referenced by the OnCustomDrawIndentCell's AViewInfo parameter.

Related Information

l Custom Draw

Page 185 of 1199


TcxTreeListIndicatorCellViewInfo Object
Hierarchy

Provides the ViewInfo information specific to the node indicator.

Unit
cxTL

Syntax

TcxTreeListIndicatorCellViewInfo = class(TcxTreeListCustomHeaderCellViewInfo)

Description
The TcxTreeListIndicatorCellViewInfo class contains the following properties:

Member Type Write Access Description

Kind TcxIndicatorKind Read/Write Specifies the indicator mark used to identify the
corresponding node's state (focused, selected,
inserted or edited).

Position TcxTreeListIndicatorPosition Read Only Returns the position occupied by an indicator


TcxTreeListIndicatorPosition = cell (available positions: node indicator, quick
(tlipBands, tlipColumns, band customization button, quick column
tlipContent, tlipFooter); customization button, footer's indicator cell).

The TcxTreeListIndicatorCellViewInfo object is referenced by the OnCustomDrawIndicatorCell's AViewInfo parameter.

Related Information

l Custom Draw

Page 186 of 1199


TcxTreeListBand.Expandable
TcxTreeListBand

Specifies whether the current band is able to display expand buttons (also called an expandable band).

Syntax

type
TcxTreeListBandExpandable = (tlbeDefault, tlbeExpandable, tlbeNotExpandable);
property Expandable: TcxTreeListBandExpandable;

Description
Options include:

Value Meaning

tlbeDefault Expand buttons are displayed within the first


visible bottom band if none of the other bands are
set as tlbeExpandable.
 

tlbeExpandable The band displays expand buttons. If multiple


bands are set as tlbeExpandable, the first visible
bottom band will display expand buttons.
If the categorized paint style is applied to the
TreeList control, the expandable band is always
considered to be the first visible bottom band.
 

tlbeNotExpandable The band cannot display expand buttons. If all


visible bands are set as tlbeNotExpandable,
expand buttons are not painted within the
TreeList control.

Use the ActuallyExpandable property to determine whether the current band or one of its child bands displays expand buttons.
To access the band that displays expand buttons, use the TreeList control's Bands.ExpandableBand property.

The default value of the Expandable property is tlbeDefault.

Page 187 of 1199


TcxTreeListBandPart type
Enumerates band areas.

Unit
cxTL

Syntax

type
TcxTreeListBandPart = (tlbpHeader, tlbpContent, tlbpGroupFooter, tlbpFooter, tlbpSeparator

Description
Values include:

Value Meaning

tlbpHeader Band header

tlbpContent Band content

tlbpGroupFooter Group footer

tlbpFooter Footer

tlbpSeparator Band separator

Related Information

l TcxCustomTreeList.OnCustomDrawBandCell
l TcxTreeListBandCellViewInfo Object

Page 188 of 1199


TcxTreeListBuiltInMenuItemType type
Enumerates available types of built-in context menu items.

Unit
cxTL

Syntax

type
TcxTreeListBuiltInMenuItemType = (tlmitDefault, tlmitChecked, tlmitSubItem);

Description
Values include:

Value Meaning

tlmitDefault A menu item represents a button.

tlmitChecked A menu item represents a checkable option.

tlmitSubItem A menu item represents a submenu – it contains other child items.

Related Information

l TcxTreeListPopupMenu.CreateMenuItem

Page 189 of 1199


TcxTreeListCaption Object
Hierarchy   Properties

Represents a class that allows you to define settings of a band or a column caption.

Unit
cxTL

Syntax

TcxTreeListCaption = class(TcxOwnedPersistent)

Description
The class is exposed via the Band.Caption or the Column.Caption property of a band or a column respectively. The class
methods provided allow you to specify the textual content of the caption, its horizontal and vertical alignment, the glyph displayed
within the caption and its horizontal & vertical alignment, to specify whether the caption content can be displayed in more than a
single line and other parameters.

Page 190 of 1199


TcxTreeListCustomizing Object
Hierarchy   Properties   Methods

The Customize window.

Unit
cxTL

Syntax

TcxTreeListCustomizing = class(TPersistent);

Description
The TcxTreeListCustomizing object provides the following API to control the Customize window behavior:
l The RowCount property – specifies the number of column or band headers visible in the window.
l The Visible property – specifies the window's visibility.
l The MakeBandPageVisible and MakeColumnPageVisible methods are used to switch between the window's Bands and
Columns tabs.

This object is referenced by the tree list's Customizing property.

Related Information

l Customization Form
l ExpressBars: Customization Form
l ExpressNavBar: Customization Form
l ExpressPivotGrid: Customization Form

Page 191 of 1199


TcxTreeListImageIndexType type
Enumerates types of images displayed in the node.

Unit
cxTL

Syntax

type
TcxTreeListImageIndexType = (tlitImageIndex, tlitSelectedIndex, tlitStateIndex, tlitOverla

Description
Values include:

Value Meaning

tlitImageIndex A node select image that indicates an unselected node.

tlitSelectedIndex A node select image that indicates a selected node.

tlitStateIndex An image that indicates a node's specific state.

tlitOverlayIndex An additional image overlaid on the node select image.

tlitOverlayStateIndex An additional image overlaid on the node specific state image.

Related Information

l TcxCustomTreeList.OnGetNodeImageIndex

Page 192 of 1199


TcxTreeListLikeParams Object
Hierarchy   Properties   Methods

Represents search pattern wildcards used by the tree list's FindNodeByText method in the tlfmLike mode.

Unit
cxTL

Syntax

TcxTreeListLikeParams = class(TObject)

Description
The TcxTreeListLikeParams class provides the Percent and UnderLine properties that are used to specify wildcards in the
search string.

The TcxTreeListLikeParams object is referenced by the FindNodeByText method's ALik eParams parameter.

Page 193 of 1199


TcxTreeListNodeAttachMode type
Specifies the manner in which one node is attached to another.

Unit
cxTL

Syntax

type
TcxTreeListNodeAttachMode = (tlamAdd, tlamAddFirst, tlamAddChild, tlamAddChildFirst, tlamI

Description
Values include:

Mode Description

tlamAdd Adds a node at the same level as the existing node and makes the new node last.

tlamAddFirst Adds a node at the same level as the existing node and makes the new node first.

tlamAddChild Adds a child node to the existing node and makes the new node last.

tlamAddChildFirst Adds a child node to the existing node and makes the new node first.

tlamInsert Inserts a node at the same level just before the existing node.

Related Information

l TcxCustomTreeList.AddNode
l TcxCustomTreeList.OnMoveTo
l TcxTreeListNode.CanMove
l TcxTreeListNode.MoveTo

Page 194 of 1199


TcxTreeListNode.CheckGroupType
TcxTreeListNode

Specifies the type of control to be displayed in the node's children to indicate their checked state.

Syntax

type
TcxTreeListNodeCheckGroupType = (ncgNone, ncgCheckGroup, ncgRadioGroup);
property CheckGroupType: TcxTreeListNodeCheckGroupType;

Description
The tree list provides two types of controls that can be used in nodes:
l Check boxes – used for multiple node selection.
l Radio buttons – used for selection of a single node from a group of nodes.

If specified, the control is automatically assigned to all children that the current node owns.
The property is in effect if the tree list's OptionsView.CheckGroups option is active.

At design time, use the Items Editor to specify controls for nodes.

Values include:

Value Meaning

ncgNone None of controls are shown in nodes.

ncgCheckGroup A check box is shown in nodes.

ncgRadioGroup A radio button is shown in nodes.

Related Information

l TcxCustomTreeList.OnNodeCheckChanged
l TcxTreeListNode.AllowGrayed
l TcxTreeListNode.Checked
l TcxTreeListNode.Enabled
l TcxTreeListNode.HasCheckbox

Page 195 of 1199


cxTreeListDefMinWidth global constant
Specifies the default minimum width (in pixels) of bands and columns in all TreeList controls.

Unit
cxTL

Syntax

const
cxTreeListDefMinWidth = 20;

Description
This global constant specifies the default value of:
l The TcxTreeListColumn class' MinWidth property. You can reset the property to its default value by calling the column's
RestoreWidths procedure;
l The TcxTreeListBand class' MinWidth property. You can reset the property to its default value by calling the band's
RestoreWidths procedure.

Related Information

l cxTreeListDefWidth global constant

Page 196 of 1199


cxTreeListDefWidth global constant
Specifies the default width (in pixels) of bands and columns in all TreeList controls.

Unit
cxTL

Syntax

const
cxTreeListDefWidth = 100;

Description
This global constant specifies the TcxTreeListColumn class' default Width property value. You can reset the column's Width and
MinWidth properties to their default values by calling the RestoreWidths procedure.

Related Information

l cxTreeListDefMinWidth global constant

Page 197 of 1199


cxExportTLToCSV Procedure
Exports the tree list's content to a CSV (comma-separated values) file.

Unit
cxTLExportLink

Syntax

procedure cxExportTLToCSV(const AFileName: string; ATreeList: TcxCustomTreeList; AExpand: Bo

Description
The cxExportTLToCSV method exports records from the ATreeList control to a CSV file.
The AFileName parameter defines the name and the path of the resulting CSV file. Any extension specified in this parameter is replace
The AExpand parameter indicates whether to export all TreeList nodes that have child nodes displayed in the grid, including those tha
The ASaveAll parameter indicates whether to export just the selected or all nodes.
Use the ASeparator parameter to specify the character used to delimit text values in the resulting CSV file. By default, the character is
The AHandler parameter references an optional object that implements the following interfaces, enabling you to handle events:
l IcxExportBeforeSave, before the export operation;
and/or
l IcxExportProgress, during the operation.
Refer to the interface descriptions to learn more.
The AEncoding parameter specifies the character encoding format used for the resulting CSV file. If no encoding is specified or nil is p

Concepts

l Export Data

Page 198 of 1199


cxExportTLToExcel Procedure
Exports the tree list's content to a file in Microsoft Excel 97-2003 format.

Unit
cxTLExportLink

Syntax

procedure cxExportTLToExcel(const AFileName: string; ATreeList: TcxCustomTreeList; AExpand:

Description
This method exports records from the ATreeList control to a file in Microsoft Excel 97-2003 format (an XLS file). To export ATreeList re

The AFileName parameter defines the name and the path of the resulting XLS file. Any extension specified in this parameter is replace
The AExpand parameter indicates whether to export all TreeList nodes that have child nodes displayed in the grid, including those tha
The ASaveAll parameter indicates whether to export just the selected or all nodes.
If the AUseNativeFormat parameter is True, the export routine tries to convert the display text of grid cells to the corresponding Excel

An editor assigned to a grid cell The corresponding Excel format

TcxCurrencyEdit Currency

TcxDateEdit Date

TcxTimeEdit Time

TcxCalcEdit or TcxSpinEdit Float

If a cell's text cannot be converted to the required format (if the cell contains invalid characters), it is exported as a string.

If an editor, whose type is not listed in the above table, is assigned to an item, the export routine still tries to convert item cells in turn
If AUseNativeFormat is set to False, the displayed text of all cells is exported as is without conversion.

The AHandler parameter references an optional object that implements the following interfaces, enabling you to handle events:
l IcxExportBeforeSave, before the export operation;
and/or
l IcxExportProgress, during the operation.
Refer to the interface descriptions to learn more.

Add the dxSpreadSheetFormattedTextUtils unit to your project to enable support for rich text formatted content displayed by cxRichEd

The following screenshot demonstrates the contents of resulting XLS file:

Page 199 of 1199


cxExportTLToHTML Procedure
Exports the tree list's content to a file in HTML format.

Unit
cxTLExportLink

Syntax

procedure cxExportTLToHTML(const AFileName: string; ATreeList: TcxCustomTreeList; AExpand: B

Description
This method exports records from the ATreeList control in HTML format.
The AFileName parameter defines the name and the path of the resulting HTML file. Any extension specified in this parameter is replac
The AExpand parameter indicates whether to export all TreeList nodes that have child nodes displayed in the grid, including those tha
The ASaveAll parameter indicates whether to export just the selected or all nodes.
The AHandler parameter references an optional object that implements the following interfaces, enabling you to handle events:
l IcxExportBeforeSave, before the export operation;
and/or
l IcxExportProgress, during the operation.
Refer to the interface descriptions to learn more.

Add the dxSpreadSheetFormattedTextUtils unit to your project to enable support for rich text formatted content displayed by cxRichEd

Note:   The cxExportTLToHTML method creates image files to display node images as inline images in the resulting HTML file. Use

The following screenshot demonstrates the resulting HTML file:

Page 200 of 1199


cxExportTLToText Procedure
Exports the tree list's content to a text file.

Unit
cxTLExportLink

Overloaded Variants

Syntax

procedure cxExportTLToText(const AFileName: string; ATreeList: TcxCustomTreeList; AExpand: B


procedure cxExportTLToText(const AFileName: string; ATreeList: TcxCustomTreeList; AExpand: B

Description
The cxExportTLToText method exports records from the ATreeList control to a text file.
The AFileName parameter defines the name and the path of the resulting text file. Any extension specified in this parameter is replace
The AExpand parameter indicates whether to export all TreeList nodes that have child nodes displayed in the grid, including those tha
The ASaveAll parameter indicates whether to export just the selected or all nodes.
You can use the ASeparator parameter to specify the string to delimit cells exported to text format. In addition, you can define prefix a
The AHandler parameter references an optional object that implements the following interfaces, enabling you to handle events:
l IcxExportBeforeSave, before the export operation;
and/or
l IcxExportProgress, during the operation.
Refer to the interface descriptions to learn more.
The AEncoding parameter specifies the character encoding format used for the resulting TXT file. If no encoding is specified or nil is pa

The following screenshot demonstrates the contents of the resulting TXT file:

Concepts

l Export Data

Page 201 of 1199


cxExportTLToXLSX Procedure
Exports the tree list's content to a file in Microsoft Excel 2007 or later format.

Unit
cxTLExportLink

Syntax

procedure cxExportTLToXLSX(const AFileName: string; ATreeList: TcxCustomTreeList; AExpand: B

Description
The cxExportTLToXLSX method parameters are similar to cxExportTLToExcel method parameters, except for the default extension o

Add the dxSpreadSheetFormattedTextUtils unit to your project to enable support for rich text formatted content displayed by cxRichEd

Concepts

l Export Data

Page 202 of 1199


cxExportTLToXML Procedure
Exports the tree list's content to a file in XML format.

Unit
cxTLExportLink

Syntax

procedure cxExportTLToXML(const AFileName: string; ATreeList: TcxCustomTreeList; AExpand: Bo

Description
The cxExportTLToXML method exports records from the ATreeList control to XML format.
The AFileName parameter defines the name and the path of the resulting XML file. Any extension specified in this parameter is replace
The AExpand parameter indicates whether to export all TreeList nodes that have child nodes displayed in the grid, including those tha
The ASaveAll parameter indicates whether to export just the selected or all nodes.
The AHandler parameter references an optional object that implements the following interfaces, enabling you to handle events:
l IcxExportBeforeSave, before the export operation;
and/or
l IcxExportProgress, during the operation.
Refer to the interface descriptions to learn more.

Note:   Together with exporting the control's content into an XML file, the cxExportTLToXML method creates an XSL file that defines
exported HTML file when viewed in a browser.
In addition, the cxExportTLToXML method creates image files to display node images as inline images in the resulting XML file. Use

Concepts

l Export Data

Page 203 of 1199


Refresh Data
Feature Center   Data Exchange   Bind to a Data Source

By design, a tree list control automatically updates itself, if the data is modified in the linked data source. However, in some
cases you need to explicitly update the tree list. This may take place when the data source was intentionally locked for
notifications to the control, or when the DBMS engine doesn't provide proper notifications.
For this purpose, invoke the tree list's FullRefresh method, which will reload the data.
This method is also used if tree list elements are customized via events using external controls. For an example that illustrates
the use of the method when external controls are involved in the customization of elements, refer to the
ExpressQuantumTreeList Features Demo.

Page 204 of 1199


Bound Mode
Data Loading Modes

In bound mode, the data is persisted in a database. For this purpose, the TcxDBTreeList control is bound to a TDataSet.
A dataset must have a particular structure, so that the TreeList control can build a node hierarchy. Each dataset record must
contain a unique key value field that will identify the node in the control, and a parent key value field that will identify its parent
node.
To learn more about a dataset structure that must conform to the tree list content, refer to the Self-Referenced Dataset help
topic.
To learn how to link a tree list to the data source, refer to the Connecting to Data help topic.

Concepts

l Concepts

Page 205 of 1199


Column Header Context Menu
The column header context menu allows end-users to change the column's visibility, apply or clear sorting against its values,
invoke the customization form, change the visibility of the footer and group footers, etc. The column header context menu can
be invoked by right-clicking the column header.

The table below lists the main properties that affect the menu's appearance and behavior:

Availability The TreeList control's PopupMenus.ColumnHeaderMenu.UseBuiltInMenu option.


 

Contents To invoke a custom context menu at runtime, specify the menu via the TreeList control's
PopupMenus.ColumnHeaderMenu.PopupMenu property and set the
PopupMenus.ColumnHeaderMenu.UseBuiltInMenu property to False. Otherwise, the built-in
context menu will be displayed.
Use the TreeList control's PopupMenus.ColumnHeaderMenu.Items property to toggle the
visibility of specific menu items in the built-in context menu.
Handle the TreeList control's PopupMenus.ColumnHeaderMenu.OnPopup event to
customize the contents of the invoked context menu.
 

Behavior Handle the TreeList control's PopupMenus.ColumnHeaderMenu.OnClick event to respond to


clicks on items within the built-in context menu.
 

Localization The scxTreeListSortAscendingMenuItem, scxTreeListSortDescendingMenuItem,


scxTreeListClearSortingMenuItem, scxTreeListFooterMenuItem,
scxTreeListGroupFootersMenuItem, scxTreeListGroupFootersInvisibleMenuItem,
scxTreeListGroupFootersVisibleWhenExpandedMenuItem,
scxTreeListGroupFootersAlwaysVisibleMenuItem,
scxTreeListRemoveThisColumnMenuItem, scxTreeListFieldChooserMenuItem,
scxTreeListHorizontalAlignmentMenuItem, scxTreeListHorizontalAlignmentLeftMenuItem,
scxTreeListHorizontalAlignmentCenterMenuItem,
scxTreeListHorizontalAlignmentRightMenuItem, scxTreeListVerticalAlignmentMenuItem,
scxTreeListVerticalAlignmentBottomMenuItem,
scxTreeListVerticalAlignmentCenterMenuItem,
scxTreeListVerticalAlignmentTopMenuItem, scxTreeListBestFitMenuItem, and
scxTreeListBestFitAllColumnsMenuItem resource strings.

Related Information
Page 206 of 1199
l Footer Context Menu
l Group Footer Context Menu

Page 207 of 1199


Concepts
Section Navigator

The topics listed below provide you with the basic information on the ExpressQuantumTreeList features:
l Data Loading Modes
l Options
l Self-Referenced Dataset
l Visual Elements

Page 208 of 1199


Footer Context Menu
The footer context menu allows end-users to specify the required summary types, adjust the calculation base or disable
summary calculation for footer cells. This menu can be invoked by right-clicking the footer or any footer cell.

The table below lists the main properties which affect the menu's appearance and behavior:

Availability The TreeList control's PopupMenus.FooterMenu.UseBuiltInMenu option.


 

Contents To invoke a custom context menu at runtime, specify the menu via the TreeList control's
PopupMenus.FooterMenu.PopupMenu property and set the
PopupMenus.FooterMenu.UseBuiltInMenu property to False. Otherwise, the built-in context
menu will be displayed.
Use the TreeList control's PopupMenus.FooterMenu.Items property to toggle the visibility of
specific menu items in the built-in context menu.
Handle the TreeList control's PopupMenus.FooterMenu.OnPopup event to customize the
contents of the invoked context menu.
 

Behavior Handle the TreeList control's PopupMenus.FooterMenu.OnClick event to respond to clicks on


items within the built-in context menu.
 

Localization The scxTreeListNoneMenuItem, scxTreeListSumMenuItem, scxTreeListMinMenuItem,


scxTreeListMaxMenuItem, scxTreeListCountMenuItem, scxTreeListAvgMenuItem, and
scxTreeListAllNodesMenuItem resource strings.

Related Information

l Column Header Context Menu


l Group Footer Context Menu

Page 209 of 1199


Group Footer Context Menu
The group footer context menu allows end-users to specify the required summary types, adjust the calculation base or disable
summary calculation for group footer cells. This menu can be invoked by right-clicking a group footer or any group footer cell.

The table below lists the main properties which affect the menu's appearance and behavior:

Availability The TreeList control's PopupMenus.GroupFooterMenu.UseBuiltInMenu option.


 

Contents To invoke a custom context menu at runtime, specify the menu via the TreeList control's
PopupMenus.GroupFooterMenu.PopupMenu property, and set the
PopupMenus.GroupFooterMenu.UseBuiltInMenu property to False. Otherwise, the built-in
context menu will be displayed.
Use the TreeList control's PopupMenus.GroupFooterMenu.Items property to toggle the
visibility of specific menu items in the built-in context menu.
Handle the TreeList control's PopupMenus.GroupFooterMenu.OnPopup event to customize
the contents of the invoked context menu.
 

Behavior Handle the TreeList control's PopupMenus.GroupFooterMenu.OnClick event to respond to


clicks on items within the built-in context menu.
 

Localization The scxTreeListNoneMenuItem, scxTreeListSumMenuItem, scxTreeListMinMenuItem,


scxTreeListMaxMenuItem, scxTreeListCountMenuItem, scxTreeListAvgMenuItem, and
scxTreeListAllNodesMenuItem resource strings.

Related Information

l Column Header Context Menu


l Footer Context Menu

Page 210 of 1199


How to Custom Paint Band Headers
Task-Based Help

The following example demonstrates how to handle the tree list's OnCustomDrawBandHeaderCell event, used to manually paint band h
In the example, the leftmost visible band header is custom painted.

[Delphi]
//...
procedure <Form>.<TreeList>CustomDrawBandHeaderCell(Sender: TcxCustomTreeList; ACanvas: TcxCanva
begin
// draw the first visible band header
if not TcxTreeListBandHeaderCellViewInfo(AViewInfo).Band.IsLeftMost then
begin
// allow default painting
ADone := False;
Exit;
end;
// apply the current font and color settings
cxApplyViewParams(ACanvas, AViewInfo.ViewParams);
// paint the band header's background
ACanvas.FillRect(AViewInfo.BoundsRect);
// draw the band's caption text
ACanvas.DrawTexT('CustomDrawBandHeader', AViewInfo.TextBounds, 0, True);
// draw the band's borders
ACanvas.FrameRect(AViewInfo.BoundsRect, clBlack);
// suppress the default painting
ADone := True;
end;

Related Information

l Custom Draw

Page 211 of 1199


How to Custom Paint the Tree List Background
Task-Based Help

The following example demonstrates how to handle the tree list's OnCustomDrawBackgroundCell event, used to manually paint the tre

[Delphi]
//...
var
ABitmap: TBitmap;
//...
procedure <Form>.FormCreate(Sender: TObject);
begin
ABitmap := TBitmap.Create;
ABitmap.LoadFromFile('E:\EARTH16.BMP');
end;
//...
procedure <Form>.<TreeList>CustomDrawBackgroundCell(Sender: TcxCustomTreeList; ACanvas: TcxCanva
begin
// paint the background rectangle with the specified bitmap
ACanvas.FillRect(AViewInfo.BoundsRect, ABitmap);
// suppress the default painting
ADone := True;
end;

Related Information

l Custom Draw
l ExpressCrossPlatformLibrary: TcxIndicatorKind type

Page 212 of 1199


How to Display Print Preview and Print the Tree List
Task-Based Help

The following code snippet demonstrates how to create a report link for the TreeList control and display the print preview window,
by using a TdxComponentPrinter component. This component is shipped with the ExpressPrinting System, which is a separate
product.

[Delphi]
uses
//...
..., dxPScxTL5Lnk;
//...
var
ATreeListReportLink: TBasedxReportLink;
begin
// Creates a report link for the TreeList control and adds it to a component printer
ATreeListReportLink := dxComponentPrinter1.AddLink(TreeListControl);
// Invokes the print preview window
dxComponentPrinter1.Preview(True, ATreeListReportLink);
end;

[C++ Builder]
//...
#pragma link "dxPScxTL5Lnk"
//...
// Creates a report link for the TreeList control and adds it to a component printer
TBasedxReportLink *ATreeListReportLink = dxComponentPrinter1->AddLink(TreeLinkControl);
// Invokes the print preview window
dxComponentPrinter1->Preview(True, ATreeListReportLink);

The result is shown in the image below.

Page 213 of 1199


Related Information

l Print Data
l ExpressPivotGrid: Print Data

Page 214 of 1199


How to Implement Sorting
The ExpressQuantumTreeList provides easy data sorting at runtime. The TreeList control represents data in columns, each of
which has a caption displayed within the column header panel. A user can click the column header to sort data by the column's
values. To sort data by multiple columns, column headers should be clicked while holding down the Shift key. When data is
sorted by a column, a small arrow is displayed in its caption indicating the current sort order. You can remove sorting against a
particular column by clicking its header again while pressing the Ctrl key.
Note:   Sorting is performed for the nodes located at the same level and having the same parent node.

You may not want a user to be able to sort data by a particular column's values – see the TreeList's OptionsBehavior.Sorting or
the column's Options.Sorting property.
When data is sorted by multiple columns, the sort order plays an important role. Sorting orders the data according to the first
column specified for sorting. Other column values only come into play if the previous column's data is identical. Use the
SortedColumnCount and SortedColumns properties to find out the order of sorted columns.
The following image shows the treelist control with data sorted by the Budget and Location columns. Data is sorted in
ascending order by the Budget column and in descending order by Location.

Here is the code snippet needed to achieve the same result:

[Delphi]
// lock updates
cxTreeList1.BeginUpdate;
try
// clear sorting
cxTreeList1.ClearSorting;
// sort the budget column in ascending order
tlcolBudget.SortOrder := soAscending;
// sort the location column in descending order
tlcolLocation.SortOrder := soDescending;
finally
// unlock updates and apply the changes
cxTreeList1.EndUpdate;
end;

code /code

Concepts

Page 215 of 1199


l Sorting Data
l Sorting Nodes
l TcxTreeListOptionsData.AnsiSort
l TcxTreeListOptionsData.CaseInsensitive
l TcxTreeListOptionsData.MultiThreadedSorting
l ExpressPivotGrid: Sorting Data

Page 216 of 1199


Choose a Section:
Concepts
Feature Center
Visual Elements
Design-Time Features
End-User Capabilities
Task-Based Help

Page 217 of 1199


Example: Band.ApplyBestFit, TreeList.FullExpand
The following simple code shows how to apply best fit to a band

[Delphi]
procedure <Form>.FormShow(Sender: TObject);
begin
cxTreeList1.Bands[0].Caption.Text := 'Primary information about product';
cxTreeList1.Bands[0].ApplyBestFit;
end;

[C++ Builder]
void __fastcall <Form>::FormShow(TObject *Sender) {
cxTreeList1->Bands->Items[0]->Caption->Text ="Primary information about product";
cxTreeList1->Bands->Items[0]->ApplyBestFit();
}

Page 218 of 1199


Example: Bands.Add, Bands.Count, Bands
The following sample shows how to add a new band to the tree list control. The miAddBandClick method invokes a dialog box that
allows the end-user to provide the new band's caption. The miAddBandClick event calls the GetBandByCaption method, which
checks if a band with the caption specified already exists.

[Delphi]
procedure <Form>.miAddBandClick(Sender: TObject);
var
ABandCaption: String;
begin
if InputQuery('Create band', 'Specify a caption of the band', ABandCaption) then
if GetBandByCaption(ABandCaption) <> nil then
MessageDlg('Band with this caption already exists', mtWarning, [mbOK], 0)
else
with cxDBTreeList.Bands.Add do
begin
Caption.Text := ABandCaption;
Caption.AlignHorz := taCenter;
end;
end;
function <Form>.GetBandByCaption(ABandCaption: String): TcxTreeListBand;
var
I: Integer;
begin
Result := nil;
for I := 0 to cxDBTreeList.Bands.Count - 1 do
if cxDBTreeList.Bands[I].Caption.Text = ABandCaption then
begin
Result := cxDBTreeList.Bands[I];
Break;
end;
end;

[C++ Builder]
void __fastcall <Form>::miAddBandClick(TObject *Sender){
String ABandCaption;
if (InputQuery("Create band", "Specify a caption of the band", ABandCaption))
if (GetBandByCaption(ABandCaption) != NULL)
MessageDlg("Band with this caption already exists", mtWarning, TMsgDlgButtons()<<mbOK, 0);
else {
TcxTreeListBand *ABand = cxDBTreeList->Bands->Add();
ABand->Caption->Text = ABandCaption;
ABand->Caption->AlignHorz = taCenter;
}
}
TcxTreeListBand* <Form>::GetBandByCaption(String ABandCaption) {
TcxTreeListBand *Result = NULL;
for (int I = 0; I < cxDBTreeList->Bands->Count; I++)
if (cxDBTreeList->Bands->Items[I]->Caption->Text == ABandCaption){
Page 219 of 1199
Result = cxDBTreeList->Bands->Items[I];
}
return Result;
}

Page 220 of 1199


Example: Column.Focused, Node.Focused,
Node.GetPrevVisible, Node.GetPrev, Node.GetNextVisib
Node.GetNext
The following sample searches a tree list column's values for a search string. The SearchByColumn method accepts the following par
AColumn specifies the column to be searched.
AText provides the search string.
AForward specifies the direction of the search. If set to True, the search is forward; otherwise, the search goes backward.
AVisibleOnly specifies whether the search engine should only use the visible cells of the column. If set to True, the search engine only
visible cells within the column; otherwise, all the values of the column are searched for the search string (AText parameter). In the latte
engine finds a match, the node to which the match belongs is made visible (by expanding all its parent nodes).

[Delphi]
procedure SearchByColumn(AColumn: TcxTreeListColumn; AText: String; AForward, AVisibleOnly: Bool
var
ANode: TcxTreeListNode;
begin
ANode := cxTreeList.FocusedNode;
repeat
if Pos(UpperCase(AText), UpperCase(ANode.Texts[AColumn.ItemIndex])) <> 0 then
begin
// ensure that the column and the node that contains the match are visible
AColumn.Focused := True;
AColumn.MakeVisible;
ANode.Focused := True;
ANode.MakeVisible;
Break;
end;
// only taking visible nodes into consideration
if AVisibleOnly then
begin
if AForward then
ANode := ANode.GetNextVisible
else
ANode := ANode.GetPrevVisible;
end
else
begin
if AForward then
ANode := ANode.GetNext
else
ANode := ANode.GetPrev;
end;
until ANode = nil
end;

[C++ Builder]
void __fastcall SearchByColumn(TcxTreeListColumn *AColumn, String AText, bool AForward, bool AVi
Page 221 of 1199
TcxTreeListNode *ANode = cxTreeList->FocusedNode;
break;
}
if (AVisibleOnly) {
// only taking visible nodes into consideration
if (AForward) ANode = ANode->GetNextVisible(); else ANode = ANode->GetPrevVisible();
} else {
if (AForward) ANode = ANode->GetNext();
else ANode = ANode->GetPrev();
}
} while(ANode != NULL);
}

Page 222 of 1199


Example: Column.OnGetDisplayText
The following sample uses the OnGetDisplayText event. The event handler changes the category value of group nodes.

[Delphi]
procedure <Form>.<Column>GetDisplayText(Sender: TcxTreeListColumn;
ANode: TcxTreeListNode; var Value: String);
begin
if ANode.IsGroupNode then
// adding the number of the first level child nodes
Value := Value + ' (' + IntToStr(ANode.Count) + ')';
end;

[C++ Builder]
void __fastcall <Form>::<Column>GetDisplayText(TcxTreeListColumn *Sender, TcxTreeListNode *ANode
if (ANode->IsGroupNode) {
// adding the number of the first level child nodes
Value = Value + " (" + IntToStr(ANode->Count) + ")";
}
}

Page 223 of 1199


Example: Node.Selected, TreeList.GetSelections,
OptionSelection.MultiSelect
The following sample selects all the nodes within the control that have identical values within a column. The index of the column
is passed via the AItemIndex parameter. You can pass the index of the focused column as a parameter (see FocusedColumn).
Additionally, you can use the OnFocusedColumnChanged event to select the “same” nodes when the end-user selects
columns within the control.

Note that the MultiSelect option should be enabled.

[Delphi]
procedure SelectIdenticalNodes(AItemIndex: Integer);
var
I, J: Integer;
AValue: String;
ASelectedNodes: TList;
AValueList: TStringList;
begin
if not cxTreeList.OptionsSelection.MultiSelect then Exit;
ASelectedNodes := TList.Create;
AValueList := TStringList.Create;
try
cxTreeList.GetSelections(ASelectedNodes);
for I := 0 to ASelectedNodes.Count - 1 do
begin
AValue := TcxTreeListNode(ASelectedNodes[I]).Texts[AItemIndex];
if AValueList.IndexOf(AValue) = -1 then
AValueList.Add(AValue);
end;
cxTreeList.BeginUpdate;
try
for I := 0 to cxTreeList.Nodes.Count - 1 do
begin
AValueList.Sort;
AValue := cxTreeList.Nodes[I].Texts[AItemIndex];
if AValueList.Find(AValue, J) then
cxTreeList.Nodes[I].Selected := True;
end;
finally
cxTreeList.EndUpdate;
end;
finally
AValueList.Free;
ASelectedNodes.Free;
end;
end;

[C++ Builder]
void SelectIdenticalNodes(int AItemIndex){

Page 224 of 1199


if (!cxTreeList->OptionsSelection->MultiSelect) return;
TList *ASelectedNodes = new TList();
TStringList *AValueList = new TStringList();
String AValue;
try {
cxTreeList->GetSelections(ASelectedNodes);
for (int I = 0; I < ASelectedNodes->Count; I++){
AValue = ((TcxTreeListNode*)ASelectedNodes->Items[I])->Texts[AItemIndex];
if (AValueList->IndexOf(AValue) == -1)
AValueList->Add(AValue);
}
cxTreeList->BeginUpdate();
try {
int J;
for (int I = 0; I < cxTreeList->Nodes->Count; I++){
AValueList->Sort();
AValue = cxTreeList->Nodes->Items[I]->Texts[AItemIndex];
if (AValueList->Find(AValue, J))
cxTreeList->Nodes->Items[I]->Selected = true;
}
}
__finally{
cxTreeList->EndUpdate();
}
}
__finally{
delete AValueList;
delete ASelectedNodes;
}
}

Page 225 of 1199


Example: OnGetContentStyle
The following sample uses the OnGetContentStyle event. The event handler assigns a style to the current node depending on whether
Note that the sample requires an instance of the style repository. The repository should contain the following two styles: styCategory

[Delphi]
procedure <Form>.<TreeList>StylesGetContentStyle(Sender: TcxCustomTreeList; AColumn: TcxTreeList
begin
if ANode.IsGroupNode then
AStyle := styCategory
else
AStyle := styTask;
end;

[C++ Builder]
void __fastcall <Form>::<TreeList>StylesGetContentStyle(TcxCustomTreeList *Sender, TcxTreeListCo
if (ANode->IsGroupNode) {
AStyle = styCategory;
} else {
AStyle = styTask;
}
}

Page 226 of 1199


Example: OnGetEditingProperties
The following sample demonstrates how to change the in-place editor just before it activates (i.e. before the end-user starts editing a ce
Note that the sample requires an instance of the cxEditRepository component. The repository should have at least one item (named e
control, the OnGetEditingProperties event is fired substituting the default in-place editor with eriBlobMemo.

[Delphi]
procedure <Form>.<Column>GetEditingProperties(Sender: TcxTreeListColumn; ANode: TcxTreeListNode;
begin
EditProperties := eriBlobMemo.Properties;
end;

[C++ Builder]
void __fastcall <Form>::<Column>GetEditingProperties(TcxTreeListColumn *Sender, TcxTreeListNode
EditProperties = eriBlobMemo->Properties;
}

Page 227 of 1199


Example: OnGetEditProperties
The following sample shows how to handle the column's OnGetEditProperties event in order to change a column's default in-place edito
Note that the sample requires an instance of the cxEditRepository component. The repository should have at least one item (named e

[Delphi]
procedure <Form>.<Column>GetEditProperties(Sender: TcxTreeListColumn; ANode: TcxTreeListNode; va
begin
EditProperties := eriTextMemo.Properties;
end;

[C++ Builder]
void __fastcall <Form>::<Column>GetEditProperties(TcxTreeListColumn *Sender, TcxTreeListNode *AN
EditProperties = eriTextMemo->Properties;
}

Page 228 of 1199


Example: OnGetHotTrackStyle
The following sample shows the use of the OnGetHotTrackStyle event. The event handler changes the style of a node depending on the
The sample requires that an instance of the style repository is available. The repository should contain at least two styles: a style for h

[Delphi]
procedure <Form>.<TreeList>GetHotTrackStyle(
Sender: TcxCustomTreeList; AColumn: TcxTreeListColumn; ANode: TcxTreeListNode; var AStyle: Tcx
begin
if ANode.Level = 0 then
AStyle := stlHotRoot
else
AStyle := stlHotItem;
end;

[C++ Builder]
void __fastcall <Form>::<TreeList>GetHotTrackStyle(TcxCustomTreeList *Sender, TcxTreeListColumn
if (ANode->Level == 0)
AStyle = stlHotRoot;
else
AStyle = stlHotItem;
}

Page 229 of 1199


Example: OnGetNodeImageIndex
The following example shows how to handle the OnGetNodeImageIndex event. The event handler specifies the custom node image dep

[Delphi]
procedure <Form>.<TreeList>GetNodeImageIndex(Sender: TcxCustomTreeList; ANode: TcxTreeListNode;
begin
// exit from the handler if the currently handled image is a state image or a overlay state imag
if AIndexType in [tlitStateIndex, tlitOverlayStateIndex] then Exit;
if ANode.Level = 0 then
begin
AIndex := 0;
if ANode.Expanded then
Inc(AIndex);
end
else
AIndex := 4;
if ANode.HotTrack then
if ANode.Level = 0 then
Inc(AIndex, 2)
else
Inc(AIndex);
end;

[C++ Builder]
void __fastcall <Form>::<TreeList>GetNodeImageIndex(TcxCustomTreeList *Sender, TcxTreeListNode *
// exit from the handler if the currently handled image is a state image or a overlay state imag
if (AIndexType == tlitStateIndex) || (AIndexType == tlitOverlayStateIndex) return;
if (ANode->Level == 0) {
AIndex = 0;
if (ANode->Expanded) ++AIndex;
}
else
AIndex = 4;
if (ANode->HotTrack) {
if (ANode->Level == 0)
AIndex += 2;
else
++AIndex;
}
}

Page 230 of 1199


Example: OnHotTrackNode
The following sample utilizes the OnHotTrackNode event to change the cursor over the first level nodes to crHandPoint.

[Delphi]
procedure <Form>.<TreeList>HotTrackNode(
Sender: TcxCustomTreeList; ANode: TcxTreeListNode; AShift: TShiftState;
var ACursor: TCursor);
begin
if ANode.Level = 1 then
ACursor := crHandPoint
else
ACursor := crDefault;
end;

[C++ Builder]
void __fastcall <Form>::<TreeList>HotTrackNode(TcxCustomTreeList *Sender, TcxTreeListNode *ANode
if (ANode->Level == 1)
ACursor = crHandPoint;
else
ACursor = crDefault;
}

Page 231 of 1199


Example: OnIsGroupNode
The following sample uses the OnIsGroupNode event. The event handler checks whether the current node is a root level node and, if so
group node.
Note that it is necessary to set the PaintStyle to tlpsCategorized.

[Delphi]
procedure <Form>.<TreeList>IsGroupNode(Sender: TcxCustomTreeList;
ANode: TcxTreeListNode; var IsGroup: Boolean);
begin
IsGroup := ANode.Level = 0;
end;

[C++ Builder]
void __fastcall <Form>::<TreeList>IsGroupNode(TcxCustomTreeList *Sender, TcxTreeListNode *ANode,
IsGroup = (ANode->Level == 0);
}

Page 232 of 1199


Example: Searching, Behavior.IncSearch, Behavior.IncS
Behavior.ExpandOnIncSearching, SearchingText, Canc
The following sample implements the incremental search feature using code. The IncSearch method accepts the following parameters
ASearchColumn represents the column whose values are searched.
ASearchingText provides the search string.
AExpandOnIncSearching specifies whether a collapsed node should expand if one of its child nodes contains a suitable value. The par

[Delphi]
procedure IncSearch(ASearchColumn: TcxTreeListColumn; ASearchingText: String; AExpandOnIncSearch
begin
cxTreeList.OptionsBehavior.IncSearch := True;
cxTreeList.OptionsBehavior.IncSearchItem := ASearchColumn;
cxTreeList.OptionsBehavior.ExpandOnIncSearch := AExpandOnIncSearching;
cxTreeList.SearchingText := ASearchingText;
repeat
if not cxTreeList.FindNext(True) then
begin
cxTreeList.CancelSearching;
Break;
end;
until cxTreeList.FocusedNode.Texts[ASearchColumn.ItemIndex] = ASearchingText
end;

[C++ Builder]
void __fastcall IncSearch(TcxTreeListColumn *ASearchColumn, AnsiString ASearchingText, bool AExp
Form1->cxTreeList->OptionsBehavior->IncSearch = true;
Form1->cxTreeList->OptionsBehavior->IncSearchItem = ASearchColumn;
Form1->cxTreeList->OptionsBehavior->ExpandOnIncSearch = AExpandOnIncSearching;
Form1->cxTreeList->SearchingText = ASearchingText;
do {
if (!(Form1->cxTreeList->FindNext(true))) {
Form1->cxTreeList->CancelSearching();
return;
}
} while (Form1->cxTreeList->FocusedNode->Texts[ASearchColumn->ItemIndex] == ASearchingText);
}

Page 233 of 1199


Example: TreeList.ColumnByName
The following sample adds a new child node and sets a value of a cell within the node. The cell belongs to a column provided by
the ColumnByName property. The AddNode method accepts the following parameters:
AParent represents a node to which the new child node is added.
AValue represents the value for the cell.

Note that the sample requires that a “Notes” column exists.

[Delphi]
procedure AddNode(AParent: TcxTreeListNode, AValue: string);
begin
AParent.AddChild;
cxTreeList.ColumnByName('Notes').Value := AValue;
end;

[C++ Builder]
void __fastcall AddNode(TcxTreeListNode *AParent, char * AValue) {
AParent->AddChild();
cxTreeList->ColumnByName("Notes")->Value = AValue;
}

Page 234 of 1199


Example: TreeList.ColumnCount, TreeList.Columns
The following sample code populates a string list with column captions. The GetColumnsList method uses the Columns and
ColumnCount properties to get access to the collection of columns within the control and to determine the number of columns
within the collection.
Note that the AColumns parameter passed to the GetColumnsList method should be already initialized.

[Delphi]
procedure GetColumnsList(AColumns: TStringList);
var
I: Integer;
begin
for I := 0 to cxTreeList.ColumnCount - 1 do
AColumns.AddObject(cxTreeList.Columns[I].Caption.Text, cxTreeList.Columns[I]);
end;

[C++ Builder]
void GetColumnsList(TStringList *AColumns){
for (int I = 0; I < cxTreeList->ColumnCount; I++)
AColumns->AddObject(cxTreeList->Columns[I]->Caption->Text, cxTreeList->Columns[I]);
}

Page 235 of 1199


Example: TreeList.CreateColumn,
Column.ApplyBestFit
The following sample shows how to create columns. The CreateColumns method accepts the following parameters:
AColumns contains captions for new columns. Note that this parameter should be initialized.
ABand represents the band to which the new columns will belong.

[Delphi]
procedure CreateColumns(AColumns: TStringList; ABand: TcxTreeListBand);
var
I: Integer;
begin
for I := 0 to AColumns.Count - 1 do
with cxTreeList.CreateColumn(ABand) do
begin
Caption.Text := AColumns[I];
ApplyBestFit;
end;
end;

[C++ Builder]
void __fastcall CreateColumns(TStringList *AColumns, TcxTreeListBand *ABand)
{
TcxTreeListColumn *AColumn;
for (int I = 0; I < AColumns->Count; I++) {
AColumn = cxTreeList->CreateColumn(ABand);
AColumn->Caption->Text = AColumns->Strings[I];
}
}

Page 236 of 1199


Example: TreeList.Customizing,
Customizing.MakeBandPageVisible,
Customizing.MakeColumnPageVisible,
SimpleCustomizeBox
The following sample shows how to display the customization form. The ShowCustomizationForm method accepts the
following parameters:
AIsSimple specifies whether the customization form is in simple mode. If set to True, the form will have only the columns sheet
available; otherwise, both the columns and the bands sheets are exposed.
AMak eBandsSheetVisible specifies whether to switch to the bands sheet when the customization form is displayed. Note that
this parameter has no effect unless AIsSimple is set to False.

[Delphi]
procedure ShowCustomizationForm(AIsSimple, AMakeBandsPageVisible: Boolean);
begin
cxTreeList.OptionsView.SimpleCustomizeBox := AIsSimple;
if not AIsSimple then
begin
if AMakeBandsSheetVisible then
cxTreeList.Customizing. AMakeBandsPageVisible
else
cxTreeList.Customizing.MakeColumnPageVisible;
end;
cxTreeList.Customizing.Visible := True;
end;

[C++ Builder]
void __fastcall ShowCustomizationForm(bool AIsSimple, bool AMakeBandsPageVisible) {
cxTreeList->OptionsView->SimpleCustomizeBox = AIsSimple;
cxTreeList->Customizing->Visible = true;
if (!AIsSimple) {
if (AMakeBandsSheetVisible)
cxTreeList->Customizing->MakeBandPageVisible();
else
cxTreeList->Customizing->MakeColumnPageVisible();
}
}

Page 237 of 1199


Example: TreeList.FocusedColumn,
TreeList.FocusedNode
The following sample changes the value of the currently focused cell within the control. The SetFocusedCellValue method uses
the FocusedNode and FocusedColumn properties to get access to the cell.

[Delphi]
procedure SetFocusedCellValue(AValue: Variant);
begin
cxTreeList.FocusedNode.Values[cxTreeList.FocusedColumn.ItemIndex] := AValue;
end;

[C++ Builder]
void SetFocusedCellValue(Variant AValue){
cxTreeList->FocusedNode->Values[cxTreeList ->FocusedColumn->ItemIndex] = AValue;
}

Page 238 of 1199


Example: TreeList.Items
The following sample demonstrates how to implement the functionality of a radio group using check box in-place editors. The
ExtendedRadioButtonCheck method accepts the following parameters:
ATreeList represents the tree list control.
ANode represents a node within the control.
AItemIndex represents the index of a column containing Boolean values.
The method uses the Items property to iterate through the collection of nodes within the tree list control.

The example assumes that your tree list control has a column with check boxes assigned as in-place editors. When the end-user che
within the column, all other check boxes get unchecked automatically. This behavior fakes the behavior of a radio group control. Altern
use the built-in radio group functionality.

[Delphi]
procedure ExtendedRadioButtonCheck(ATreeList: TcxTreeList; ANode: TcxTreeListNode; AItemIndex: I
var
I: Integer;
begin
ATreeList.BeginUpdate;
try
for I := 0 to ATreeList.Count - 1 do
if ATreeList.Items[I] = ANode then
ATreeList.Items[I].Values[AItemIndex] := True
else
ATreeList.Items[I].Values[AItemIndex] := False;
end;
finally
ATreeList.EndUpdate;
end;
end;

[C++ Builder]
void __fastcall ExtendedRadioButtonCheck(TcxTreeList *ATreeList, TcxTreeListNode *ANode, int A
ATreeList->BeginUpdate();
try {
for (int i = 0; i < ATreeList->Count; i++) {
if (ATreeList->Items[i] == ANode) {
ATreeList->Items[i]->Values[AItemIndex]= true;
} else {
ATreeList->Items[i]->Values[AItemIndex] = false;
}
}
} __finally {
ATreeList->EndUpdate();
}
}

Page 239 of 1199


Example: TreeList.Items[], TreeList.Count, Node.AddCh
Node.AddChildFirst
The following sample code returns a child node of the node specified.
The AParent parameter provides the tree list node whose child node is obtained.
The AIndex parameter specifies the zero-based index of the child node required.
The AddFirst parameter specifies whether the new child node should be added at the beginning or at the end of the child nodes collect

The GetNodeInstance method allows you to obtain a child node at the specified index. If the index is greater or equal to the number o
child node is added. In this case, the position of the new node depends on the AddFirst parameter. Set AddFirst to True, to add a new
beginning of the child nodes collection; set it to False, to add a new child node to the end of the collection.

[Delphi]
function GetNodeInstance(AParent: TcxTreeListNode; AIndex: Integer; AddFirst: boolean = False):
begin
if AIndex < AParent.Count then
Result := AParent.Items[AIndex]
else
if AddFirst then
Result := AParent.AddChildFirst
else
Result := AParent.AddChild;
end;

[C++ Builder]
TcxTreeListNode* GetNodeInstance(TcxTreeListNode *AParent, int AIndex, bool AddFirst){
TcxTreeListNode *Result;
if (AIndex < AParent->Count)
Result = AParent->Items[AIndex];
else{
if (AddFirst)
Result = AParent->AddChildFirst();
else
Result = AParent->AddChild();
}
return Result;
}

Page 240 of 1199


Example: TreeList Provider Mode
This example shows how to populate a tree list with the data in provider mode when the smart load feature is disabled (the TreeList co
It uses a file named DEPARTMENTS.TXT as the data store. This file was created by exporting data from the self-referencing DEPARTM

The following image demonstrates the code execution result:

[Delphi]
unit TLProviderModeUnit;
interface
uses
Windows, Messages, SysUtils, StrUtils, Variants, Classes, Controls, Forms, Dialogs, cxCustomDa
type
TTLProviderModeForm = class(TForm)
VirtualTreeList: TcxVirtualTreeList;
procedure FormCloseQuery(Sender: TObject; var CanClose: Boolean);
procedure FormCreate(Sender: TObject);
procedure FormDestroy(Sender: TObject);
end;
{ TcxProviderRecordHandle }
TcxProviderRecordHandle = class
private
FParent: TcxProviderRecordHandle; Page 241 of 1199
begin
Result := RootHandle;
end;
function TcxCustomDemoDataSource.GetValue(ARecordHandle: TcxDataRecordHandle; AItemHandle: TcxDa
var
I: Integer;
begin
with TcxProviderRecordHandle(ARecordHandle) do
begin
I := Integer(AItemHandle);
Result := Values[I];
end;
end;
procedure TcxCustomDemoDataSource.SetValue(
ARecordHandle: TcxDataRecordHandle; AItemHandle: TcxDataItemHandle;
const AValue: Variant);
var
I: Integer;
begin
with TcxProviderRecordHandle(ARecordHandle) do
begin
I := Integer(AItemHandle);
if VarIsNull(AValue) then
Values[I] := ''
else
Values[I] := AValue;
end;
FModified := True;
end;
procedure TcxCustomDemoDataSource.LoadData;
const
AFieldNamesRecordNumber = 0;
AKeyField = 0;
AParentKeyField = 1;
var
ARecords, AValues: TStringList;
procedure CreateColumns();
var
I: Integer;
begin
AValues.DelimitedText := ARecords[AFieldNamesRecordNumber];
for I := 0 to AValues.Count - 1 do
with TLProviderModeForm.VirtualTreeList.CreateColumn() do
begin
Caption.Text := AValues[I];
Caption.AlignHorz := taCenter;
end;
ARecords.Delete(AFieldNamesRecordNumber);
end;
function AddRecordHandle(AParentHandle: TcxProviderRecordHandle;
const ARecord: string): TcxProviderRecordHandle;
Page 242 of 1199
var
const
AKeyField = 0;
var
I, J: Integer;
function CompareKeyValues(Item1, Item2: Pointer): Integer;
var
AKeyValue1, AKeyValue2: Integer;
begin
AKeyValue1 := StrToInt(TcxProviderRecordHandle(Item1).Values[AKeyField]);
AKeyValue2 := StrToInt(TcxProviderRecordHandle(Item2).Values[AKeyField]);
Result := CompareValue(AKeyValue1, AKeyValue2);
end;
begin
// originate the order of records as it was in the file store before loading data into the b
FRecordsList.Sort(@CompareKeyValues);
for I := 0 to FRecordsList.Count - 1 do
begin
AValue := '';
AValues := '';
with TcxProviderRecordHandle(FRecordsList[I]) do
begin
for J := 0 to Values.Count - 1 do
begin
AValue := Values[J] ;
if J <> (Values.Count - 1) then
AValues := AValues + AValue + ATabChar
else
AValues := AValues + AValue;
end;
end;
ARecords.Add(AValues);
end;
end;
begin
ARecords := TStringList.Create;
AddColumnCaptions;
AddRecords;
try
ARecords.SaveToFile(AFileName);
finally
ARecords.Free;
end;
end;
procedure TTLProviderModeForm.FormCreate(Sender: TObject);
begin
VirtualTreeList.CustomDataSource := TcxCustomDemoDataSource.Create;
VirtualTreeList.FullExpand;
end;
procedure TTLProviderModeForm.FormDestroy(Sender: TObject);
begin
VirtualTreeList.DataController.CustomDataSource.Free;
Page 243 of 1199
VirtualTreeList.DataController.CustomDataSource := nil;
Example: TreeList.Sorted,
TreeList.SortedColumnCount, TreeList.SortedColumns
Column.SortOrder
The following sample changes the sort order of all the columns within the tree list control. Note: the TreeList control's Sorted property
must be set to True or the method does nothing.

[Delphi]
procedure InvertSorting;
var
I: Integer;
ASortDesc: Boolean;
begin
if not cxTreeList.Sorted then Exit;
cxTreeList.BeginUpdate;
try
for I := 0 to cxTreeList.SortedColumnCount - 1 do
begin
ASortDesc := cxTreeList.SortedColumns[I].SortOrder = soDescending;
// changing the sort order of the current column
cxTreeList.SortedColumns[I].SortOrder := TcxDataSortOrder(Integer(not ASortDesc) + 1);
end;
finally
cxTreeList.EndUpdate;
end;
end;

[C++ Builder]
void __fastcall InvertSorting() {
if (!(Form1->cxTreeList->Sorted)) {
return;
}
Form1->cxTreeList->BeginUpdate();
try {
for (int i; i < Form1->cxTreeList->SortedColumnCount; i++) {
bool ASortDesc = Form1->cxTreeList->SortedColumns[i]->SortOrder == soDescending;
// changing the sort order of the current column
Form1->cxTreeList->SortedColumns[i]->SortOrder = (TcxDataSortOrder)((int)(!ASortDesc) + 1)
}
} __finally {
Form1->cxTreeList->EndUpdate();
}
}

Page 244 of 1199


Example: TreeList.VisibleColumnCount,
TreeList.VisibleColumns
The following sample code fills a string list with captions of the visible columns within the control. The GetVisibleColumnsList method
the VisibleColumns and VisibleColumnCount properties to get access to the collection and to determine the number of visible columns
the collection.
Note that the AColumns parameter should be already initialized.

[Delphi]
procedure GetVisibleColumnsList(AColumns: TStringList);
var
I: Integer;
begin
for I := 0 to cxTreeList.VisibleColumnCount - 1 do
AColumns.AddObject(cxTreeList.VisibleColumns[I].Caption.Text, cxTreeList.VisibleColumns[I]);
end;

[C++ Builder]
void GetVisibleColumnsList(TStringList *AColumns){
for (int I = 0; I < cxTreeList->VisibleColumnCount; I++)
AColumns->AddObject(cxTreeList->VisibleColumns[I]->Caption->Text, cxTreeList->VisibleColumns
}

Page 245 of 1199


How to Custom Paint Band Backgrounds
Task-Based Help

The tree list's OnCustomDrawBandCell event is used to paint the following band background areas: band header, band content (data ce
If you want to custom paint a particular area in a different manner, use the event's ViewInfo.Part property to determine the area to paint
by the TcxTreeListBandPart enumeration.

The following example is taken from the CustomDrawDemo that is shipped with the product. It demonstrates how to handle the tree li
band's background.

// Delphi
// ...

uses

// ...

CustomDrawDemoConsts;
procedure <Form>.<TreeList>CustomDrawBandHeader(Sender: TcxCustomTreeList; ACanvas: TcxCanvas; A
const

// specify areas to draw

ADrawArea: array [tlbpHeader..tlbpFooter] of TCustomDrawArea = (cdaHeader, cdaCellsGroup, cdaG


begin
ADone := DrawItem(FCustomDrawInfo[ADrawArea[AViewInfo.Part]], ACanvas, AViewInfo.BoundsRect);
end;
function TCustomDrawDemoMainForm.DrawItem(AItem: TcxItemCustomDrawInfo; ACanvas: TcxCanvas; cons
begin
case AItem.DrawingStyle of
cdsBkImage:
ACanvas.FillRect(R, AItem.Bitmap);
cdsGradient:
DrawGradient(ACanvas.Canvas, R,
ColorScheme[Integer(AItem.ColorScheme), 1],
ColorScheme[Integer(AItem.ColorScheme), 0], 40,
Integer(AItem.ColorScheme) > 1);
end;
Result := (AItem.DrawingStyle <> cdsDefaultDrawing);
end;

Related Information

l Custom Draw

Page 246 of 1199


How to Custom Paint Column Headers
Task-Based Help

The following example demonstrates how to handle the tree list's OnCustomDrawHeaderCell event, used to manually paint column hea

[Delphi]
//...
procedure <Form>.<TreeList>CustomDrawHeaderCell(Sender: TObject; ACanvas: TcxCanvas; AViewInfo:
var ADone: Boolean);
begin
// specify the default color and font settings
cxApplyViewParams (ACanvas, AViewInfo.ViewParams);
// changes the font style to bold
AViewInfo.ViewParams.Font.Style := [fsBold];
// specify the column header's background color
ACanvas.Brush.Color := $FAE6E6;
// paint the column header
ACanvas.FillRect(AViewInfo.BoundsRect);
// draw the column's caption
ACanvas.DrawTexT(AViewInfo.Text, AViewInfo.TextBounds, 0, True);
// draw a frame around the header
ACanvas.FrameRect(AViewInfo.BoundsRect, clBlack, 1);
with AViewInfo do
if (SortOrder <> soNone) then
// paint the sort glyph, if sorting is applied
TcxTreeList(Sender).LookAndFeel.Painter.DrawSortingMark(ACanvas, SortMarkBounds, SortOrder
// suppress the default painting
ADone := True;
end;

Related Information

l Custom Draw

Page 247 of 1199


How to Custom Paint Data Cells
Task-Based Help

The following example demonstrates how to handle the tree list's OnCustomDrawDataCell event, used to manually paint data cells.
In the example, only selected data cells are custom painted. For the required result, the following settings have been specified: the tree
OptionsSelection.InvertSelect property is False.

// Delphi
// ...

procedure <Form>.<TreeList>CustomDrawDataCell(Sender: TcxCustomTreeList; ACanvas: TcxCanvas; AVi


begin
if not AViewInfo.Selected then Exit
else
begin
//paint the focused node
ACanvas.Brush.Color := $80FFFF;
end;
end;

This is the code execution result:

Related Information

l Custom Draw

Page 248 of 1199


How to Custom Paint Footer Cells
Task-Based Help

The tree list's OnCustomDrawFooterCell event is used to manually paint both group footer cells and footer cells. In the handler impleme
distinguished using the AViewInfo.Node property that references the node against which summaries are calculated. Footer cells alway
the root node. In the example, the node is identified via the node's Level property, which returns –1 for the root node.

The following example demonstrates how to handle the OnCustomDrawFooterCell event, so that footers and group footers are painted d

[Delphi]
//...
procedure <Form>.<TreeList>CustomDrawFooterCell(Sender: TObject; ACanvas: TcxCanvas; AViewInfo:
var ADone: Boolean);
begin
if AViewInfo.Node.Level = -1 then
//paint footer cells
ACanvas.Brush.Color := $9988FE
else
//paint group footer cells
ACanvas.Brush.Color := $D0FFD0;
end;

This is the code execution result:

Related Information

l Custom Draw

Page 249 of 1199


How to Custom Paint Indent Cells
Task-Based Help

The following example demonstrates how to handle the tree list's OnCustomDrawIndentCell event used to manually paint indent cells.
In the example, the event handler checks whether a node contains an expand button, and if the expand button exists, paints it (the Int
used for this purpose).

[Delphi]
//...
uses
//...
cxGeometry;
procedure <Form>.<TreeList>CustomDrawIndentCell(Sender: TcxCustomTreeList; ACanvas: TcxCanvas; A
procedure InternalDrawExpandButtonSign(ACanvas: TcxCanvas; const R: TRect; AExpanded: Boolean;
var
ASize, X, Y: Integer;
begin
with R do
begin
ASize := Right - Left - 2 * 2;
X := (Left + Right) div 2;
Y := (Top + Bottom) div 2;
end;
ACanvas.Brush.Color := AColor;
ACanvas.FillRect(Rect(X - ASize div 2, Y, X + ASize div 2 + 1, Y + 1));
if not AExpanded then
ACanvas.FillRect(Rect(X, Y - ASize div 2, X + 1, Y + ASize div 2 + 1));
end;
procedure InternalDrawExpandButton (ACanvas: TcxCanvas; R: TRect; AExpanded: Boolean; AColor:
begin
with ACanvas, R do
begin
Brush.Color := AColor;
FillRect(cxRect(Left - 1, Top - 1, Right + 1, Bottom + 1));
Brush.Color := clBtnFace;
FillRect(cxRect(Left, Top, Right, Bottom));
InternalDrawExpandButtonSign(ACanvas, R, AExpanded, clBtnText);
end;
end;
begin
// assign the default font and color settings
cxApplyViewParams(ACanvas, AViewInfo.ViewParams);
// specify the indent cell color
ACanvas.Brush.Color := $FAE6E6 - $000100;
// paint indent cells
ACanvas.FillRect(AViewInfo.VisibleRect);
if (AViewInfo.Button) then
begin
// if the current indent cell painted belongs to a group node, then paint the expand butto
InternalDrawExpandButton(ACanvas,Page 250 of 1199
AViewInfo.GlyphRect, AViewInfo.Node.Expanded);
How to Custom Paint Node Indicators
Task-Based Help

The following example demonstrates how to handle the tree list's OnCustomDrawIndicatorCell event, used to manually paint node indic
In the example, a focus glyph for the focused node is painted manually as well as indicator cells.

[Delphi]
//...
procedure <Form>.<TreeList>CustomDrawIndicatorCell(Sender: TcxCustomTreeList; ACanvas: TcxCanvas
var
IndicatorKind: TcxIndicatorKind;
// paint the indicator image (arrow)
procedure InternalDrawIndicatorImage(ACanvas: TcxCanvas;
const R: TRect; AKind: TcxIndicatorKind);
var
X, Y: Integer;
begin
if AKind = ikNone then Exit;
with cxIndicatorImages, R do
begin
X := (Left + Right - Width) div 2;
Y := (Top + Bottom - Height) div 2;
end;
// draw built-in indicator images
cxIndicatorImages.Draw(ACanvas.Canvas, X, Y, Ord(AKind) - 1);
end;
begin
// specify the background color
ACanvas.Brush.Color := $FAE6E6;
// paint the background
ACanvas.FillRect(AViewInfo.BoundsRect);
if (AViewInfo.Node <> nil) and (AViewInfo.Node.Focused) then
// the corresponding node is focused
IndicatorKind := ikArrow
else
// the corresponding node is not focused
IndicatorKind := ikNone;
InternalDrawIndicatorImage(ACanvas, AViewInfo.BoundsRect, IndicatorKind);
// draw a frame around the indicator cell
ACanvas.FrameRect(AViewInfo.BoundsRect, clBlack, 1);
// suppress the default painting
ADone := True;
end;

Related Information

l Custom Draw

Page 251 of 1199


How to Custom Paint Previews
Task-Based Help

The following example demonstrates how to handle the tree list's OnCustomDrawPreviewCell event, used to manually paint previews.
In the example, the focused node's preview is painted differently than other previews.

[Delphi]
//...
procedure <Form>.<TreeList>CustomDrawPreviewCell(Sender: TcxCustomTreeList; ACanvas: TcxCanvas;
begin
if (AViewInfo.Node.Focused) then
begin
ACanvas.Brush.Color := $FAE6E6;
ACanvas.Font.Style := [fsBold, fsItalic];
end
else
begin
ACanvas.Brush.Color := $AAE8EE;
ACanvas.Font.Style := ACanvas.Font.Style - [fsBold];
end;
// paint the preview section's background
ACanvas.FillRect(AViewInfo.BoundsRect);
// change the font style to italic
ACanvas.Font.Style := [fsItalic];
// draw the preview section's contents
ACanvas.DrawTexT(AViewInfo.DisplayValue, AViewInfo.VisibleRect, 0, True);
// suppress the default painting
ADone := True;
end;

Related Information

l Custom Draw

Page 252 of 1199


Dynamic Loading
The ExpressQuantumTreeList control enables you to implement dynamic loading of its nodes, i.e. by only loading its root-level nodes
when the application starts. Child nodes are loaded as their parent nodes are expanded. Note: this technique requires the
ExpressQuantumTreeList control to be in unbound mode (the TcxTreeList control must be used).
This topic provides a simple example of implementing dynamic loading. It reads the file structure of your local hard drive and displays it
within the TreeList.
There are three basic things to do in order to use dynamic loading:
l Create the methods that will be used to load child nodes for the specified parent node. These methods can also be used to fill the
root level with nodes. Note: the TreeListNode.HasChildren node property must be set to True for nodes that will contain child
nodes. This displays the expanding/collapsing button for such nodes.
l Fill the root level with nodes when the application starts.
l Handle the TreeList.OnExpanding event. The handler must add child nodes to the node being expanded.
All these items will be implemented in the sample application below.

As was stated above, dynamic loading can only be implemented when working in unbound mode. Use the TcxTreeList control to work
in unbound mode. Three columns are created in this example: Name, Type and Size.

You can use the following code to create the columns required:

[Delphi]
//...
var
FColumn: TcxTreeListColumn;
begin
FColumn := cxTreeList1.CreateColumn;
FColumn.Caption.Text := 'Name';
FColumn.PropertiesClass := TcxTextEditProperties;
FColumn := cxTreeList1.CreateColumn;
FColumn.Caption.Text := 'Type';
FColumn.PropertiesClass := TcxTextEditProperties;
FColumn := cxTreeList1.CreateColumn;
Page 253 of 1199
FColumn.Caption.Text := 'Size';
//...

The next step is to declare a procedure to search for the files and folders at the specified path and to create the nodes required. The
ScanPath procedure declared below performs this task. It receives the path of files to be displayed within the parent node and the
parent node itself as its parameters. When calling this procedure to fill the root level (in the TForm.OnCreate event handler) the root
path is specified as the first parameter and TreeList.Root is passed as the parent node. The TreeListNode.HasChildren property for
each node displaying a folder is set to True. This forces the TreeList control to display expand buttons for these nodes.

procedure TForm1.ScanPath(APath: string; AParent: TcxTreeListNode);


var
FHandle: Integer;
FSearchRec: TSearchRec;
FNode: TcxTreeListNode;
function AddFileNode(AName: string; ASize: string): TcxTreeListNode;
var
FNode: TcxTreeListNode;
begin
FNode := AParent.AddChild;
with FNode do
begin
Texts[0] := AName;
Texts[2] := ASize;
end;
Result := FNode;
end;
begin
FHandle := FindFirst(APath + '\*.*', faAnyFile, FSearchRec);
if FHandle = 0 then
repeat
if (FSearchRec.Name <> '.') and (FSearchRec.Name <> '..') then
begin
if (FSearchRec.Attr and faDirectory) <> 0 then
begin
FNode := AddFileNode(APath + FSearchRec.Name + '\', ' ');
FNode.Texts[1] := 'Folder';
FNode.HasChildren := True;
end else
begin
FNode := AddFileNode(FSearchRec.Name, IntToStr(FSearchRec.Size));
FNode.Texts[1] := 'File';
end
end;
until FindNext(FSearchRec) <> 0;
FindClose(FSearchRec);
end;

After declaring this procedure, you can write code to fill the root level with nodes. The following code can be used for this purpose (it
sets the "C:\" logical drive to be the root):

procedure TForm1.FormCreate(Sender: TObject);


var
FColumn: TcxTreeListColumn;
begin
FColumn := cxTreeList1.CreateColumn; Page 254 of 1199
FColumn.PropertiesClass := TcxTextEditProperties;
FColumn := cxTreeList1.CreateColumn;
FColumn.Caption.Text := 'Type';
FColumn.PropertiesClass := TcxTextEditProperties;
FColumn := cxTreeList1.CreateColumn;
FColumn.Caption.Text := 'Size';
FColumn.PropertiesClass := TcxTextEditProperties;
ScanPath('C:\', cxTreeList1.Nodes.Root);
end;

The last step is to implement dynamic loading. When an end-user expands a folder node, the TreeList.OnExpanding event occurs. This
event handler calls the ScanPath procedure passing the first column value of the expanded node and node as its parameters. Note
checking the TreeListNode.Count property – this is required to avoid child nodes duplication when parent node is expanded.

procedure TForm1.cxTreeList1Expanding(Sender: TObject;


ANode: TcxTreeListNode; var Allow: Boolean);
begin
if ANode.Count = 0 then
ScanPath(ANode.Texts[0], ANode);
end;

Now you can run the application. Child nodes will be loaded when nodes are expanded.

Page 255 of 1199


TcxTreeListBandPosition Object
Hierarchy   Properties

Represents a set of options that determine layout aspects of a band within the TreeList control.

Unit
cxTL

Syntax

TcxTreeListBandPosition = class(TcxOwnedPersistent)

Description
This class introduces properties that allow you to:
l Nest the band within another band (BandIndex).
l Specify the band's horizontal position (ColIndex).
l Determine the band's visible position (VisibleColIndex).
l Access the band and parent band properties (Band and ParentBand).

The TcxTreeListBandPosition object is referenced by a band's Position property.

Page 256 of 1199


Bands
Task-Based Help

Let's create a TcxTreeList with the following bands and columns layout:

First, drop a TreeList control on a form. Invoke the Component Editor and go to the Bands tab to create two bands by pressing
the Add button:

Set the OptionsView.Bands property to True to display bands within the tree list. Set their desired captions (the Caption.Text
property), glyphs and their alignment (the Caption.Glyph, Caption.GlyphAlignHorz and Caption.GlyphAlignVert properties).

Now it is time to create columns. Invoke the Component Editor, go to the Columns tab and create five columns by pressing the
Add button. By default, they will be created in the first band, the band that has a zero index. If there is no band in your tree list
when adding columns, a new band will be created automatically.

Page 257 of 1199


After setting the Caption properties, text and glyph, we need to move two columns to the second band. It can be done by
dragging columns from one band into the other at design time or by changing their Position.BandIndex from 0 (the default value)
to 1.

The first image illustrates band captions that occupy two text lines. To achieve this result, set the OptionsView.BandLineHeight
property to 34 or increase the band's height by clicking and dragging the band's bottom edge at design time.
Now your TreeList control should look exactly like the one in the first screenshot.
The following code does the same at runtime.

[Delphi]
//...
var
ATreeList: TcxTreeList;
begin
// Create a treelist control

Page 258 of 1199


ATreeList := TcxTreeList.Create(self);
ATreeList.Parent := self;
ATreeList.Left := 10;
ATreeList.Top := 10;
ATreeList.Width := 400;
ATreeList.Height := 300;
// Make bands visible
ATreeList.OptionsView.Bands := True;
// Set the band header panel's height
ATreeList.OptionsView.BandLineHeight := 34;
// Create bands
ATreeList.Bands.Add;
ATreeList.Bands.Add;
// Set band captions
ATreeList.Bands[0].Caption.Text := 'Info';
ATreeList.Bands[1].Caption.Text := 'Phones';
// Create columns in the first band
with ATreeList.CreateColumn(ATreeList.Bands[0]) do
Caption.Text := 'Department';
with ATreeList.CreateColumn(ATreeList.Bands[0]) do
Caption.Text := 'Budget';
with ATreeList.CreateColumn(ATreeList.Bands[0]) do
Caption.Text := 'Location';
// Create columns in the second band
with ATreeList.CreateColumn(ATreeList.Bands[1]) do
Caption.Text := 'Phone';
with ATreeList.CreateColumn(ATreeList.Bands[1]) do
Caption.Text := 'Fax';
// Enable columns auto width
ATreeList.OptionsView.ColumnAutoWidth := True;
end;

Another feature of the ExpressQuantumTreeList is fixed bands. Fixing bands to the left or to the right of the control makes
compacts data representation as fixed bands are not included in horizontal scrolling. In order to fix a band, set its FixedKind
property to tlbfRight or to tlbfLeft.

Page 259 of 1199


In this case, the band becomes non-scrollable. This feature does not make sense if OptionsView.ColumnAutoWidth is set to
True.

For data-aware TreeList designed to work in bound mode you can use the DataController.CreateAllItems method, which creates
items for all fields in a bound data source and automatically links them to the corresponding fields via the DataBinding property.

Page 260 of 1199


Connecting to Data
Data Modes

This topic explains how to connect ExpressQuantumTreeList to a dataset.


A data-aware cxTreeList control is able to connect to any VCL dataset but only self-referenced datasets are suitable for
ExpressQuantumTreeList. In other cases, the control will not be able to build a tree.

Generally, the connection procedure can be divided into several steps:

1.   Data Preparation
First, all data objects necessary (dataset and data source) are created and set up.
2.   TreeList Control Preparation
A treelist control with an appropriate view is created.
3.   Data Connection
Finally, data is connected to the control.

Now let's discuss these steps in detail:

Data Preparation
The type of the underlying data engine used by the TreeList control is not important. It can be BDE, ADO, ODBC or whatever.
The only requirement is that you should use the TDataSource component as a link between a self-referenced dataset and the
control.

We will discuss two methods of data preparation: BDE and ADO.


1.   BDE
l Place TTable and TDataSource components on a form (or DataModule).
l Set up the TTable component via the Object Inspector: Set its DatabaseName property to the catalog where you have
installed the demo Data for the ExpressQuantumTreeList Suite, the TableName property to "departments.db" and the
Active property to True.

Page 261 of 1199


l Set up the TDataSource component via the Object Inspector: Set its DataSet property to a TTable class instance (normally
Table1).

2.   ADO
l Place TADOConnection, TADOTable and TDataSource components on a form.
l Set up the TADOConnection component via the Object Inspector: Use the Connection String Wizard to form a connection
string:

This is the Connection String Wizard. Press the [Build…] button to continue:

Page 262 of 1199


The following dialog will appear. Select the Microsoft Jet 4.0 OLE DB Provider data provider and click the Connection tab.

In the Connection tab, click the […] button next to the database name textbox. Navigate to the DepartmentsDB.mdb
database. This file is shipped with the ExpressQuantumTreeList Library. Click the [OK] button to apply the changes and exit
the Connection String Builder.

Page 263 of 1199


Click the [OK] button to apply the changes and exit the Connection String Wizard.

Set the LoginPrompt property to False to deactivate the database login dialog:

Page 264 of 1199


Now the ADO Connection is ready to use.
l Set up the TADOTable component via the Object Inspector: Set its Connection property to ADOConnection1, the
TableName property to "DEPARTMENTS" and the Active property to True.

l Set up the TDataSource component via the Object Inspector: Set its DataSet property to a TADOTable class instance
(normally ADOTable1).

Page 265 of 1199


TreeList Control Preparation
Drop the DBTreeList control on a form and set its Align property to alClient. Only the TcxDBTreeList control can be connected
to a dataset.

Data Connection
The next step is to connect the TreeList control to the data prepared:
l Set the DataSource property of the data controller to a TDataSource class instance (normally DataSource1):

l Set the KeyField property to the key field in a self-referenced dataset:

   
l Set the ParentField property to the parent field in the self-referenced dataset:

Page 266 of 1199


   
l Now the data is connected to the TreeList control. To display the data, call the Component Editor, go to the Columns tab
and press the Create all fields button.

   

Easy Steps to Connect


Whenever you have active datasets in a form that are accessible via the TDataSource components, all you have to do to connect
the DBTreeList control to a data source is invoke the tree list's context menu and select the required data source via the "Link to
DataSource" item. This will automatically create columns bound to dataset fields.

To connect your data-aware TreeList control to a dataset at runtime, implement the following code:

[Delphi]
with cxDBTreeList1.DataController do
begin
DataSource := DataSource1;
CreateAllItems;
end;

[C++ Builder]
cxDBTreeList1->DataController->DataSource = DataSource1;
cxDBTreeList1->DataController->CreateAllItems();

Page 267 of 1199


Note: The CreateAllItems method creates columns within a data-aware treelist for each field in the linked dataset.

If you've done everything correctly, data will appear within the control:

Page 268 of 1199


Creating And Deleting Columns
Task-Based Help

This topic covers the steps required to create and delete columns within the TreeList control.
Data-aware, unbound and virtual TreeList controls provide a Columns property maintaining the collection of columns created within
the control. The Columns property returns:
l A TcxTreeListColumn object for unbound and virtual TreeList controls.
l A TcxDBTreeListColumn object for a data-aware TreeList controls.

The only difference between these two objects is the DataBinding property type.

Adding Columns Manually


This first method is applicable to unbound, virtual and bound TreeList controls.

[Delphi]
var
AColumn: TcxTreeListColumn;
ADBColumn: TcxDBTreeListColumn;
//...
begin
//...
//create an unbound column and add it to the first band
AColumn := ATreeList.CreateColumn;
AColumn.Position.BandIndex := 0;
//the same code, but it will work if you already have a band object in your treelist control
AColumn := ATreeList.CreateColumn(ATreeList.Bands[0]);
//create a DB column and assign the valid field name
ADBColumn := TcxDBTreeListColumn(ADBTreeList.CreateColumn);
ADBColumn.Position.BandIndex := 0;
ADBColumn.DataBinding.FieldName := 'FirstName';
//...
end;

Adding Columns Within a Data-Aware TreeList control


For the data-aware TreeList control designed to work in bound mode, you can use the CreateAllItems method declared in the
DataController property. This method creates items for all fields in a data source and automatically links them to the corresponding
fields via the DataBinding property.

[Delphi]
cxDBTreeList1.DataController.CreateAllItems;

At design time, you can create all items within the Component Editor. Connect the cxDBTreeList control to a valid data source,
invoke the Component Editor, go to the Columns tab and press the Create all fields button.

Page 269 of 1199


Deleting columns
To delete a column at runtime, you just need to invoke the column's destructor. The following code is used to dispose of the first
column within the TreeList control:

[Delphi]
cxTreeList1.Columns[0].Free;

The DeleteAllColumns method allows you to destroy all columns within the control.

[Delphi]
tvPersons.DeleteAllColumns;

At design time, the Component Editor allows you to delete individual columns. Switch to the Columns panel, select the columns to
delete and press the Delete button. You can select multiple columns to delete them at once.

Related Information

l Reordering Bands and Columns


l Resizing Bands and Columns
Page 270 of 1199
Creating Summaries
Task-Based Help

This topic demonstrates how to add footer and group summaries and display them within the TreeList control.

Use the following steps to add a summary to the TreeList control at design time:
l Select a column to display a summary using the Component Editor, or by clicking a column's header in the TreeList
control.
l Switch to the Object Inspector and click the ellipsis button next to the Summary.FooterSummaryItems property to invoke
a collection editor to manage footer summaries. To manage group footer summaries, invoke a collection editor by clicking
the ellipsis button next to the Summary.GroupFooterSummaryItems property.

l In the collection editor, add a summary item and specify the required summary type via the Kind property.

l Set the TreeList control's OptionsView.Footer property to True to display the footer. Then, assign True to the column's
Options.Footer property to make footer cells visible to display footer summaries.

Page 271 of 1199


l To display group footer summaries, make the group footers and group footer cells visible by setting the TreeList control's
OptionsView.GroupFooters property and the column's Options.GroupFooter property to True.

You can display summary item properties in the Object Inspector by clicking the corresponding footer and group footer cells.

The following code demonstrates how to create and display a column's footer summary at runtime.

[Delphi]
<TreeList>.OptionsView.Footer := True;
<Column>.Options.Footer := True;
with <Column>.Summary.FooterSummaryItems.Add do
Kind := skSum;

Now you can run the application to see the result.

You can calculate a column's summaries using the values of another column. To accomplish this, select the source column via
the summary's CalculatedColumn property.

To specify the format string for summary values, use the summary's Format property. For instance, by setting this property to
'SUM = $,0.00;-$,0.00' for a currency column's footer summary, you will get the following display text in footer cells:

Page 272 of 1199


The 0.00 string is a placeholder for the summary value. Two zeros following the point identify the number of digits in the summary
value to the right of the decimal point. A comma represents the ThousandSeparator global variable. A semicolon separates two
patterns used to display positive and negative values. Other characters do not have a special meaning and are displayed on the
screen as is. Thus, if the summary value is $23.01, the cell will display the 'SUM = $23.01' string.

You can provide custom summary values by handling the OnSummary events. For example, you may use only selected nodes in
the summary calculation or perform other calculations. To learn how to use the OnSummary and OnAfterSummary events, see
the SummariesDemo shipped with the ExpressQuantumTreeList Suite.

Here is a code snippet taken from the SummariesDemo. This code calculates summaries based on the criteria specified via the
footer or group footer context menu. The FCheckBudget and FCheckVacancies values indicate whether a particular condition is
included in the criteria.

[Delphi]
procedure TSummariesDemoMainForm.tlDepartmentsSummary(
ASender: TcxCustomTreeList;
const Arguments: TcxTreeListSummaryEventArguments;
var OutArguments: TcxTreeListSummaryEventOutArguments);
begin
// If a department doesn't match the specified criteria, exclude its
// values from use in automatic summary calculations
if FCheckBudget and (Arguments.Node.Values[clBudget.ItemIndex] <= 100000) or
FCheckVacancies and not Arguments.Node.Values[clVacancy.ItemIndex] then
OutArguments.Done := True;
end;

code /code

Page 273 of 1199


Deleting Nodes
Task-Based Help

To delete nodes at runtime, set the OptionsData.Deleting property to True and press the Ctrl+Del key combination to delete the
selected records.
If the OptionsSelection.MultiSelect property is set to True, several nodes can be selected. Otherwise, only one record can be
selected (the one with focus).

To delete records programmatically, use the TreeList control's DeleteSelection method. This method deletes selected and
focused nodes and does not require any parameters, as shown in the following code:

[Delphi]
try
cxDBTreeList1.DeleteSelection;
except
on E: Exception do
ShowMessage('Cannot delete selected nodes due to the exception: ' + E.Message);
end;

[C++ Builder]
try {
cxDBTreeList1->DeleteSelection();
} catch(Exception &e) {
ShowMessage("Cannot delete selected nodes due to the exception: " + e.Message);
}

An exception may occur if records cannot be deleted. This can be caused, for instance, if the deletion violates integrity rules. If
you are working with an unbound TreeList control, there is no need to handle the exception for the DeleteSelection method,
since it should not generate any exception.

Page 274 of 1199


Implementing Drag-And-Drop Functionality
Task-Based Help

Drag-and-drop allows end-users to drag one control (or its items) to another within the same application or rearrange items within the s
different situations when you may need to implement the drag-and-drop feature within the TreeList control:
l Rearranging nodes within the TreeList control by changing their parent nodes.
l Drag and drop from a VCL control onto a TreeList control.
l Drag and drop from a TreeList control onto a VCL control.
l Drag and drop between two TreeList controls.

In this topic we will discuss all four types of drag-and-drop.

Drag and drop within a TreeList control


This is the easiest case, because it can be implemented automatically by setting the DragMode property of the TreeList control to dm
Inspector:

Additionally, at the very least you will have to provide an empty implementation of the OnDragOver event to enable drag-and-drop within
If you are working with a data-aware TreeList control, it changes parent field values during drag-and-drop operations automatically. Set
OptionsData.AutoCalcKeyValue property to True to enable automatic changing of the node's key field values.
On starting an application, you will be able to drag-and-drop nodes within the TreeList control.

Drag and drop from a VCL control onto a TreeList control


Let's create a small application with one form containing two controls: TreeList and Listbox. An end-user will be able to drag items fro
TreeList.
 1. Drop TcxTreeList and TListBox controls on a form.
 2. Create one column in the TreeList control and set the OptionsView.ColumnAutoWidth property to True.
 3. Add 5 items to the ListBox control.
 4. Change ListBox properties: DragMode to dmAutomatic and MultiSelect to True.

Page 275 of 1199


[Delphi]
procedure TForm1.cxTreeList1DragOver(Sender, Source: TObject; X, Y: Integer; State: TDragState;
begin
Accept := Source = ListBox1;
end;

 6. Write the following code for the TreeList control's OnDragDrop event to process the final part of the drag-and-drop operation.

[Delphi]
procedure TForm1.cxTreeList1DragDrop(Sender, Source: TObject; X, Y: Integer);
var
AParentNode, ANode: TcxTreeListNode;
I: Integer;
begin
if Source <> ListBox1 then exit;
// If the cursor was under a particular node, add items as children to that node.
AParentNode := cxTreeList1.HitTest.HitNode;
for I := 0 to ListBox1.Items.Count - 1 do
if ListBox1.Selected[I] then
begin
// add a new node
ANode := cxTreeList1.AddChild(AParentNode);
// set node value
ANode.Values[0] := ListBox1.Items[I];
end;
end;

The following image shows the application while dragging and after dropping:

As you can see, the dragged list box items (Item3 and Item4) are added to the TreeList control as Item1 children.

Page 276 of 1199


Drag and drop from a TreeList control onto a VCL control
 4. Disable the TreeList control's OptionsBehavior.ImmediateEditor and OptionsBehavior.AlwaysShowEditor properties and set DragM
 5. Write the following code for the Listbox control's OnDragOver and OnDragDrop events.

[Delphi]
procedure TForm1.ListBox1DragOver(Sender, Source: TObject; X, Y: Integer; State: TDragState; var
begin
Accept := Source = cxTreeList1; // accept drag-and-drop for the TreeList control only
end;
procedure TForm1.ListBox1DragDrop(Sender, Source: TObject; X, Y: Integer);
var
I: Integer;
begin
// exit if the drag-and-drop operation was initialized from a control different from cxTreeLis
if Source <> cxTreeList1 then exit;
// loop through selected nodes and add them to the ListBox1 control
for I := 0 to cxTreeList1.SelectionCount - 1 do
ListBox1.Items.Add(cxTreeList1.Selections[I].Values[0]);
end;

The following image shows the application while dragging:

Page
And the following image shows the TreeList control after 277 of 1199
dropping:
Dragging one TreeList control to another has one major difference from the examples above: the tree structure must be recreated on th
 1. Drop a TcxTreeList control on a form.
 2. Create a column in the TreeList control and set the OptionsView.ColumnAutoWidth property to True.
 3. Invoke the Items Editor and add several nodes.
 4. Disable the OptionsBehavior.ImmediateEditor and OptionsBehavior.AlwaysShowEditor properties and set DragMode to dmAutoma
 5. Copy the TreeList control to the clipboard and paste it into the same form, so that we have two controls with the same settings.

 6. Write the following code for the OnDragOver and OnDragDrop events of the TreeList controls. Note that we use the same code for b

[Delphi]
procedure TForm1.cxTreeList1DragOver(Sender, Source: TObject; X, Y: Integer; State: TDragState;
begin
// accept drag-and-drop from the other treelist control only
Accept := (Source is TcxTreeList) and (Sender <> Source);
end;
// Since we want to store the tree structure in the TreeList control
// the method looks pretty complex
procedure TForm1.cxTreeList1DragDrop(Sender, Source: TObject; X, Y: Integer);
var
ASourceTreeList, ADestTreeList: TcxTreeList;
AParentNode: TcxTreeListNode;
// get the correct parent node
// new inserted nodes have their data property set to the source node
// for the original nodes, the data property equals nil
function GetParentNode(ANewNode: TcxTreeListNode): TcxTreeListNode;
var
I: Integer;
ANode: TcxTreeListNode;
begin
Result := nil;
// loop through all nodes in the destination treelist control
for I := 0 to ADestTreeList.Nodes.Count - 1 do
// is it a new inserted node?
if ADestTreeList.Nodes.Items[I].Data <> nil then
begin
// get the source node
ANode := TcxTreeListNode(ADestTreeList.Nodes.Items[I].Data);
// if the new source node has ANode as parent
if ANewNode.HasAsParent(ANode) and
((Result = nil) or TcxTreeListNode(Result.Data).HasAsParent(ANode)) then
Page 278 of 1199
Result := ADestTreeList.Nodes.Items[I];
// loop through all selected nodes in the source treelist control
for I := 0 to ASourceTreeList.SelectionCount - 1 do
begin
ASelectedNode := ASourceTreeList.Selections[I];
// add a new node
ANode := ADestTreeList.AddChild(GetParentNode(ASelectedNode), ASelectedNode);
// set the data in cell(s)
ANode.Values[0] := ASelectedNode.Values[0]
end;
// set the data property for all nodes to nil
for I := 0 to ADestTreeList.Nodes.Count - 1 do
ADestTreeList.Nodes.Items[I].Data := nil;
end;

The following image shows the resulting application while dragging:

And the following image shows the drag-and-drop result:

Note:   You may also find the following TreeList control properties useful when handling drag-and-drop operations: OptionsView.DropN
OptionsBehavior.AutoDragCopy, OptionsBehavior.DragCollapse, and OptionsBehavior.DragExpand.

Related Information

l TcxTreeListNode Object
l TcxUnboundTreeListNode Object
l TcxVirtualTreeListNode Object

Page 279 of 1199


Obtaining And Setting Cell Values
Task-Based Help

This topic describes how you can get and set values for TreeList control cells.

Every cell is identified by its node and column. For data-ware TreeList columns, refer to the fields of the connected dataset.
At runtime, a user can easily navigate through nodes and edit cell values. When moving from one node to another within a data-
aware TreeList control, changed data is posted to the database. You can prevent a user from editing cells in a number of ways:

l the column's Options.Editing property specifies whether a user can edit its cells (provided that any cell can be edited, see
OptionsData.Editing)
l the column's Options.Focusing enables/disables focusing its cells
l the control's OptionsData.Editing enables/disables editing all columns within this TreeList control
l the control's OptionsSelection.CellSelect determines whether individual columns can be selected within a node

The methods of getting and setting TreeList cell values differ depending on the TreeList control type that you are working with:
data-ware or unbound TreeList controls.

Unbound TreeList controls


The TcxTreeList control stores data using an internal ExpressDataController object. Use the Values array property of the Node
object to get a particular cell value:

[Delphi]
MyEditText.Text := MyNode.Values[MyColumn.ItemIndex];

[C++ Builder]
MyEditText->Text = MyNode->Values[MyColumn->ItemIndex];

There are two important things that are necessary to remember when using this method:
 1) You have to use the column's ItemIndex property to access a particular cell. This property is not changed when modifying the
column order; while the column's Index property may be changed.
 2) In the previous versions of the ExpressQuantumTreeList, data was stored in string arrays. Now you may change the data
type stored in a column by using the DataBinding.Field.DataType property.

You can set data for nodes in a single call by using the Node.AssignValues method:

[Delphi]
MyNode.AssignValues(['Corporate Headquarters', 1000000, 'Monterey',
'(408) 555-1234', '(408) 555-1234']);

Data-aware TreeList controls


For a data-aware TreeList control, you can use the same method to obtain a cell value as for an unbound TreeList control. If you
set a cell value via the Values property, it will be cached by the ExpressDataController, but the connected dataset will not be
updated.
You can only change data via VCL Dataset (TField) methods or via a DataController object for the focused node (the current
record).

[Delphi]
cxDBTreeList1.DataController.Edit;
cxDBTreeList1.FocusedNode.Values[col1.ItemIndex] := 'New Value';
Page 280 of 1199
cxDBTreeList1.DataController.Post;

[C++ Builder]
cxDBTreeList1->DataController->Edit();
cxDBTreeList1->FocusedNode->Values[col1.ItemIndex] := 'New Value';
cxDBTreeList1->DataController->Post();

Page 281 of 1199


Selecting Nodes
Task-Based Help

The TreeList control provides various facilities for selecting nodes via its OptionsSelection property. Refer to the
TcxTreeListOptionsSelection class reference for detailed information on all selection options.

Standard selection mode, a single selection, is enabled when the TreeList.OptionsSelection.MultiSelect property is set to False.
Thus only one node can be selected at a time (the focused node). Focusing a record automatically selects it. You can use the
following code to focus and select the top node within the TreeList control at the same time:

[Delphi]
if cxTreeList1.TopNode <> nil then
cxTreeList1.TopNode.Focused := True;

[C++ Builder]
if (cxTreeList1->TopNode != null)
cxTreeList1->TopNode->Focused = true;

If the OptionsSelection.MultiSelect property is set to True, you can select multiple nodes at once. When a user clicks any node,
it is focused and selected at the same time, however he/she can deselect the focused node by clicking it with the Ctrl key
pressed.

To select/deselect multiple nodes, you can use the Selected property of the node object. The following code selects every
second node in the TreeList control:

[Delphi]
var
I: Integer;
begin
for I := 0 to cxTreeList1.Count - 1 do
cxTreeList1.Items[I].Selected := (cxTreeList1.Items[I].AbsoluteIndex mod 2 = 0);
end;

[C++ Builder]
for (int i = 0; i < cxTreeList1->Count; i++)
cxTreeList1->Items[I]->Selected = (cxTreeList1->Items[I]->AbsoluteIndex % 2 == 0);
}

Use the SelectAll method to select all nodes in the TreeList control:

[Delphi]
cxTreeList1.SelectAll;

[C++ Builder]
cxTreeList1->SelectAll();

Page 282 of 1199


Setting the TreeList Appearance
Task-Based Help

The TreeList control provides several ways to modify its appearance:


l Look And Feel. Changes the look & feel of the entire TreeList control.
l Styles. Affects the appearance of the TreeList elements that support the Styles technology.
l Custom Draw. Can change the appearance of many of the TreeList elements.

Let's explore each option in detail.

Look And Feel


ExpressQuantumTreeList has a LookAndFeel property, which provides four options:
l Standard
l Flat
l UltraFlat
l Office 2003

You can switch between them via the LookAndFeel.Kind property. You can also apply skins via the LookAndFeel.SkinName property.

The following code demonstrates shows how to apply the Flat appearance to your TreeList control:

[Delphi]
cxTreeList1.LookAndFeel.Kind := lfFlat;

[C++ Builder]
cxTreeList1->LookAndFeel->Kind = lfFlat;

If you are using the Windows XP (or later) operating system, you can make your TreeList look like a Windows native control. To accom
True.

[Delphi]
cxTreeList1.LookAndFeel.NativeStyle := True;

[C++ Builder]
cxTreeList1->LookAndFeel->NativeStyle = true;

Note:   The NativeStyle property has a higher priority than the Kind and SkinName properties. Thus, if the NativeStyle property is set, t

Styles
Styles allow you to customize the appearance of particular TreeList elements such as bands and columns, etc. A style affects the ele
events that occur when a style is about to change. You can write code in these event handlers to implement conditional style changes

The following code sets different styles for different group rows:

[Delphi]
var
cxMyStyle1, cxMyStyle2: TcxStyle;
//...
//Put the following code into the form's constructor
Page 283 of 1199
cxMyStyle1 := TcxStyle.Create(Self);
AStyle = cxMyStyle1;
else AStyle = cxMyStyle2;
}

The result of the code above is shown in the image below:

Custom Draw
The Custom Draw feature provides the most powerful method of customizing the TreeList's appearance. This is an event-based techn
of custom draw events. Each event provides the arguments necessary for painting TreeList elements. These parameters include:
Sender – the standard parameter passed to all event handlers;
AViewInfo – the element's ViewInfo;
ACanvas – the TreeList control's canvas.
ADone – a Boolean parameter that indicates whether default painting should be performed.
These parameters are discussed in detail in the Custom Draw base concepts. The ACanvas parameter needs an additional explanatio
ACanvas parameter) is a wrapper around the standard VCL canvas (TCanvas) and the latter is available via ACanvas.Canvas.
Note:   The ACanvas parameter contains the canvas of the whole TreeList control and so you may need to calculate the current eleme
parameter contains a Bounds property representing the current element's bounding rectangle.

The following code draws an image as a cell background.

[Delphi]
procedure TForm1.TreeListCustomDrawCell (Sender: TObject; ACanvas: TcxCanvas; AViewInfo: TcxTree
var
ARec: TRect;
ATextToDraw: string;
begin
ACanvas.Canvas.Brush.Bitmap := Image1.Picture.Bitmap;
ACanvas.Canvas.FillRect(AViewInfo.BoundsRect);
SetBkMode(ACanvas.Canvas.Handle, TRANSPARENT);
ACanvas.DrawText(AViewInfo.DisplayValue, AViewInfo.ContentRect, 0);
ADone := True;
end;

[C++ Builder] Page 284 of 1199


void __fastcall TForm1::TreeListCustomDrawCell(
Page 285 of 1199
Unbound Mode
Data Loading Modes

This topic explains the basics of how to handle the data in unbound mode.
In unbound mode, a tree list doesn't connect to any data source. The View is populated with the data programmatically.
The example below is taken from the ExpressQuantumTreeList Features demo.

Creating and initializing columns


Columns within a TreeList control can be created at design or runtime. To create columns at design time, use the Component Editor.
for details.
If a TreeList is not connected to a data source, columns must be created manually. For each column, it is required to set the appropri
DataBinding.ValueTypeClass property for this purpose. See the TcxValueType class topic for the types available.
The following example shows how to specify the value type for four columns of the TreeList Control.

[Delphi]
clnDepartment.DataBinding.ValueTypeClass := TcxStringValueType;
clnBudget.DataBinding.ValueTypeClass := TcxCurrencyValueType;
clnLocation.DataBinding.ValueTypeClass := TcxStringValueType;
clnPhone1.DataBinding.ValueTypeClass := TcxStringValueType;
clnPhone2.DataBinding.ValueTypeClass := TcxStringValueType;

Loading data
The Values property of the node object allows you to get/set values of a particular data cell. It requires a column index to be supplied.
AssignValues method that allows the values for the all cells to be set in one operation by using an open array. In our demo, we are usi

[Delphi]
procedure TForm1.InitData;
function AddNode(AParent: TcxTreeListNode; const AValues: Array of Variant; AImageIndex: Inte
begin
Result := TreeList.AddChild(AParent);
Result.AssignValues(AValues);
Result.Imageindex := AImageIndex;
end;
var
ARootNode, ASalesMarketingNode: TcxTreeListNode;
begin
ARootNode := AddNode(nil, ['Corporate Headquarters', 1000000, 'Monterey', '(408) 555-1234', '(
ASalesMarketingNode := AddNode(ARootNode, ['Sales and Marketing', 22000, 'San Francisco', '(41
AddNode(ASalesMarketingNode, ['Field Office: Canada', 500000, 'Toronto', '(416) 677-1000', '(4
AddNode(ASalesMarketingNode, ['Field Office: East Coast', 500000, 'Boston', '(617) 555-1234',
end;

This is the code execution result:

Page 286 of 1199


Using a Lookup Column
Task-Based Help

A lookup column allows the display and editing of records from a lookup dataset. This column type is handled by the
LookupComboBox editor.
There are two ways to set up a lookup column.
The first is to connect your DBTreeListColumn to a lookup field that was created in Delphi's persistent field editor. For more
information on how to create a persistent Lookup field, see the 'Defining a lookup field' topic in the Delphi documentation. If a
dataset contains a lookup field that is properly set up, a user just has to assign the lookup field name to the
DBTreeListColumn.DataBinding.FieldName property.
The second way of setting up a lookup column is to use the column's Properties or RepositoryItem property. The PropertiesClass
property allows you to choose the column's bound editor class. The RepositoryItem property allows you to choose one of the
editors previously created. After an appropriate value to either of these properties, the Properties property will contain an object
providing editor settings:

[Delphi]
//...
TreeListUSERID.PropertiesClass := TcxLookupComboBoxProperties;
//...

If you choose the LookupCombo editor class, you will get an editor class that includes properties for configuring ListSource,
ListColumns and KeyFieldNames and the DataBinding.FieldName to replace the LookupComboBox.DataBinding property
used to match the value of the lookup dataset field (KeyFieldNames).
Let's examine how the TreeListUSERID lookup column is configured in the ExpressQuantumTreeList web demo, (the Task
Manager module). The TreeListUSERID column is set up to show the full name of the person whose USERID field in the
PROJECTS table matches the ID field in the USERS table. The following image shows the design time settings applied to the
TreeListUSERID lookup column's editor:

Page 287 of 1199


[Delphi]
//...
TreeListUSERID.PropertiesClass := TcxLookupComboBoxProperties;
With TcxLookupComboBoxProperties(TreeListUSERID.Properties) do
begin
ListSource := dsMain.dsUsers;
ListFieldNames := 'FULLNAME';
KeyFieldNames := 'ID';
end;
TreeListUSERID.DataBinding.FieldName := 'USERID';
//...

The following image shows the User column at runtime:

Page 288 of 1199


TcxCustomDataTreeList.DataController
TcxCustomDataTreeList

Provides access to the data controller that obtains records from a TreeList data source.

Syntax

property DataController: TcxDataTreeListDataController;

Description
Supported data sources include:
l The virtual TreeList control's custom data source;
l The data-aware TreeList control's data source.

ReadOnly Property

Page 289 of 1199


TcxCustomDataTreeList.OptionsData
TcxCustomDataTreeList

Specifies settings used to control the data processing in data-aware modes.

Syntax

property OptionsData: TcxVirtualTreeListOptionsData;

Description
Use the OptionsData property to determine which actions can be performed for the dataset providing records for the control.
They include inserting, appending, editing and deleting records. Data options also indicate whether the virtual TreeList control
operates in smart load mode (the SmartLoad property). When in smart load mode, TreeList nodes are loaded as they are
expanded.

Page 290 of 1199


TcxCustomDBTreeList.DataController
TcxCustomDBTreeList

Represents an object that manages the connection to a data source.

Syntax

property DataController: TcxDBTreeListDataController;

Description
Use the DataController property to access a TcxDBTreeListDataController object to manage the tree list's connection to a data
source. The DataController.DataSource property specifies the dataset to which the cxDBTreeList control is connected.
The DataController.KeyField and DataController.ParentField properties are required to build the tree structure.
DataController.KeyField values identify records. The DataController.ParentField property designates the dataset field whose
values define the record's position within the tree structure. DataController.ParentField values specify the DataController.KeyField
value of the record (node in the tree structure) owning the record (node).

The TcxDBTreeList component provides the design-time capability to easily connect its data controller to a data source located
on a form. To accomplish this, invoke the tree list's context menu and select the required data source via the "Link to
DataSource" item. If the data source is linked to a dataset, the data controller automatically calls its CreateAllItems method to
create columns bound to dataset fields.

Related Information

l TcxDBTreeListDataController Object
l TcxDBTreeListDataController.KeyField
l TcxDBTreeListDataController.ParentField

Page 291 of 1199


TcxCustomDBTreeList.FindNodeByKeyValue
TcxCustomDBTreeList

Locates a treelist node by its key field value.

Syntax

function FindNodeByKeyValue(const AKeyValue: Variant; AStartNode: TcxTreeListNode = nil; AEx

Description
Use the FindNodeByKeyValue method to locate the treelist node by its key field value. The required key field value is specified via th
parameter. The AExpandedOnly parameter determines whether the expanded child nodes of the expanded parents are involved into sea

The return value of this method is the located node. If this method cannot locate node by the specified text, it returns nil.

Page 292 of 1199


TcxCustomDBTreeList.GetColumnByFieldName
TcxCustomDBTreeList

Returns the column by the corresponding field's name.

Syntax

function GetColumnByFieldName(const AFieldName: string): TcxDBTreeListColumn;

Description
The GetColumnByFieldName method returns nil, if the specified field is not found.
AFieldName specifies the name of the field by which the column is to be obtained.

Page 293 of 1199


TcxCustomDBTreeList.OnGetUniqueKeyValue
TcxCustomDBTreeList

Enables you to specify the unique identifier for a new node.

Syntax

type
TcxDBTreeListGetUniqueKeyValueEvent = procedure(Sender: TcxCustomDBTreeList; var KeyValue:
property OnGetUniqueKeyValue: TcxDBTreeListGetUniqueKeyValueEvent;

Description
Fires if the tree list's OnInitInsertingRecord event is not handled, and the OptionsData.AutoCalcKeyValue is True.
Implement the OnGetUniqueKeyValue event to manually generate the node ID, if the tree list's OptionsData.AutoCalcKeyValue is Tr
unique value is generated by means of the control) and you need, for some reason, to override the auto-generated key.
KeyValue specifies the unique identifier.

Related Information

l TcxCustomDBTreeList.OnInitInsertingRecord
l TcxDBTreeListOptionsData.AutoCalcKeyValue

Page 294 of 1199


TcxCustomDBTreeList.OnInitInsertingRecord
TcxCustomDBTreeList

Occurs before a node is inserted into the TreeList control.

Syntax

type
TcxDBTreeListInitInsertingRecordEvent = procedure(Sender: TcxCustomDBTreeList; AFocusedNod
property OnInitInsertingRecord: TcxDBTreeListInitInsertingRecordEvent;

Description
The OnInitInsertingRecord event is fired before the end-user inserts a node into the TreeList control. The AFocusedNode parameter
default handling is required. Set it to True to prevent the default handling.
Handle this event to calculate the ParentField value for the inserted record (since it is not implemented automatically).

Related Information

l TcxCustomDBTreeList.OnGetUniqueKeyValue
l TcxDBTreeListOptionsData.AutoCalcKeyValue

Page 295 of 1199


TcxCustomDBTreeList.RootValue
TcxCustomDBTreeList

Specifies the ParentField property value for root level nodes.

Syntax

property RootValue: Variant;

Description
Use the RootValue property to specify the ParentField value for root level nodes. These nodes correspond to records whose
parent field values have no corresponding keys. They are displayed at the root nesting level (the Node.Level property value for
them is 0).

Page 296 of 1199


TcxCustomTreeList.AbsoluteCount
TcxCustomTreeList

Returns the number of nodes created in the tree list.

Syntax

property AbsoluteCount: Integer;

Description
This property returns the number of nodes provided by the AbsoluteItems property. To obtain the number of visible nodes, use the
AbsoluteVisibleCount property.

ReadOnly Property

Page 297 of 1199


TcxCustomTreeList.AbsoluteItems
TcxCustomTreeList

Provides zero-based indexed access to nodes created in the tree list.

Syntax

property AbsoluteItems[Index: Integer]: TcxTreeListNode;

Description
This property provides a flat list of all nodes created in the tree list, regardless of their hierarchy level and visibility. Nodes in this
list follow the sort order applied to the tree list. Use the AbsoluteCount property to obtain the number of nodes in the list.

Related Information

l TcxCustomTreeList.AbsoluteVisibleItems

Page 298 of 1199


TcxCustomTreeList.AbsoluteVisibleCount
TcxCustomTreeList

Returns the number of nodes that are visible in the tree list.

Syntax

property AbsoluteVisibleCount: Integer;

Description
This property returns the number of nodes provided by the AbsoluteVisibleItems property. To obtain the number of all nodes
created in the tree list, regardless of their hierarchy level and visibility, use the AbsoluteCount property.

ReadOnly Property

Page 299 of 1199


TcxCustomTreeList.AbsoluteVisibleItems
TcxCustomTreeList

Provides zero-based indexed access to nodes that are visible in the tree list.

Syntax

property AbsoluteVisibleItems[Index: Integer]: TcxTreeListNode;

Description
Nodes in this list follow the sort order applied to the tree list. Use the AbsoluteVisibleCount property to obtain the number of
visible nodes in the list.

Related Information

l TcxCustomTreeList.AbsoluteItems
l TcxTreeListNode.VisibleIndex

Page 300 of 1199


TcxCustomTreeList.AddNode
TcxCustomTreeList

In unbound mode, adds a node to the control at the specified position.

Syntax

function AddNode(ANode, ARelative: TcxTreeListNode; AData: Pointer; AttachMode: TcxTreeListN

Description
This function returns the added node. After the node has been added, the tree list sorts nodes (if sorting is in effect).
ANode specifies the node to be added. If ANode is nil, a new node will be created.
ARelative specifies the parent node. If ARelative is nil, ANode will be added to the root node (see the tree list's Root property).
AData specifies the custom data associated with the node (see the node's Data property).
AttachMode specifies the node's position in the parent's child collection.

Note:   The AddNode function is only used in the unbound mode. In bound and provider modes, a node is added by means of a data s
or AddChildFirst methods for this purpose.

Related Information

l TcxTreeListNode.AddChild
l TcxTreeListNode.AddChildFirst

Page 301 of 1199


TcxCustomTreeList.AdjustColumnsWidth
TcxCustomTreeList

Horizontally resizes the tree list, so that it fits the client area.

Syntax

procedure AdjustColumnsWidth;

Description
Use the AdjustColumnsWidth method if the tree list has been horizontally resized (narrowed or extended), and it is required to
restore the control to the client area's boundaries if, for some reason, automatic column adjusting is disabled (the tree list's
OptionsView.ColumnAutoWidth property is False).
To prohibit column sizing for end-users, set the tree list's OptionsCustomizing.ColumnHorzSizing property to False. To prohibit
sizing of a particular column, set the column's Options.Sizing property to False.

To adjust the tree list contents, use the ApplyBestFit method.

Related Information

l TcxTreeListOptionsView.ColumnAutoWidth

Page 302 of 1199


TcxCustomTreeList.ApplyBestFit
TcxCustomTreeList

Horizontally resizes the tree list, so that contents fit cells.

Syntax

procedure ApplyBestFit;

Description
Use the ApplyBestFit method if due to sizing operations the contents have been clipped. This method iterates through the tree
list's visible bands and calls their ApplyBestFit method.

To prohibit column sizing for end-users, set the tree list's OptionsCustomizing.ColumnHorzSizing property to False. To prohibit
sizing of a particular column, set the column's Options.Sizing property to False.

To limit a column's width to a certain value when applying Best Fit to this column, use the BestFitMaxWidth property. To adjust
the columns, use the AdjustColumnsWidth method.

Related Information

l TcxTreeListBand.ApplyBestFit
l TcxTreeListColumn.ApplyBestFit

Page 303 of 1199


TcxCustomTreeList.ApplyFindFilterText
TcxCustomTreeList

Applies a specified search string to the Find Panel's box.

Syntax

procedure ApplyFindFilterText(const AText: string);

Description
This method assigns the search string passed as the AText parameter to the tree list's DataController.FindFilterText property.

Related Information

l TcxCustomTreeList.ClearFindFilterText
l TcxCustomTreeList.GetFindFilterText

Page 304 of 1199


TcxCustomTreeList.Bands
TcxCustomTreeList

Provides access to the tree list bands.

Syntax

property Bands: TcxTreeListBands;

Description
At design time, use the Bands collection editor to specify bands for the tree list.
Refer to the TcxTreeListBands class description for details.

Examples

l Example: Bands.Add, Bands.Count, Bands

Page 305 of 1199


TcxCustomTreeList.Cancel
TcxCustomTreeList

Discards any changes made to the linked storage during the transaction opened by the Edit method.

Syntax

procedure Cancel;

Description
Use the Cancel method if, for some reason, the transaction cannot be committed.
To complete data changes, use the Post method instead.

Page 306 of 1199


TcxCustomTreeList.CancelEdit
TcxCustomTreeList

Closes an in-place editor and discards changes made to the data cell's content.

Syntax

procedure CancelEdit;

Description
To exit from in-place editing and save the modified data, use the tree list's HideEdit method instead.

If you first need to determine whether a tree list is in edit mode, use the tree list's IsEditing property.
In-place editing in the focused cell can be activated using the tree list's ShowEdit method.

Related Information

l TcxCustomTreeList.FocusedColumn
l TcxCustomTreeList.HideEdit
l TcxCustomTreeList.InplaceEditor
l TcxCustomTreeList.IsActive
l TcxCustomTreeList.IsEditing
l TcxCustomTreeList.ShowEdit
l TcxCustomTreeList.ShowEditByKey
l TcxCustomTreeList.ShowEditByMouse

Page 307 of 1199


TcxCustomTreeList.CancelSearching
TcxCustomTreeList

Stops the incremental search.

Syntax

procedure CancelSearching;

Description
The CancelSearching method assigns an empty string to the SearchingText property, and this stops the incremental search
started either programmatically (see the FindNext method), or by an end-user (incremental search is enabled if the
OptionsBehavior.IncSearch option is active).

Examples

l Example: Searching, Behavior.IncSearch, Behavior.IncSearchItem, Behavior.ExpandOnIncSearching, SearchingText,


CancelSearching

Related Information

l ExpressEditors: TcxControlOptionsBehavior.IncSearch

Page 308 of 1199


TcxCustomTreeList.CellRect
TcxCustomTreeList

Returns a data cell's bounding rectangle, in tree list coordinates.

Syntax

function CellRect(ANode: TcxTreeListNode; AColumn: TcxTreeListColumn): TRect;

Description
ANode and AColumn identify the data cell. Note that if either ANode or AColumn is invisible, the method returns an invalidated
rectangle.

Related Information

l TcxCustomTreeList.GetEditRect

Page 309 of 1199


TcxCustomTreeList.Clear
TcxCustomTreeList

Removes all nodes from the control.

Syntax

procedure Clear;

Description
The Clear method deletes nodes in the View, and doesn't affect the data store (in bound and provider modes).
This method is not dependent upon the tree list's OptionsData.Deleting option.

To delete a particular node, use the node's Delete method instead.

Related Information

l TcxCustomTreeList.ClearSelection

Page 310 of 1199


TcxCustomTreeList.ClearFindFilterText
TcxCustomTreeList

Clears the search string that is currently applied to the Find Panel's box.

Syntax

procedure ClearFindFilterText;

Description
This method assigns an empty string to the tree list's DataController.FindFilterText property. To apply a search string, use either
this property or the ApplyFindFilterText procedure.

Related Information

l TcxCustomTreeList.GetFindFilterText

Page 311 of 1199


TcxCustomTreeList.ClearSelection
TcxCustomTreeList

Unselects all the selected nodes.

Syntax

procedure ClearSelection(KeepPrimary: Boolean = False); virtual;

Description
Note that selection and deselection of multiple nodes is allowed if the OptionsSelection.MultiSelect option is active. Otherwise,
the method does nothing.
KeepPrimary specifies whether the first selected node will remain selected. Set KeepPrimary to False, to unselect all nodes.

If you wish to unselect a particular node, use the Deselect method instead.

Related Information

l TcxCustomTreeList.Deselect
l TcxCustomTreeList.OnSelectionChanged
l TcxCustomTreeList.Select
l TcxCustomTreeList.SelectAll
l TcxCustomTreeList.SelectionCount
l TcxCustomTreeList.Selections
l TcxTreeListNode.Selected
l TcxTreeListOptionsSelection.MultiSelect

Page 312 of 1199


TcxCustomTreeList.ClearSorting
TcxCustomTreeList

Clears sorting in all columns.

Syntax

procedure ClearSorting;

Description
Alternatively, use the Sorted property for this purpose.
To clear sorting in a particular column, set the column's SortOrder property to soNone.

Related Information

l TcxCustomTreeList.Sorted
l TcxCustomTreeList.SortedColumnCount
l TcxCustomTreeList.SortedColumns
l TcxTreeListOptionsData.MultiThreadedSorting

Page 313 of 1199


TcxCustomTreeList.ColumnByName
TcxCustomTreeList

Returns a column by its name.

Syntax

function ColumnByName(const AName: string): TcxTreeListColumn;

Description
AName specifies the column name (as it is specified by the column's Name property). The column's Name property and AName
are matched as strings.
If AName doesn't match the corresponding item in the Columns collection, the method returns nil.

For indexed access to columns, use the tree list's Columns property.

Examples

l Example: TreeList.ColumnByName

Related Information

l TcxCustomTreeList.Columns

Page 314 of 1199


TcxCustomTreeList.ColumnCount
TcxCustomTreeList

Returns the number of columns.

Syntax

property ColumnCount: Integer;

Description
For indexed access to columns, use the Columns property.
To obtain the number of columns that belong to a particular band, use the band's ColumnCount property. For indexed access to
the band's columns, use the band's Columns property.

ReadOnly Property

Examples

l Example: TreeList.ColumnCount, TreeList.Columns

Related Information

l TcxCustomTreeList.Columns
l TcxTreeListBand.Columns

Page 315 of 1199


TcxCustomTreeList.Columns
TcxCustomTreeList

Provides indexed access to columns.

Syntax

property Columns[Index: Integer]: TcxTreeListColumn;

Description
Index specifies the column's position in the collection.
The total number of columns can be obtained via the ColumnCount property.
To obtain the number of columns that belong to a particular band, use the band's ColumnCount property. For indexed access to
the band's columns, use the band's Columns property.

Examples

l Example: TreeList.ColumnCount, TreeList.Columns

Related Information

l TcxCustomTreeList.ColumnCount
l TcxCustomTreeList.VisibleColumnCount
l TcxCustomTreeList.VisibleColumns
l TcxTreeListBand.ColumnCount

Page 316 of 1199


TcxCustomTreeList.ConditionalFormatting
TcxCustomTreeList

Provides access to the conditional formatting controller.

Syntax

property ConditionalFormatting: TcxDataControllerConditionalFormatting;

Description
Use this property to employ the Tree List control's conditional formatting functionality. For instance, you can display the
"Conditional Formatting Rules Manager" dialog by calling the ConditionalFormatting.ShowRulesManagerDialog procedure or
apply a new conditional formatting rule to the specified dataset field by invoking the ConditionalFormatting.Add procedure.
Refer to the TcxDataControllerConditionalFormatting class description for detailed information on all available options.

ReadOnly Property

Related Information

l ExpressQuantumGrid: TcxCustomGridTableView.ConditionalFormatting
l ExpressSpreadSheet: TdxSpreadSheetTableView.ConditionalFormatting
l ExpressVerticalGrid: TcxCustomVerticalGrid.ConditionalFormatting

Page 317 of 1199


TcxCustomTreeList.CopyAllToClipboard
TcxCustomTreeList

Copies the tree list's contents to the clipboard as text.

Syntax

procedure CopyAllToClipboard;

Description
Column headers are only copied to the clipboard, if the tree list's OptionsView.Headers option is active.
In the resulting text, nodes are separated by the new line delimiter (the CRLF sequence). Values are tabulated. The text contains
no qualifiers.

To copy only selected nodes to the clipboard, use the CopySelectedToClipboard method.

Related Information

l Copy Data to the Clipboard


l ExpressPivotGrid: Copy Data to the Clipboard

Page 318 of 1199


TcxCustomTreeList.CopySelectedToClipboard
TcxCustomTreeList

Copies selected nodes to the clipboard as text.

Syntax

procedure CopySelectedToClipboard;

Description
Column headers are only copied to the clipboard if the tree list's OptionsView.Headers option is active.
In the resulting text, nodes are separated by the new line delimiter (the CRLF sequence). Values are tabulated. The text contains
no qualifiers.

To copy all the tree list contents to the clipboard, use the CopyAllToClipboard method.

Related Information

l Copy Data to the Clipboard


l ExpressPivotGrid: Copy Data to the Clipboard

Page 319 of 1199


TcxCustomTreeList.Count
TcxCustomTreeList

Returns the number of root-level nodes.

Syntax

property Count: Integer;

Description
For indexed access to the root-level nodes, use the Items property.

ReadOnly Property

Examples

l Example: TreeList.Items[], TreeList.Count, Node.AddChild, Node.AddChildFirst

Page 320 of 1199


TcxCustomTreeList.CreateColumn
TcxCustomTreeList

Creates a new column.

Syntax

function CreateColumn(ABand: TcxTreeListBand = nil): TcxTreeListColumn; virtual;

Description
ABand specifies the band that owns the new column. If ABand is nil, the column is assigned to either the first visible band (see
the band's Visible property) or to the first band stored in the band collection (see the tree list's Bands property). If no bands were
created in the control, a new band is automatically created.
The newly created column is added to the end of the band's Columns collection.

Examples

l Example: TreeList.CreateColumn, Column.ApplyBestFit

Related Information

l TcxCustomTreeList.DeleteAllColumns

Page 321 of 1199


TcxCustomTreeList.Customizing
TcxCustomTreeList

References a Customize window instance.

Syntax

property Customizing: TcxTreeListCustomizing;

Description
A Customize window instance exists regardless of whether the window is open or not. To specify the Customize window's
visibility, use its Visible property.
To learn more about the Customize window, refer to the Customization Form help topic.

Examples

l Example: TreeList.Customizing, Customizing.MakeBandPageVisible, Customizing.MakeColumnPageVisible,


SimpleCustomizeBox

Page 322 of 1199


TcxCustomTreeList.DefaultLayout
TcxCustomTreeList

Specifies whether the default layout is applied to the tree list.

Syntax

property DefaultLayout: Boolean;

Description
Set this property to True, to restore the default layout.
This property is retained for backward-compatibility purposes. Use the MakeDefaultLayout method instead.

The default value of the DefaultLayout property is False.

Page 323 of 1199


TcxCustomTreeList.DefaultRowHeight
TcxCustomTreeList

Specifies the default height for all nodes, in pixels.

Syntax

property DefaultRowHeight: Integer;

Description
This property is overridden by the node's Height property (if specified).
To allow end-users to change the DefaultRowHeight property value, set the TreeList control's OptionsCustomizing.RowSizing
property to True.

Note:   The tree list doesn't validate the specified height if it doesn't display the node's contents in their entirety.

Page 324 of 1199


TcxCustomTreeList.DeleteAllColumns
TcxCustomTreeList

Removes all columns from the control.

Syntax

procedure DeleteAllColumns; virtual;

Description
If columns were removed, the View's content is cleared.

Related Information

l TcxCustomTreeList.CreateColumn

Page 325 of 1199


TcxCustomTreeList.DeleteSelection
TcxCustomTreeList

Permanently deletes selected nodes.

Syntax

procedure DeleteSelection;

Description
This method deletes selected nodes in the View, and also removes persistent data from the linked storage (in bound and provider
modes). The method also deletes children of selected nodes.
This method is in effect, if the tree list's OptionsData.Deleting option is active, and the tree list is not in edit mode (the IsEditing
property is False).

If you wish to delete all nodes in the View, use the Clear method.

Related Information

l TcxTreeListNode.Delete
l TcxTreeListNode.DeleteChildren

Page 326 of 1199


TcxCustomTreeList.Deselect
TcxCustomTreeList

Deselects a node.

Syntax

procedure Deselect(Node: TcxTreeListNode); virtual;

Description
Node specifies the node to deselect.

Alternatively, set the node's Selected property to False, to deselect a node.


To deselect all the selected nodes simultaneously, use the ClearSelection method.

Related Information

l TcxCustomTreeList.ClearSelection
l TcxCustomTreeList.OnSelectionChanged
l TcxCustomTreeList.Select
l TcxCustomTreeList.SelectAll
l TcxCustomTreeList.SelectionCount
l TcxCustomTreeList.Selections
l TcxTreeListNode.Selected
l TcxTreeListOptionsSelection.MultiSelect

Page 327 of 1199


TcxCustomTreeList.Edit
TcxCustomTreeList

Allows updates in the linked storage.

Syntax

procedure Edit;

Description
Use the Edit method to make the underlying storage modifiable.
This method is used in concert with the Post method, for wrapping statements (see the node's Values property) that update node
values in the corresponding storage record. For rollback purposes, use the Cancel method instead of the Post method.

This method is in effect if the tree list's OptionsData.Editing option is active.

Related Information

l TcxTreeListNode.Values

Page 328 of 1199


TcxCustomTreeList.Filter
TcxCustomTreeList

Provides access to the filter applied to the tree list.

Syntax

property Filter: TcxDataFilterCriteria;

Description
Use this property or the DataController.Filter property to control filtering: manage filter conditions, customize the filter dropdown
list, etc. If a filter is applied, the tree list displays only those nodes that match the specified filter conditions. You can link the tree
list to the TcxFilterControl component to enable filter customization for end-users.
Handle the OnFilterNode event to further filter the nodes.

ReadOnly Property

Page 329 of 1199


TcxCustomTreeList.Find
TcxCustomTreeList

Searches for a node using the specified criteria and parameters.

Syntax

type
TcxTreeListFindFunc = function(ANode: TcxTreeListNode; AData: Pointer): Boolean;
function Find(AData: Pointer; AStart: TcxTreeListNode; AExpandedOnly, AForward: Boolean; AFi

Description
AData specifies the search criteria to be forwarded to the TcxTreeListFindFunc function implementation passed as the AFilter paramet
instance, if you associated a node with an object via the Data property, you can pass a reference to this object as the AData paramete
below).
AStart specifies the starting point of the search. If nil is passed, the search is performed from the beginning of the View.
AExpandedOnly specifies whether child nodes of the expanded parents are included into the search.
AForward specifies the search direction. Set AForward to True, to search forward. Otherwise, a backward search is performed.
AFilter specifies the function (a TcxTreeListFindFunc function implementation) which performs the search based on the AData criteria.
True; otherwise – False.
AIgnoreStartNode specifies whether to ignore a node that matches AStart. Set AIgnoreStartNode to True, to ignore this node.

If the matching node is not found, the Find function returns nil.

The following code example shows how to search for a particular node by an order (a TOrder object) associated with it. An order stored
function.

[Delphi]
var
FOrder: TOrder;
// Creating and initializing the order object.
FOrder := TOrder.Create;
// ...
// Associating a node with the order.
ANode.Data := FOrder;
// ...
// A TcxTreeListFindFunc function implementation.
function MyFilter(ANode: TcxTreeListNode; AData: Pointer): Boolean;
begin
Result := ANode.Data = AData;
end;
// ...
var
ASampleNode: TcxTreeListNode;
// ...
// Searching for the first node associated with the order.
ASampleNode := cxTreeList1.Find(FOrder, nil, False, True, MyFilter);
// ...
// Node manipulations.
// ... Page 330 of 1199
TcxCustomTreeList.FindNext
TcxCustomTreeList

Searches for a node containing the text specified by the SearchingText property.

Syntax

function FindNext(AForward: Boolean): Boolean;

Description
This method is used for the incremental search. It searches for the first data cell in the focused column that contains the
specified string.
If the match was successful, the method returns True; otherwise, False is returned. The method also returns False if no column
is focused, when searching.
AForward specifies the search direction. Set AForward to True, to search forward. Otherwise, a backward search is performed.

Examples

l Example: Searching, Behavior.IncSearch, Behavior.IncSearchItem, Behavior.ExpandOnIncSearching, SearchingText,


CancelSearching

Page 331 of 1199


TcxCustomTreeList.FindNodeByText
TcxCustomTreeList

Searches for the first node that contains the specified text.

Syntax

type
TcxTreeListFindMode = (tlfmNormal, tlfmLike, tlfmExact);
function FindNodeByText(const AText: string; AColumn: TcxTreeListColumn; AStartNode: TcxTree

Description
If the match was successful, the FindNodeByText method returns the first found node and stops the search. If the match is not found
AText specifies the text by which a node is to be located.
AColumn specifies the column within which the search is to be performed.
AStartNode specifies the node from which the search starts.
AExpandedOnly specifies whether the expanded child nodes of the expanded parents are involved in the search.
AForward specifies the search direction. Set AForward to True, to search forward. Otherwise, a backward search is performed.
ACaseSensitive specifies whether the search is case sensitive. Set ACaseSensitive to True, to perform a case-sensitive search.
AMode specifies the search mode. Values include:

Value Meaning

tlfmNormal Searches for any entries of AText in a data cell's content.

tlfmLike Performs a pattern search of AText.

tlfmExact Performs exact search of AText.

For instance, in tlfmNormal mode for the 'ar' search string, successive calls to the method will return the following strings: Earth, Mars,
In tlfmLike mode, for the '%a_u%' search pattern, successive calls to the method will return the following strings: Saturn, Janus, Encel
To learn more, refer to the ExpressQuantumTreeList Features demo (module Search).
ALik eParams specifies wildcards used in the pattern search (AMode is tlfmLike).
AIgnoreStartNode specifies whether to ignore a node that matches ANode. Set AIgnoreStartNode to True, to ignore the node.

Related Information

l Example: Searching, Behavior.IncSearch, Behavior.IncSearchItem, Behavior.ExpandOnIncSearching, SearchingText, CancelSear

Page 332 of 1199


TcxCustomTreeList.FocusedColumn
TcxCustomTreeList

Specifies the focused column.

Syntax

property FocusedColumn: TcxTreeListColumn;

Description
Note that a column cannot be focused if the column's Focusing option is False, or the tree list's OptionsSelection.CellSelect is
False.
The FocusedColumn property returns nil if the tree list is empty, or no column is focused.

Alternatively, the column can also be focused using the tree list's Columns.Focused property.

Examples

l Example: TreeList.FocusedColumn, TreeList.FocusedNode

Related Information

l TcxCustomTreeList.FocusedNode
l TcxTreeListColumn.Focused
l TcxTreeListColumn.Options

Page 333 of 1199


TcxCustomTreeList.FocusedNode
TcxCustomTreeList

Specifies the focused node.

Syntax

property FocusedNode: TcxTreeListNode;

Description
Specifying the focused node makes the node visible on-screen. This may result in expanding collapsed parent nodes, and
scrolling the View (if the node is beyond the View's boundaries).
Note that focusing of the specified node cannot be performed if the OnCanFocusNode's or the OnCanSelectNode's Allow
parameter is False.
The FocusedNode property returns nil if the tree list is empty, or no node is focused.

Alternatively, the node can also be focused using the node's Focused property.

Examples

l Example: TreeList.FocusedColumn, TreeList.FocusedNode

Related Information

l TcxCustomTreeList.FocusedColumn
l TcxTreeListNode Object
l TcxTreeListOptionsView.FocusRect

Page 334 of 1199


TcxCustomTreeList.FullCollapse
TcxCustomTreeList

Collapses all expanded nodes.

Syntax

procedure FullCollapse;

Description
If you wish to collapse a particular node, use the node's Collapse method.

All collapsed nodes can be expanded using the FullExpand method.

Related Information

l TcxTreeListNode.Expanded

Page 335 of 1199


TcxCustomTreeList.FullExpand
TcxCustomTreeList

Expands all collapsed nodes.

Syntax

procedure FullExpand;

Description
If you wish to expand a particular node, use the node's Expand method.

All expanded nodes can be collapsed using the FullCollapse method.

Related Information

l TcxTreeListNode.Expanded

Page 336 of 1199


TcxCustomTreeList.FullRefresh
TcxCustomTreeList

Updates the tree list.

Syntax

procedure FullRefresh; virtual;

Description
Use this method to completely reload the data in the control, if automatic updates haven't been applied to the control.

Related Information

l Refresh Data

Page 337 of 1199


TcxCustomTreeList.GetEditRect
TcxCustomTreeList

Returns the data cell edit container's rectangle, in tree list coordinates.

Syntax

function GetEditRect(ANode: TcxTreeListNode; AColumn: TcxTreeListColumn): TRect;

Description
ANode and AColumn identify the node cell. Note that if either ANode or AColumn is invisible, the method returns an invalidated
rectangle.

This method is used internally.

Related Information

l TcxCustomTreeList.CellRect

Page 338 of 1199


TcxCustomTreeList.GetFindFilterText
TcxCustomTreeList

Returns the search string that is currently applied to the Find Panel and is displayed by its Find box.

Syntax

function GetFindFilterText: string;

Description
This function returns the tree list's DataController.FindFilterText property value. To apply a search string, use either this property
or the ApplyFindFilterText procedure.

Page 339 of 1199


TcxCustomTreeList.GetNodeAt
TcxCustomTreeList

Returns the node by the specified coordinates.

Syntax

function GetNodeAt(X, Y: Integer): TcxTreeListNode;

Description
X and Y specify the node's upper-left corner, in tree list coordinates. If the specified coordinates are not valid, nil will be returned.

This method is used internally.

Page 340 of 1199


TcxCustomTreeList.GetSelections
TcxCustomTreeList

Populates AList with selected nodes.

Syntax

function GetSelections(AList: TList): TcxTreeListNode;

Description
AList is populated with nodes stored in the SelectionList collection, if multiple node selection is allowed (the tree list's
OptionsSelection.MultiSelect option is True). Otherwise, the currently selected node is added to AList.
The method returns the last node in the collection (if multiple node selection is allowed), or the currently selected node (if the
multiple selection is not allowed).

Related Information

l TcxCustomTreeList.ClearSelection
l TcxCustomTreeList.Deselect
l TcxCustomTreeList.OnSelectionChanged
l TcxCustomTreeList.Select
l TcxCustomTreeList.SelectAll
l TcxCustomTreeList.SelectionCount
l TcxTreeListNode.Selected
l TcxTreeListOptionsSelection.MultiSelect

Page 341 of 1199


TcxCustomTreeList.GotoBOF
TcxCustomTreeList

Moves focus to the first node in the control.

Syntax

procedure GotoBOF;

Description
The method scrolls the View, if the node is beyond the View's boundaries.
To move focus to the last node, use the GotoEOF method.

Related Information

l Navigation and Scrolling


l TcxCustomTreeList.FocusedNode
l TcxTreeListNode.GetNextVisible
l TcxTreeListNode.GetPrevVisible
l TcxTreeListNode.IsFirstVisible
l TcxTreeListNode.IsLastVisible
l TcxTreeListNode.IsVisible
l TcxTreeListNode.MakeVisible

Page 342 of 1199


TcxCustomTreeList.GotoEOF
TcxCustomTreeList

Moves focus to the last node in the control.

Syntax

procedure GotoEOF;

Description
The method scrolls the View, if the node is beyond the View's boundaries.
To move focus to the first node, use the GotoBOF method.

Related Information

l Navigation and Scrolling


l TcxTreeListNode.GetNextVisible
l TcxTreeListNode.GetPrevVisible
l TcxTreeListNode.IsFirstVisible
l TcxTreeListNode.IsLastVisible
l TcxTreeListNode.IsVisible
l TcxTreeListNode.MakeVisible

Page 343 of 1199


TcxCustomTreeList.GotoNext
TcxCustomTreeList

Moves focus one node down.

Syntax

procedure GotoNext;

Description
The method does nothing if no node is focused, or if the currently focused node is the last node in the control.
To move focus one node up, use the GotoPrev method.

Related Information

l Navigation and Scrolling


l TcxTreeListNode.GetNextVisible
l TcxTreeListNode.GetPrevVisible
l TcxTreeListNode.IsFirstVisible
l TcxTreeListNode.IsLastVisible
l TcxTreeListNode.IsVisible
l TcxTreeListNode.MakeVisible

Page 344 of 1199


TcxCustomTreeList.GotoNextPage
TcxCustomTreeList

Scrolls focus one page down.

Syntax

procedure GotoNextPage;

Description
The page, in this context, is the number of entirely visible nodes in the View.
To scroll focus one page up, use the GotoPrevPage method.

If you wish to move focus to the first or to the last node in the control, use the GotoBOF or the GotoEOF method.

Related Information

l Navigation and Scrolling


l TcxTreeListNode.GetNextVisible
l TcxTreeListNode.GetPrevVisible
l TcxTreeListNode.IsFirstVisible
l TcxTreeListNode.IsLastVisible
l TcxTreeListNode.IsVisible
l TcxTreeListNode.MakeVisible

Page 345 of 1199


TcxCustomTreeList.GotoPrev
TcxCustomTreeList

Moves focus one node up.

Syntax

procedure GotoPrev;

Description
The method does nothing if no node is focused, or if the currently focused node is the first node in the control.
To move focus one node down, use the GotoNext method.

Related Information

l Navigation and Scrolling


l TcxTreeListNode.GetNextVisible
l TcxTreeListNode.GetPrevVisible
l TcxTreeListNode.IsFirstVisible
l TcxTreeListNode.IsLastVisible
l TcxTreeListNode.IsVisible
l TcxTreeListNode.MakeVisible

Page 346 of 1199


TcxCustomTreeList.GotoPrevPage
TcxCustomTreeList

Scrolls focus one page up.

Syntax

procedure GotoPrevPage;

Description
The page, in this context, is the number of entirely visible nodes in the View.
To move focus to the next page, use the GotoNextPage method.

If you wish to move focus to the first or to the last node in the control, use the GotoBOF or the GotoEOF method.

Related Information

l Navigation and Scrolling


l TcxTreeListNode.GetNextVisible
l TcxTreeListNode.GetPrevVisible
l TcxTreeListNode.IsFirstVisible
l TcxTreeListNode.IsLastVisible
l TcxTreeListNode.IsVisible
l TcxTreeListNode.MakeVisible

Page 347 of 1199


TcxCustomTreeList.HideEdit
TcxCustomTreeList

Closes an in-place editor and saves changes made to the data cell's content.

Syntax

procedure HideEdit;

Description
To exit from in-place editing without saving, use the tree list's CancelEdit method instead.

If you first need to determine whether a tree list is in edit mode, use the tree list's IsEditing property.
In-place editing in the focused cell can be activated using the tree list's ShowEdit method.

Related Information

l TcxCustomTreeList.CancelEdit
l TcxCustomTreeList.FocusedColumn
l TcxCustomTreeList.InplaceEditor
l TcxCustomTreeList.IsActive
l TcxCustomTreeList.IsEditing
l TcxCustomTreeList.ShowEdit
l TcxCustomTreeList.ShowEditByKey
l TcxCustomTreeList.ShowEditByMouse

Page 348 of 1199


TcxCustomTreeList.HideFindPanel
TcxCustomTreeList

Hides the Find Panel.

Syntax

procedure HideFindPanel;

Description
Call the HideFindPanel or ShowFindPanel method to switch the panel visibility. End-users can switch the panel visibility only in
fpdmManual display mode. Handle the tree list's OnFindPanelVisibilityChanged event to track panel visibility changes.

Page 349 of 1199


TcxCustomTreeList.HitTest
TcxCustomTreeList

Returns the HitTest information about the tree list element located at a specific point.

Syntax

property HitTest: TcxTreeListHitTest;

Description
Refer to the TcxTreeListHitTest class description to learn about the available HitTest members.

ReadOnly Property

Page 350 of 1199


TcxCustomTreeList.Images
TcxCustomTreeList

Represents a collection of images used as an indication of focused nodes.

Syntax

property Images: TCustomImageList;

Description
Images for the corresponding select states are specified using the following properties:
l An image for the selected node – the node's SelectedIndex property.
l An image for the unselected node – the node's ImageIndex property.

Examples

l Example: OnGetNodeImageIndex

Related Information

l TcxCustomTreeList.OnGetNodeImageIndex
l TcxCustomTreeList.StateImages
l TcxTreeListNode.ImageIndex
l TcxTreeListNode.SelectedIndex
l TcxTreeListNode.StateIndex

Page 351 of 1199


TcxCustomTreeList.InplaceEditor
TcxCustomTreeList

Returns the active in-place editor.

Syntax

property InplaceEditor: TcxCustomEdit;

Description
The property returns nil if no in-place editor is currently activated (the IsEditing property returns False).

ReadOnly Property

Related Information

l TcxCustomTreeList.FocusedColumn
l TcxCustomTreeList.IsEditing

Page 352 of 1199


TcxCustomTreeList.IsActive
TcxCustomTreeList

Indicates whether the control has focus, or if an in-place editor is opened and focused.

Syntax

property IsActive: Boolean;

Description
The property returns True, if the tree list is focused or if an in-place editor is opened and focused.

ReadOnly Property

Related Information

l TcxCustomTreeList.FocusedColumn
l TcxCustomTreeList.FocusedNode

Page 353 of 1199


TcxCustomTreeList.IsBOF
TcxCustomTreeList

Checks whether the first node in the control is focused.

Syntax

function IsBOF: Boolean;

Description
To check whether the last node is focused, use the IsEOF method.

If the tree list is empty (no node exists), then both IsBOF and IsEOF methods return True.

Related Information

l Navigation and Scrolling


l TcxTreeListNode.GetNextVisible
l TcxTreeListNode.GetPrevVisible
l TcxTreeListNode.IsFirstVisible
l TcxTreeListNode.IsLastVisible
l TcxTreeListNode.IsVisible
l TcxTreeListNode.MakeVisible

Page 354 of 1199


TcxCustomTreeList.IsEditing
TcxCustomTreeList

Checks whether the tree list is in edit mode.

Syntax

property IsEditing: Boolean;

Description
The property returns True, if the tree list is in edit mode.

To exit from edit mode, use the node's EndEdit method. Edit mode is activated using the tree list's ShowEdit method.

ReadOnly Property

Related Information

l TcxCustomTreeList.FocusedColumn
l TcxCustomTreeList.InplaceEditor
l TcxCustomTreeList.ShowEdit
l TcxTreeListNode.EndEdit

Page 355 of 1199


TcxCustomTreeList.IsEOF
TcxCustomTreeList

Checks whether the last node in the control is focused.

Syntax

function IsEOF: Boolean;

Description
To check whether the last node is focused, use the IsBOF method.

If the tree list is empty (no node exists), then both IsBOF and IsEOF methods return True.

Related Information

l Navigation and Scrolling


l TcxTreeListNode.GetNextVisible
l TcxTreeListNode.GetPrevVisible
l TcxTreeListNode.IsFirstVisible
l TcxTreeListNode.IsLastVisible
l TcxTreeListNode.IsVisible
l TcxTreeListNode.MakeVisible

Page 356 of 1199


TcxCustomTreeList.IsFindPanelVisible
TcxCustomTreeList

Determines if the Find Panel is currently displayed.

Syntax

function IsFindPanelVisible: Boolean;

Description
This function returns True if the Find Panel is currently displayed onscreen; otherwise – False. Call the HideFindPanel or
ShowFindPanel method to switch the panel visibility. End-users can switch the panel visibility only in fpdmManual display
mode. Handle the tree list's OnFindPanelVisibilityChanged event to track panel visibility changes.

Page 357 of 1199


TcxCustomTreeList.Items
TcxCustomTreeList

Provides indexed access to the root-level nodes.

Syntax

property Items[Index: Integer]: TcxTreeListNode;

Description
Index specifies the node's position in the collection.
The total number of root-level nodes can be obtained using the Count property.

ReadOnly Property

Examples

l Example: TreeList.Items[], TreeList.Count, Node.AddChild, Node.AddChildFirst

Page 358 of 1199


TcxCustomTreeList.LastNode
TcxCustomTreeList

Returns the last node.

Syntax

property LastNode: TcxTreeListNode;

Description
The property ignores the node visibility (see the node's IsHidden property) when searching for the last node.
The first node can be obtained using the TopNode property.

ReadOnly Property

Related Information

l TcxCustomTreeList.LastVisibleNode
l TcxCustomTreeList.TopVisibleNode
l TcxTreeListNode.getFirstChild
l TcxTreeListNode.GetLastChild
l TcxTreeListNode.GetNext
l TcxTreeListNode.GetNextChild
l TcxTreeListNode.getNextSibling
l TcxTreeListNode.GetNextVisible
l TcxTreeListNode.GetPrev
l TcxTreeListNode.GetPrevChild
l TcxTreeListNode.getPrevSibling
l TcxTreeListNode.GetPrevVisible
l TcxTreeListNode.IsFirstVisible
l TcxTreeListNode.IsLastVisible
l TcxTreeListNode.MakeVisible
l TcxTreeListNode.VisibleIndex

Page 359 of 1199


TcxCustomTreeList.LastVisibleNode
TcxCustomTreeList

Specifies the lower node visible in the tree list's View.

Syntax

property LastVisibleNode: TcxTreeListNode;

Description
Assigning a node to this property scrolls the tree list's content to make this node visible at the tree list's bottom edge. Use the
LastNode property to access the last visible node without scrolling the content.

Related Information

l TcxCustomTreeList.TopVisibleNode
l TcxTreeListNode.MakeVisible

Page 360 of 1199


TcxCustomTreeList.MakeDefaultLayout
TcxCustomTreeList

Restores the control's default layout.

Syntax

procedure MakeDefaultLayout; virtual;

Description
The method removes bands from the control and creates a new band instead, placing all the columns in it. Then, the method
restores default column settings (see the column's RestoreDefaults property).

Related Information

l TcxCustomTreeList.DefaultLayout
l TcxCustomTreeList.RestoreColumnsDefaults

Page 361 of 1199


TcxCustomTreeList.OnAfterSummary
TcxCustomTreeList

Occurs after all summaries have been calculated.

Syntax

type
TNotifyEvent = procedure(Sender: TObject) of object;
property OnAfterSummary: TNotifyEvent;

Description
The OnAfterSummary event occurs after all summaries have been calculated. You can read and change an individual summary
value via the Summary property. Refer to the Creating Summaries help topic for details.
Sender specifies the tree list.

Related Information

l Creating Summaries
l Group Summaries
l TcxCustomTreeList.OnSummary
l TcxTreeListColumnSummary.FooterSummaryItems
l TcxTreeListColumnSummary.GroupFooterSummaryItems
l TcxTreeListSummary.FooterSummaryItems
l TcxTreeListSummary.GroupFooterSummaryItems

Page 362 of 1199


TcxCustomTreeList.OnBandHeaderClick
TcxCustomTreeList

Enables you to respond to band header clicks.

Syntax

type
TcxTreeListBandChangedEvent = procedure(Sender: TcxCustomTreeList; ABand: TcxTreeListBand)
property OnBandHeaderClick: TcxTreeListBandChangedEvent;

Description
Sender specifies the tree list.
ABand specifies the band whose header has been clicked.

Page 363 of 1199


TcxCustomTreeList.OnBandPosChanged
TcxCustomTreeList

Enables you to respond to end-user changes made to a band's visibility or position within the tree list.

Syntax

type
TcxTreeListBandChangedEvent = procedure(Sender: TcxCustomTreeList; ABand: TcxTreeListBand)
property OnColumnHeaderClick: TcxTreeListBandChangedEvent;

Description
Sender specifies the tree list.
ABand specifies the band whose visibility or position has been changed by an end-user.

Note:   The OnBandPosChanged is not fired for bands whose parent band has been hidden or made visible.

Page 364 of 1199


TcxCustomTreeList.OnBandSizeChanged
TcxCustomTreeList

Enables you to respond to band sizing.

Syntax

type
TcxTreeListBandChangedEvent = procedure(Sender: TcxCustomTreeList; ABand: TcxTreeListBand)
property OnBandSizeChanged: TcxTreeListBandChangedEvent;

Description
Fires after a band has been horizontally resized.

Sender specifies the tree list.


ABand specifies the band that has been resized.

Page 365 of 1199


TcxCustomTreeList.OnBeginDragNode
TcxCustomTreeList

Enables you to control node dragging.

Syntax

type
TcxTreeListNodeChangingEvent = procedure(Sender: TcxCustomTreeList; ANode: TcxTreeListNode
property OnBeginDragNode: TcxTreeListNodeChangingEvent;

Description
Fires when an end-user starts dragging a node within the tree list.

Sender specifies the tree list.


ANode specifies the node being dragged.
Allow specifies whether node dragging is allowed. Set Allow to True, to allow the drag action.

Concepts

l Implementing Drag-And-Drop Functionality

Page 366 of 1199


TcxCustomTreeList.OnCanFocusNode
TcxCustomTreeList

Enables you to control which nodes can be focused by end-users.

Syntax

type
TcxTreeListNodeChangingEvent = procedure(Sender: TcxCustomTreeList; ANode: TcxTreeListNode
property OnCanFocusNode: TcxTreeListNodeChangingEvent;

Description
Fires when a node is being focused.

Sender specifies the tree list.


ANode specifies the node being focused.
Allow specifies whether ANode can be focused. Set Allow to True, to allow focusing.

Related Information

l TcxCustomTreeList.FocusedNode
l TcxCustomTreeList.OnCanSelectNode
l TcxCustomTreeList.OnFocusedNodeChanged
l TcxCustomTreeList.OnSelectionChanged
l TcxCustomTreeList.Select

Page 367 of 1199


TcxCustomTreeList.OnCanSelectNode
TcxCustomTreeList

Enables you to control which nodes can be selected by end-users.

Syntax

type
TcxTreeListNodeChangingEvent = procedure(Sender: TcxCustomTreeList; ANode: TcxTreeListNode
property OnCanSelectNode: TcxTreeListNodeChangingEvent;

Description
Fires when a node is being selected, when the OnCanFocusNode's Allow parameter is True.

Sender specifies the tree list.


ANode specifies the node being selected.
Allow specifies whether ANode can be selected. Set Allow to True, to allow selection.

Related Information

l TcxCustomTreeList.FocusedNode
l TcxCustomTreeList.OnCanFocusNode
l TcxCustomTreeList.OnFocusedNodeChanged
l TcxCustomTreeList.OnSelectionChanged
l TcxCustomTreeList.Select

Page 368 of 1199


TcxCustomTreeList.OnChange
TcxCustomTreeList

Enables you to respond to changes made in a tree list.

Syntax

type
TNotifyEvent = procedure(Sender: TObject) of object;
property OnChange: TNotifyEvent;

Description
Fires every time, after a tree list has been updated (for instance, when cell selection changes occur within the focused row).
This event fires after an update, following the interval specified by the tree list's OptionsBehavior.ChangeDelay property.

Sender specifies the tree list.

Page 369 of 1199


TcxCustomTreeList.OnCollapsed
TcxCustomTreeList

Enables you to perform specific actions after a node has been collapsed.

Syntax

type
TcxTreeListNodeChangedEvent = procedure(Sender: TcxCustomTreeList; ANode: TcxTreeListNode)
property OnCollapsed: TcxTreeListNodeChangedEvent;

Description
Handle the OnCollapsing event if you want to manually specify which nodes can be collapsed.

Sender specifies the tree list.


ANode specifies the node that has been collapsed.

Page 370 of 1199


TcxCustomTreeList.OnCollapsing
TcxCustomTreeList

Enables you to specify whether a particular node can be collapsed.

Syntax

type
TcxTreeListNodeChangingEvent = procedure(Sender: TcxCustomTreeList; ANode: TcxTreeListNode
property OnCollapsing: TcxTreeListNodeChangingEvent;

Description
Fires when a node is being collapsed.

Sender specifies the tree list.


ANode specifies the node being collapsed.
Allow specifies whether ANode can be collapsed. Set Allow to False, to prevent the node from collapsing.

To provide actions after the node has been collapsed, handle the OnCollapsed event instead.

Page 371 of 1199


TcxCustomTreeList.OnColumnHeaderClick
TcxCustomTreeList

Enables you to respond to column header clicks.

Syntax

type
TcxTreeListColumnChangedEvent = procedure(Sender: TcxCustomTreeList; AColumn: TcxTreeListC
property OnColumnHeaderClick: TcxTreeListColumnChangedEvent;

Description
Since sorting is performed by end-users via header clicks, use this event to disable sorting in this manner.

Sender specifies the tree list.


AColumn specifies the column whose header has been clicked.

Page 372 of 1199


TcxCustomTreeList.OnColumnPosChanged
TcxCustomTreeList

Enables you to respond to end-user changes made to a column's visibility or position within the tree list.

Syntax

type
TcxTreeListColumnChangedEvent = procedure(Sender: TcxCustomTreeList; AColumn: TcxTreeListC
property OnColumnHeaderClick: TcxTreeListColumnChangedEvent;

Description
Sender specifies the tree list.
AColumn specifies the column whose visibility or position has been changed by an end-user.

Note:   The OnColumnPosChanged is not fired for columns whose parent band has been hidden or made visible.

Page 373 of 1199


TcxCustomTreeList.OnColumnSizeChanged
TcxCustomTreeList

Enables you to respond to column sizing.

Syntax

type
TcxTreeListColumnChangedEvent = procedure(Sender: TcxCustomTreeList; AColumn: TcxTreeListC
property OnColumnSizeChanged: TcxTreeListColumnChangedEvent;

Description
Sender specifies the tree list.
AColumn specifies the column that has been resized.

Page 374 of 1199


TcxCustomTreeList.OnCompare
TcxCustomTreeList

Occurs when sorting records within the TreeList control.

Syntax

type
TcxTreeListNodeCompareEvent = procedure(Sender: TcxCustomTreeList; ANode1, ANode2: TcxTree
property OnCompare: TcxTreeListNodeCompareEvent;

Description
The OnCompare event occurs when sorting node values.
The ANode1 and ANode2 parameters identify the nodes that must be compared.
The ACompare parameter represents the comparison result that must be defined by a developer. A negative value assigned to the para
ANode2. And vice versa, if the ACompare parameter is set to a positive value, ANode1 is considered to be "greater" than ANode2. Two
parameter is set to 0.
By default, the ACompare parameter is set to 1, thus indicating that ANode1 is "greater" than ANode2.

Use the OnCompare event when you want to change the default comparison rules. For instance, you can group records with Null valu
other rows according to their values (the same year and month) and so on.
Note:   If your OnCompare event handler implementation is not thread-safe, we recommend that you disable the use of multi-threaded
OptionsData.MultiThreadedSorting property.

The following example demonstrates how to sort nodes by the selected column:

[Delphi]
//...
procedure <Form>.<TreeList>Compare(Sender: TcxCustomTreeList; ANode1,
ANode2: TcxTreeListNode; var ACompare: Integer);
var
val_ind : Integer;
begin
val_ind := TreeList.FocusedColumn.ItemIndex;
ACompare := ANode2.Values[val_ind] - ANode1.Values[val_ind];
end;

Page 375 of 1199


TcxCustomTreeList.OnCustomDrawBackgroundCell
TcxCustomTreeList

Enables you to custom paint the tree list background.

Syntax

type
TcxTreeListCustomDrawBackgroundCellEvent = procedure(Sender: TcxCustomTreeList; ACanvas: T
property OnCustomDrawBackgroundCell: TcxTreeListCustomDrawBackgroundCellEvent;

Description
Sender specifies the tree list.
ACanvas specifies the drawing surface.
AViewInfo provides the ViewInfo information used to paint the tree list background.
ADone specifies whether default painting is required. Set ADone to True, to prevent default code execution.

To learn how to handle this event, refer to the How To Custom Paint the Tree List Background help topic.

Related Information

l Custom Draw

Page 376 of 1199


TcxCustomTreeList.OnCustomDrawBandCell
TcxCustomTreeList

Enables you to custom paint band backgrounds.

Syntax

type
TcxTreeListCustomDrawBandCellEvent = procedure(Sender: TcxCustomTreeList; ACanvas: TcxCanv
property OnCustomDrawBandCell: TcxTreeListCustomDrawBandCellEvent;

Description
Sender specifies the tree list.
ACanvas specifies the drawing surface.
AViewInfo provides the ViewInfo information used to paint the band background.
ADone specifies whether default painting is required. Set ADone to True, to prevent default code execution.

To learn how to handle this event, refer to the How To Custom Paint Band Backgrounds help topic.

Related Information

l Custom Draw

Page 377 of 1199


TcxCustomTreeList.OnCustomDrawBandHeaderCell
TcxCustomTreeList

Enables you to custom paint band headers.

Syntax

type
TcxTreeListCustomDrawHeaderCellEvent = procedure(Sender: TcxCustomTreeList; ACanvas: TcxCa
property OnCustomDrawBandHeaderCell: TcxTreeListCustomDrawHeaderCellEvent;

Description
Sender specifies the tree list.
ACanvas specifies the drawing surface.
AViewInfo provides the ViewInfo information used to paint the band header.
ADone specifies whether default painting is required. Set ADone to True, to prevent default code execution.

To learn how to handle this event, refer to the How To Custom Paint Band Headers help topic.

Related Information

l Custom Draw

Page 378 of 1199


TcxCustomTreeList.OnCustomDrawDataCell
TcxCustomTreeList

Enables you to custom paint data cells.

Syntax

type
TcxTreeListCustomDrawEditCellEvent = procedure(Sender: TcxCustomTreeList; ACanvas: TcxCanv
property OnCustomDrawEditCell: TcxTreeListCustomDrawEditCellEvent;

Description
Sender specifies the tree list.
ACanvas specifies the drawing surface.
AViewInfo provides the ViewInfo information used to paint the data cell.
ADone specifies whether default painting is required. Set ADone to True, to prevent default code execution.

To learn how to handle this event, refer to the How To Custom Paint Data Cells help topic.

Related Information

l Custom Draw

Page 379 of 1199


TcxCustomTreeList.OnCustomDrawFooterCell
TcxCustomTreeList

Enables you to custom paint footer cells.

Syntax

type
TcxTreeListCustomDrawFooterCellEvent = procedure(Sender: TcxCustomTreeList; ACanvas: TcxCa
property OnCustomDrawFooterCell: TcxTreeListCustomDrawFooterCellEvent;

Description
Sender specifies the tree list.
ACanvas specifies the drawing surface.
AViewInfo provides the ViewInfo information used to paint the footer cell.
ADone specifies whether default painting is required. Set ADone to True, to prevent default code execution.

To learn how to handle this event, refer to the How To Custom Paint Footer Cells help topic.

Related Information

l Custom Draw

Page 380 of 1199


TcxCustomTreeList.OnCustomDrawHeaderCell
TcxCustomTreeList

Enables you to custom paint column headers.

Syntax

type
TcxTreeListCustomDrawHeaderCellEvent = procedure(Sender: TcxCustomTreeList; ACanvas: TcxCa
property OnCustomDrawHeaderCell: TcxTreeListCustomDrawHeaderCellEvent;

Description
Sender specifies the tree list.
ACanvas specifies the drawing surface.
AViewInfo provides the ViewInfo information used to paint the column header.
ADone specifies whether default painting is required. Set ADone to True, to prevent default code execution.

To learn how to handle this event, refer to the How To Custom Paint Column Headers help topic.

Related Information

l Custom Draw

Page 381 of 1199


TcxCustomTreeList.OnCustomDrawIndentCell
TcxCustomTreeList

Enables you to custom paint indent cells.

Syntax

type
TcxTreeListCustomDrawIndentCellEvent = procedure(Sender: TcxCustomTreeList; ACanvas: TcxCa
property OnCustomDrawIndentCell: TcxTreeListCustomDrawIndentCellEvent;

Description
Sender specifies the tree list.
ACanvas specifies the drawing surface.
AViewInfo provides the ViewInfo information used to paint the indent cell.
ADone specifies whether default painting is required. Set ADone to True, to prevent default code execution.

To learn how to handle this event, refer to the How To Custom Paint Indent Cells help topic.

Related Information

l Custom Draw

Page 382 of 1199


TcxCustomTreeList.OnCustomDrawIndicatorCell
TcxCustomTreeList

Enables you to custom paint node indicators.

Syntax

type
TcxTreeListCustomDrawIndicatorCellEvent = procedure(Sender: TcxCustomTreeList; ACanvas: Tc
property OnCustomDrawIndicatorCell: TcxTreeListCustomDrawIndicatorCellEvent;

Description
Sender specifies the tree list.
ACanvas specifies the drawing surface.
AViewInfo provides the ViewInfo information used to paint the node indicator.
ADone specifies whether default painting is required. Set ADone to True, to prevent default code execution.

To learn how to handle this event, refer to the How To Custom Paint Node Indicators help topic.

Related Information

l Custom Draw

Page 383 of 1199


TcxCustomTreeList.OnCustomDrawPreviewCell
TcxCustomTreeList

Enables you to custom paint preview sections.

Syntax

type
TcxTreeListCustomDrawEditCellEvent = procedure(Sender: TcxCustomTreeList; ACanvas: TcxCanv
property OnCustomDrawPreviewCell: TcxTreeListCustomDrawEditCellEvent;

Description
Sender specifies the tree list.
ACanvas specifies the drawing surface.
AViewInfo provides the ViewInfo information used to paint the preview section.
ADone specifies whether default painting is required. Set ADone to True, to prevent default code execution.

To learn how to handle this event, refer to the How To Custom Paint Previews help topic.

Related Information

l Custom Draw

Page 384 of 1199


TcxCustomTreeList.OnCustomizationVisibleChanged
TcxCustomTreeList

Enables you to perform specific actions after a Customize window's visibility has been changed.

Syntax

type
TNotifyEvent = procedure(Sender: TObject) of object;
property OnCustomizationVisibleChanged: TNotifyEvent;

Description
Sender specifies the tree list.

Handle this event if you need to update external controls that are involved in operations related to the Customize window, or
update output text in the control when the Customize window is displayed.

Page 385 of 1199


TcxCustomTreeList.OnDataChanged
TcxCustomTreeList

Enables you to perform specific actions after the data has been posted to a data store.

Syntax

type
TNotifyEvent = procedure(Sender: TObject) of object;
property OnDataChanged: TNotifyEvent;

Description
Sender specifies the tree list.

Page 386 of 1199


TcxCustomTreeList.OnDeletion
TcxCustomTreeList

Enables you to perform specific actions when a node is being deleted.

Syntax

type
TcxTreeListNodeChangedEvent = procedure(Sender: TcxCustomTreeList; ANode: TcxTreeListNode)
property OnDeletion: TcxTreeListNodeChangedEvent;

Description
Sender specifies the tree list.
ANode specifies the node being deleted.

The tree list allows you to specify additional data for each node (using the node's Data property). If this data is specified, it must be rel
before a node is deleted. For this purpose, handle the OnDeletion event.

The following example shows how to handle the OnDeletion event to deallocate the node's data object before the node is completely d
// Delphi
// ...

procedure <TForm>.<cxTreeList>Deletion(Sender: TcxCustomTreeList; ANode: TcxTreeListNode);

var

P: Pointer;

begin

P := ANode.Data;
if P <> nil then
Dispose(P);
end;

Related Information

l TcxTreeListNode.Delete
l TcxTreeListNode.DeleteChildren
l TcxTreeListNode.Deleting
l TcxTreeListOptionsData.Deleting

Page 387 of 1199


TcxCustomTreeList.OnEdited
TcxCustomTreeList

Enables you to perform specific actions after the data cell's in-place editor has been deactivated.

Syntax

type
TcxTreeListColumnChangedEvent = procedure(Sender: TcxCustomTreeList; AColumn: TcxTreeListC
property OnEdited: TcxTreeListColumnChangedEvent;

Description
Sender specifies the tree list.
AColumn specifies the column whose data cell has been edited.

Related Information

l TcxCustomTreeList.OnEditing

Page 388 of 1199


TcxCustomTreeList.OnEditing
TcxCustomTreeList

Enables you to specify whether editing is allowed in a particular data cell.

Syntax

type
TcxTreeListEditingEvent = procedure(Sender: TcxCustomTreeList; AColumn: TcxTreeListColumn;
property OnEditing: TcxTreeListEditingEvent;

Description
Sender specifies the tree list.
AColumn specifies the column whose data cell has been edited.
Allow specifies whether in-place editing is allowed. Pass True as Allow to allow in-place editing.

Related Information

l TcxCustomTreeList.OnEdited
l TcxTreeListColumn.OnGetEditingProperties

Page 389 of 1199


TcxCustomTreeList.OnEditValueChanged
TcxCustomTreeList

Enables you to perform specific actions after editing a data cell's value is complete.

Syntax

type
TcxTreeListColumnChangedEvent = procedure(Sender: TcxCustomTreeList; AColumn: TcxTreeListC
property OnEditValueChanged: TcxTreeListColumnChangedEvent;

Description
Sender specifies the tree list.
AColumn specifies the column whose data cell has been edited.

Page 390 of 1199


TcxCustomTreeList.OnExpanded
TcxCustomTreeList

Enables you to perform specific actions after a node has been expanded.

Syntax

type
TcxTreeListNodeChangedEvent = procedure(Sender: TcxCustomTreeList; ANode: TcxTreeListNode)
property OnExpanded: TcxTreeListNodeChangedEvent;

Description
Sender specifies the tree list.
ANode specifies the node that has been expanded.

Handle the OnExpanding event to prohibit expansion for particular nodes.

Page 391 of 1199


TcxCustomTreeList.OnExpanding
TcxCustomTreeList

Allows implementing dynamic node loading or prohibiting expansion for individual nodes.

Syntax

type
TcxTreeListNodeChangingEvent = procedure(Sender: TcxCustomTreeList; ANode: TcxTreeListNode
property OnExpanding: TcxTreeListNodeChangingEvent;

Description
Sender specifies the tree list.
ANode specifies the node being expanded.
Allow specifies whether node expansion is allowed. Pass True as Allow to allow expansion.

The OnExpanding event can be used for Dynamic Loading.


To provide actions after the node has been expanded, handle the OnExpanded event instead.

Page 392 of 1199


TcxCustomTreeList.OnFilterControlDialogShow
TcxCustomTreeList

Enables you to customize the Filter Builder dialog before showing it.

Syntax

type
TNotifyEvent = procedure(Sender: TObject) of object;
property OnFilterControlDialogShow: TNotifyEvent;

Description
The Filter Builder dialog allows end-users to build complex filter criteria with an unlimited number of filter conditions combined by logica
users can invoke this dialog by clicking the Filter button in the tree list's navigator.

The Sender parameter specifies the dialog's form. Cast an object passed as this parameter to TfmFilterControlDialog defined in the cxF
unit to access the settings of the form and its controls. For example, you can use the Sender.FilterControl property to access the filter
provides filter criteria customization.

The code example below shows how to handle the OnFilterControlDialogShow event to hide the dialog's Open and Save As… butto
dialog's caption, and hide the filter control's tree lines.

[Delphi]
uses
..., cxFilterControlDialog;
// ...
procedure <Form>.<TreeList>FilterControlDialogShow(Sender: TObject);
var
frm: TfmFilterControlDialog;
begin
frm := Sender as TfmFilterControlDialog;
frm.Caption := 'Filter Builder';
frm.btOpen.Visible := False;
frm.btSave.Visible := False; Page 393 of 1199
frm.FilterControl.ShowLevelLines := False;
TfmFilterControlDialog* frm = (TfmFilterControlDialog*)Sender;
frm->Caption := 'Filter Builder';
frm->btOpen->Visible := false;
frm->btSave->Visible := false;
frm->FilterControl->ShowLevelLines := false;
}

Page 394 of 1199


TcxCustomTreeList.OnFilterNode
TcxCustomTreeList

Enables you to filter out specific nodes.

Syntax

type
TcxTreeListFilterNodeEvent = procedure(Sender: TcxCustomTreeList; ANode: TcxTreeListNode;
property OnFilterNode: TcxTreeListFilterNodeEvent;

Description
This event fires after applying the filter criteria specified via the Filter property and allows you to further filter nodes.
Sender specifies the tree list.
ANode specifies the node being processed.
Pass False as the Accept parameter to filter out the node and hide it in the tree list. Otherwise, the node and all its parent nodes are c
essence, the tree list displays a node if any of its children meet the filter criteria, even if the node does not.

Note:   This event fires for all nodes matching the filter criteria provided by the Filter property, including those hidden either via their Vis

Related Information

l TcxTreeListNode.IsHidden

Page 395 of 1199


TcxCustomTreeList.OnFocusedColumnChanged
TcxCustomTreeList

Enables you to perform specific actions after an active column has been changed.

Syntax

type
TcxTreeListFocusedColumnChanged = procedure(Sender: TcxCustomTreeList; APrevFocusedColumn,
property OnFocusedColumnChanged: TcxTreeListFocusedColumnChanged;

Description
Sender specifies the tree list.
APrevFocusedColumn specifies the column that has lost focus. APrevFocusedColumn returns nil if there was no focused column befo
AFocusedColumn specifies the column that has been focused.

Page 396 of 1199


TcxCustomTreeList.OnFocusedNodeChanged
TcxCustomTreeList

Enables you to respond to node focusing.

Syntax

type
TcxTreeListFocusedNodeChangedEvent = procedure(Sender: TcxCustomTreeList; APrevFocusedNode
property OnFocusedNodeChanged: TcxTreeListFocusedNodeChangedEvent;

Description
Sender specifies the tree list.
APrevFocusedNode specifies the node that has lost focus. APrevFocusedNode returns nil if there was no focused node before AFocu
AFocusedNode specifies the node that has been focused.

Page 397 of 1199


TcxCustomTreeList.OnGetCellHint
TcxCustomTreeList

Enables you to customize a View element's hint.

Syntax

type
TcxTreeListGetCellHintEvent = procedure(Sender: TcxCustomTreeList; ACell: TObject; var ATe
property OnGetCellHint: TcxTreeListGetCellHintEvent;

Description
Sender specifies the tree list.
ACell provides ViewInfo about a tree list element whose hint is about to be shown. The following table summarizes available view eleme
the ACell parameter to the appropriate class to use its members.

View Element Associated Class

Data Cell TcxTreeListEditCellViewInfo

Footer or Group Footer TcxTreeListFooterCellViewInfo

Band Header or Column Header TcxTreeListHeaderCellViewInfo

AText specifies the text to be rendered in the hint window.


ANeedShow specifies whether the hint will be displayed. By default, ANeedShow is set to False, indicating the element's content is no
ANeedShow to True to display the hint.

Note:   The OnGetCellHint event fires before a hint is shown for a tree list element located under the mouse pointer. To enable hints w
HeaderHints options within the OptionsBehavior option set.

Page 398 of 1199


TcxCustomTreeList.OnGetDragDropText
TcxCustomTreeList

Enables you to customize the drag and drop hint's text.

Syntax

type
TcxTreeListGetDragDropTextEvent = procedure(Sender: TcxCustomTreeList; ANode: TcxTreeListN
property OnGetDragDropText: TcxTreeListGetDragDropTextEvent;

Description
If the tree list's OptionsBehavior.DragDropText option is active, the drag and drop hint window is displayed while a node is being dragge
OnDragOver event is handled). This window contains the string representation of the node's leftmost visible data cell value. If multiple n
focused node's value.

Sender specifies the tree list.


ANode specifies the dragged node. If multiple nodes are dragged, ANode specifies the focused node.
Use AText to customize the hint text.

Note:   In addition to hints, you can display specially designed drop indicators to assist end-users during drag-and-drop operations. To
OptionsView.DropNodeIndicator property to True.

Concepts

l Implementing Drag-And-Drop Functionality

Related Information

l Reordering Nodes

Page 399 of 1199


TcxCustomTreeList.OnGetLevelImages
TcxCustomTreeList

Enables you to associate certain node image collections with the corresponding node levels.

Syntax

type
TcxTreeListGetLevelImagesEvent = procedure(Sender: TcxCustomTreeList; ALevel: Integer; var
property OnGetLevelImages: TcxTreeListGetLevelImagesEvent;

Description
Default collections of appropriate node images for all nodes are specified using the tree list's Images and StateImages properties. The
are about to be assigned for a node level. You can handle this event to display nodes with different image sizes.

Sender specifies the tree list.


ALevel specifies the node level.
AImages specifies the collection of node images.
AStateImages specifies the collection of node state images.

Related Information

l TcxCustomTreeList.OnGetNodeImageIndex
l TcxTreeListNode.SelectedIndex

Page 400 of 1199


TcxCustomTreeList.OnGetNodeHeight
TcxCustomTreeList

Enables you to specify the custom height for individual nodes.

Syntax

type
TcxTreeListGetNodeHeightEvent = procedure(Sender: TcxCustomTreeList; ANode: TcxTreeListNod
property OnGetNodeHeight: TcxTreeListGetNodeHeightEvent;

Description
This event is raised for every node to determine its height.

Sender specifies the tree list.


ANode specifies the node whose height is being obtained.
AHeight specifies the node's height. If AHeight is set to 0, the node is not displayed. A tree list doesn't provide any constraints on the

Page 401 of 1199


TcxCustomTreeList.OnGetNodeImageIndex
TcxCustomTreeList

Enables you to specify custom images for nodes.

Syntax

type
{$IFDEF DELPHI17}
TcxImageIndex = System.UITypes.TImageIndex;
{$ELSE}
TcxImageIndex = ImgList.TImageIndex;
{$ENDIF}
TcxTreeListGetNodeImageIndexEvent = procedure(Sender: TcxCustomTreeList; ANode: TcxTreeLis
property OnGetNodeImageIndex: TcxTreeListGetNodeImageIndexEvent;

Description
Sender specifies the tree list.
ANode specifies the node whose images are to be painted.
AIndexType specifies the image type.
AIndex specifies the image index in the node image collection.

Examples

l Example: OnGetNodeImageIndex

Related Information

l TcxCustomTreeList.Images
l TcxCustomTreeList.OnGetLevelImages
l TcxCustomTreeList.StateImages
l TcxTreeListNode.ImageIndex
l TcxTreeListNode.SelectedIndex
l TcxTreeListNode.StateIndex

Page 402 of 1199


TcxCustomTreeList.OnGetNodePreviewHeight
TcxCustomTreeList

Enables you to specify the custom height for individual preview sections.

Syntax

type
TcxTreeListGetNodePreviewHeightEvent = procedure(Sender: TcxCustomTreeList; ANode: TcxTree
property OnGetNodePreviewHeight: TcxTreeListGetNodePreviewHeightEvent;

Description
Sender specifies the tree list.
ANode specifies the node whose preview's height is being calculated.
ADisplayValue returns the value displayed in the preview.
AHeight specifies the preview's height.

Page 403 of 1199


TcxCustomTreeList.OnGetStoredProperties
TcxCustomTreeList

Enables you to customize a list of the tree list's properties to be stored to external data stores.

Syntax

type
TcxGetStoredPropertiesEvent = procedure(Sender: TObject; AProperties: TStrings) of object;
property OnGetStoredProperties: TcxGetStoredPropertiesEvent;

Description
Whenever the storing process is started by the StoreToIniFile, StoreToRegistry, or StoreToStream method call, a list of the properties
to store is produced. By default, the list is empty. You can add custom property names to this list and handle the
OnGetStoredPropertyValue and OnSetStoredPropertyValue events to provide property values to be saved to and restored from a data
store. Make certain that items in the list uniquely identify the property names they correspond to.
The Sender parameter specifies the TreeList control whose properties are to be stored.
The AProperties parameter provides access to the list of properties to be stored.

The following code represents an OnGetStoredProperties event handler, demonstrating how to extend the list with items that
correspond to the tree list's OptionsView.Footer and OptionsView.GroupFooters properties.

[Delphi]
procedure <Form>.<TreeList>GetStoredProperties(Sender: TObject; AProperties: TStrings);
begin
AProperties.Add('OptionsView_Footer');
AProperties.Add('OptionsView_GroupFooters');
end;

[C++ Builder]
void __fastcall <Form>::<TreeList>GetStoredProperties(TObject *Sender, TStrings *AProperties)
{
AProperties->Add("OptionsView_Footer");
AProperties->Add("OptionsView_GroupFooters");
}

Note:   To customize the manner in which band properties are persisted, handle a band's OnGetStoredProperties,
OnGetStoredPropertyValue, and OnSetStoredPropertyValue events. To customize the manner in which column properties are
persisted, handle a column's OnGetStoredProperties, OnGetStoredPropertyValue, and OnSetStoredPropertyValue events.

Concepts

l Save and Restore Layout

Related Information

l TcxTreeListBand.OnGetStoredProperties
l TcxTreeListColumn.OnGetStoredProperties

Page 404 of 1199


TcxCustomTreeList.OnGetStoredPropertyValue
TcxCustomTreeList

Enables you to provide values for tree list properties to be saved to external data stores.

Syntax

type
TcxGetStoredPropertyValueEvent = procedure(Sender: TObject; const AName: string; var AValu
property OnGetStoredPropertyValue: TcxGetStoredPropertyValueEvent;

Description
This event is fired for each property within the list specified in the OnGetStoredProperties event handler. To restore tree list properties,
OnSetStoredPropertyValue event.
The Sender parameter specifies the TreeList control whose properties are stored.
The AName parameter identifies the property name.
Pass the property value as the AValue parameter.

The following code represents an OnGetStoredPropertyValue event handler, demonstrating how to save the values of the tree list's O
OptionsView.GroupFooters properties previously specified for storage within the tree list's OnGetStoredProperties event handler.

[Delphi]
procedure <Form>.<TreeList>GetStoredPropertyValue(Sender: TObject; const AName: String; var AVal
begin
if Sender is TcxCustomTreeList then
begin
if AName = 'OptionsView_Footer' then
begin
AValue := TcxCustomTreeList(Sender).OptionsView.Footer;
Exit;
end;
if AName = 'OptionsView_GroupFooters' then
begin
AValue := TcxCustomTreeList(Sender).OptionsView.GroupFooters;
Exit;
end;
end;
end;

[C++ Builder]
void __fastcall <Form>::<TreeList>GetStoredPropertyValue(TObject *Sender, const AnsiString AName
{
if(AName == "OptionsView_Footer") {
if(dynamic_cast<TcxCustomTreeList*>(Sender)) {
AValue = TcxCustomTreeList(Sender).OptionsView->Footer;
return;
}
}
if(AName == "OptionsView_GroupFooters") {
Page 405 of 1199
if(dynamic_cast<TcxCustomTreeList*>(Sender)) {
l TcxTreeListColumn.OnGetStoredPropertyValue

Page 406 of 1199


TcxCustomTreeList.OnHotTrackNode
TcxCustomTreeList

Enables you to respond to node hot-tracking.

Syntax

type
TcxTreeListOnHotTrackNodeEvent = procedure(Sender: TcxCustomTreeList; ANode: TcxTreeListNo
property OnHotTrackNode: TcxTreeListOnHotTrackNodeEvent;

Description
Sender specifies the tree list.
ANode specifies the node being hot-tracked.
AShift specifies the keyboard's shift state.
ACursor specifies the mouse pointer.

Examples

l Example: OnHotTrackNode

Page 407 of 1199


TcxCustomTreeList.OnInitStoredObject
TcxCustomTreeList

Enables you to initialize columns that are created when restoring the tree list's layout from external data stores.

Syntax

type
TcxInitStoredObjectEvent = procedure(Sender, AObject: TObject) of object;
property OnInitStoredObject: TcxInitStoredObjectEvent;

Description
When the tree list's layout is restored from a data store by calling the RestoreFromIniFile, RestoreFromRegistry, or
RestoreFromStream method, and a data store column is missing in the TreeList control, this column is automatically created in
the tree list, provided that the method is called with True passed as the AChildrenCreating parameter. After it's been created, the
OnInitStoredObject event is fired. You can handle this event to properly initialize the object which corresponds to the created
column. Initialization includes re-associating column events with existing event handlers and assigning column properties.

The TreeList control being restored from a data store and the column that has been created are passed as the Sender and
AObject parameters of the OnInitStoredObject event, respectively.

The following code represents the OnInitStoredObject event handler, demonstrating how to re-associate the events of all the
columns (no specific identification is made) whose property storing and restoring is customized by handling a column's
OnGetStoredProperties, OnGetStoredPropertyValue and OnSetStoredPropertyValue events with existing event handlers (the
ColumnGetStoredProperties, ColumnGetStoredPropertyValue and ColumnSetStoredPropertyValue procedures, respectively).

[Delphi]
procedure <Form>.<TreeList>InitStoredObject(Sender, AObject: TObject);
begin
if AObject is TcxTreeListColumn then
with TcxTreeListColumn(AObject) do
begin
OnGetStoredProperties := ColumnGetStoredProperties;
OnGetStoredPropertyValue := ColumnGetStoredPropertyValue;
OnSetStoredPropertyValue := ColumnSetStoredPropertyValue;
end;
end;

[C++ Builder]
void __fastcall <Form>::<TreeList>InitStoredObject(TObject *Sender, TObject *AObject)
{
if(dynamic_cast<TcxTreeListColumn*>(AObject)) {
TcxTreeListColumn* AColumn = dynamic_cast<TcxTreeListColumn*>(AObject);
AColumn->OnGetStoredProperties = ColumnGetStoredProperties;
AColumn->OnGetStoredPropertyValue = ColumnGetStoredPropertyValue;
AColumn->OnSetStoredPropertyValue = ColumnSetStoredPropertyValue;
}
}

Page 408 of 1199


Concepts

l Save and Restore Layout

Page 409 of 1199


TcxCustomTreeList.OnIsGroupNode
TcxCustomTreeList

Enables you to specify group nodes.

Syntax

type
TcxTreeListIsGroupNodeEvent = procedure(Sender: TcxCustomTreeList; ANode: TcxTreeListNode;
property OnIsGroupNode: TcxTreeListIsGroupNodeEvent;

Description
The OnIsGroupNode event fires if the tree list's OptionsView.PaintStyle property value is tlpsCategorized.

Sender specifies the tree list.


ANode specifies the node being processed.
IsGroup specifies whether the node is a group node. Set IsGroup to True, to make the node a group node.

Examples

l Example: OnIsGroupNode

Related Information

l TcxTreeListNode.IsGroupNode
l TcxTreeListOptionsView.CategorizedColumn
l TcxTreeListOptionsView.PaintStyle

Page 410 of 1199


TcxCustomTreeList.OnLayoutChanged
TcxCustomTreeList

Enables you to respond to tree list updates.

Syntax

type
TNotifyEvent = procedure(Sender: TObject) of object;
property OnLayoutChanged: TNotifyEvent;

Description
Fires after a tree list layout has been changed (for example, the event is generated in response to node focusing, or column
rearrangement).

Sender specifies the tree list.

Related Information

l TcxDBTreeList Object
l TcxTreeList Object
l TcxVirtualTreeList Object

Page 411 of 1199


TcxCustomTreeList.OnLeftPosChanged
TcxCustomTreeList

Enables you to respond when the current tree list is horizontally scrolled, either by keyboard navigation or by moving the horizontal
scroll bar.

Syntax

type
TNotifyEvent = procedure(Sender: TObject) of object;
property OnLeftPosChanged: TNotifyEvent;

Description
Sender specifies the tree list.
You can handle this event to synchronize horizontal scrolling within the tree list and other controls. The following code snippet
demonstrates how this can be accomplished for the tree list and the ExpressQuantumGrid's Table View.

[Delphi]
type
TcxCustomTreeListAccess = class(TcxCustomTreeList);
procedure <Form>.<TreeList>LeftPosChanged(Sender: TObject);
begin
// Synchronize the left visible position of the controls
<GridTableView>.Controller.LeftPos := TcxCustomTreeListAccess(<TreeList>).Controller.LeftPos;
end;

Page 412 of 1199


TcxCustomTreeList.OnMoveTo
TcxCustomTreeList

Enables you to respond to node dragging within the tree list.

Syntax

type
TcxTreeListMoveToEvent = procedure(Sender: TcxCustomTreeList; AttachNode: TcxTreeListNode;
property OnMoveTo: TcxTreeListMoveToEvent;

Description
Sender specifies the tree list.
AttachNode specifies the target node.
AttachMode specifies the type of a relationship between AttachNode and Nodes.
Nodes contains dragged nodes.
IsCopy specifies whether dragged nodes will be copied or moved to the target location. Set IsCopy to True, to create clones in the new
Done specifies whether default processing is required. Set Done to True, to prevent default code execution.

Page 413 of 1199


TcxCustomTreeList.OnNodeChanged
TcxCustomTreeList

Enables you to respond to changes made to a node.

Syntax

type
TcxTreeListNodeDataChangedEvent = procedure(Sender: TcxCustomTreeList; ANode: TcxTreeListN
property OnNodeChanged: TcxTreeListNodeDataChangedEvent;

Description
Fires after the data has been changed in a node's data cell, when in provider or unbound mode.

Sender specifies the tree list.


ANode specifies the node whose data cell has been changed.
AColumn specifies the column whose data cell has been changed.

Page 414 of 1199


TcxCustomTreeList.OnNodeCheckChanged
TcxCustomTreeList

Enables you to respond to changes made to the node check box's state.

Syntax

type
TcxTreeListNodeCheckChangedEvent = procedure(Sender: TcxCustomTreeList; ANode: TcxTreeList
property OnNodeCheckChanged: TcxTreeListNodeCheckChangedEvent;

Description
Fires when the check box's state has been changed by an end-user or programmatically (see the node's CheckClick method, Checked

Sender specifies the tree list.


ANode specifies the node whose check box has been checked.
AState specifies the check box's state.

Related Information

l TcxTreeListNode.CheckGroupType
l TcxTreeListOptionsView.CheckGroups

Page 415 of 1199


TcxCustomTreeList.OnSelectionChanged
TcxCustomTreeList

Enables you to respond to node selections.

Syntax

type
TNotifyEvent = procedure(Sender: TObject) of object;
property OnSelectionChanged: TNotifyEvent;

Description
To obtain the number of selected nodes, use the SelectionCount property.
For indexed access to selected nodes, use the Selections property.

Sender specifies the tree list.

Related Information

l TcxCustomTreeList.ClearSelection
l TcxCustomTreeList.Deselect
l TcxCustomTreeList.Select
l TcxCustomTreeList.SelectAll
l TcxCustomTreeList.SelectionCount
l TcxCustomTreeList.Selections
l TcxTreeListNode.Selected
l TcxTreeListOptionsSelection.MultiSelect

Page 416 of 1199


TcxCustomTreeList.OnSetStoredPropertyValue
TcxCustomTreeList

Enables you to restore tree list property values from external data stores.

Syntax

type
TcxSetStoredPropertyValueEvent = procedure(Sender: TObject; const AName: string; const AVa
property OnSetStoredPropertyValue: TcxSetStoredPropertyValueEvent;

Description
This event is fired for each property within the list specified in the OnGetStoredProperties event handler. Handle the OnSetStoredProp
custom property values that were explicitly specified via the OnGetStoredPropertyValue event handler.
The Sender parameter specifies the tree list whose properties are restored.
The AName parameter identifies the property name. Its value is returned by the AValue parameter. Use this value to assign a correspo

The following code represents an OnSetStoredPropertyValue event handler, demonstrating how to restore the tree list's OptionsView
OptionsView.GroupFooters property values previously saved within the tree list's OnGetStoredPropertyValue event handler.

[Delphi]
procedure <Form>.<TreeList>SetStoredPropertyValue(Sender: TObject; const AName: String; const AV
begin
if Sender is TcxCustomTreeList then
begin
if AName = 'OptionsView_Footer' then
begin
TcxCustomTreeList(Sender).OptionsView.Footer := AValue;
Exit;
end;
if AName = 'OptionsView_GroupFooters' then
begin
TcxCustomTreeList(Sender).OptionsView.GroupFooters := AValue;
Exit;
end;
end;
end;

[C++ Builder]
void __fastcall <Form>::<TreeList>SetStoredPropertyValue(TObject *Sender, const AnsiString AName
{
if(AName == "OptionsView_Footer") {
if(dynamic_cast<TcxCustomTreeList*>(Sender)) {
TcxCustomTreeList(Sender).OptionsView->Footer = AValue;
return;
}
}
if(AName == "OptionsView_GroupFooters") {
if(dynamic_cast<TcxCustomTreeList*>(Sender)) {
Page 417 of 1199
TcxCustomTreeList(Sender).OptionsView->GroupFooters = AValue;
TcxCustomTreeList.OnSorted
TcxCustomTreeList

Enables you to perform specific actions after node sorting is complete.

Syntax

type
TNotifyEvent = procedure(Sender: TObject) of object;
property OnSorted: TNotifyEvent;

Description
Sender specifies the tree list.

Related Information

l TcxCustomTreeList.OnSorting
l TcxTreeListNode.AlphaSort
l TcxTreeListNode.Focused
l TcxTreeListNode.MakeVisible

Page 418 of 1199


TcxCustomTreeList.OnSorting
TcxCustomTreeList

Enables you to perform specific actions when sorting nodes.

Syntax

type
TNotifyEvent = procedure(Sender: TObject) of object;
property OnSorting: TNotifyEvent;

Description
Sender specifies the tree list.

Related Information

l TcxCustomTreeList.OnSorted
l TcxTreeListNode.AlphaSort
l TcxTreeListNode.Focused
l TcxTreeListNode.MakeVisible

Page 419 of 1199


TcxCustomTreeList.OnSummary
TcxCustomTreeList

Enables you to perform custom summary calculations.

Syntax

type
TcxTreeListSummaryEventArguments = record
Node: TcxTreeListNode;
SummaryItem: TcxTreeListSummaryItem;
end;
TcxTreeListSummaryEventOutArguments = record
Value: Variant;
SummaryValue: Variant;
CountValue: Integer;
Done: Boolean;
end;
TcxTreeListSummaryEvent = procedure(ASender: TcxCustomTreeList; const Arguments: TcxTreeLi
property OnSummary: TcxSummaryEvent;

Description
Sender specifies the tree list.
Arguments and OutArguments specify the passed arguments and the resulting data of the performed calculation.

Values include:

TcxTreeListSummaryEventArguments

Field Description

Node Specifies the currently processed node.

SummaryItem Specifies summary settings.

TcxTreeListSummaryEventOutArguments

Field Description

Value Specifies the value of a node's data cell that belongs to the column used
in a calculation.

SummaryValue Specifies the summary value that has been calculated for the previously
processed nodes.

CountValue Specifies the number of nodes that have already been processed.

Done Specifies whether default calculation is required. Set Done to True, to


prevent default calculation.

Refer to the Creating Summaries help topic for details.


Page 420 of 1199
TcxCustomTreeList.OnTopRecordIndexChanged
TcxCustomTreeList

Occurs when scrolling the TreeList's contents.

Syntax

type
TNotifyEvent = procedure(Sender: TObject) of object;
property OnTopRecordIndexChanged: TNotifyEvent;

Description
Write an event handler to perform actions when an end-user scrolls the control's contents.
The Sender parameter gives access to the TreeList control that initiated the event.

To access the top visible node, use the TopVisibleNode property.

Page 421 of 1199


TcxCustomTreeList.OptionsBehavior
TcxCustomTreeList

Specifies the tree list's behavior options.

Syntax

property OptionsBehavior: TcxTreeListOptionsBehavior;

Description
Refer to the TcxTreeListOptionsBehavior description, for details.

Page 422 of 1199


TcxCustomTreeList.OptionsCustomizing
TcxCustomTreeList

Specifies the tree list's options controlling end-user actions.

Syntax

property OptionsCustomizing: TcxTreeListOptionsCustomizing;

Description
Refer to the TcxTreeListOptionsCustomizing description, for details.

Page 423 of 1199


TcxCustomTreeList.OptionsData
TcxCustomTreeList

Specifies the tree list's data processing options.

Syntax

property OptionsData: TcxTreeListOptionsData;

Description
Refer to the TcxTreeListOptionsData description, for details.

Page 424 of 1199


TcxCustomTreeList.OptionsSelection
TcxCustomTreeList

Specifies the tree list's node and cell selection options.

Syntax

property OptionsSelection: TcxTreeListOptionsSelection;

Description
Refer to the TcxTreeListOptionsSelection description, for details.

Page 425 of 1199


TcxCustomTreeList.OptionsView
TcxCustomTreeList

Specifies the tree list's display options.

Syntax

property OptionsView: TcxTreeListOptionsView;

Description
Refer to the TcxTreeListOptionsView description, for details.

Page 426 of 1199


TcxCustomTreeList.PopupMenus
TcxCustomTreeList

Provides access to the TreeList control's context menus.

Syntax

property PopupMenus: TcxTreeListPopupMenus;

Description
Represents the following menus:
l Column header context menu (ColumnHeaderMenu).
l Footer context menu (FooterMenu).
l Group footer context menu (GroupFooterMenu).

Page 427 of 1199


TcxCustomTreeList.Post
TcxCustomTreeList

Sends the changed data to the linked storage.

Syntax

procedure Post;

Description
Call the Edit (which starts the transaction) and Post methods to wrap statements (see the node's Values property) that update
node values in the corresponding storage record.
For rollback purposes, use the Cancel method instead of the Post method.

Related Information

l TcxTreeListNode.Values

Page 428 of 1199


TcxCustomTreeList.Preview
TcxCustomTreeList

Specifies options for Outlook-style node preview sections.

Syntax

property Preview: TcxTreeListPreview;

Description
Refer to the TcxTreeListPreview description, for details.

Page 429 of 1199


TcxCustomTreeList.RestoreColumnsDefaults
TcxCustomTreeList

Restores the default settings of all columns.

Syntax

procedure RestoreColumnsDefaults;

Description
This method restores the following settings:
l The column's sort order (see the SortOrder property) is set to soNone.
l The column's caption text alignments (see the TcxTreeListCaption.AlignHorz and TcxTreeListCaption.AlignVert properties)
are set to taLeftJustify and vaTop.
l The column's width is set to its default value (see the column's MinWidth and Width properties).
l Default column options are restored to their default values (see the column's Options property).

To restore only the default column width, use the RestoreColumnsWidths method.

Related Information

l TcxCustomTreeList.MakeDefaultLayout
l TcxCustomTreeList.RestoreColumnsWidths

Page 430 of 1199


TcxCustomTreeList.RestoreColumnsWidths
TcxCustomTreeList

Restores the default width of all columns.

Syntax

procedure RestoreColumnsWidths;

Description
To restore all columns settings, use the RestoreColumnsDefaults method.

Related Information

l TcxCustomTreeList.MakeDefaultLayout
l TcxTreeListColumn.MinWidth
l TcxTreeListColumn.RestoreDefaults
l TcxTreeListColumn.Width

Page 431 of 1199


TcxCustomTreeList.RestoreFromIniFile
TcxCustomTreeList

Restores TreeList-specific information from an INI file.

Syntax

procedure RestoreFromIniFile(const AStorageName: string; AChildrenCreating: Boolean = False;

Description
Use the RestoreFromIniFile method to restore TreeList-specific information from an INI file. Restoring the TreeList structure can be
ensure that the control contains all columns connected to dataset fields at the time when data was saved to the INI file.
Stored structure information includes: instance names, band and column settings. Stored elements' (bands and columns) settings spe
The AStorageName parameter specifies the INI file path and name.
The AChildrenCreating parameter determines whether non-existent TreeList elements (bands and columns) present within an INI file a
TreeList elements not present within the INI file are deleted when restoring.
The ARestoreTreeListName parameter corresponds to the ASaveTreeListName parameter of the storing procedure.
If ASaveTreeListName is set to an empty string, the storing procedure saves the current tree list's name to a data store. Use this mod
names. If multiple columns with unassigned names are saved, only the settings of the last unnamed column will be persisted.
If the ASaveTreeListName parameter of the storing procedure specifies a non-empty string, the current tree list's name is ignored and T
and then apply them to (restore in) another tree list. To enable this mode, you have to set the ARestoreTreeListName parameter to the
In this mode, columns are stored by their IDs. ID is a unique zero-based identifier that is assigned to a column when it's created at run
created column might get the ID of the deleted column. So, the IDs of columns won't be reused within the current state of the tree list,
The restoring procedure recognizes columns by their IDs, i.e. if the data store contains settings for columns with IDs equal to 0, 1, and
existing columns are created/deleted based on the AChildrenCreating and AChildrenDeleting parameter values. Note that the tree list,

Note:   You can handle the OnInitStoredObject event to properly initialize the object, which corresponds to the re-created column (prov
by re-associating its events with existing event handlers and assigning its properties.

Related Information

l TcxCustomTreeList.RestoreFromRegistry
l TcxCustomTreeList.RestoreFromStream
l TcxCustomTreeList.StoreToRegistry
l TcxCustomTreeList.StoreToStream
l TcxTreeListColumn Object

Page 432 of 1199


TcxCustomTreeList.RestoreFromRegistry
TcxCustomTreeList

Restores TreeList-specific information from the system registry.

Syntax

procedure RestoreFromRegistry(const AStorageName: string; AChildrenCreating: Boolean = False

Description
Use the RestoreFromRegistry method to restore TreeList-specific information from the system registry. Restoring the TreeList struc
structure, ensure that the control contains all columns connected to dataset fields at the time when data was saved to the registry key
Stored structure information includes: instance names, band and column settings. Stored elements' (bands and columns) settings spe
AStorageName specifies the HKEY_USERS' subkey.
The AChildrenCreating parameter determines whether non-existent TreeList elements (bands and columns) present within the stream
TreeList elements not present within the stream file are deleted when restoring.
For information on the ARestoreTreeListName parameter, see the RestoreFromIniFile method description.

Related Information

l TcxCustomTreeList.RestoreFromIniFile
l TcxCustomTreeList.RestoreFromStream

Page 433 of 1199


TcxCustomTreeList.RestoreFromStream
TcxCustomTreeList

Restores TreeList-specific information from a stream.

Syntax

procedure RestoreFromStream(AStream: TStream; AChildrenCreating: Boolean = False; AChildrenD

Description
Use the RestoreFromStream method to restore TreeList-specific information from a stream. Restoring the TreeList structure can be
structure, ensure that the control contains all columns connected to the dataset fields at the time when data was saved to the stream.
Stored structure information includes: instance names, band and column settings. Stored elements' (bands and columns) settings spe
The AChildrenCreating parameter determines whether non-existent TreeList elements (bands and columns) present within the stream
whether existing TreeList elements not present within the stream file are deleted when restoring.
For information on the ARestoreTreeListName parameter, see the RestoreFromIniFile method description.

Related Information

l TcxCustomTreeList.RestoreFromIniFile
l TcxCustomTreeList.RestoreFromRegistry

Page 434 of 1199


TcxCustomTreeList.Root
TcxCustomTreeList

Provides access to the virtual node that considered to be the parent of root level nodes.

Syntax

property Root: TcxTreeListNode;

Description
Since this node is a root node, its Parent property returns nil, and the Level property returns –1.

ReadOnly Property

Page 435 of 1199


TcxCustomTreeList.Searching
TcxCustomTreeList

Checks whether an incremental search is currently performed in the tree list.

Syntax

property Searching: Boolean;

Description
The property returns True, if an incremental search is being performed.
Note that incremental search is enabled if the tree list's OptionsBehavior.IncSearch option is active.

ReadOnly Property

Examples

l Example: Searching, Behavior.IncSearch, Behavior.IncSearchItem, Behavior.ExpandOnIncSearching, SearchingText,


CancelSearching

Page 436 of 1199


TcxCustomTreeList.SearchingText
TcxCustomTreeList

Specifies the string used by the FindNext method.

Syntax

property SearchingText: string;

Description
The FindNext method searches for nodes containing the text that matches the specified string.

Examples

l Example: Searching, Behavior.IncSearch, Behavior.IncSearchItem, Behavior.ExpandOnIncSearching, SearchingText,


CancelSearching

Page 437 of 1199


TcxCustomTreeList.Select
TcxCustomTreeList

Selects specified nodes.

Syntax

procedure Select(Node: TcxTreeListNode; ShiftState: TShiftState = []); virtual;


procedure Select(const ANodes: array of TcxTreeListNode); virtual;
procedure Select(ANodesList: TList); virtual;

Description
The first overload selects nodes using end-user input emulation. Note that the overload does nothing, if the
OptionsSelection.MultiSelect option is inactive.

Node specifies the node to select.


ShiftState specifies the keyboard shortcut. The way the nodes can be selected is dependent upon the following values:
ssShift – a set of adjacent nodes will be selected (starting from the selected node through to Node).
ssCtrl – a single node will be added to the current selection.

The second and third overloads select nodes specified by ANodes or ANodesList (nodes are represented in overloads either by
an array or via a list of pointers).

This method is not in effect if the OnCanFocusNode's or the OnCanSelectNode's Allow parameter is set to False.

Related Information

l TcxCustomTreeList.ClearSelection
l TcxCustomTreeList.Deselect
l TcxCustomTreeList.OnSelectionChanged
l TcxCustomTreeList.SelectAll
l TcxCustomTreeList.SelectionCount
l TcxCustomTreeList.Selections
l TcxTreeListNode.Selected
l TcxTreeListOptionsSelection.MultiSelect

Page 438 of 1199


TcxCustomTreeList.SelectAll
TcxCustomTreeList

Selects all nodes.

Syntax

procedure SelectAll;

Description
Note that selection of multiple nodes is allowed, if the OptionsSelection.MultiSelect option is active. Otherwise, the SelectAll
method does nothing. The method is also not in effect if the OnCanSelectNode's Allow parameter is set to False.

To select a particular node, use the tree list's Select method.


If you wish to deselect all the selected nodes simultaneously, use the ClearSelection method.

Related Information

l TcxCustomTreeList.ClearSelection
l TcxCustomTreeList.Deselect
l TcxCustomTreeList.OnSelectionChanged
l TcxCustomTreeList.Select
l TcxCustomTreeList.SelectionCount
l TcxCustomTreeList.Selections
l TcxTreeListNode.Selected
l TcxTreeListOptionsSelection.MultiSelect

Page 439 of 1199


TcxCustomTreeList.SelectionCount
TcxCustomTreeList

Returns the number of selected nodes.

Syntax

property SelectionCount: Integer;

Description
For indexed access to selected nodes, use the Selections property.
To enable the multi-select feature, activate the tree list's OptionsSelection.MultiSelect option.

ReadOnly Property

Related Information

l TcxCustomTreeList.ClearSelection
l TcxCustomTreeList.Deselect
l TcxCustomTreeList.OnSelectionChanged
l TcxCustomTreeList.Select
l TcxCustomTreeList.SelectAll
l TcxCustomTreeList.Selections
l TcxTreeListNode.Selected
l TcxTreeListOptionsSelection.MultiSelect

Page 440 of 1199


TcxCustomTreeList.SelectionList
TcxCustomTreeList

Provides access to the collection of selected nodes.

Syntax

property SelectionList: TList;

Description
For indexed access to selected nodes, use the Selections property instead.
To enable the multi-select feature, activate the tree list's OptionsSelection.MultiSelect option.

ReadOnly Property

Related Information

l TcxCustomTreeList.ClearSelection
l TcxCustomTreeList.Deselect
l TcxCustomTreeList.OnSelectionChanged
l TcxCustomTreeList.Select
l TcxCustomTreeList.SelectAll
l TcxCustomTreeList.SelectionCount
l TcxTreeListNode.Selected
l TcxTreeListOptionsSelection.MultiSelect

Page 441 of 1199


TcxCustomTreeList.Selections
TcxCustomTreeList

Provides indexed access to the selected nodes.

Syntax

property Selections[Index: Integer]: TcxTreeListNode;

Description
To obtain the total number of selected nodes, use the SelectionCount property.
To enable the multi-select feature, activate the tree list's OptionsSelection.MultiSelect option.

ReadOnly Property

Related Information

l TcxCustomTreeList.ClearSelection
l TcxCustomTreeList.Deselect
l TcxCustomTreeList.OnSelectionChanged
l TcxCustomTreeList.Select
l TcxCustomTreeList.SelectAll
l TcxCustomTreeList.SelectionCount
l TcxTreeListNode.Selected
l TcxTreeListOptionsSelection.MultiSelect

Page 442 of 1199


TcxCustomTreeList.ShowEdit
TcxCustomTreeList

Activates an in-place editor for the focused data cell.

Syntax

procedure ShowEdit;

Description
Note that the ShowEdit method does nothing if either the tree list's OptionsData.Editing or the OptionsSelection.CellSelect
option is inactive.
To exit from in-place editing without saving, use the tree list's CancelEdit method. If you wish to save the modified data and exit,
use the tree list's HideEdit method.

Related Information

l TcxCustomTreeList.CancelEdit
l TcxCustomTreeList.FocusedColumn
l TcxCustomTreeList.HideEdit
l TcxCustomTreeList.InplaceEditor
l TcxCustomTreeList.IsActive
l TcxCustomTreeList.IsEditing
l TcxCustomTreeList.ShowEditByKey
l TcxCustomTreeList.ShowEditByMouse

Page 443 of 1199


TcxCustomTreeList.ShowEditByKey
TcxCustomTreeList

Activates an in-place editor for the focused data cell, emulating activation, as with a keyboard action.

Syntax

procedure ShowEditByKey(AKey: Char);

Description
AKey specifies the keyboard shortcut.

To activate an in-place editor, emulating it as with a mouse action, use the ShowEditByMouse method.

Related Information

l TcxCustomTreeList.CancelEdit
l TcxCustomTreeList.FocusedColumn
l TcxCustomTreeList.HideEdit
l TcxCustomTreeList.InplaceEditor
l TcxCustomTreeList.IsActive
l TcxCustomTreeList.IsEditing
l TcxCustomTreeList.ShowEdit
l TcxCustomTreeList.ShowEditByMouse

Page 444 of 1199


TcxCustomTreeList.ShowEditByMouse
TcxCustomTreeList

Activates an in-place editor for the focused data cell, emulating activation, as with a mouse action.

Syntax

procedure ShowEditByMouse(X, Y: Integer; AShift: TShiftState);

Description
X and Y specify the mouse pointer location (in tree list coordinates).
AShift specifies the mouse input type.

To activate an in-place editor, emulating it as with a keyboard action, use the ShowEditByKey method.

Related Information

l TcxCustomTreeList.CancelEdit
l TcxCustomTreeList.FocusedColumn
l TcxCustomTreeList.HideEdit
l TcxCustomTreeList.InplaceEditor
l TcxCustomTreeList.IsActive
l TcxCustomTreeList.IsEditing
l TcxCustomTreeList.ShowEditByKey

Page 445 of 1199


TcxCustomTreeList.ShowFindPanel
TcxCustomTreeList

Invokes the Find Panel.

Syntax

procedure ShowFindPanel;

Description
Call the HideFindPanel or ShowFindPanel method to switch the panel visibility. End-users can switch the panel visibility only in
fpdmManual display mode. Handle the tree list's OnFindPanelVisibilityChanged event to track panel visibility changes.

Page 446 of 1199


TcxCustomTreeList.Sorted
TcxCustomTreeList

Returns whether columns are sorted.

Syntax

property Sorted: Boolean;

Description
The property returns True, if at least one column is sorted. To clear sorting in all columns, set the Sorted property to False.
Alternatively, you can use the ClearSorting method for this purpose.
However, no sorting is applied if the Sorted property is set to True. For this purpose, use the column's SortOrder property
instead.

To clear sorting in a particular column, set the column's SortOrder property to soNone.
The total number of sorted columns can be obtained using the SortedColumnCount property.
For indexed access to sorted columns, use the SortedColumns property.

Examples

l Example: TreeList.Sorted, TreeList.SortedColumnCount, TreeList.SortedColumns, Column.SortOrder

Related Information

l TcxCustomTreeList.SortedColumnCount
l TcxCustomTreeList.SortedColumns
l TcxTreeListOptionsData.MultiThreadedSorting

Page 447 of 1199


TcxCustomTreeList.SortedColumnCount
TcxCustomTreeList

Returns the number of sorted columns.

Syntax

property SortedColumnCount: Integer;

Description
For indexed access to sorted columns, use the SortedColumns property.
To determine whether columns are sorted, use the Sorted property.

ReadOnly Property

Examples

l Example: TreeList.Sorted, TreeList.SortedColumnCount, TreeList.SortedColumns, Column.SortOrder

Related Information

l TcxCustomTreeList.Sorted

Page 448 of 1199


TcxCustomTreeList.SortedColumns
TcxCustomTreeList

Provides indexed access to sorted columns.

Syntax

property SortedColumns[Index: Integer]: TcxTreeListColumn;

Description
The SortedColumns collection stores columns whose SortOrder property is other than soNone.
The order of columns in the collection defines the sorting hierarchy in the View.

To obtain the total number of items in the collection, use the SortedColumnCount property.
To determine whether columns are sorted, use the Sorted property.

ReadOnly Property

Examples

l Example: TreeList.Sorted, TreeList.SortedColumnCount, TreeList.SortedColumns, Column.SortOrder

Related Information

l TcxTreeListOptionsBehavior.MultiSort

Page 449 of 1199


TcxCustomTreeList.StateImages
TcxCustomTreeList

Represents a collection of images used for indicating specific states of a node.

Syntax

property StateImages: TCustomImageList;

Description
State images are used to specify the application-specific states of the node.
An image for a node is specified via the node's StateIndex property.

Examples

l Example: OnGetNodeImageIndex

Related Information

l TcxCustomTreeList.Images
l TcxCustomTreeList.OnGetNodeImageIndex
l TcxTreeListNode.ImageIndex
l TcxTreeListNode.SelectedIndex
l TcxTreeListNode.StateIndex
l TcxTreeListOptionsView.DynamicFocusedStateImages

Page 450 of 1199


TcxCustomTreeList.StoreToIniFile
TcxCustomTreeList

Saves TreeList-specific information to an INI file.

Syntax

procedure StoreToIniFile(AStorageName: string; AReCreate: Boolean = True; const ASaveTreeLis

Description
Use the StoreToIniFile method to save TreeList-specific information to an INI file. This information can be restored to keep changes a
control. The TreeList structure is restored by a RestoreFromIniFile method call. Before restoring the TreeList structure, ensure that th
columns connected to the dataset fields at the time the data was saved.
Stored structure information includes: instance names, band and column settings. Stored elements' (bands, columns) settings specify
elements, captions, sort order, data binding etc.
The AStorageName parameter specifies the INI file path and name.
The AReCreate parameter determines whether the INI file required is recreated by each StoreToIniFile method call. If this parameter v
file is deleted and then created again. Otherwise, information is appended to the end of the existing file.
For information on the ASaveTreeListName parameter, see the RestoreFromIniFile method description.

Related Information

l TcxCustomTreeList.StoreToRegistry
l TcxCustomTreeList.StoreToStream

Page 451 of 1199


TcxCustomTreeList.StoreToRegistry
TcxCustomTreeList

Stores TreeList-specific information to the registry.

Syntax

procedure StoreToRegistry(AStorageName: string; AReCreate: Boolean = True; const ASaveTreeLi

Description
Use the StoreToRegistry method to save TreeList-specific information to the registry. This information can be restored after the chan
TreeList control. Use the RestoreFromRegistry method to restore the TreeList structure. Before restoring the TreeList structure, ens
all the columns connected to dataset fields at the time when the data was saved.
Stored structure information includes: instance names, band and column settings. Stored elements' (bands, columns) settings specify
elements, captions, sort order, data binding etc.
The registry path for the TreeList information is formed by adding the AStorageName suffix to the HKEY_CURRENT_USER key.
The AReCreate parameter determines whether the required key is recreated by each StoreToRegistry method call. If this parameter v
registry key is deleted and then created again. Otherwise, information is appended to the existing key.
For information on the ASaveTreeListName parameter, see the RestoreFromIniFile method description.

Related Information

l TcxCustomTreeList.StoreToIniFile
l TcxCustomTreeList.StoreToStream

Page 452 of 1199


TcxCustomTreeList.StoreToStream
TcxCustomTreeList

Saves TreeList-specific information to a stream.

Syntax

procedure StoreToStream(AStream: TStream; const ASaveTreeListName: string = '');

Description
Use the StoreToStream method to save TreeList-specific information to a stream. This information can be restored after
changes have been applied to the TreeList control. Use the RestoreFromStream method to restore the TreeList structure.
Before restoring the TreeList structure, ensure that the control contains all the columns connected to dataset fields at the time
when the data was saved.
Stored structure information includes: instance names, band and column settings. Stored elements' (bands, columns) settings
specify the position and visibility of elements, captions, sort order, data binding etc.
The AStream parameter identifies an instance of the TStream class (or a descendant) where the TreeList information is stored.
For information on the ASaveTreeListName parameter, see the RestoreFromIniFile method description.

Related Information

l TcxCustomTreeList.StoreToIniFile
l TcxCustomTreeList.StoreToRegistry

Page 453 of 1199


TcxCustomTreeList.Styles
TcxCustomTreeList

Specifies style settings for the tree list's elements.

Syntax

property Styles: TcxTreeListStyles;

Description
The TcxTreeListStyles class contains settings that allow you to customize the appearance of the TreeList control's elements.
Refer to the TcxTreeListStyles description, for details.

Page 454 of 1199


TcxCustomTreeList.Summary
TcxCustomTreeList

Provides access to the collection of summaries specified in the tree list.

Syntax

property Summary: TcxTreeListSummary;

Description
The property provides access to summaries of both types – footer and group summaries. Refer to the TcxTreeListSummary
description, for details.

ReadOnly Property

Related Information

l Creating Summaries
l Group Summaries
l TcxCustomTreeList.OnAfterSummary
l TcxCustomTreeList.OnSummary
l TcxTreeListColumn.Summary

Page 455 of 1199


TcxCustomTreeList.TopNode
TcxCustomTreeList

Returns the first node instance.

Syntax

property TopNode: TcxTreeListNode;

Description
This property ignores the node visibility (see the node's IsHidden property) when searching for the first node.
To obtain the first visible node, use the TopVisibleNode property instead.

ReadOnly Property

Related Information

l TcxCustomTreeList.LastNode
l TcxCustomTreeList.TopVisibleNode
l TcxTreeListNode.getFirstChild
l TcxTreeListNode.GetLastChild
l TcxTreeListNode.GetNext
l TcxTreeListNode.GetNextChild
l TcxTreeListNode.getNextSibling
l TcxTreeListNode.GetNextVisible
l TcxTreeListNode.GetPrev
l TcxTreeListNode.GetPrevChild
l TcxTreeListNode.getPrevSibling
l TcxTreeListNode.GetPrevVisible
l TcxTreeListNode.IsFirstVisible
l TcxTreeListNode.IsLastVisible
l TcxTreeListNode.IsVisible
l TcxTreeListNode.MakeVisible
l TcxTreeListNode.VisibleIndex

Page 456 of 1199


TcxCustomTreeList.TopVisibleNode
TcxCustomTreeList

Specifies the top node visible in the tree list's View.

Syntax

property TopVisibleNode: TcxTreeListNode;

Description
Assigning a node to this property scrolls the tree list's content to make this node visible at the tree list's top edge. Use the
TopNode property to access the first visible node without scrolling the content.

Related Information

l TcxCustomTreeList.LastVisibleNode
l TcxTreeListNode.MakeVisible

Page 457 of 1199


TcxCustomTreeList.VisibleColumnCount
TcxCustomTreeList

Returns the number of visible columns.

Syntax

property VisibleColumnCount: Integer;

Description
This property returns the number of columns whose Visible property returns True. For indexed access to visible columns, use
the VisibleColumns property.

ReadOnly Property

Examples

l Example: TreeList.VisibleColumnCount, TreeList.VisibleColumns

Related Information

l TcxCustomTreeList.ColumnCount
l TcxCustomTreeList.Columns

Page 458 of 1199


TcxCustomTreeList.VisibleColumns
TcxCustomTreeList

Provides indexed access to visible columns.

Syntax

property VisibleColumns[Index: Integer]: TcxTreeListColumn;

Description
Index specifies the column's position in the collection.
Use the VisibleColumnCount property to obtain the total number of visible columns.

Examples

l Example: TreeList.VisibleColumnCount, TreeList.VisibleColumns

Related Information

l TcxCustomTreeList.ColumnCount
l TcxCustomTreeList.Columns

Page 459 of 1199


TcxCustomTreeList.VisibleCount
TcxCustomTreeList

Returns the number of visible nodes.

Syntax

property VisibleCount: Integer;

Description
Nodes that are located beyond the View's boundaries or partially clipped by the View's boundaries, and children of collapsed
parents are not taken into account.
For indexed access to nodes available in the View (including nodes that are beyond the boundaries), use the
AbsoluteVisibleItems property. This property provides a flat list of nodes to be displayed in the View. To access a subset of
nodes that relate to the VisibleCount, use the tree list's TopVisibleNode and LastVisibleNode's AbsoluteIndex properties as
bounds of a subset.

ReadOnly Property

Related Information

l TcxTreeListNode.GetNextVisible
l TcxTreeListNode.GetPrevVisible
l TcxTreeListNode.IsFirstVisible
l TcxTreeListNode.IsLastVisible
l TcxTreeListNode.IsVisible
l TcxTreeListNode.MakeVisible

Page 460 of 1199


TcxCustomVirtualTreeList.CustomDataSource
TcxCustomVirtualTreeList

Specifies the custom data source for the virtual TreeList control.

Syntax

property CustomDataSource: TcxTreeListCustomDataSource;

Description
The virtual TreeList control allows you to work with tree-like data structures of your own format. The only thing you need to do is
to implement your own data source class derived from the TcxTreeListCustomDataSource class. For detailed information, please
refer to the Introduction To Provider Mode help topic. The CustomDataSource property lets you access this data source via the
TreeList control.

Page 461 of 1199


TcxCustomVirtualTreeList.HandleFromNode
TcxCustomVirtualTreeList

Returns the node's record handle.

Syntax

function HandleFromNode(ANode: TcxTreeListNode): TcxDataRecordHandle; virtual;

Description
ANode specifies the node for which the record handle is to be obtained. If nil is passed as ANode, the root node's record handle
will be returned.

Page 462 of 1199


TcxCustomVirtualTreeList.NodeFromHandle
TcxCustomVirtualTreeList

Returns the node by its record handle.

Syntax

function NodeFromHandle(ARecordHandle: TcxDataRecordHandle): TcxTreeListNode; virtual;

Description
ARecordHandle specifies the record handle.
If a match was not found, the method returns nil.

Page 463 of 1199


TcxCustomVirtualTreeList.OnGetChildCount
TcxCustomVirtualTreeList

Enables you to control the number of child nodes for loading.

Syntax

type
TcxVirtualTreeListGetChildCountEvent = procedure(Sender: TcxCustomTreeList; AParentNode: T
property OnGetChildCount: TcxVirtualTreeListGetChildCountEvent;

Description
Handle the OnGetChildCount event to load only the specified number of children for certain parent nodes.
This event is used if both of the following conditions are met:
l The TcxTreeListCustomDataSource's descendant is not implemented.
l The smart load feature is enabled.

Implementation of the event handler is an alternative way of overriding the TcxTreeListCustomDataSource's GetChildCount method, an
used (see the Introduction To Provider Mode help topic).

Sender specifies the tree list.


AParentNode specifies the node whose children are to be loaded.
ACount specifies the number of children to load.

Related Information

l Introduction To Provider Mode


l TcxCustomVirtualTreeList.OnGetNodeValue
l TcxCustomVirtualTreeList.OnSetNodeValue

Page 464 of 1199


TcxCustomVirtualTreeList.OnGetNodeValue
TcxCustomVirtualTreeList

Enables you to control data reading from the custom data source.

Syntax

type
TcxVirtualTreeListNodeValueEvent = procedure(Sender: TcxCustomTreeList; ANode: TcxTreeList
property OnGetNodeValue: TcxVirtualTreeListNodeValueEvent;

Description
Handle the OnGetNodeValue event if the TcxTreeListCustomDataSource's descendant is not implemented.
Implementation of the event handler is an alternative way of overriding the TcxTreeListCustomDataSource's GetValue method, and is a
Provider Mode help topic).

Sender specifies the tree list.


ANode and AColumn specify the data cell whose content is being handled.
AValue specifies the value to be obtained from the data source.

Related Information

l Introduction To Provider Mode


l TcxCustomVirtualTreeList.OnGetChildCount
l TcxCustomVirtualTreeList.OnSetNodeValue

Page 465 of 1199


TcxCustomVirtualTreeList.OnSetNodeValue
TcxCustomVirtualTreeList

Enables you to control data writing to the custom data source.

Syntax

type
TcxVirtualTreeListNodeValueEvent = procedure(Sender: TcxCustomTreeList; ANode: TcxTreeList
property OnSetNodeValue: TcxVirtualTreeListNodeValueEvent;

Description
Handle the OnSetNodeValue event if the TcxTreeListCustomDataSource's descendant is not implemented.
Implementation of the event handler is an alternative way of overriding the TcxTreeListCustomDataSource's SetValue method, and is a
Provider Mode help topic).

Sender specifies the tree list.


ANode and AColumn specify the data cell whose content is being handled.
AValue specifies the value to be sent to the data source.

Related Information

l Introduction To Provider Mode


l TcxCustomVirtualTreeList.OnGetChildCount
l TcxCustomVirtualTreeList.OnGetNodeValue

Page 466 of 1199


TcxDataTreeListDataController.CustomDataSource
TcxDataTreeListDataController

Specifies the custom data source.

Syntax

property CustomDataSource: TcxTreeListCustomDataSource;

Description
This property enables you to access the properties and methods of the user defined data source. This data source provides data
for the virtual TreeList control working in provider mode.

Page 467 of 1199


TcxDataTreeListDataController.TreeList
TcxDataTreeListDataController

Provides access to the owner TreeList control.

Syntax

property TreeList: TcxCustomDataTreeList;

Description
This property enables you to access the properties and methods of the TreeList control to which the data controller belongs.

ReadOnly Property

Page 468 of 1199


TcxDBItemDataBinding.Field
TcxDBItemDataBinding

Returns the dataset field associated with an item.

Syntax

property Field: TField;

Description
Use the Field property to obtain the dataset field associated with an item. To change the dataset field associated with the item,
use the FieldName property.

ReadOnly Property

Related Information

l TcxDBItemDataBinding.FieldName

Page 469 of 1199


TcxDBItemDataBinding.FieldName
TcxDBItemDataBinding

Specifies the item's field name.

Syntax

property FieldName: string;

Description
The FieldName property identifies the dataset field to which the current item is bound. This field itself can be accessed via the
Field property.
When the FieldName property is assigned, the data field type determines the default editor used to edit the item's content. The
following table lists the default editors corresponding to field types. This correspondence is specified by the
DBRepositoryItemClasses array declared in the cxEditDBRegisteredRepositoryItems unit:

Field type Associated editor

ftBoolean TcxCheckBox

ftCurrency, ftBCD, ftFMTBcd TcxCurrencyEdit

ftDate, ftDateTime TcxDateEdit

ftTime TcxTimeEdit

ftBytes, ftVarBytes, ftBlob, ftFmtMemo, ftParadoxOle, TcxBlobEdit


ftDBaseOle, ftTypedBinary

ftMemo TcxMemo

ftGraphic TcxImage

For fields not listed in the above table, the TcxMaskEdit is used.
If you need to change the default editor, use the column's Properties or PropertiesClassName property.

Related Information

l TcxDBItemDataBinding.Field
l ExpressEditors: TcxCustomInplaceEditContainer.Properties
l ExpressEditors: TcxCustomInplaceEditContainer.PropertiesClassName

Page 470 of 1199


TcxDBTreeListColumn.DataBinding
TcxDBTreeListColumn

Represents the TreeList column connection to a data source.

Syntax

property DataBinding: TcxDBItemDataBinding;

Description
Each TcxDBTreeListColumn is connected to a data source via a TcxDBItemDataBinding object. The DataBinding.FieldName
property identifies the data source field, associated with a column. The DataBinding.Field property returns the TField object,
representing the appropriate data source field.

Page 471 of 1199


TcxDBTreeListDataController.CreateAllItems
TcxDBTreeListDataController

Creates items for all dataset fields.

Syntax

procedure CreateAllItems; virtual;

Description
When the cxDBTreeList control is bound to a data source, initially it displays no data. Call the CreateAllItems method to create
items corresponding to all dataset fields. An item represents a TreeList column.
The CreateAllItems method initializes the DataBinding property of each item created. The dataset field name for the current item
is assigned to the DataBinding.FieldName property. The item's visibility is determined by the Visible property value of the
corresponding dataset field.
Items created are added to the first existing band. If the TreeList.Bands collection is empty, a band is created and items are
moved to it.

Related Information

l TcxCustomTreeList.Columns

Page 472 of 1199


TcxDBTreeListDataController.DataSet
TcxDBTreeListDataController

Provides access to the dataset linked to the tree list via a data source.
ReadOnly Property

Syntax

property DataSet: TDataSet;

Related Information

l TcxDBTreeListDataController.DataSource

Page 473 of 1199


TcxDBTreeListDataController.DataSource
TcxDBTreeListDataController

Specifies the data source used for binding the dataset to the tree list.

Syntax

property DataSource: TDataSource;

Related Information

l TcxDBTreeListDataController.DataSet

Page 474 of 1199


TcxDBTreeListDataController.ImageIndexField
TcxDBTreeListDataController

Specifies the name of a field from which to acquire indexes for images.

Syntax

property ImageIndexField: string;

Description
Use the ImageIndexField property to specify the name of a field that contains indexes for the treelist ImageIndex property that
determines what images to display when a node is in its normal state and is currently selected.

Page 475 of 1199


TcxDBTreeListDataController.KeyField
TcxDBTreeListDataController

Specifies the name of the dataset field whose values identify dataset records.

Syntax

property KeyField: string;

Description
The KeyField property designates the dataset field, whose values are used to identify dataset records. The KeyField and
ParentField properties describe the record position within the tree structure. The ParentField value of a specific record (node)
specifies the KeyField value of the parent record (node) for the current record (node).

Page 476 of 1199


TcxDBTreeListDataController.ParentField
TcxDBTreeListDataController

Specifies the name of the dataset field containing the parent node's key field values.

Syntax

property ParentField: string;

Description
The KeyField and ParentField properties are required to build a tree structure.
KeyField values identify records. The ParentField property designates the dataset field whose values define the record's position
within the tree structure. The values of ParentField specify the KeyField value of the record (node in the tree structure), owning
the current record (node).
If a record has a ParentField value without a corresponding key field value within the dataset, this record is displayed at the root
of the tree structure. Child records of a record (node) have the same ParentField value, which matches the KeyField value of
their parent record (node).

Page 477 of 1199


TcxDBTreeListDataController.StateIndexField
TcxDBTreeListDataController

Specifies the name of the field from which to acquire indexes for state images.

Syntax

property StateIndexField: string;

Description
Use the StateIndexField to specify the name of a field that contains indexes for the StateIndex property of the cxTreeListNode
to determine images that reflect state information.

Page 478 of 1199


TcxDBTreeListDataController.TreeList
TcxDBTreeListDataController

Provides access to the TreeList which is controlled by the current data controller.

Syntax

property TreeList: TcxCustomDataTreeList;

Description
Use the TreeList property to access the properties and methods of the TreeList control which is controlled by the current data
controller.

ReadOnly Property

Page 479 of 1199


TcxDBTreeListNode.KeyValue
TcxDBTreeListNode

Specifies the node's unique identifier.

Syntax

property KeyValue: Variant;

Description
Use this property to manually specify the node's unique identifier within the tree list's OnInitInsertingRecord event handler, if
automatic generation of the identifier is disabled (see the tree list's OptionsData.AutoCalcKeyValue property).
Refer to the tree list's OnInitInsertingRecord help topic, for details.

Page 480 of 1199


TcxDBTreeListNode.ParentKeyValue
TcxDBTreeListNode

Specifies the parent node's unique identifier.

Syntax

property ParentKeyValue: Variant;

Description
Use this property to manually specify the node parent's unique identifier within the tree list's OnInitInsertingRecord event handler,
if automatic generation of the identifier is disabled (see the tree list's OptionsData.AutoCalcKeyValue property).
Refer to the tree list's OnInitInsertingRecord help topic, for details.

Page 481 of 1199


TcxDBTreeListOptionsData.AutoCalcKeyValue
TcxDBTreeListOptionsData

Determines whether the key field values for new records are calculated automatically.

Syntax

property AutoCalcKeyValue: Boolean;

Description
You can insert nodes into the cxDBTreeList control by pressing the Insert key (the OptionsData.Inserting options must be set to
True for this purpose). If the AutoCalcKeyValue option is activated, the key field value for the node (record) inserted is
calculated automatically. Note: the parent field value for the record inserted must be obtained manually, regardless of the
AutoCalcKeyValue option's state.
If the AutoCalcKeyValue option is deactivated, you must handle the OnInitInsertingRecord event to calculate key and parent
field values for new records.

The default value of the AutoCalcKeyValue property is False.

Related Information

l TcxCustomDBTreeList.OnGetUniqueKeyValue
l TcxCustomDBTreeList.OnInitInsertingRecord

Page 482 of 1199


TcxDBTreeListOptionsData.SmartRefresh
TcxDBTreeListOptionsData

Determines the manner in which dataset records are updated.

Syntax

property SmartRefresh: Boolean;

Description
By default, the TcxDBTreeListDataController updates all dataset records, regardless of whether a record has been changed or
not. If the SmartRefresh option is activated, the TreeList data controller reloads only changed records. This option is only in
effect when the SmartLoad option is deactivated, the key field for the dataset is specified and the source of changes is the
cxDBTreeList control.

The default value of the SmartRefresh property is False.

Page 483 of 1199


TcxDBTreeListOptionsData.SyncMode
TcxDBTreeListOptionsData

Specifies whether synchronization between the grid control and its corresponding TDataSet is enabled.

Syntax

property SyncMode: Boolean;

Description
If SyncMode is set to True, the current node within the TreeList control is always synchronized with the current record in its
corresponding TDataSet. Whenever you move focus to another node within the TreeList control, the active TDataSet record is
also changed to point to the same data, and vice versa. When the active TDataSet record is changed, focus is moved to the
corresponding node within the TreeList control.

The default value of the SyncMode property is True.

Page 484 of 1199


TcxTreeListBandOptions.Customizing
TcxTreeListBandOptions

Specifies whether end-users can change the band's visibility.

Syntax

property Customizing: Boolean;

Description
Set this property to False, to prohibit end-users from changing the visibility of the band using any of the following methods:
l Dragging the band's header from the band header panel or customization form.
l Clicking a corresponding item within the Quick Band Customization dropdown.

The Customizing property is in effect only if the TreeList control's OptionsCustomizing.BandCustomizing property is set to
True.

Note:   Dragging bands is enabled only when a band's Options.Moving property and the TreeList control's
OptionsCustomizing.BandMoving property are set to True. Fixed bands cannot be moved. Use the TreeList control's
OptionsCustomizing.BandHiding property to customize the manner in which end-users can hide bands, using drag-and-drop
operations.

The default value of the Customizing property is True.

Page 485 of 1199


TcxTreeListBandOptions.Hidden
TcxTreeListBandOptions

Specifies whether the current band is visible in the customization form.

Syntax

property Hidden: Boolean;

Description
If the Hidden property is set to True, the band is not displayed in the customization form after it has been dragged from the
control into the customization form.
Note:   To activate the customization form set the TcxTreeListCustomizing.Visible property to True. To allow dragging the band
set the TcxTreeListBandOptions.Moving property to True. To authorize dragging the band from the control to the customization
form set the TcxTreeListBandOptions.Customizing property to True.

The default value of the Hidden property is False.

Page 486 of 1199


TcxTreeListBandOptions.Moving
TcxTreeListBandOptions

Indicates whether the band can be relocated among other bands within the control.

Syntax

property Moving: Boolean;

Description
Set this property to False, to prohibit end-users from moving the band. The Moving property is in effect only if the TreeList
control's OptionsCustomizing.BandMoving property is set to True.
To programmatically move the band, use its Position property.

Note:   If the Moving property is set to False, the Customizing property value is ignored. Fixed bands cannot be moved,
regardless of the Moving property value.

The default value of the Moving property is True.

Page 487 of 1199


TcxTreeListBandOptions.OnlyOwnColumns
TcxTreeListBandOptions

Indicates whether the end-user can drag columns to/from the band.

Syntax

property OnlyOwnColumns: Boolean;

Description
By default, this property is False, so users can drag columns to/from the band. If set to True, users can only move columns
within the band (i.e. not between bands).

Note: Users can drag a column to/from the customization form regardless of the OnlyOwnColumns value.

Additionally, you can use members of the TcxTreeListOptionsCustomizing object exposed via the control's OptionsCustomizing
property to define options common to all bands and columns.

For more detailed information on options, refer to the Options article.

The default value of the OnlyOwnColumns property is False.

Page 488 of 1199


TcxTreeListBandOptions.RestoreDefaults
TcxTreeListBandOptions

Restores the default options settings.

Syntax

procedure RestoreDefaults; virtual;

Description
Call the RestoreDefaults method to restore the default band options settings. This method sets the Sizing, Customizing and
Moving properties to True.

Page 489 of 1199


TcxTreeListBandOptions.Sizing
TcxTreeListBandOptions

Specifies whether end-users can horizontally resize the band.

Syntax

property Sizing: Boolean;

Description
Set this property to False to prohibit end-users from horizontally resizing the band by dragging its header's right edge.
To prevent all bands from being horizontally resized by end-users, set the TreeList control's
OptionsCustomizing.BandHorzSizing property to False. If this property is set to False, horizontal sizing is prohibited for all
bands regardless of their Sizing property values.
To enable instant visualization of band sizing, set the TreeList control's OptionsCustomizing.DynamicSizing property to True.

The default value of the Sizing property is True.

Related Information

l TcxTreeListBandOptions.VertSizing

Page 490 of 1199


TcxTreeListBandOptions.VertSizing
TcxTreeListBandOptions

Specifies whether end-users can vertically resize the band.

Syntax

property VertSizing: Boolean;

Description
Set this property to False to prohibit end-users from vertically resizing the band by dragging its header's bottom edge.
To prevent all bands from being vertically resized by end-users, set the TreeList control's OptionsCustomizing.BandVertSizing
property to False. If this property is set to False, vertical sizing is prohibited for all bands regardless of their VertSizing property
values.

The default value of the VertSizing property is True.

Related Information

l TcxTreeListBandOptions.Sizing

Page 491 of 1199


TcxTreeListBandPosition.Band
TcxTreeListBandPosition

Provides access to the band that owns the current option set.
ReadOnly Property

Syntax

property Band: TcxTreeListBand;

Page 492 of 1199


TcxTreeListBandPosition.BandIndex
TcxTreeListBandPosition

Specifies the band's parent band.

Syntax

property BandIndex: Integer;

Description
The parent band is identified by its index within the TreeList control's Bands collection. To remove a band from its parent band,
set the BandIndex property to –1. As a result, the band is positioned at the root nesting level.

To access the properties of the parent band, use the ParentBand property.

Related Information

l TcxTreeListBand.MoveBand

Page 493 of 1199


TcxTreeListBandPosition.ColIndex
TcxTreeListBandPosition

Specifies the band's horizontal position.

Syntax

property ColIndex: Integer;

Description
For nested bands, this property specifies the position of a band within its parent band's ChildBands collection. For root bands,
the ColIndex property specifies a band's RootIndex property value.
To determine a band's visible horizontal position, use the VisibleColIndex property.

Page 494 of 1199


TcxTreeListBandPosition.ParentBand
TcxTreeListBandPosition

Provides access to the immediate parent band that displays the current band.

Syntax

property ParentBand: TcxTreeListBand;

Description
For root bands, this property returns nil.
To specify the parent band, use the BandIndex property.

ReadOnly Property

Related Information

l TcxTreeListBand.ParentBand
l TcxTreeListBand.RootParentBand

Page 495 of 1199


TcxTreeListBandPosition.TreeList
TcxTreeListBandPosition

Provides access to the TreeList control containing the band to which the current option set is applied.
ReadOnly Property

Syntax

property TreeList: TcxCustomTreeList;

Page 496 of 1199


TcxTreeListBandPosition.VisibleColIndex
TcxTreeListBandPosition

Returns the horizontal position of the band within its parent band.

Syntax

property VisibleColIndex: Integer;

Description
For root bands, this property returns a band's VisibleRootIndex property value. If a band is hidden, the VisibleColIndex property
returns –1.
To move a band to a specific position within its parent band, use the ColIndex property.

ReadOnly Property

Page 497 of 1199


TcxTreeListBandRows.Band
TcxTreeListBandRows

Provides access to the band associated with the current collection of band rows.

Syntax

property Band: TcxTreeListBand;

Description
If a band is nested within the TreeList control, a band row is associated with this band only if the band is positioned at the
bottom of the band hierarchy.

ReadOnly Property

Page 498 of 1199


TcxTreeListBandRows.Count
TcxTreeListBandRows

Returns the number of band rows contained within the current collection.

Syntax

property Count: Integer;

Description
This property returns the number of items within the Items indexed collection.

ReadOnly Property

Page 499 of 1199


TcxTreeListBandRows.First
TcxTreeListBandRows

Provides access to the first band row within the current collection.

Syntax

property First: TcxTreeListBandRow;

Description
This property returns the first item within the Items indexed collection.

ReadOnly Property

Related Information

l TcxTreeListBandRows.Last

Page 500 of 1199


TcxTreeListBandRows.Items
TcxTreeListBandRows

Provides indexed access to band rows contained within the current collection.

Syntax

property Items[Index: Integer]: TcxTreeListBandRow;

Description
Use the Count property to determine the number of band rows within the Items collection. To access band rows that are currently
visible within the column header panel, use the VisibleItems property.

ReadOnly Property

Concepts

l Stacked Columns

Page 501 of 1199


TcxTreeListBandRows.Last
TcxTreeListBandRows

Provides access to the last band row within the current collection.

Syntax

property Last: TcxTreeListBandRow;

Description
This property returns the last item within the Items indexed collection.

ReadOnly Property

Related Information

l TcxTreeListBandRows.First

Page 502 of 1199


TcxTreeListBandRows.LineCount
TcxTreeListBandRows

Returns the combined height of all visible band rows within the current collection, in text lines.

Syntax

property LineCount: Integer;

Description
This property value is calculated based on the LineCount property values of band rows that are currently visible in the column
header panel.

To access visible band rows, use the VisibleItems indexed collection.

ReadOnly Property

Related Information

l TcxTreeListBands.ColumnLineCount

Page 503 of 1199


TcxTreeListBandRows.RowMaxWidth
TcxTreeListBandRows

Returns the maximum possible width of band rows within the current collection, in pixels.

Syntax

property RowMaxWidth: Integer;

Description
This property value is calculated as the maximum Width property value of all band rows, contained in the Items collection.

ReadOnly Property

Related Information

l TcxTreeListBandRows.RowMinWidth

Page 504 of 1199


TcxTreeListBandRows.RowMinWidth
TcxTreeListBandRows

Returns the minimum possible width of band rows within the current collection, in pixels.

Syntax

property RowMinWidth: Integer;

Description
This property value is calculated as the maximum MinWidth property value of all band rows, contained in the Items collection.

ReadOnly Property

Related Information

l TcxTreeListBandRows.RowMaxWidth

Page 505 of 1199


TcxTreeListBandRows.VisibleItemCount
TcxTreeListBandRows

Returns the number of band rows contained within the current collection.

Syntax

property VisibleItemCount: Integer;

Description
This property returns the number of items within the VisibleItems indexed collection.

ReadOnly Property

Page 506 of 1199


TcxTreeListBandRows.VisibleItems
TcxTreeListBandRows

Provides indexed access to band rows in the current collection that are currently visible within the column header panel.

Syntax

property VisibleItems[Index: Integer]: TcxTreeListBandRow;

Description
If a band row doesn't display any column header and its VisibleItemCount property returns 0, this band row is not removed from
the TcxTreeListBandRows collection (the Items property). Instead, the band row is marked as hidden, and is removed from the
VisibleItems collection.
Use the VisibleItemCount property to determine the number of band rows within the VisibleItems collection.

ReadOnly Property

Concepts

l Stacked Columns

Page 507 of 1199


TcxTreeListBandRow.Band
TcxTreeListBandRow

Provides access to the band associated with the current row.

Syntax

property Band: TcxTreeListBand;

Description
If a band is nested within the TreeList control, a band row is associated with this band only if the band is positioned at the
bottom of the band hierarchy.

ReadOnly Property

Page 508 of 1199


TcxTreeListBandRow.BandRows
TcxTreeListBandRow

Provides access to the collection of band rows associated with the current row's band.

Syntax

property BandRows: TcxTreeListBandRows;

Description
To access a particular band row in this collection, use the BandRows.Items property.

ReadOnly Property

Page 509 of 1199


TcxTreeListBandRow.Count
TcxTreeListBandRow

Returns the number of columns arranged within the current band row.

Syntax

property Count: Integer;

Description
This property returns the number of items within the Items indexed collection.

ReadOnly Property

Related Information

l TcxTreeListBandRow.VisibleItemCount

Page 510 of 1199


TcxTreeListBandRow.First
TcxTreeListBandRow

Provides access to the first visible column within the current band row.

Syntax

property First: TcxTreeListColumn;

Description
This property returns nil if no columns are displayed within the current band row.

ReadOnly Property

Related Information

l TcxTreeListBandRow.IndexOf
l TcxTreeListBandRow.Last
l TcxTreeListBandRow.VisibleItems

Page 511 of 1199


TcxTreeListBandRow.Index
TcxTreeListBandRow

Returns the position of the current band row within a band's collection of band rows.

Syntax

property Index: Integer;

Description
Use the BandRows.Items property to access a particular band row within the collection by its Index property value. To determine
the band row's vertical position within the column header panel, use the VisibleIndex property.

ReadOnly Property

Related Information

l TcxTreeListBandRow.IsFirst
l TcxTreeListBandRow.IsLast

Page 512 of 1199


TcxTreeListBandRow.IndexOf
TcxTreeListBandRow

Returns the position of a specified column within the current band row.

Syntax

function IndexOf(AColumn: TcxTreeListColumn): Integer;

Description
This function returns the position of the column passed as the AColumn parameter within the Items collection.

ReadOnly Property

Page 513 of 1199


TcxTreeListBandRow.IsFirst
TcxTreeListBandRow

Indicates whether the current band row is the first item within a band's collection of band rows.

Syntax

property IsFirst: Boolean;

Description
Use the BandRows.Items collection to access a particular band row by its index.

ReadOnly Property

Related Information

l TcxTreeListBandRow.IsLast

Page 514 of 1199


TcxTreeListBandRow.IsLast
TcxTreeListBandRow

Indicates whether the current band row is the last item within a band's collection of band rows.

Syntax

property IsLast: Boolean;

Description
Use the BandRows.Items collection to access a particular band row by its index.

ReadOnly Property

Related Information

l TcxTreeListBandRow.IsFirst

Page 515 of 1199


TcxTreeListBandRow.Items
TcxTreeListBandRow

Provides indexed access to columns arranged within the current band row.

Syntax

property Items[Index: Integer]: TcxTreeListColumn;

Description
Use the Count property to determine the number of columns within the Items collection. To access columns that are visible
within the band row, use the VisibleItems property.

ReadOnly Property

Related Information

l TcxTreeListBandRow.IndexOf

Page 516 of 1199


TcxTreeListBandRow.Last
TcxTreeListBandRow

Provides access to the last visible column within the current band row.

Syntax

property Last: TcxTreeListColumn;

Description
This property returns nil if no columns are displayed within the current band row.

ReadOnly Property

Related Information

l TcxTreeListBandRow.First
l TcxTreeListBandRow.IndexOf
l TcxTreeListBandRow.VisibleItems

Page 517 of 1199


TcxTreeListBandRow.LineCount
TcxTreeListBandRow

Returns the height of the current band row within the column header panel, in text lines.

Syntax

property LineCount: Integer;

Description
A band row's height is determined as the maximum height of visible columns arranged within this band row.

To specify a column's height, use the column's Position.LineCount property.


Use the VisibleIndex property to get a band row's vertical position within the column header panel. To determine the text line at
which the row is positioned, use the LineOffset property.

ReadOnly Property

Page 518 of 1199


TcxTreeListBandRow.LineOffset
TcxTreeListBandRow

Returns the text line at which the current band row is positioned.

Syntax

property LineOffset: Integer;

Description
The property value is determined as the sum of the LineCount property values of band rows preceding the current band row.
The following image shows three band rows and their LineOffset property values.

ReadOnly Property

Related Information

l TcxTreeListBandRows.VisibleItems

Page 519 of 1199


TcxTreeListBandRow.MinWidth
TcxTreeListBandRow

Returns the minimum width of the current band row, in pixels.

Syntax

property MinWidth: Integer;

Description
This property returns the sum of MinWidth property values of all visible columns arranged within the current band row. To get the
band row's width, use the Width property.

ReadOnly Property

Page 520 of 1199


TcxTreeListBandRow.TreeList
TcxTreeListBandRow

Provides access to the TreeList control to which the band row belongs.

Syntax

property TreeList: TcxCustomTreeList;

Description
To access the control-specific members, cast the TreeList property value to the respective class.

ReadOnly Property

Page 521 of 1199


TcxTreeListBandRow.VisibleIndex
TcxTreeListBandRow

Returns the vertical position of the current band row within the column header panel.

Syntax

property VisibleIndex: Integer;

Description
The VisibleIndex property value determines the band row's position within a band's collection of visible band rows. Use the Index
property to determine the position of the current band row within a band's collection of band rows.

ReadOnly Property

Page 522 of 1199


TcxTreeListBandRow.VisibleItemCount
TcxTreeListBandRow

Returns the number of columns that are visible within the current band row.

Syntax

property VisibleItemCount: Integer;

Description
This property returns the number of items within the VisibleItems indexed collection.

ReadOnly Property

Page 523 of 1199


TcxTreeListBandRow.VisibleItems
TcxTreeListBandRow

Provides indexed access to columns that are visible within the band row.

Syntax

property VisibleItems[Index: Integer]: TcxTreeListColumn;

Description
Use the VisibleItemCount property to determine the number of columns within the VisibleItems collection.
To access all columns arranged within the current band row, use the Items property.

ReadOnly Property

Page 524 of 1199


TcxTreeListBandRow.Width
TcxTreeListBandRow

Returns the band row's width, in pixels.

Syntax

property Width: Integer;

Description
This property returns the sum of Width property values of all visible columns arranged within the current band row. To get the
band row's minimum width, use the MinWidth property.

ReadOnly Property

Page 525 of 1199


TcxTreeListBandStyles.Band
TcxTreeListBandStyles

Provides access to the band to which the current set of styles is applied.
ReadOnly Property

Syntax

property Band: TcxTreeListBand;

Page 526 of 1199


TcxTreeListBandStyles.Content
TcxTreeListBandStyles

Specifies the style for the band's content.

Syntax

property Content: TcxStyle;

Description
The Content property allows you to define the style (font, background color) of all cells within the control. It is possible to
redefine the style for particular cells by handling the OnGetContentStyle event.

Additionally, you can specify the style settings of the band header and footer using the Header and Footer properties.

Page 527 of 1199


TcxTreeListBandStyles.Footer
TcxTreeListBandStyles

Specifies the style for the band's footer.

Syntax

property Footer: TcxStyle;

Description
The Footer property allows you to define the style (font, background color) of all cells within the band footer. It is possible to
redefine the style for particular cells within the band footer by handling the OnGetColumnFooterStyle event.

Additionally, you can specify the style settings of the band's content and header using the Content and Header properties.

Page 528 of 1199


TcxTreeListBandStyles.Header
TcxTreeListBandStyles

Specifies the style for the band header.

Syntax

property Header: TcxStyle;

Description
The Header property allows you to define the style (font, background color) of all headers within the band. It is possible to
redefine the style for particular column headers within the band by handling the OnGetColumnHeaderStyle event.

Additionally, you can specify the style settings of the band's content and footer using the Content and Footer properties.

Page 529 of 1199


TcxTreeListBandStyles.HeaderBackground
TcxTreeListBandStyles

Specifies the background of the band's header.

Syntax

property HeaderBackground: TcxStyle;

Description
The HeaderBackground property allows you to define the background of the band's header. It is possible to redefine the style
by handling the OnGetBandBackgroundStyle event.

Page 530 of 1199


TcxTreeListBandStyles.TreeList
TcxTreeListBandStyles

Provides access to the TreeList control that owns the band to which the current set of styles is applied.
ReadOnly Property

Syntax

property TreeList: TcxCustomTreeList;

Page 531 of 1199


TcxTreeListBands.Add
TcxTreeListBands

Appends a new band to the collection.

Syntax

function Add: TcxTreeListBand;

Description
This function returns a newly created band instance. To associate a column with the band, assign its index within the collection
to the column's Position.BandIndex property.

Examples

l Example: Bands.Add, Bands.Count, Bands

Page 532 of 1199


TcxTreeListBands.BottomItemCount
TcxTreeListBands

Returns the number of bottom bands in the current band collection.

Syntax

property BottomItemCount: Integer;

Description
This property returns the number of items within the BottomItems collection.

ReadOnly Property

Related Information

l TcxTreeListBands.RootItemCount

Page 533 of 1199


TcxTreeListBands.BottomItems
TcxTreeListBands

Provides indexed access to all the bottom bands in the current band collection.

Syntax

property BottomItems[Index: Integer]: TcxTreeListBand;

Description
To determine the number of items within the BottomItems collection, use the BottomItemCount property.

ReadOnly Property

Related Information

l TcxTreeListBands.Items
l TcxTreeListBands.RootItems

Page 534 of 1199


TcxTreeListBands.ColumnLineCount
TcxTreeListBands

Returns the height of the column header panel, in text lines.

Syntax

property ColumnLineCount: Integer;

Description
This property value is calculated as the maximum BandRows.LineCount property value of all bands that are currently visible in the
column header panel.

ReadOnly Property

Page 535 of 1199


TcxTreeListBands.Create
TcxTreeListBands

Creates a new TcxTreeListBands object instance.

Syntax

constructor Create(AOwner: TcxCustomTreeList); virtual;

Description
This constructor calls the inherited constructor and initializes the control's properties and fields. The AOwner parameter is used
to pass an instance of the TcxCustomTreeList class descendant to which the collection belongs. Normally, you do not need to
call the Create constructor.

Page 536 of 1199


TcxTreeListBands.ExpandableBand
TcxTreeListBands

Provides access to the band that displays expand buttons (contains an expandable column).

Syntax

property ExpandableBand: TcxTreeListBand;

Description
If an expandable band is a bottom band, the ExpandableBand property provides access to this band. Otherwise, this property
provides access to an expandable band's first visible bottom child band.

ReadOnly Property

Related Information

l TcxTreeListBand.ActuallyExpandable

Page 537 of 1199


TcxTreeListBands.FirstVisible
TcxTreeListBands

Returns the first visible band within the current band collection.

Syntax

property FirstVisible: TcxTreeListBand;

Description
Use the LastVisible property to access the last visible band in the collection. To access a certain visible band, use VisibleItems
indexed collection.

ReadOnly Property

Page 538 of 1199


TcxTreeListBands.Items
TcxTreeListBands

Returns indexed access to individual bands within the collection.

Syntax

property Items[AIndex: Integer]: TcxTreeListBand;

Description
The AIndex parameter represents the zero-based index of the band.
To determine the number of bands within the collection, use the Count property.

Related Information

l TcxTreeListBands.Add
l TcxTreeListBands.BottomItems
l TcxTreeListBands.RootItems
l TcxTreeListBands.VisibleItems

Page 539 of 1199


TcxTreeListBands.LastVisible
TcxTreeListBands

Returns the last visible band within the current band collection.

Syntax

property LastVisible: TcxTreeListBand;

Description
Use the FirstVisible property to access the first visible band in the collection. To access a certain visible band, use VisibleItems
indexed collection.

ReadOnly Property

Page 540 of 1199


TcxTreeListBands.LineCount
TcxTreeListBands

Returns the number of rows that the band header panel occupies.

Syntax

property LineCount: Integer;

Description
To determine the number of rows that a particular band header occupies, use the band's LineCount property.

ReadOnly Property

Page 541 of 1199


TcxTreeListBands.RestoreDefaults
TcxTreeListBands

Restores the default settings for all bands within the collection.

Syntax

procedure RestoreDefaults; virtual;

Description
Call this procedure to restore the default widths and Options settings for all bands at once. The RestoreDefaults procedure calls
the Options.RestoreDefaults and RestoreWidths procedures for every band within the collection.

Page 542 of 1199


TcxTreeListBands.RestoreWidths
TcxTreeListBands

Restores the default widths of all bands within the collection.

Syntax

procedure RestoreWidths; virtual;

Description
Call this procedure to restore the default width of all the collection's bands at once. The RestoreWidths procedure calls the
RestoreWidths procedure for every band within the collection.
Call the RestoreDefaults procedure to restore the default settings of all bands within the collection.

Related Information

l TcxTreeListBand.RestoreDefaults
l TcxTreeListBand.RestoreWidths

Page 543 of 1199


TcxTreeListBands.RootItemCount
TcxTreeListBands

Returns the number of root bands in the current band collection.

Syntax

property RootItemCount: Integer;

Description
This property returns the number of items within the RootItems collection.

ReadOnly Property

Related Information

l TcxTreeListBands.BottomItemCount

Page 544 of 1199


TcxTreeListBands.RootItems
TcxTreeListBands

Provides indexed access to all the root bands in the current band collection.

Syntax

property RootItems[Index: Integer]: TcxTreeListBand;

Description
To determine the number of items within the RootItems collection, use the RootItemCount property.

ReadOnly Property

Related Information

l TcxTreeListBands.BottomItems
l TcxTreeListBands.Items

Page 545 of 1199


TcxTreeListBands.TreeList
TcxTreeListBands

Provides access to the TreeList control to which the current band collection belongs.

Syntax

property TreeList: TcxCustomTreeList;

Description
To access the control-specific members, cast the TreeList property value to the respective class.

ReadOnly Property

Page 546 of 1199


TcxTreeListBands.VisibleIndexOf
TcxTreeListBands

Returns the position of a specified band within the VisibleItems collection.

Syntax

function VisibleIndexOf(ABand: TcxTreeListBand): Integer;

Description
The band is passed as the ABand parameter.

Page 547 of 1199


TcxTreeListBands.VisibleItemCount
TcxTreeListBands

Returns the number of visible bands in the current band collection.

Syntax

property VisibleItemCount: Integer;

Description
This property returns the number of items within the VisibleItems collection.

ReadOnly Property

Related Information

l TcxTreeListBands.VisibleLeftFixedCount
l TcxTreeListBands.VisibleRightFixedCount
l TcxTreeListBands.VisibleRootItemCount
l TcxTreeListBands.VisibleRootLeftFixedCount
l TcxTreeListBands.VisibleRootRightFixedCount

Page 548 of 1199


TcxTreeListBands.VisibleItems
TcxTreeListBands

Provides indexed access to all visible bands in the current band collection.

Syntax

property VisibleItems[Index: Integer]: TcxTreeListBand;

Description
To determine the number of items within the VisibleItems collection, use the VisibleItemCount property.

ReadOnly Property

Related Information

l TcxTreeListBands.FirstVisible
l TcxTreeListBands.Items
l TcxTreeListBands.LastVisible
l TcxTreeListBands.VisibleIndexOf
l TcxTreeListBands.VisibleRootItems

Page 549 of 1199


TcxTreeListBands.VisibleLeftFixedCount
TcxTreeListBands

Returns the number of visible bands that are fixed to the left edge of the TreeList control.

Syntax

property VisibleLeftFixedCount: Integer;

Description
The VisibleLeftFixedCount property value includes the VisibleRootLeftFixedCount property value.

ReadOnly Property

Related Information

l TcxTreeListBands.VisibleItemCount
l TcxTreeListBands.VisibleRightFixedCount
l TcxTreeListBands.VisibleRootLeftFixedCount

Page 550 of 1199


TcxTreeListBands.VisibleRightFixedCount
TcxTreeListBands

Returns the number of visible bands that are fixed to the right edge of the TreeList control.

Syntax

property VisibleRightFixedCount: Integer;

Description
The VisibleRightFixedCount property value includes the VisibleRootRightFixedCount property value.

ReadOnly Property

Related Information

l TcxTreeListBands.VisibleItemCount
l TcxTreeListBands.VisibleLeftFixedCount
l TcxTreeListBands.VisibleRootRightFixedCount

Page 551 of 1199


TcxTreeListBands.VisibleRootItemCount
TcxTreeListBands

Returns the number of visible root bands in the current band collection.

Syntax

property VisibleRootItemCount: Integer;

Description
This property returns the number of items within the VisibleRootItems collection.

ReadOnly Property

Related Information

l TcxTreeListBand.Visible
l TcxTreeListBands.VisibleItemCount
l TcxTreeListBands.VisibleRootLeftFixedCount
l TcxTreeListBands.VisibleRootRightFixedCount

Page 552 of 1199


TcxTreeListBands.VisibleRootItems
TcxTreeListBands

Provides indexed access to visible root bands in the current band collection.

Syntax

property VisibleRootItems[Index: Integer]: TcxTreeListBand;

Description
To determine the number of items within the VisibleRootItems collection, use the VisibleRootItemCount property.

ReadOnly Property

Related Information

l TcxTreeListBand.Visible
l TcxTreeListBands.VisibleItems
l TcxTreeListBands.VisibleRootLeftFixedCount
l TcxTreeListBands.VisibleRootRightFixedCount

Page 553 of 1199


TcxTreeListBands.VisibleRootLeftFixedCount
TcxTreeListBands

Returns the number of visible root bands that are fixed to the left edge of the TreeList control.
ReadOnly Property

Syntax

property VisibleRootLeftFixedCount: Integer;

Related Information

l TcxTreeListBands.VisibleLeftFixedCount
l TcxTreeListBands.VisibleRootItemCount
l TcxTreeListBands.VisibleRootRightFixedCount

Page 554 of 1199


TcxTreeListBands.VisibleRootRightFixedCount
TcxTreeListBands

Returns the number of visible root bands that are fixed to the right edge of the TreeList control.
ReadOnly Property

Syntax

property VisibleRootRightFixedCount: Integer;

Related Information

l TcxTreeListBands.VisibleRightFixedCount
l TcxTreeListBands.VisibleRootItemCount
l TcxTreeListBands.VisibleRootLeftFixedCount

Page 555 of 1199


TcxTreeListBand.ActuallyExpandable
TcxTreeListBand

Indicates whether the current band or one of its child bands displays expand buttons.

Syntax

property ActuallyExpandable: Boolean;

Description
This property returns True if any of the following conditions are met:
l The current band is expandable.
l One of the band's child bands is expandable.

To access the band that displays expand buttons, use the TreeList control's Bands.ExpandableBand property.

ReadOnly Property

Page 556 of 1199


TcxTreeListBand.ActuallyVisible
TcxTreeListBand

Indicates whether the current band displays its contents within the TreeList control.

Syntax

property ActuallyVisible: Boolean;

Description
This property returns True if the following conditions are met:
l The band's Visible property is set to True.
l The band is not nested.
l If the band is nested, its parent band's ActuallyVisible property returns True.

To determine whether the column's header is displayed within the TreeList control, use a column's IsHidden property.

ReadOnly Property

Page 557 of 1199


TcxTreeListBand.ApplyBestFit
TcxTreeListBand

Adjusts the band's width to the minimum, required to display the content of all columns in their entirety.

Syntax

procedure ApplyBestFit;

Description
This method iterates through the band's visible columns and calls their ApplyBestFit method.

End-users can double-click a band header's right edge to apply Best Fit to this band. To prevent end-users from changing the
band's width in this manner, disable the band's Options.Sizing property or the TreeList control's
OptionsCustomizing.BandHorzSizing property.

To limit a column's width to a certain value when applying Best Fit to this column, use the column's BestFitMaxWidth property.

Examples

l Example: Band.ApplyBestFit, TreeList.FullExpand

Related Information

l TcxCustomTreeList.ApplyBestFit
l TcxTreeListColumn.ApplyBestFit

Page 558 of 1199


TcxTreeListBand.Assign
TcxTreeListBand

Copies the properties of another band.

Syntax

procedure Assign(Source: TPersistent); override;

Description
The Assign method copies properties from the band specified via the Source parameter. The values returned by the
DisplayWidth, MinWidth and Width properties of the source object are assigned to the corresponding properties of the band. The
band's visibility is determined by the Visible property value of the source. Band options (see Options) and style settings (see
Styles) as well as the caption (see Caption) and the FixedKind property value are copied.

Page 559 of 1199


TcxTreeListBand.BandRows
TcxTreeListBand

Provides access to the collection of band rows associated with the current band.

Syntax

property BandRows: TcxTreeListBandRows;

Description
Use the BandRows.Items property to access a specific row by its index within the collection. Refer to the TcxTreeListBandRows
class description for detailed information on available options.

ReadOnly Property

Page 560 of 1199


TcxTreeListBand.Bands
TcxTreeListBand

Provides access to the collection to which the current band belongs.


ReadOnly Property

Syntax

property Bands: TcxTreeListBands;

Page 561 of 1199


TcxTreeListBand.Caption
TcxTreeListBand

Provides access to the object representing the band's caption.

Syntax

property Caption: TcxTreeListCaption;

Description
The Caption property exposes a TcxTreeListCaption instance whose members can be used to customize the band caption's
look and feel. Also, you are able to specify the horizontal and vertical alignment of the caption's text, whether its contents can be
displayed over several lines and whether an image is displayed within the caption area.

Page 562 of 1199


TcxTreeListBand.ChildBandCount
TcxTreeListBand

Returns the number of immediate child bands assigned to the current band.

Syntax

property ChildBandCount: Integer;

Description
This property returns the number of items within the ChildBands collection.

ReadOnly Property

Related Information

l TcxTreeListOptionsCustomizing.NestedBands

Page 563 of 1199


TcxTreeListBand.ChildBands
TcxTreeListBand

Provides indexed access to the immediate child bands nested within the current band.

Syntax

property ChildBands[Index: Integer]: TcxTreeListBand;

Description
To determine the number of items within the ChildBands collection, use the ChildBandCount property.

ReadOnly Property

Concepts

l Nested Bands

Page 564 of 1199


TcxTreeListBand.ColumnCount
TcxTreeListBand

Returns the number of columns associated with the current band.

Syntax

property ColumnCount: Integer;

Description
This property returns the number of elements within the Columns collection. To access all columns created within the TreeList
control, use its Columns zero-based indexed collection.
To determine the number of columns that are visible within a band, use its VisibleColumnCount property.
Note:   If a band is not a bottom band, the ColumnCount property returns 0.

ReadOnly Property

Page 565 of 1199


TcxTreeListBand.Columns
TcxTreeListBand

Provides indexed access to columns associated with the current band.

Syntax

property Columns[Index: Integer]: TcxTreeListColumn;

Description
Use the ColumnCount property to determine the number of columns within the Columns collection.
To access a band's visible columns, use its VisibleColumns zero-based indexed collection.
Note:   If a band is not a bottom band, the Columns collection is empty.

Page 566 of 1199


TcxTreeListBand.Create
TcxTreeListBand

Creates and initializes a TcxTreeListBand class instance.

Syntax

constructor Create(Collection: TCollection); override;

Description
Use the constructor when you need to create a band manually. The constructor creates a list to hold visible columns (the list will
contain only those columns whose Visible property returns True), a list for all columns (unlike the previous list, this one will
contain all columns associated with the band), initializes the band options (see Options) and the style settings of the band (see
Styles), creates the band's caption object (see Caption) and finally sets the Visible property of the band to True.

Related Information

l TcxCustomTreeList.CreateColumn

Page 567 of 1199


TcxTreeListBand.Destroy
TcxTreeListBand

Destroys the band.

Syntax

destructor Destroy; override;

Description
It is best to use the Free method, which calls Destroy.
The destructor destroys the band's Caption object, its column list (which contains all columns associated with the band), its list
of visible columns (which only contains those columns whose Visible property returns True) and its Options & Styles objects.

Page 568 of 1199


TcxTreeListBand.DisplayWidth
TcxTreeListBand

Returns the band's width on screen, in pixels.

Syntax

property DisplayWidth: Integer;

Description
The return value is determined by the combined width of all the band's child bands and their columns. To specify the band's
width, use its Width property.

ReadOnly Property

Related Information

l TcxTreeListColumn.DisplayWidth

Page 569 of 1199


TcxTreeListBand.FixedKind
TcxTreeListBand

Specifies whether the band is involved in horizontal scrolling.

Syntax

type
TcxTreeListBandFixedKind = (tlbfNone, tlbfLeft, tlbfRight);
property FixedKind: TcxTreeListBandFixedKind;

Description
Options include:

Value Meaning

tlbfNone The band is not fixed.

tlbfLeft The band is fixed to the TreeList control's left side.

tlbfRight The band is fixed to the TreeList control's right side.

For more detailed information about fixed bands, refer to the Bands article.

The default value of the FixedKind property is tlbfNone.

Related Information

l TcxTreeListBands.VisibleLeftFixedCount
l TcxTreeListBands.VisibleRightFixedCount
l TcxTreeListBands.VisibleRootLeftFixedCount
l TcxTreeListBands.VisibleRootRightFixedCount

Page 570 of 1199


TcxTreeListBand.HasAsParent
TcxTreeListBand

Determines whether the current band has a specified band as a parent band.

Syntax

function HasAsParent(ABand: TcxTreeListBand): Boolean;

Description
This function performs a recursive search of the parent bands and returns True if the current band or one of its parent bands has
the band specified by the ABand parameter as a parent band. Otherwise, this function returns False.

Related Information

l TcxTreeListBand.ParentBand
l TcxTreeListBandPosition.BandIndex
l TcxTreeListBandPosition.ParentBand

Page 571 of 1199


TcxTreeListBand.IndentWidth
TcxTreeListBand

Determines the increment (in pixels) by which a band containing an expandable band is increased during node expansion.

Syntax

property IndentWidth: Integer;

Description
The resulting band width is returned by the DisplayWidth property.

ReadOnly Property

Page 572 of 1199


TcxTreeListBand.Index
TcxTreeListBand

Returns the band index within the TreeList control's Bands collection.

Syntax

property Index;

Description
To determine the band index within the Bands.VisibleItems collection, use the VisibleIndex property.

Page 573 of 1199


TcxTreeListBand.IndexOf
TcxTreeListBand

Returns the position of a specified band within the current band's ChildBands collection.

Syntax

function IndexOf(AChildBand: TcxTreeListBand): Integer;

Description
The AChildBand parameter specifies the child band.
If AChildBand is not a child band of the current band, –1 is returned.

Related Information

l TcxTreeListBand.HasAsParent

Page 574 of 1199


TcxTreeListBand.IsBottom
TcxTreeListBand

Specifies whether the current band is at the bottom of the TreeList control's band hierarchy.

Syntax

property IsBottom: Boolean;

Description
This property returns True for a band that has no child bands. Only these bands have rows in which columns are arranged. To
access a particular bottom band, use a band's Bands.BottomItems collection.

ReadOnly Property

Related Information

l TcxTreeListColumn Object

Page 575 of 1199


TcxTreeListBand.IsLastAsChild
TcxTreeListBand

Determines whether the current band is the last visible band within its parent band.

Syntax

property IsLastAsChild: Boolean;

Description
This property returns True if any of the following conditions are met:
l The current band is nested and it's the last visible child band within its parent band.
l The current band isn't nested and it's the last visible root band.

ReadOnly Property

Page 576 of 1199


TcxTreeListBand.IsLeftMost
TcxTreeListBand

Indicates whether the band is the leftmost one displayed within the control.

Syntax

property IsLeftMost: Boolean;

Description
When this property returns True, the band's VisibleIndex returns 0.
To determine whether the band is the rightmost one within the control, use the IsRightMost property.

ReadOnly Property

Page 577 of 1199


TcxTreeListBand.IsRightMost
TcxTreeListBand

Indicates whether the band is the rightmost one displayed within the control.

Syntax

property IsRightMost: Boolean;

Description
When this property returns True, the band is located at the right of the control.
To determine whether the band is the leftmost one within the control, use the IsLeftMost property.

ReadOnly Property

Page 578 of 1199


TcxTreeListBand.IsRoot
TcxTreeListBand

Identifies if the band is at the root level.

Syntax

property IsRoot: Boolean;

Description
This property returns True if the band is not nested (that is, has no parent bands); otherwise – False. Use the Bands.RootItems
and Bands.VisibleRootItems properties to access the bands at the root level.

ReadOnly Property

Related Information

l TcxTreeListBand.RootIndex
l TcxTreeListBand.VisibleRootIndex
l TcxTreeListBandPosition.BandIndex

Page 579 of 1199


TcxTreeListBand.Level
TcxTreeListBand

Returns the band's nesting level.

Syntax

property Level: Integer;

Description
This property returns 0 if the band is at the root level (that is, the ParentBand property is nil).

ReadOnly Property

Page 580 of 1199


TcxTreeListBand.LineCount
TcxTreeListBand

Returns the number of rows that the current band's header occupies within the band header panel.

Syntax

property LineCount: Integer;

Description
For hidden bands, this property returns 0.
Use the TreeList control's BandLineHeight property to specify the height of a band header row, in pixels.

ReadOnly Property

Page 581 of 1199


TcxTreeListBand.MinWidth
TcxTreeListBand

Specifies the band's minimum width, in pixels.

Syntax

property MinWidth: Integer;

Description
Use this property to change the lower bound of the Width property values. To identify the band's display width, use the
DisplayWidth property.

The MinWidth property automatically updates by multiplying its current value by the form's scaling factor every time it changes
at design-time or runtime.

Set the TreeList control's OptionsCustomizing.BandHorzSizing property to True to allow end-users to adjust the band's width.

The default value of the MinWidth property is cxTreeListDefMinWidth.

Page 582 of 1199


TcxTreeListBand.MoveBand
TcxTreeListBand

Nests a specific band at the specified position within the current band.

Syntax

procedure MoveBand(ABand: TcxTreeListBand; AColIndex: Integer);

Description
The ABand parameter specifies the band being moved.
The AColIndex parameter specifies the possible position of the band within the current band. This parameter value corresponds to
a band's Position.ColIndex property value.

Page 583 of 1199


TcxTreeListBand.OnGetStoredProperties
TcxTreeListBand

Enables you to customize a list of the current band's properties to be stored to external data stores.

Syntax

type
TcxGetStoredPropertiesEvent = procedure(Sender: TObject; AProperties: TStrings) of object;
property OnGetStoredProperties: TcxGetStoredPropertiesEvent;

Description
Whenever the storing process is started by the StoreToIniFile, StoreToRegistry, or StoreToStream method call, a list of the properties
to store is produced. When the OnGetStoredProperties event is fired, the list is already populated with band property names, which
are stored by default. These property names are specified by the BandPropertiesName global constant. You can add custom property
names to the list and handle the band's OnGetStoredPropertyValue and OnSetStoredPropertyValue events to provide property values t
be saved to and restored from a data store. Make certain that items in the list uniquely identify the property names they correspond to.
The Sender parameter specifies the current band.
The AProperties parameter provides access to the list of properties to be stored.

The following code represents an OnGetStoredProperties event handler, demonstrating how to extend the list with an item that
corresponds to a band's Expandable property.

[Delphi]
procedure <Form>.<Band>GetStoredProperties(Sender: TObject; AProperties: TStrings);
begin
AProperties.Add('Expandable');
end;

[C++ Builder]
void __fastcall <Form>::<Band>GetStoredProperties(TObject *Sender, TStrings *AProperties)
{
AProperties->Add("Expandable");
}

Note:   To customize the manner in which tree list properties are persisted, handle the tree list's OnGetStoredProperties,
OnGetStoredPropertyValue, and OnSetStoredPropertyValue events. To customize the manner in which column properties are
persisted, handle a column's OnGetStoredProperties, OnGetStoredPropertyValue, and OnSetStoredPropertyValue events.

Concepts

l Save and Restore Layout

Related Information

l TcxCustomTreeList.OnGetStoredProperties
l TcxTreeListColumn.OnGetStoredProperties

Page 584 of 1199


TcxTreeListBand.OnGetStoredPropertyValue
TcxTreeListBand

Enables you to provide values for band properties to be saved to external data stores.

Syntax

type
TcxGetStoredPropertyValueEvent = procedure(Sender: TObject; const AName: string; var AValu
property OnGetStoredPropertyValue: TcxGetStoredPropertyValueEvent;

Description
This event is fired for each property (including default properties) within the list specified in the band's OnGetStoredProperties event han
properties, handle the OnSetStoredPropertyValue event.
The Sender parameter specifies the current band.
The AName parameter identifies the property name.
Pass the property value as the AValue parameter.

The following code represents an OnGetStoredPropertyValue event handler demonstrating how to save the values of a band's Expan
specified for storing within the band's OnGetStoredProperties event handler.

[Delphi]
procedure <Form>.<Band>GetStoredPropertyValue(Sender: TObject; const AName: String; var AValue:
begin
if Sender is TcxTreeListBand then
begin
if AName = 'Expandable' then
begin
AValue := TcxTreeListBand(Sender).Expandable;
Exit;
end;
end;
end;

[C++ Builder]
void __fastcall <Form>::<Band>GetStoredPropertyValue(TObject *Sender, const AnsiString AName, Va
{
if(AName == "Expandable") {
if(dynamic_cast<TcxTreeListBand*>(Sender)) {
TcxTreeListBand * ABand = (TcxTreeListBand *)Sender;
AValue = ABand->Expandable;
return;
}
}
}

Concepts

l Save and Restore Layout


Page 585 of 1199
TcxTreeListBand.OnSetStoredPropertyValue
TcxTreeListBand

Enables you to restore the current band's property values from external data stores.

Syntax

type
TcxSetStoredPropertyValueEvent = procedure(Sender: TObject; const AName: string; const AVa
property OnSetStoredPropertyValue: TcxSetStoredPropertyValueEvent;

Description
This event is fired for each property (including default properties) within the list specified in the band's OnGetStoredProperties event han
OnSetStoredPropertyValue event to restore custom property values that were explicitly specified via the OnGetStoredPropertyValue
The Sender parameter specifies the current band.
The AName parameter identifies the property name. Its value is returned by the AValue parameter. Use this value to assign a correspo

The following code represents an OnSetStoredPropertyValue event handler demonstrating how to restore a band's Expandable prope
the band's OnGetStoredPropertyValue event handler.

[Delphi]
procedure <Form>.<Band>SetStoredPropertyValue(Sender: TObject; const AName: String; const AValue
begin
if Sender is TcxTreeListBand then
begin
if AName = 'Expandable' then
begin
TcxTreeListBand(Sender).Expandable := AValue;
Exit;
end;
end;
end;

[C++ Builder]
void __fastcall <Form>::<Band>SetStoredPropertyValue(TObject *Sender, const AnsiString AName, co
{
if(AName == "Expandable") {
if(dynamic_cast<TcxTreeListBand*>(Sender)) {
TcxTreeListBand * ABand = (TcxTreeListBand *)Sender;
ABand->Expandable = AValue;
return;
}
}
}

Concepts

l Save and Restore Layout

Page 586 of 1199


Related Information
TcxTreeListBand.Options
TcxTreeListBand

Provides access to the band's appearance and behavior options.

Syntax

property Options: TcxTreeListBandOptions;

Description
You can use this property to hide or display the band, and manage the band customization capabilities available to end-users.
Refer to the TcxTreeListBandOptions class description for detailed information on available options.

Page 587 of 1199


TcxTreeListBand.ParentBand
TcxTreeListBand

Provides access to the band's immediate parent.

Syntax

property ParentBand: TcxTreeListBand;

Description
Use this property to access the band's parent. The ParentBand property returns nil if the band is at the root level. You can use
the Position.BandIndex property to assign a parent for the band.

ReadOnly Property

Related Information

l TcxTreeListBand.RootParentBand
l TcxTreeListBandPosition.ParentBand

Page 588 of 1199


TcxTreeListBand.Position
TcxTreeListBand

Provides access to settings that specify the band's position within the TreeList control.

Syntax

property Position: TcxTreeListBandPosition;

Description
Refer to the TcxTreeListBandPosition class description, to learn about available settings.

Page 589 of 1199


TcxTreeListBand.RestoreDefaults
TcxTreeListBand

Restores the band's default settings.

Syntax

procedure RestoreDefaults; virtual;

Description
This procedure calls the Options.RestoreDefaults and RestoreWidths procedures internally.

Related Information

l TcxTreeListBands.RestoreDefaults

Page 590 of 1199


TcxTreeListBand.RestoreWidths
TcxTreeListBand

Restores the band's default width.

Syntax

procedure RestoreWidths;

Description
Call this procedure to reset the MinWidth and Width properties to their default values (that is, cxTreeListDefMinWidth and 0,
respectively).
Call the RestoreDefaults procedure to restore all the band's settings to the default values.

Related Information

l TcxTreeListBands.RestoreWidths

Page 591 of 1199


TcxTreeListBand.RootIndex
TcxTreeListBand

Returns the band's position within root bands.

Syntax

property RootIndex: Integer;

Description
For root bands, this property returns a band's position within the TreeList control's Bands.RootItems indexed collection. For all
other bands, the RootIndex property returns –1.
To determine the visible position of the band's header within the band header panel, use the VisibleRootIndex property.

Page 592 of 1199


TcxTreeListBand.RootParentBand
TcxTreeListBand

Provides access to the root band that nests the current band.

Syntax

property RootParentBand: TcxTreeListBand;

Description
If a band is nested, this property iterates all parent bands to return the root band to which the band corresponds. For root bands,
the RootParentBand property returns nil.

ReadOnly Property

Related Information

l TcxTreeListBand.ParentBand

Page 593 of 1199


TcxTreeListBand.Styles
TcxTreeListBand

Specifies the band's various style settings.

Syntax

property Styles: TcxTreeListBandStyles;

Description
Using the object exposed via the Styles property, you can define the style settings of the contents, footer and header elements
of the band.

Page 594 of 1199


TcxTreeListBand.TreeList
TcxTreeListBand

Provides access to the TreeList control to which the band belongs.


Description
To access the control-specific members, cast the TreeList property value to the respective class.

ReadOnly Property

Syntax

property TreeList: TcxCustomTreeList;

Page 595 of 1199


TcxTreeListBand.Visible
TcxTreeListBand

Indicates whether the band is visible.

Syntax

property Visible: Boolean;

Description
Read the Visible property to determine whether the band is visible. Set the property to True (default) to make the band visible.
Set it to False to hide the band. Additionally, you can hide all bands by setting the Bands property to False.

The default value of the Visible property is True.

Page 596 of 1199


TcxTreeListBand.VisibleColumnCount
TcxTreeListBand

Returns the number of visible columns within the band.

Syntax

property VisibleColumnCount: Integer;

Description
Columns whose Visible property returns True are displayed within the band. To obtain indexed access to individual visible
columns, use the object exposed via the band's VisibleColumns property.

ReadOnly Property

Related Information

l TcxCustomTreeList.ColumnCount
l TcxCustomTreeList.Columns
l TcxCustomTreeList.VisibleColumnCount
l TcxCustomTreeList.VisibleColumns

Page 597 of 1199


TcxTreeListBand.VisibleColumns
TcxTreeListBand

Provides indexed access to individual visible columns.

Syntax

property VisibleColumns[Index: Integer]: TcxTreeListColumn;

Description
Columns within this collection follow each other in consecutive order as they appear in the TreeList control - from left to right, top
to bottom.
The column is visible when its Visible property value is True.
To determine the number of visible columns within a band, use the band's VisibleColumnCount property.

Related Information

l TcxCustomTreeList.ColumnCount
l TcxCustomTreeList.Columns
l TcxCustomTreeList.VisibleColumnCount
l TcxCustomTreeList.VisibleColumns

Page 598 of 1199


TcxTreeListBand.VisibleIndex
TcxTreeListBand

Returns the current band's position within the collection of visible bands.

Syntax

property VisibleIndex: Integer;

Description
To determine the band's position within all created bands, use the Index property.

ReadOnly Property

Related Information

l TcxTreeListBandRows.VisibleItemCount
l TcxTreeListBandRows.VisibleItems

Page 599 of 1199


TcxTreeListBand.VisibleRootIndex
TcxTreeListBand

Returns the band header's position within root band headers.

Syntax

property VisibleRootIndex: Integer;

Description
For root bands, this property returns a band's position within the TreeList control's Bands.VisibleRootItems indexed collection.
For all other bands, the VisibleRootIndex property returns –1.
To access all root bands created within the TreeList control, use the Bands.RootItems indexed collection.

ReadOnly Property

Page 600 of 1199


TcxTreeListBand.Width
TcxTreeListBand

Specifies the band's width, in pixels.

Syntax

property Width: Integer;

Description
Use this property to set the custom band width. It cannot be less than the MinWidth property value. If the Width property is set
to:
l A custom value, changing the width of the band's child bands or their columns does not affect the current band's width.
l 0 (that is, by default), the band's width is calculated automatically based on the combined width of all the band's child
bands and their columns.

The TreeList control automatically adjusts the display widths of columns and bands when its OptionsView.ColumnAutoWidth
property is set to True and the ApplyBestFit procedure is invoked. Use the DisplayWidth property to identify the band's width on
a screen.

The Width property automatically updates by multiplying its current value by the form's scaling factor every time it changes at
design-time or runtime.

To restore the band's default MinWidth and Width property values, call the RestoreWidths procedure.

Note:   Invoking the ApplyBestFit procedure provided by a TreeList control or the band sets the Width property to 0.

The default value of the Width property is 0.

Page 601 of 1199


TcxTreeListBuiltInMenu.PopupMenu
TcxTreeListBuiltInMenu

Provides access to a TPopupMenu object representing the current built-in context menu.

Syntax

property PopupMenu: TPopupMenu;

Description
Do not use this property directly to manage built-in menu content. In context menus, you should call a context menu's
CreateMenuItem function to populate the associated built-in menu with items.

ReadOnly Property

Page 602 of 1199


TcxTreeListCaption.AlignHorz
TcxTreeListCaption

Specifies the horizontal alignment of the caption's text.

Syntax

property AlignHorz: TAlignment;

Description
Use the AlignHorz property to specify the horizontal alignment of the caption's text. To specify the vertical alignment, use the
AlignVert property.

Additionally, you can specify the horizontal alignment of the glyph displayed within the caption by using the GlyphAlignHorz
property.

The default value of the AlignHorz property is taLeftJustify.

Page 603 of 1199


TcxTreeListCaption.AlignVert
TcxTreeListCaption

Specifies the vertical alignment of the caption's text.

Syntax

type
TcxAlignmentVert = (vaTop, vaBottom, vaCenter);
property AlignVert: TcxAlignmentVert;

Description
Use the AlignVert property to specify the vertical alignment of the caption's text. To specify the horizontal alignment, use the
AlignHorz property.

Additionally, you can specify the vertical alignment of the glyph displayed within the caption using the GlyphAlignVert property.

The default value of the AlignVert property is vaTop.

Page 604 of 1199


TcxTreeListCaption.Glyph
TcxTreeListCaption

Defines the image displayed within the caption.

Syntax

property Glyph: TdxSmartGlyph;

Description
Use the Glyph property to define the image displayed within the caption.

You can specify the horizontal and vertical alignment of the caption's image using the GlyphAlignHorz and GlyphAlignVert
properties.

Page 605 of 1199


TcxTreeListCaption.GlyphAlignHorz
TcxTreeListCaption

Specifies the horizontal alignment of the image displayed within the caption.

Syntax

property GlyphAlignHorz: TAlignment;

Description
Use the GlyphAlignHorz property to specify the horizontal alignment of the image displayed within the caption.
Additionally, you can specify the vertical alignment of the caption image by using the GlyphAlignVert property.

To define the image to be displayed within the caption, use the Glyph property.

The default value of the GlyphAlignHorz property is taLeftJustify.

Page 606 of 1199


TcxTreeListCaption.GlyphAlignVert
TcxTreeListCaption

Specifies the vertical alignment of the image displayed within the caption.

Syntax

type
TcxAlignmentVert = (vaTop, vaBottom, vaCenter);
property GlyphAlignVert: TcxAlignmentVert;

Description
Use the GlyphAlignVert property to specify the vertical alignment of the image displayed within the caption.
Additionally, you can specify the horizontal alignment of the caption image using the GlyphAlignHorz property.

To define the image to be displayed within the caption, use the Glyph property.

The default value of the GlyphAlignVert property is vaTop.

Page 607 of 1199


TcxTreeListCaption.MultiLine
TcxTreeListCaption

Specifies whether the caption's text can be displayed in several lines.

Syntax

property MultiLine: Boolean;

Description
The property is only in effect when the caption width is insufficient to display its entire text. When the property is set to True, the
text can be displayed in multiple lines within the caption (if the caption area is tall enough). If set to False, text clipping may
occur.
To allow the height of band rows to be automatically adjusted to completely display column header captions, set the TreeList
control's OptionsView.HeaderAutoHeight property to True.

The default value of the MultiLine property is False.

Page 608 of 1199


TcxTreeListCaption.ShowEndEllipsis
TcxTreeListCaption

Specifies whether an end ellipsis is displayed when the caption's width is insufficient to display its entire text.

Syntax

property ShowEndEllipsis: Boolean;

Description
The property is only in effect when the text width (see Text) is greater than the caption's width. In this case, setting the property
to True appends the truncated caption text with an ellipsis. The end-user should resize the caption to see its whole text.
Otherwise, setting the property to False disables the end ellipsis.

You can allow the end-user to display the caption's contents in several lines by using the MultiLine property.

The default value of the ShowEndEllipsis property is True.

Related Information

l TcxTreeListOptionsBehavior.HeaderHints

Page 609 of 1199


TcxTreeListCaption.Text
TcxTreeListCaption

Defines the caption text.

Syntax

property Text: string;

Description
Use the Text property to define the caption's text. This value will be displayed within the caption.

You can specify the horizontal and vertical alignment of the text by using the AlignHorz and AlignVert properties.

Additionally, you can add an image to the caption by using the Glyph property.

Page 610 of 1199


TcxTreeListColumnHeaderPopupMenu.Items
TcxTreeListColumnHeaderPopupMenu

Specifies the visibility of menu items.

Syntax

type
TcxTreeListColumnHeaderPopupMenuItem = (tlchmiSortAscending, tlchmiSortDescending, tlchmiC
TcxTreeListColumnHeaderPopupMenuItems = set of TcxTreeListColumnHeaderPopupMenuItem;
property Items: TcxTreeListColumnHeaderPopupMenuItems;

Description
Set an option flag within the Items property to make a corresponding menu item visible.
The image and table below show menu items and corresponding option flags and command identity values used to create these items,

# Option Flag Command Identity Value

1 tlchmiSortAscending tlcmSortAscending

2 tlchmiSortDescending tlcmSortDescending

3 tlchmiClearSorting tlcmClearSorting

4 tlchmiFooter tlcmFooter

5 tlchmiGroupFooters Sub-menu items:


tlcmGroupFootersInvisible
tlcmGroupFootersVisibleWhenExpanded
tlcmGroupFootersAlwaysVisible

6 tlchmiRemoveThisColumn tlcmRemoveThisColumn

7 tlchmiFieldChooser tlcmFieldChooser

8 tlchmiHorzAlignment Sub-menu items:


tlcmHorzAlignmentLeft
tlcmHorzAlignmentCenter
tlcmHorzAlignmentRight

9 tlchmiVertAlignment Sub-menu items:


Page 611 of 1199
tlcmVertAlignmentTop
TcxTreeListColumnOptions.CellEndEllipsis
TcxTreeListColumnOptions

Specifies whether to display an ellipsis within column cells with truncated content.

Syntax

property CellEndEllipsis: Boolean;

Description
If the TreeList control's OptionsView.CellEndEllipsis option is disabled, a column's CellEndEllipsis property value is ignored.

The default value of the CellEndEllipsis property is True.

Related Information

l TcxTreeListOptionsBehavior.FooterHints
l ExpressEditors: TcxControlOptionsBehavior.CellHints

Page 612 of 1199


TcxTreeListColumnOptions.Column
TcxTreeListColumnOptions

Provides access to the column containing the current option set.


ReadOnly Property

Syntax

property Column: TcxTreeListColumn;

Page 613 of 1199


TcxTreeListColumnOptions.EditAutoHeight
TcxTreeListColumnOptions

Specifies the sizing mode for the column's multi-line in-place editor.

Syntax

type
TcxItemInplaceEditAutoHeight = (ieahDefault, iaehNone);
property EditAutoHeight: TcxItemInplaceEditAutoHeight;

Description
Options include:

Value Meaning

ieahDefault The column's in-place editor is sized as specified by the tree list's
OptionsBehavior.EditAutoHeight property.

iaehNone No sizing. The in-place editor's height remains unchanged – it occupies


an entire cell. An editor automatically wraps and vertically scrolls its
content. The tree list's OptionsBehavior.EditAutoHeight property value is
ignored for this column.

Important Note: Auto sizing is not supported by drop-down editors, non-text editors, editors with embedded buttons, or input
mask text editors.

The default value of the EditAutoHeight property is ieahDefault.

Page 614 of 1199


TcxTreeListColumnOptions.Footer
TcxTreeListColumnOptions

Specifies whether footer cells are displayed for the column.

Syntax

property Footer: Boolean;

Description
Set this property to True to display footer cells for the column within the TreeList control's footer.

The default value of the Footer property is True.

Related Information

l TcxTreeListColumnOptions.GroupFooter

Page 615 of 1199


TcxTreeListColumnOptions.GroupFooter
TcxTreeListColumnOptions

Specifies whether group footer cells are displayed for the column.

Syntax

property GroupFooter: Boolean;

Description
Set this property to True to display group footer cells for the column within the TreeList control's group footers.

The default value of the GroupFooter property is True.

Related Information

l TcxTreeListColumnOptions.Footer

Page 616 of 1199


TcxTreeListColumnOptions.Hidden
TcxTreeListColumnOptions

Specifies the visibility of the column within the customization form.

Syntax

property Hidden: Boolean;

Description
Set this property to True to hide the column in the customization form. This prohibits end-users from placing this column back to
the TreeList control.

To change the visibility of a band in the customization form, use the band's Options.Hidden property. Note that modifying this
property does not affect the Hidden property of columns residing within the band.

The default value of the Hidden property is False.

Related Information

l TcxTreeListBandOptions.Hidden
l TcxTreeListBandOptions.Moving
l ExpressEditors: TcxCustomEditContainerItemOptions.Customizing

Page 617 of 1199


TcxTreeListColumnOptions.RestoreDefaults
TcxTreeListColumnOptions

Restores the column's default option settings.

Syntax

procedure RestoreDefaults; virtual;

Description
The method sets the column's Sorting, Sizing, Customizing, Editing, TabStop, Focusing, and Moving options to True.

Page 618 of 1199


TcxTreeListColumnOptions.Sizing
TcxTreeListColumnOptions

Specifies whether end-users can horizontally resize the column.

Syntax

property Sizing: Boolean;

Description
Set this property to False to prohibit end-users from horizontally resizing the column by dragging its header's right edge.
To prevent all columns from being horizontally resized by end-users, set the TreeList control's
OptionsCustomizing.ColumnHorzSizing property to False. If this property is set to False, horizontal sizing is prohibited for all
columns regardless of their Sizing property values.
To enable instant visualization of column sizing, set the TreeList control's OptionsCustomizing.DynamicSizing property to True.

The default value of the Sizing property is True.

Related Information

l TcxTreeListBandOptions.Sizing
l TcxTreeListColumnOptions.VertSizing
l TcxTreeListOptionsCustomizing.DynamicSizing

Page 619 of 1199


TcxTreeListColumnOptions.VertSizing
TcxTreeListColumnOptions

Specifies whether end-users can vertically resize the column.

Syntax

property VertSizing: Boolean;

Description
Set this property to False to prohibit end-users from vertically resizing the column by dragging its header's bottom edge.
To prevent all columns from being vertically resized by end-users, set the TreeList control's
OptionsCustomizing.ColumnVertSizing property to False. Note that column options aren't in effect in this instance.

The default value of the VertSizing property is True.

Related Information

l TcxTreeListBandOptions.VertSizing
l TcxTreeListColumnOptions.Sizing

Page 620 of 1199


TcxTreeListColumnPosition.Band
TcxTreeListColumnPosition

Provides access to the band containing the column.

Syntax

property Band: TcxTreeListBand;

Description
To move a column to another band, use the BandIndex property or the SetPositionEx method.

ReadOnly Property

Page 621 of 1199


TcxTreeListColumnPosition.BandIndex
TcxTreeListColumnPosition

Specifies the band that contains the column.

Syntax

property BandIndex: Integer;

Description
The band is identified by its index within the TreeList control's Bands collection. To remove a column from its band, set the
BandIndex property to –1. As a result, the column will be hidden in the TreeList control.

To access the properties of a band containing a particular column, use the Band property.

Related Information

l TcxTreeListColumnPosition.SetPosition
l TcxTreeListColumnPosition.SetPositionEx
l TcxTreeListColumnPosition.VisibleBandIndex

Page 622 of 1199


TcxTreeListColumnPosition.ColIndex
TcxTreeListColumnPosition

Specifies the horizontal position of the column within its band.

Syntax

property ColIndex: Integer;

Description
The image below shows stacked columns and their ColIndex and RowIndex property values.

Changing the ColIndex property automatically updates the VisibleColIndex, VisibleIndex and VisibleIndexAtBand property
values.

Note:   Modifying the ColIndex property doesn't affect the ItemIndex property value.

Related Information

l TcxTreeListColumnPosition.RowIndex
l TcxTreeListColumnPosition.SetPosition
l TcxTreeListColumnPosition.SetPositionEx

Page 623 of 1199


TcxTreeListColumnPosition.Column
TcxTreeListColumnPosition

Provides access to the column that owns the current option set.
ReadOnly Property

Syntax

property Column: TcxTreeListColumn;

Related Information

l TcxTreeListColumnPosition.ColIndex
l TcxTreeListColumnPosition.SetPositionEx

Page 624 of 1199


TcxTreeListColumnPosition.LineCount
TcxTreeListColumnPosition

Specifies the column header's height, in text lines.

Syntax

property LineCount: Integer;

Description
Set this property to a value greater than 1 to display multi-line cells for the column.
End-users can vertically resize column headers if both the TreeList control's OptionsCustomizing.ColumnVertSizing property
and a column's Options.VertSizing property are set to True.
To wrap the column caption's text within a column header, set the column's Caption.Multiline property to True.

The default value of the LineCount property is 1.

Page 625 of 1199


TcxTreeListColumnPosition.Row
TcxTreeListColumnPosition

Provides access to the band row containing the column.

Syntax

property Row: TcxTreeListBandRow;

Description
Use the RowIndex property to specify the band row for the column. To determine the visible vertical position of the column's
header within the column header panel, use the VisibleRowIndex property.

ReadOnly Property

Page 626 of 1199


TcxTreeListColumnPosition.RowIndex
TcxTreeListColumnPosition

Specifies the vertical position of the column within its band.

Syntax

property RowIndex: Integer;

Description
Use this property to stack columns within a band. Once assigned, the RowIndex property value identifies a band row containing
the current column. This value is equal to the number of columns that are stacked on the column.
The image below shows stacked columns and their ColIndex and RowIndex property values.

Use the Row property to access the band row containing the column. To determine the visible vertical position of the column's
header within the column header panel, use the VisibleRowIndex property.

Related Information

l TcxTreeListColumnPosition.SetPosition
l TcxTreeListColumnPosition.SetPositionEx

Page 627 of 1199


TcxTreeListColumnPosition.SetPosition
TcxTreeListColumnPosition

Moves the column within its band.

Syntax

procedure SetPosition(AColIndex, ARowIndex: Integer; IsInsertRow: Boolean = False);

Description
Call this method to simultaneously change the column's Position.ColIndex and Position.RowIndex property values. New
property values are passed as the AColIndex and ARowIndex parameters.
The IsInsertRow parameter value is ignored. To make a column occupy an entire row in a band, call the SetPositionEx method
and pass True as the IsInsertRow parameter.

The SetPositionEx method represents an extended version of the SetPosition method. Call the SetPositionEx method to move a
column to a certain band or make this column occupy an entire row in a band.

Related Information

l TcxTreeListColumnPosition.SetPositionEx

Page 628 of 1199


TcxTreeListColumnPosition.SetPositionEx
TcxTreeListColumnPosition

Moves the column at a specific position in a specified band.

Syntax

procedure SetPositionEx(ABandIndex, AColIndex, ARowIndex: Integer; IsInsertRow: Boolean = Fa

Description
Call this method to simultaneously change the column's Position.BandIndex, Position.ColIndex, and Position.RowIndex property valu
New property values are passed as the ABandIndex, AColIndex and ARowIndex parameters, respectively.
Pass True as the IsInsertRow parameter to make the column occupy an entire row in a band.

Related Information

l TcxTreeListColumnPosition.SetPosition

Page 629 of 1199


TcxTreeListColumnPosition.TreeList
TcxTreeListColumnPosition

Provides access to the TreeList control containing the current option set.
ReadOnly Property

Syntax

property TreeList: TcxCustomTreeList;

Page 630 of 1199


TcxTreeListColumnPosition.VisibleBandIndex
TcxTreeListColumnPosition

Returns the visible position of the band that contains this column.

Syntax

property VisibleBandIndex: Integer;

Description
If the column is assigned to a band, the VisibleBandIndex property returns the band's VisibleIndex property value. Otherwise, –
1 is returned. Use the TreeList control's Bands.VisibleItems collection to access a particular band that is currently visible within
the TreeList control.
To programmatically move a column to a band, use the BandIndex property, or call the SetPositionEx method.

ReadOnly Property

Related Information

l TcxTreeListColumnPosition.Band

Page 631 of 1199


TcxTreeListColumnPosition.VisibleColIndex
TcxTreeListColumnPosition

Returns the visible horizontal position of the column within its band row.

Syntax

property VisibleColIndex: Integer;

Description
This property returns the column's position within the band row's VisibleItems collection.
To move a column to a specific position within its band row, use the ColIndex property or call the SetPosition or SetPositionEx
method.

ReadOnly Property

Page 632 of 1199


TcxTreeListColumnPosition.VisibleRowIndex
TcxTreeListColumnPosition

Returns the visible vertical position of the band row containing the column, within the column header panel.

Syntax

property VisibleRowIndex: Integer;

Description
This property returns the band row's position within its BandRows.VisibleItems collection.
To programmatically move a column to a specific band row within its band, use the RowIndex property or call the SetPosition or
SetPositionEx method.
To specify whether end-users can vertically move or stack columns, use the TreeList control's
OptionsCustomizing.ColumnMoving and OptionsCustomizing.StackedColumns properties.

ReadOnly Property

Related Information

l TcxTreeListColumnPosition.Row

Page 633 of 1199


TcxTreeListColumnStyles.Band
TcxTreeListColumnStyles

Provides access to the band containing the column to which the current set of styles is applied.
ReadOnly Property

Syntax

property Band: TcxTreeListBand;

Related Information

l TcxTreeListColumn Object
l TcxTreeListColumnStyles.Column

Page 634 of 1199


TcxTreeListColumnStyles.Column
TcxTreeListColumnStyles

Provides access to the column to which the current set of styles is applied.
ReadOnly Property

Syntax

property Column: TcxTreeListColumn;

Related Information

l TcxTreeListColumn Object
l TcxTreeListColumnStyles.Band

Page 635 of 1199


TcxTreeListColumnStyles.Footer
TcxTreeListColumnStyles

Specifies the styles for the column footer cell.

Syntax

property Footer: TcxStyle;

Description
The Footer property allows you to define the style (font, background color) of the footer cell within the control's footer. It is
possible to modify the style of an individual column's footer cell by handling the OnGetColumnFooterStyle event.

Additionally, you can define the style settings of the column's contents and header using the Content and Header properties
respectively.

Page 636 of 1199


TcxTreeListColumnStyles.Header
TcxTreeListColumnStyles

Specifies the styles for the column header.

Syntax

property Header: TcxStyle;

Description
The Header property allows you to define the style (font, background) for the column header. It is possible to modify the style of
an individual column header by handling the OnGetColumnHeaderStyle event.

Additionally, you can define the style settings of the column's contents and footer using the Content and Footer properties
respectively.

Page 637 of 1199


TcxTreeListColumnStyles.TreeList
TcxTreeListColumnStyles

Provides access to the TreeList control that owns the column to which the current set of styles is applied.
ReadOnly Property

Syntax

property TreeList: TcxCustomTreeList;

Related Information

l TcxTreeListColumn Object

Page 638 of 1199


TcxTreeListColumnSummary.Column
TcxTreeListColumnSummary

Provides access to the column that displays the summaries.


ReadOnly Property

Syntax

property Column: TcxTreeListColumn;

Related Information

l TcxTreeListSummaryItem.CalculatedColumn
l TcxTreeListSummaryItem.Column
l TcxTreeListSummaryItems.Column

Page 639 of 1199


TcxTreeListColumnSummary.FooterSummaryItems
TcxTreeListColumnSummary

Provides access to a column's footer summary collection.

Syntax

property FooterSummaryItems: TcxTreeListSummaryItems;

Description
Refer to the TcxTreeListSummaryItems class description, to learn about available collection options.
To access all footer summaries created within the TreeList control, use its Summary.FooterSummaryItems collection.

Related Information

l TcxTreeListColumnSummary.FooterVisibleCount
l TcxTreeListColumnSummary.GroupFooterSummaryItems
l TcxTreeListSummary.FooterSummaryItems

Page 640 of 1199


TcxTreeListColumnSummary.FooterVisibleCount
TcxTreeListColumnSummary

Returns the number of a column's footer summaries that are currently visible within the TreeList control.

Syntax

property FooterVisibleCount: Integer;

Description
This property is intended for internal use.
This property returns the number of summaries within the FooterSummaryItems collection whose Visible property is set to True.

ReadOnly Property

Related Information

l TcxTreeListColumnSummary.GroupFooterVisibleCount
l TcxTreeListSummary.FooterSummaryVisibleCount

Page 641 of 1199


TcxTreeListColumnSummary.GroupFooterSummaryItem
TcxTreeListColumnSummary

Provides access to a column's group summary collection.

Syntax

property GroupFooterSummaryItems: TcxTreeListSummaryItems;

Description
Refer to the TcxTreeListSummaryItems class description, to learn about available collection options.
To access all group summaries created within the TreeList control, use its Summary.GroupFooterSummaryItems collection.

Related Information

l TcxTreeListColumnSummary.FooterSummaryItems
l TcxTreeListColumnSummary.GroupFooterVisibleCount
l TcxTreeListSummary.GroupFooterSummaryItems

Page 642 of 1199


TcxTreeListColumnSummary.GroupFooterVisibleCount
TcxTreeListColumnSummary

Returns the number of a column's group summaries currently visible within the TreeList control.

Syntax

property GroupFooterVisibleCount: Integer;

Description
This property is intended for internal use.
This property returns the number of summaries within the GroupFooterSummaryItems collection whose Visible property is set to True.

ReadOnly Property

Related Information

l TcxTreeListColumnSummary.FooterVisibleCount
l TcxTreeListSummary.GroupFooterSummaryVisibleCount

Page 643 of 1199


TcxTreeListColumn.ActuallyVisible
TcxTreeListColumn

Indicates whether the current column is displayed within the TreeList control.

Syntax

property ActuallyVisible: Boolean;

Description
This property returns True if the following conditions are met:
l The column's Visible property is set to True.
l The column is associated with a band that is currently visible within the TreeList control.

To determine whether the column's header is displayed within the TreeList control, use the IsHidden property.

ReadOnly Property

Page 644 of 1199


TcxTreeListColumn.ApplyBestFit
TcxTreeListColumn

Adjusts the column's width to the minimum required to display the content of all its cells in their entirety.

Syntax

procedure ApplyBestFit;

Description
This method iterates through nodes and calculates the maximum width of the column's data cells required to display its values
without truncation. This width is assigned then to the column's Width property.
The ApplyBestFit method takes into account the following column attributes:
l The caption specified via the Caption property.
l Data cell values.
l Footer cell values.
End-users can double-click a column header's right edge to apply Best Fit to this column. To prevent end-users from changing
the column's width in this manner, disable the column's Options.Sizing property or the TreeList control's
OptionsCustomizing.ColumnHorzSizing property.

To limit a column's width to a certain value when applying Best Fit to this column, use the BestFitMaxWidth property.

Examples

l Example: TreeList.CreateColumn, Column.ApplyBestFit

Related Information

l TcxCustomTreeList.ApplyBestFit
l TcxTreeListBand.ApplyBestFit

Page 645 of 1199


TcxTreeListColumn.Assign
TcxTreeListColumn

Assigns properties of one column to another.

Syntax

procedure Assign(Source: TPersistent); override;

Description
The Assign method can be used to copy property values from one column to another.
The Source parameter specifies the source column.

The method assigns the following properties:


l DisplayWidth
l MinWidth
l Width
l Position
l Caption
l SortOrder
l Visible.

Page 646 of 1199


TcxTreeListColumn.BestFitMaxWidth
TcxTreeListColumn

Specifies the maximum width (in pixels) for the column with Best Fit applied.

Syntax

property BestFitMaxWidth: Integer;

Description
Use this property to limit the column's width to the specified number of pixels when applying Best Fit to the column. Set the
BestFitMaxWidth property to 0 to remove the limitation on column width with Best Fit applied.

The BestFitMaxWidth property automatically updates by multiplying its current value by the form's scaling factor every time it
changes at design-time or runtime.

The default value of the BestFitMaxWidth property is 0.

Page 647 of 1199


TcxTreeListColumn.Caption
TcxTreeListColumn

Provides access to settings that determine the appearance of the current column's caption.

Syntax

property Caption: TcxTreeListCaption;

Description
Refer to the TcxTreeListCaption class description, to learn about available options.

Page 648 of 1199


TcxTreeListColumn.DataBinding
TcxTreeListColumn

Specifies an object which links the current column to a data field.

Syntax

property DataBinding: TcxItemDataBinding;

Description
Use the DataBinding.ValueType or DataBinding.ValueTypeClass properties of the object to define the data type of column
values.
At design time, you can select a data type for a column from its DataBinding.ValueType property which provides a list of the
available data types.

Page 649 of 1199


TcxTreeListColumn.DisplayTexts
TcxTreeListColumn

Gets the display text of particular column value.

Syntax

property DisplayTexts[ANode: TcxTreeListNode]: string;

Description
The ANode parameter specifies the node that identifies a particular column value.

Use the column's Values property to obtain the actual values stored within column cells.
To obtain the number of values stored within the column, use its ValueCount property.

ReadOnly Property

Page 650 of 1199


TcxTreeListColumn.DisplayWidth
TcxTreeListColumn

Specifies the column's width on screen, in pixels.

Syntax

property DisplayWidth: Integer;

Description
The property value is determined by the IndentWidth and MinWidth property values. The return value may differ from the Width
property value, which simply returns the width assigned programmatically, or at design time. You can use the DisplayWidth
property to override the column's display width, when it's calculated automatically – either by assigning an owner band's Width
property or enabling the TreeList control's OptionsView.ColumnAutoWidth option.

Note:   The DisplayWidth property returns 0 if the column is currently hidden within the TreeList control.

Related Information

l TcxTreeListColumn.ApplyBestFit
l TcxTreeListOptionsView.ColumnAutoWidth

Page 651 of 1199


TcxTreeListColumn.Editing
TcxTreeListColumn

Indicates whether the current column is being edited (in edit mode).

Syntax

property Editing;

Description
This property returns True if any cell corresponding to the current column is currently being edited. To obtain the value of the cell
being edited, use the EditValue property.

Note:   Setting the TreeList control's OptionsData.Editing property to False, automatically assigns False to a column's Editing
property.

Related Information

l TcxCustomTreeList.CancelEdit
l TcxCustomTreeList.OnEdited
l TcxCustomTreeList.OnEditing
l TcxCustomTreeList.ShowEdit
l TcxCustomTreeList.ShowEditByKey
l TcxCustomTreeList.ShowEditByMouse
l TcxTreeListNode.EndEdit

Page 652 of 1199


TcxTreeListColumn.EditValue
TcxTreeListColumn

Specifies the value of the cell being edited.

Syntax

property EditValue: Variant;

Description
To determine whether a column is in edit mode, use its Editing property. If none of the column's cells is being edited, the
EditValue property value returns an unassigned variant.

Related Information

l ExpressEditors: TcxControlOptionsData.Editing
l ExpressEditors: TcxCustomEditContainerItemOptions.Editing

Page 653 of 1199


TcxTreeListColumn.Focused
TcxTreeListColumn

Indicates whether the current column is focused.

Syntax

property Focused;

Description
This property returns True if any cell corresponding to the current column is currently focused. To obtain the value of the cell
being edited, use the EditValue property.

Note:   The Focused property returns False if the TreeList control's OptionsSelection.CellSelect option is disabled. In this
instance, end-users cannot select and focus individual cells.

Examples

l Example: Column.Focused, Node.Focused, Node.GetPrevVisible, Node.GetPrev, Node.GetNextVisible, Node.GetNext

Page 654 of 1199


TcxTreeListColumn.IndentWidth
TcxTreeListColumn

Determines the increment (in pixels) by which the expandable column's width is increased during node expansion.

Syntax

property IndentWidth: Integer;

Description
This property returns the increment by which the width of the expandable column is increased if its width is less than the
column's MinWidth property value. The resulting column width is returned by the DisplayWidth property.

ReadOnly Property

Page 655 of 1199


TcxTreeListColumn.IsHidden
TcxTreeListColumn

Indicates whether the column is displayed within the TreeList control.

Syntax

property IsHidden: Boolean;

Description
This property returns True if any of the following conditions are met:
l The column's Visible property is set to False.
l The column is not assigned to any band.
l The band containing the column is hidden.
l The column's values are used within the preview section.

To determine whether the column's values are displayed within the TreeList control, use the ActuallyVisible property.

ReadOnly Property

Page 656 of 1199


TcxTreeListColumn.IsLeft
TcxTreeListColumn

Indicates whether the current column is the first visible one within its band.

Syntax

property IsLeft: Boolean;

Description
Use the column's IsRight property to determine whether the column is the last visible column within its band.
To specify the position of a column within the TreeList control or a particular band, use the column's Position property.

ReadOnly Property

Related Information

l TcxTreeListColumn.VisibleIndexAtBand
l TcxTreeListColumnPosition.Band

Page 657 of 1199


TcxTreeListColumn.IsPreview
TcxTreeListColumn

Specifies whether the column's values are used within the preview section.

Syntax

property IsPreview: Boolean;

Description
Setting this property to True assigns the current column to the TreeList control's Preview.Column property.

Page 658 of 1199


TcxTreeListColumn.IsRight
TcxTreeListColumn

Indicates whether the current column is the last visible one within its band.

Syntax

property IsRight: Boolean;

Description
Use the column's IsLeft property to determine whether the current column is the first visible column within its band.
To specify the position of a column within the TreeList control or a particular band, use the column's Position property.

ReadOnly Property

Related Information

l TcxTreeListColumn.VisibleIndexAtBand
l TcxTreeListColumnPosition.Band

Page 659 of 1199


TcxTreeListColumn.ItemIndex
TcxTreeListColumn

Specifies the position of the current column within the TreeList control's Columns collection.

Syntax

property ItemIndex: Integer;

Description
Use this property to perform one of the following:
l Modify the column's position within the TreeList control. Alternatively, you can use the column's Position or VisibleIndex
property.
l Obtain the column value within a particular node via the Node.Values property.

Page 660 of 1199


TcxTreeListColumn.MakeVisible
TcxTreeListColumn

Horizontally scrolls the TreeList control to bring the current column into view.

Syntax

procedure MakeVisible;

Page 661 of 1199


TcxTreeListColumn.MinWidth
TcxTreeListColumn

Specifies the column's minimum width, in pixels.

Syntax

property MinWidth: Integer;

Description
Use this property to change the lower bound of the Width property values. To identify or change the column display width, use
the DisplayWidth property.

The MinWidth property automatically updates by multiplying its current value by the form's scaling factor every time it changes
at design-time or runtime.

To restore the column's default MinWidth and Width property values, call the RestoreWidth procedure.

The default value of the MinWidth property is cxTreeListDefMinWidth.

Related Information

l TcxTreeListColumn.ApplyBestFit
l TcxTreeListOptionsCustomizing.BandHorzSizing
l TcxTreeListOptionsCustomizing.ColumnHorzSizing

Page 662 of 1199


TcxTreeListColumn.OnGetDisplayText
TcxTreeListColumn

Enables you to specify the display text for a data cell.

Syntax

type
TcxTreeListOnGetDisplayValueEvent = procedure(Sender: TcxTreeListColumn; ANode: TcxTreeLis
property OnGetDisplayText: TcxTreeListOnGetDisplayValueEvent;

Description
The Sender parameter specifies the column to which the currently processed cell belongs.
The ANode parameter specifies the node in which the cell resides.
Use the Value parameter to return the display text for the value displayed in the data cell identified by the Sender and ANode paramete
string representation of the cell value.

To format both a cell's display value and edit value, assign an in-place editor to a column via the column's Properties property. To dyna
cells, handle the column's OnGetEditProperties and OnGetEditingProperties events.

Examples

l Example: Column.OnGetDisplayText

Page 663 of 1199


TcxTreeListColumn.OnGetEditingProperties
TcxTreeListColumn

Enables you to dynamically specify a cell's in-place editor type.

Syntax

type
TcxTreeListGetEditPropertiesEvent = procedure(Sender: TcxTreeListColumn; ANode: TcxTreeLis
property OnGetEditingProperties: TcxTreeListGetEditPropertiesEvent;

Description
By default, all cells of a column use the same in-place editor determined by the column's Properties, PropertiesClass, PropertiesClass
handle the OnGetEditingProperties event.
The Sender parameter specifies the column to which the currently processed cell belongs.
The ANode parameter specifies the node in which the cell resides.
A cell being processed is identified by the Sender and ANode parameter values. Pass the cell's editor property type via the EditPropert
repository as a store for editor properties. Create repository items corresponding to specific editors and adjust their properties as your
the EditProperties parameter, as shown below.

[Delphi]
// ...
procedure <Form>.<Column>GetEditingProperties(Sender: TcxTreeListColumn; ANode: TcxTreeListNode;
begin
// specifying the editor type for group nodes
if ANode.IsGroupNode then
EditProperties := <cxEditRepository>.Items[<GetItemIndex(ANode)>].Properties;
end;

To provide different display value formatting editors for a column's cells, handle the column's OnGetEditProperties event.

To prevent in-place editing for certain cells, handle the TreeList control's OnEditing event.

Examples

l Example: OnGetEditingProperties

Related Information

l TcxCustomTreeList.OnEditing
l TcxTreeListColumn.OnGetEditProperties

Page 664 of 1199


TcxTreeListColumn.OnGetEditProperties
TcxTreeListColumn

Enables you to dynamically specify a cell's display value formatting editor type.

Syntax

type
TcxTreeListGetEditPropertiesEvent = procedure(Sender: TcxTreeListColumn; ANode: TcxTreeLis
property OnGetEditProperties: TcxTreeListGetEditPropertiesEvent;

Description
By default, all cells of a column use the same display value formatting editor determined by the column's Properties, PropertiesClass,
editors for cell display values, handle the OnGetEditProperties event.
The Sender parameter specifies the column to which the currently processed cell belongs.
The ANode parameter specifies the node in which the cell resides.
A cell being processed is identified by the Sender and ANode parameter values. Pass the cell's editor property type via the EditPropert
repository (the TcxEditRepository component) as a store for editor properties. Create repository items corresponding to specific editors
these repository items to pass it via the EditProperties parameter.

To provide different in-place editors for a column's cells, handle the column's OnGetEditingProperties event.

Examples

l Example: OnGetEditProperties

Related Information

l TcxTreeListColumn.OnGetEditingProperties

Page 665 of 1199


TcxTreeListColumn.OnGetStoredProperties
TcxTreeListColumn

Enables you to customize a list of the current column's properties to be stored to external data stores.

Syntax

type
TcxGetStoredPropertiesEvent = procedure(Sender: TObject; AProperties: TStrings) of object;
property OnGetStoredProperties: TcxGetStoredPropertiesEvent;

Description
Whenever the storing process is started by the StoreToIniFile, StoreToRegistry, or StoreToStream method call, a list of the properties
to store is produced. When the OnGetStoredProperties event is fired, the list is already populated with column property names, whic
are stored by default. These property names are specified by the ColumnPropertiesName global constant. You can add custom
property names to the list and handle the column's OnGetStoredPropertyValue and OnSetStoredPropertyValue events to provide
property values to be saved to and restored from a data store. Make certain that items in the list uniquely identify the property names
they correspond to.
The Sender parameter specifies the current column.
The AProperties parameter provides access to the list of properties to be stored.

The following code represents an OnGetStoredProperties event handler, demonstrating how to extend the list with an item that
corresponds to a column's Options.Footer property.

[Delphi]
procedure <Form>.<Column>GetStoredProperties(Sender: TObject; AProperties: TStrings);
begin
AProperties.Add('Options_Footer');
end;

[C++ Builder]
void __fastcall <Form>::<Column>GetStoredProperties(TObject *Sender, TStrings *AProperties)
{
AProperties->Add("Options_Footer");
}

Note:   To customize the manner in which tree list properties are persisted, handle the tree list's OnGetStoredProperties,
OnGetStoredPropertyValue, and OnSetStoredPropertyValue events. To customize the manner in which band properties are persisted,
handle a band's OnGetStoredProperties, OnGetStoredPropertyValue, and OnSetStoredPropertyValue events.

Concepts

l Save and Restore Layout

Related Information

l TcxCustomTreeList.OnGetStoredProperties
l TcxTreeListBand.OnGetStoredProperties

Page 666 of 1199


TcxTreeListColumn.OnGetStoredPropertyValue
TcxTreeListColumn

Enables you to provide values for column properties to be saved to external data stores.

Syntax

type
TcxGetStoredPropertyValueEvent = procedure(Sender: TObject; const AName: string; var AValu
property OnGetStoredPropertyValue: TcxGetStoredPropertyValueEvent;

Description
This event is fired for each property (including default properties) within the list specified in the column's OnGetStoredProperties event h
properties, handle the OnSetStoredPropertyValue event.
The Sender parameter specifies the current column.
The AName parameter identifies the property name.
Pass the property value as the AValue parameter.

The following code represents an OnGetStoredPropertyValue event handler demonstrating how to save the values of a column's Opti
specified for storing within the column's OnGetStoredProperties event handler.

[Delphi]
procedure <Form>.<Column>GetStoredPropertyValue(Sender: TObject; const AName: String; var AValue
begin
if Sender is TcxTreeListColumn then
begin
if AName = 'Options_Footer' then
begin
AValue := TcxTreeListColumn(Sender).Options.Footer;
Exit;
end;
end;
end;

[C++ Builder]
void __fastcall <Form>::<Column>GetStoredPropertyValue(TObject *Sender, const AnsiString AName,
{
if(AName == "Options_Footer") {
if(dynamic_cast<TcxTreeListColumn*>(Sender)) {
TcxTreeListColumn * AColumn = (TcxTreeListColumn *)Sender;
AValue = AColumn->Options->Footer;
return;
}
}
}

Concepts

l Save and Restore Layout


Page 667 of 1199
TcxTreeListColumn.OnSetStoredPropertyValue
TcxTreeListColumn

Enables you to restore the current column's property values from external data stores.

Syntax

type
TcxSetStoredPropertyValueEvent = procedure(Sender: TObject; const AName: string; const AVa
property OnSetStoredPropertyValue: TcxSetStoredPropertyValueEvent;

Description
This event is fired for each property (including default properties) within the list specified in the column's OnGetStoredProperties event h
OnSetStoredPropertyValue event to restore custom property values that were explicitly specified via the OnGetStoredPropertyValue
The Sender parameter specifies the current column.
The AName parameter identifies the property name. Its value is returned by the AValue parameter. Use this value to assign a correspo

The following code represents an OnSetStoredPropertyValue event handler demonstrating how to restore a column's Options.Footer
within the column's OnGetStoredPropertyValue event handler.

[Delphi]
procedure <Form>.<Column>SetStoredPropertyValue(Sender: TObject; const AName: String; const AVal
begin
if Sender is TcxTreeListColumn then
begin
if AName = 'Options_Footer' then
begin
TcxTreeListColumn(Sender).Options.Footer := AValue;
Exit;
end;
end;
end;

[C++ Builder]
void __fastcall <Form>::<Column>SetStoredPropertyValue(TObject *Sender, const AnsiString AName,
{
if(AName == "Options_Footer") {
if(dynamic_cast<TcxTreeListColumn*>(Sender)) {
TcxTreeListColumn * AColumn = (TcxTreeListColumn *)Sender;
AColumn->Options->Footer = AValue;
return;
}
}
}

Note:   To properly initialize columns that are created during the restoring process, handle the tree list's OnInitStoredObject event.

Concepts

l Save and Restore Layout


Page 668 of 1199
TcxTreeListColumn.OnValidateDrawValue
TcxTreeListColumn

Enables you to customize the manner in which validation errors are visualized in the column's data cells.

Syntax

type
TcxTreeListValidateDrawValueEvent = procedure(Sender: TcxTreeListColumn; ANode: TcxTreeLis
property OnValidateDrawValue: TcxSetStoredPropertyValueEvent;

Description
The Sender and ANode parameters identify the column and the node that correspond to the currently processed data cell.
The AValue parameter contains the cell editor's edit value. Test the AValue against the same validation logic as you have for the colum
The AData parameter references a TcxEditValidateInfo object to be used to visualize validation errors in the cell editor. For this event, t
fails validation, you can customize these properties to specify the error icon and error message for the cell editor.

Note that error icons and error messages can be displayed only if the appropriate flags are set within the column Properties.ValidationO

To see how to tailor the OnValidateDrawValue event, the Properties.ValidationOptions property, and the column Properties.OnValida
the ExpressQuantumTreeList Suite.

Related Information

l TcxUnboundTreeListNode Object
l TcxVirtualTreeListNode Object
l ExpressBars: TcxCustomBarEditItem.EditValue
l ExpressEditors: TcxCalcEdit.EditValue
l ExpressEditors: TcxCurrencyEdit.EditValue
l ExpressEditors: TcxCustomCheckListBox.EditValue
l ExpressEditors: TcxCustomEdit.EditValue
l ExpressEditors: TcxCustomLookupComboBox.EditValue
l ExpressEditors: TdxCustomColorGallery.EditValue
l ExpressQuantumGrid: TcxCustomExtLookupComboBox.EditValue
l ExpressQuantumGrid: TcxCustomGridTableItem.EditValue
l ExpressQuantumGrid: TcxCustomGridTableItem.OnValidateDrawValue
l ExpressVerticalGrid: TcxCustomEditorRowProperties.OnValidateDrawValue

Page 669 of 1199


TcxTreeListColumn.Options
TcxTreeListColumn

Provides access to the column's appearance options and settings that determine the column's response to end-user actions.

Syntax

property Options: TcxTreeListColumnOptions;

Description
Refer to the TcxTreeListColumnOptions class description, to learn about available settings.

Page 670 of 1199


TcxTreeListColumn.Position
TcxTreeListColumn

Provides access to settings that specify the column's position within a band.

Syntax

property Position: TcxTreeListColumnPosition;

Description
Refer to the TcxTreeListColumnPosition class description, to learn about available settings.

Page 671 of 1199


TcxTreeListColumn.RestoreDefaults
TcxTreeListColumn

Restores the default column settings.

Syntax

procedure RestoreDefaults; virtual;

Description
This method does the following:
l Restores column options to their default values.
l Sets the SortOrder property to soNone.
l Sets the column caption's vertical and horizontal alignment options to vaTop and taLeftJustify, respectively.
l Restores the column's default width.

Related Information

l TcxCustomTreeList.MakeDefaultLayout
l TcxTreeListColumn.RestoreWidths

Page 672 of 1199


TcxTreeListColumn.RestoreWidths
TcxTreeListColumn

Resets the column's width to its default value.

Syntax

procedure RestoreWidths; virtual;

Description
This method assigns the default values of the column's MinWidth and Width properties.

Related Information

l TcxTreeListColumn.RestoreDefaults

Page 673 of 1199


TcxTreeListColumn.SortIndex
TcxTreeListColumn

Specifies the index of the current column within sorted columns.

Syntax

property SortIndex: Integer;

Description
This property specifies the column's position within the TreeList control's SortedColumns collection. End-users can add or
remove columns from this collection by clicking column headers while holding down the Shift and Ctrl keys.
Setting the SortIndex property to –1 removes the column from the SortedColumns collection, and sets the column's SortOrder
property to soNone.

The default value of the SortIndex property is –1.

Examples

l Example: TreeList.Sorted, TreeList.SortedColumnCount, TreeList.SortedColumns, Column.SortOrder

Related Information

l TcxTreeListNode.AlphaSort

Page 674 of 1199


TcxTreeListColumn.SortOrder
TcxTreeListColumn

Specifies the sort order of the column's values.

Syntax

type
TcxDataSortOrder = (soNone, soAscending, soDescending)
property SortOrder: TcxDataSortOrder;

Description
Refer to the TcxDataSortOrder type description, to learn about available sorting options.
To provide custom sorting logic for nodes, handle the TreeList control's OnCompare event.

Note:   To allow sorting nodes by multiple columns, set the TreeList control's OptionsBehavior.MultiSort property to True. In this
instance, assigning a value other than soNone to the SortOrder property automatically appends the column to the
SortedColumns collection, and sets the column's SortIndex property. If the OptionsBehavior.MultiSort property is set to False,
the SortedColumns collection is cleared before the column is added to it.

The default value of the SortOrder property is soNone.

Examples

l Example: TreeList.Sorted, TreeList.SortedColumnCount, TreeList.SortedColumns, Column.SortOrder

Related Information

l TcxCustomTreeList.ClearSorting
l TcxTreeListNode.AlphaSort
l TcxTreeListOptionsData.AnsiSort
l TcxTreeListOptionsData.MultiThreadedSorting

Page 675 of 1199


TcxTreeListColumn.StatusHint
TcxTreeListColumn

Specifies the hint displayed in a status bar.

Syntax

property StatusHint: string;

Description
Use this property to display a column header's hint in a status bar, when the mouse pointer is over the column header.
To display column header hints in a TStatusBar control, set its AutoHint property to True. To display column header hints in a
TdxStatusBar or TdxRibbonStatusBar control, shipped with the ExpressBars Suite, add a text status bar panel, and set its
AutoHint property to True. Alternatively, you can switch the status bar to display a simple text panel and set its AutoHint
property to True.

Important Note:   The ExpressBars Suite is not a part of the ExpressQuantumTreeList Suite, and must be purchased and
installed separately.

Related Information

l ExpressBars: TdxCustomStatusBar Object


l ExpressBars: TdxRibbonStatusBar Object

Page 676 of 1199


TcxTreeListColumn.Styles
TcxTreeListColumn

Provides access to the style settings of the column's elements.

Syntax

property Styles: TcxTreeListColumnStyles;

Description
Refer to the TcxTreeListColumnStyles class description, to learn about available style settings.

Page 677 of 1199


TcxTreeListColumn.Summary
TcxTreeListColumn

Provides access to the column's summary collections.

Syntax

property Summary: TcxTreeListColumnSummary;

Description
Refer to the TcxTreeListColumnSummary class description, to learn about available settings.
To access all column summaries created within the TreeList control, use its Summary property.

Related Information

l Group Summaries
l TcxTreeListOptionsData.SummaryNullIgnore

Page 678 of 1199


TcxTreeListColumn.TreeList
TcxTreeListColumn

Provides access to the TreeList control, which owns the current column.
ReadOnly Property

Syntax

property TreeList: TcxCustomTreeList;

Page 679 of 1199


TcxTreeListColumn.Values
TcxTreeListColumn

Provides access to the column's value within a specified node.

Syntax

property Values[ANode: TcxTreeListNode]: Variant;

Description
Use this property to get and set the column's values. The ANode parameter identifies the node for which the column's value is
obtained or specified. To access all column values within a certain node, use its Values property.

Related Information

l TcxCustomDBTreeList.FindNodeByKeyValue
l TcxCustomTreeList.Find
l TcxCustomTreeList.FindNodeByText
l TcxCustomTreeList.FocusedNode
l TcxCustomTreeList.Items
l TcxTreeListNode Object
l TcxTreeListNode.Items
l TcxVirtualTreeListNode Object

Page 680 of 1199


TcxTreeListColumn.Visible
TcxTreeListColumn

Specifies the visibility of the column's values within the TreeList control.

Syntax

property Visible: Boolean;

Description
Set this property to True to allow the column's values to be displayed within the TreeList control. Note that even if you do so,
the column may still be hidden for various reasons, such as hiding its parent band. To determine whether a column is actually
visible, use its ActuallyVisible property.

The default value of the Visible property is True.

Page 681 of 1199


TcxTreeListColumn.VisibleIndex
TcxTreeListColumn

Determines the visible position of the current column within the TreeList control.

Syntax

property VisibleIndex: Integer;

Description
This property returns the column's index within the TreeList control's VisibleColumns collection. For hidden columns, the
VisibleIndex property returns –1.
To obtain the total number of elements within the VisibleColumns collection, use the TreeList control's VisibleCount property. To
determine a column's visible position within a band containing it, use the column's VisibleIndexAtBand property.

To access all columns contained within the TreeList control, use the Columns collection. The position of a column in this
collection is specified by the column's ItemIndex property.

ReadOnly Property

Related Information

l TcxTreeListColumn.Position

Page 682 of 1199


TcxTreeListColumn.VisibleIndexAtBand
TcxTreeListColumn

Determines the visible position of the current column within its band.

Syntax

property VisibleIndexAtBand: Integer;

Description
This property returns the column's index within the band's VisibleColumns collection. For hidden columns, the
VisibleIndexAtBand property returns –1.
To obtain the total number of elements within a band's VisibleColumns collection, use the band's VisibleColumnCount property.
To determine a column's visible position within the TreeList control, use the column's VisibleIndex property.

To access all columns contained within a band, use the band's Columns collection. Use the Columns.IndexOf function to
determine the position of a column in this collection.

ReadOnly Property

Related Information

l TcxTreeListColumn.Position
l TcxTreeListColumnPosition.Band

Page 683 of 1199


TcxTreeListColumn.Width
TcxTreeListColumn

Specifies the column width, in pixels.

Syntax

property Width: Integer;

Description
Use this property to set the custom column width that cannot be less than the MinWidth property value. The column
automatically adjusts its width on a screen to display all data cells without the horizontal scrollbar if the control's
OptionsView.ColumnAutoWidth property is set to True.

The Width property automatically updates by multiplying its current value by the form's scaling factor every time it changes at
design-time or runtime.

To restore the column's default MinWidth and Width property values, call the RestoreWidths procedure.

The default value of the Width property is specified by the cxTreeListDefWidth global constant.

Related Information

l TcxCustomTreeList.AdjustColumnsWidth
l TcxCustomTreeList.ApplyBestFit
l TcxTreeListColumn.ApplyBestFit
l TcxTreeListOptionsCustomizing.BandHorzSizing
l TcxTreeListOptionsCustomizing.ColumnHorzSizing

Page 684 of 1199


TcxTreeListCustomizing.MakeBandPageVisible
TcxTreeListCustomizing

Selects the Bands tab.

Syntax

procedure MakeBandPageVisible;

Description
The MakeBandPageVisible method does nothing if the Customize window is invisible (the Visible property is False), or if the
Columns tab is only displayed in the Customize window (the tree list's OptionsView.SimpleCustomizeBox option is enabled).
The Columns tab can be selected using the MakeColumnPageVisible method.

Examples

l Example: TreeList.Customizing, Customizing.MakeBandPageVisible, Customizing.MakeColumnPageVisible,


SimpleCustomizeBox

Related Information

l Customization Form
l ExpressBars: Customization Form
l ExpressNavBar: Customization Form
l ExpressPivotGrid: Customization Form

Page 685 of 1199


TcxTreeListCustomizing.MakeColumnPageVisible
TcxTreeListCustomizing

Selects the Columns tab.

Syntax

procedure MakeColumnPageVisible;

Description
The MakeColumnPageVisible method does nothing if the Customize window is invisible (the Visible property is False), or if the
Columns tab is only displayed in the Customize window (the tree list's OptionsView.SimpleCustomizeBox option is activated).
The Bands tab can be selected using the MakeBandPageVisible method.

Examples

l Example: TreeList.Customizing, Customizing.MakeBandPageVisible, Customizing.MakeColumnPageVisible,


SimpleCustomizeBox

Related Information

l Customization Form
l ExpressBars: Customization Form
l ExpressNavBar: Customization Form
l ExpressPivotGrid: Customization Form

Page 686 of 1199


TcxTreeListCustomizing.RowCount
TcxTreeListCustomizing

Specifies the Customize window's height, in rows.

Syntax

property RowCount: Integer;

Description
This property only affects the number of headers (either the band headers or column headers) visible in the Customize window,
not the total number of headers contained in the window.
If the number of the specified visible headers is less than the number of headers placed in the window, a scrollbar is displayed.

The default value of the RowCount property is 10.

Related Information

l Customization Form
l ExpressBars: Customization Form
l ExpressNavBar: Customization Form
l ExpressPivotGrid: Customization Form

Page 687 of 1199


TcxTreeListCustomizing.Visible
TcxTreeListCustomizing

Indicates whether the customization form is visible.

Syntax

property Visible: Boolean;

Description
Read the Visible property to determine the customization form's visibility. Set the property to True, to display the customization
form; set it to False, to hide it.
The customization form provides storage for bands and columns. It can be used by an end-user to hide some bands and/or
columns from the TreeList control. To do this, the end-user should drag the desired bands and/or columns to the form.
Additionally, you can use the OnCustomizationVisibleChanged event to track when the customization form's visibility changes.

Related Information

l Customization Form
l ExpressBars: Customization Form
l ExpressNavBar: Customization Form
l ExpressPivotGrid: Customization Form

Page 688 of 1199


TcxTreeListCustomPopupMenu.PopupMenu
TcxTreeListCustomPopupMenu

Specifies a TComponent descendant that is used as a custom context menu.

Syntax

property PopupMenu: TComponent;

Description
You can assign any TMenu descendant to this property. In TcxTreeListCustomPopupMenu descendants, the specified menu
is used as an option for the built-in context menu, if it's disabled via the UseBuiltInMenu property.

Page 689 of 1199


TcxTreeListCustomPopupMenu.Root
TcxTreeListCustomPopupMenu

Provides access to the virtual root menu item that nests all menu items.

Syntax

property Root: TComponent;

Description
Menu items on the first menu level represent the immediate child items of the root menu item.

ReadOnly Property

Page 690 of 1199


TcxTreeListCustomPopupMenu.TreeList
TcxTreeListCustomPopupMenu

Provides access to the TreeList control with which the context menu is associated.

Syntax

property TreeList: TcxCustomTreeList;

Description
If you're implementing a custom context menu, use this property to access TreeList settings and data.

ReadOnly Property

Page 691 of 1199


TcxTreeListFooterPopupMenu.Items
TcxTreeListFooterPopupMenu

Specifies the visibility of menu items.

Syntax

type
TcxTreeListFooterPopupMenuItem = (tlfmiSum, tlfmiMin, tlfmiMax, tlfmiAverage, tlfmiCount,
TcxTreeListFooterPopupMenuItems = set of TcxTreeListFooterPopupMenuItem;
property Items: TcxTreeListFooterPopupMenuItems;

Description
Set an option flag within the Items property to make a corresponding menu item visible.
The image and table below show menu items and corresponding option flags, and command identity values used to create these items

# Option Flag Command Identity Value

1 tlfmiSum tlcmSum

2 tlfmiMin tlcmMin

3 tlfmiMax tlcmMax

4 tlfmiAverage tlcmAverage

5 tlfmiCount tlcmCount

6 tlfmiNone tlcmNone

7 tlfmiAllNodes tlcmAllNodes

Page 692 of 1199


TcxTreeListHitTest.CanMoving
TcxTreeListHitTest

Returns whether a tree list element to which a test point belongs can be dragged.

Syntax

function CanMoving: Boolean; virtual;

Description
The CanMoving method is used to determine the availability of a drag operation for the following tree list elements:
l A band header (see the HitAtBandHeader property).
l A column header (see the HitAtColumnHeader property).

This method is for internal use only.

Related Information

l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 693 of 1199


TcxTreeListHitTest.CanSizing
TcxTreeListHitTest

Returns whether a tree list element to which a test point belongs can be resized.

Syntax

type
TcxDragSizingDirection = (dsdHorz, dsdVert);
function CanSizing: Boolean;
function CanSizing(var ASizeDirection: TcxDragSizingDirection): Boolean; virtual;

Description
The CanSizing method is used to determine the availability of resizing for the following tree list elements:
l A band header (see the HitAtBandHeader property).
l A column header (see the HitAtColumnHeader property).
l A tree list node (see the HitAtNode property).

ASizeDirection specifies the resizing direction.

This method is for internal use only.

Related Information

l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 694 of 1199


TcxTreeListHitTest.Cursor
TcxTreeListHitTest

Returns the cursor to be shown for the test point.


ReadOnly Property

Syntax

property Cursor: TCursor;

Related Information

l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 695 of 1199


TcxTreeListHitTest.HitAtBackground
TcxTreeListHitTest

Checks whether the test point belongs to the tree list background.

Syntax

property HitAtBackground: Boolean;

Description
This property returns True if the point belongs to the tree list background.

ReadOnly Property

Related Information

l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 696 of 1199


TcxTreeListHitTest.HitAtBand
TcxTreeListHitTest

Indicates whether the test point belongs to a band's content.

Syntax

property HitAtBand: Boolean;

Description
This property returns True if the point belongs to a band's content.

ReadOnly Property

Related Information

l TcxTreeListHitTest.HitAtBandHeader
l TcxTreeListHitTest.HitBand
l TcxTreeListStyles.BandContent
l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 697 of 1199


TcxTreeListHitTest.HitAtBandContainer
TcxTreeListHitTest

Indicates whether the test point belongs to the column header panel.

Syntax

property HitAtBandContainer: Boolean;

Description
This property returns True if the point belongs to the column header panel (see the image below).

You can use the HitBand property to access the band to which this column header panel point corresponds.

ReadOnly Property

Related Information

l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 698 of 1199


TcxTreeListHitTest.HitAtBandCustomizing
TcxTreeListHitTest

Indicates whether the test point belongs to the Quick Band Customization button.

Syntax

property HitAtBandCustomizing: Boolean;

Description
This property returns True if the point belongs to the Quick Band Customization button. Because this button is displayed within
an indicator cell, the HitAtIndicator property also returns True if the HitAtBandCustomizing property returns True.

ReadOnly Property

Related Information

l TcxTreeListHitTest.HitAtColumnCustomizing
l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 699 of 1199


TcxTreeListHitTest.HitAtBandHeader
TcxTreeListHitTest

Indicates whether the test point belongs to a TreeList band header.

Syntax

property HitAtBandHeader: Boolean;

Description
Use the HitAtBandHeader property to determine whether the point being tested belongs to a TreeList band header (the band
header is shown in the image below). The property returns True if the point belongs to any band header.

ReadOnly Property

Related Information

l TcxTreeListHitTest.HitAtBand
l TcxTreeListHitTest.HitAtColumnHeader
l TcxTreeListHitTest.HitBand
l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 700 of 1199


TcxTreeListHitTest.HitAtButton
TcxTreeListHitTest

Indicates whether the test point belongs to the TreeList node expand button.

Syntax

property HitAtButton: Boolean;

Description
Use the HitAtButton property to determine whether the point being tested belongs to a TreeList node expand button (this button
is shown in the image below). The property returns True if the point belongs to any node expand button.

ReadOnly Property

Related Information

l TcxTreeListHitTest.HitAtNode
l TcxTreeListHitTest.HitNode
l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 701 of 1199


TcxTreeListHitTest.HitAtCheckButton
TcxTreeListHitTest

Indicates whether the test point belongs to the node check box (radio button).

Syntax

property HitAtCheckButton: Boolean;

Description
This property returns True if the test point belongs to the node check box (radio button).

ReadOnly Property

Related Information

l TcxTreeListNode.CheckGroupType
l TcxTreeListOptionsView.CheckGroups
l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 702 of 1199


TcxTreeListHitTest.HitAtColumn
TcxTreeListHitTest

Indicates whether the test point belongs to the TreeList column.

Syntax

property HitAtColumn: Boolean;

Description
Use the HitAtColumn property to determine whether the point being tested belongs to a TreeList column (TreeList columns are
shown in the image below). The property returns True if the point belongs to any column.

ReadOnly Property

Related Information

l TcxTreeListHitTest.HitAtBand
l TcxTreeListHitTest.HitAtBandHeader
l TcxTreeListHitTest.HitBand
l TcxTreeListHitTest.HitColumn
l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 703 of 1199


TcxTreeListHitTest.HitAtColumnCustomizing
TcxTreeListHitTest

Indicates whether the test point belongs to the Quick Column Customization button.

Syntax

property HitAtColumnCustomizing: Boolean;

Description
This property returns True if the point belongs to the Quick Column Customization button. Because this button is displayed
within an indicator cell, the HitAtIndicator property also returns True if the HitAtColumnCustomizing property returns True.

ReadOnly Property

Related Information

l TcxTreeListHitTest.HitAtBandCustomizing
l TcxTreeListHitTest.HitAtIndicator
l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 704 of 1199


TcxTreeListHitTest.HitAtColumnHeader
TcxTreeListHitTest

Indicates whether the test point belongs to a TreeList column header.

Syntax

property HitAtColumnHeader: Boolean;

Description
Use the HitAtColumnHeader property to determine whether the point being tested belongs to a TreeList column header
(column headers are shown in the image below). The property returns True if the point belongs to any column header.

ReadOnly Property

Related Information

l TcxTreeListHitTest.HitAtBand
l TcxTreeListHitTest.HitAtBandHeader
l TcxTreeListHitTest.HitAtColumn
l TcxTreeListHitTest.HitBand
l TcxTreeListHitTest.HitColumn

Page 705 of 1199


l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 706 of 1199


TcxTreeListHitTest.HitAtFindPanel
TcxTreeListHitTest

Indicates if the test point belongs to the TreeList control's Find Panel.

Syntax

property HitAtFindPanel: Boolean;

Description
This property returns True if the test point falls within the Find Panel's bounds; otherwise – False.

ReadOnly Property

Related Information

l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 707 of 1199


TcxTreeListHitTest.HitAtFooter
TcxTreeListHitTest

Indicates whether the test point belongs to the TreeList footer.

Syntax

property HitAtFooter: Boolean;

Description
Use the HitAtFooter property to determine whether the point being tested belongs to the TreeList footer (the footer is shown in
the image below). The property returns True if the point belongs to the footer.

ReadOnly Property

Related Information

l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 708 of 1199


TcxTreeListHitTest.HitAtFooterItem
TcxTreeListHitTest

Indicates whether the test point belongs to a TreeList footer item.

Syntax

property HitAtFooterItem: Boolean;

Description
Use the HitAtFooterItem property to determine whether the point being tested belongs to the TreeList footer item (footer items
are shown in the image below). The property returns True if the point belongs to any footer item.

ReadOnly Property

Related Information

l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 709 of 1199


TcxTreeListHitTest.HitAtGroupFooter
TcxTreeListHitTest

Indicates whether the test point belongs to the group footer.

Syntax

property HitAtGroupFooter: Boolean;

Description
This property returns True if the test point is belongs to any group footer.

ReadOnly Property

Related Information

l TcxTreeListHitTest.HitAtFooter
l TcxTreeListHitTest.HitAtFooterItem
l TcxTreeListHitTest.HitAtGroupFooterItem
l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 710 of 1199


TcxTreeListHitTest.HitAtGroupFooterItem
TcxTreeListHitTest

Indicates whether the test point belongs to the group footer cell.

Syntax

property HitAtGroupFooterItem: Boolean;

Description
This property returns True if the test point is belongs to any group footer cell.

ReadOnly Property

Related Information

l TcxTreeListHitTest.HitAtFooter
l TcxTreeListHitTest.HitAtFooterItem
l TcxTreeListHitTest.HitAtGroupFooter
l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 711 of 1199


TcxTreeListHitTest.HitAtImage
TcxTreeListHitTest

Indicates whether the test point belongs to a TreeList node image.

Syntax

property HitAtImage: Boolean;

Description
Use the HitAtImage property to determine whether the point being tested belongs to a TreeList node image (node images are
shown in the image below). The property returns True if the point belongs to any node image area.

ReadOnly Property

Related Information

l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 712 of 1199


TcxTreeListHitTest.HitAtImages
TcxTreeListHitTest

Indicates whether the test point belongs to a TreeList node images area (state image or node image).

Syntax

property HitAtImages: Boolean;

Description
Use the HitAtImages property to determine whether the point being tested belongs to a TreeList images area (node images are
shown in the image below). The property returns True if the point belongs to any node images area.

ReadOnly Property

Related Information

l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 713 of 1199


TcxTreeListHitTest.HitAtIndent
TcxTreeListHitTest

Indicates whether the test point belongs to a TreeList node indent.

Syntax

property HitAtIndent: Boolean;

Description
Use the HitAtIndent property to determine whether the point being tested belongs to a TreeList node indent (it is shown in the
image below). The property returns True if the point belongs to any node indent.

ReadOnly Property

Related Information

l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 714 of 1199


TcxTreeListHitTest.HitAtIndicator
TcxTreeListHitTest

Indicates whether the test point belongs to the TreeList indicator.

Syntax

property HitAtIndicator: Boolean;

Description
Use the HitAtIndicator property to determine whether the point being tested belongs to the TreeList indicator (the indicator is
shown in the image below). The property returns True if the point belongs to the indicator.

ReadOnly Property

Related Information

l TcxTreeListHitTest.HitAtBandCustomizing
l TcxTreeListHitTest.HitAtColumnCustomizing
l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 715 of 1199


TcxTreeListHitTest.HitAtNavigator
TcxTreeListHitTest

Indicates whether the test point belongs to the TreeList navigator.

Syntax

property HitAtNavigator: Boolean;

Description
This property returns True if the test point belongs to the navigator.

ReadOnly Property

Related Information

l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 716 of 1199


TcxTreeListHitTest.HitAtNode
TcxTreeListHitTest

Indicates whether the test point belongs to a TreeList node.

Syntax

property HitAtNode: Boolean;

Description
Use the HitAtNode property to determine whether the point being tested belongs to a TreeList node (as shown on the image
below). The property returns True if the point belongs to any node.

Note that the node preview area is not included in the node area. Use the HitAtNodePreview property instead.

ReadOnly Property

Related Information

l TcxTreeListHitTest.HitNode
l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 717 of 1199


TcxTreeListHitTest.HitAtNodePreview
TcxTreeListHitTest

Indicates whether the test point belongs to a TreeList node preview section.

Syntax

property HitAtNodePreview: Boolean;

Description
Use the HitAtNodePreview property to determine whether the point being tested belongs to a TreeList node preview section (as
shown in the image below). The property returns True if the point belongs to any node preview section.

ReadOnly Property

Related Information

l TcxTreeListHitTest.HitNode
l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 718 of 1199


TcxTreeListHitTest.HitAtSeparator
TcxTreeListHitTest

Indicates whether the test point belongs to a TreeList fixed band separator.

Syntax

property HitAtSeparator: Boolean;

Description
Use the HitAtSeparator property to determine whether the point being tested belongs to a TreeList fixed band separator (as
shown in the image below). The property returns True if the point belongs to any fixed band separator.

ReadOnly Property

Related Information

l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 719 of 1199


TcxTreeListHitTest.HitAtSizingHorz
TcxTreeListHitTest

Indicates whether the test point belongs to a TreeList column or a band's horizontal sizing edge.

Syntax

property HitAtSizingHorz: Boolean;

Description
Use the HitAtSizingHorz property to determine whether the point being tested belongs to a TreeList column or a band's
horizontal sizing edge (sizing edges are shown in the image below). The property returns True if the point belongs to any column
or band horizontal sizing edge.

ReadOnly Property

Concepts

l Resizing Bands and Columns

Related Information

l TcxTreeListHitTest.HitAtSizingVert

Page 720 of 1199


l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 721 of 1199


TcxTreeListHitTest.HitAtSizingVert
TcxTreeListHitTest

Indicates whether the test point belongs to a TreeList column or a band's vertical sizing edge.

Syntax

property HitAtSizingVert: Boolean;

Description
Use the HitAtSizingVert property to determine whether the point being tested belongs to a TreeList column or a band's vertical
sizing edge (sizing edges are shown in the image below). The property returns True if the point belongs to any column or band
vertical sizing edge.

ReadOnly Property

Concepts

l Resizing Bands and Columns

Related Information

l TcxTreeListHitTest.HitAtSizingHorz

Page 722 of 1199


l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 723 of 1199


TcxTreeListHitTest.HitAtStateImage
TcxTreeListHitTest

Indicates whether the test point belongs to a TreeList node's state image.

Syntax

property HitAtStateImage: Boolean;

Description
Use the HitAtStateImage property to determine whether the point being tested belongs to a TreeList node's state image (node
images are shown in the image below). The property returns True if the point belongs to any node's state image area.

ReadOnly Property

Related Information

l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 724 of 1199


TcxTreeListHitTest.HitBand
TcxTreeListHitTest

Provides access to the TreeList band that corresponds to the test point.

Syntax

property HitBand: TcxTreeListBand;

Description
If the point does not correspond to any band, the HitBand property returns nil.

ReadOnly Property

Related Information

l TcxTreeListHitTest.HitAtBand
l TcxTreeListHitTest.HitAtBandContainer
l TcxTreeListHitTest.HitAtBandHeader
l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 725 of 1199


TcxTreeListHitTest.HitColumn
TcxTreeListHitTest

Provides access to the TreeList column that contains the test point.

Syntax

property HitColumn: TcxTreeListColumn;

Description
If the point does not belong to any column, the HitColumn property returns nil. To determine whether the point belongs to any
column, use the HitAtColumn property.

ReadOnly Property

Related Information

l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 726 of 1199


TcxTreeListHitTest.HitNode
TcxTreeListHitTest

Provides access to the node that contains the test point.

Syntax

property HitNode: TcxTreeListNode;

Description
If the point does not belong to any node, the HitNode property returns nil. To determine whether the point belongs to any node,
use the HitAtNode property.

ReadOnly Property

Related Information

l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 727 of 1199


TcxTreeListHitTest.TreeList
TcxTreeListHitTest

Provides access to the TreeList control that contains the test point.
ReadOnly Property

Syntax

property TreeList: TcxCustomTreeList;

Related Information

l ExpressEditors: TcxCustomHitTestController.HitX
l ExpressEditors: TcxCustomHitTestController.HitY

Page 728 of 1199


TcxTreeListLikeParams.Create
TcxTreeListLikeParams

Instantiates a TcxTreeListLikeParams object with the specified wildcards.

Syntax

constructor Create(APercent: Char = '%'; AUnderline: Char = '_');

Description
This constructor sets the TcxTreeListLikeParams object's properties to the default values (the Percent property to the '%', and
the Underline property to the '_').

Page 729 of 1199


TcxTreeListLikeParams.Percent
TcxTreeListLikeParams

Specifies the wildcard used for matching any number of characters.

Syntax

property Percent: Char;

Page 730 of 1199


TcxTreeListLikeParams.UnderLine
TcxTreeListLikeParams

Specifies the wildcard used for matching a single character.

Syntax

property UnderLine: Char;

Page 731 of 1199


TcxTreeListNode.AbsoluteIndex
TcxTreeListNode

Returns the node's index within the control.

Syntax

property AbsoluteIndex: Integer;

Description
Use the AbsoluteIndex property to obtain the node's index. This index is zero-based and starts from the root node. The first
sibling node has the AbsoluteIndex value 1. Then the child nodes of this node are indexed, if any. When all child nodes of a
node are indexed, indexing continues from the next node at the upper level. In other words, indexes are assigned to nodes as if
all parent nodes within the TreeList control are expanded.
The following image explains node indexing:

Note: this property value is affected when the node order is changed.

ReadOnly Property

Related Information

l TcxTreeListNode.Index
l TcxTreeListNode.IndexOf

Page 732 of 1199


TcxTreeListNode.AddChild
TcxTreeListNode

Adds a child node.

Syntax

function AddChild: TcxTreeListNode; virtual;

Description
Use the AddChild method to add a child node to the current one. This method returns the node added. The new node is
appended to the end of the child collection. Use the AddChildFirst method instead to add the child node at the first position. The
node's child nodes can be accessed via its Items property.

Note:   Only use this method when working with TcxTreeList (an unbound mode TreeList control).

Examples

l Example: TreeList.Items[], TreeList.Count, Node.AddChild, Node.AddChildFirst

Related Information

l TcxTreeListNode.AddChildFirst

Page 733 of 1199


TcxTreeListNode.AddChildFirst
TcxTreeListNode

Inserts a child node.

Syntax

function AddChildFirst: TcxTreeListNode; virtual;

Description
Use the AddChildFirst method to insert a new child node into the node. The new node is inserted at the first position within the
child collection. Use the AddChild method instead to insert the new node at the first position of the collection. The node's child
nodes can be accessed via its Items property.

Examples

l Example: TreeList.Items[], TreeList.Count, Node.AddChild, Node.AddChildFirst

Related Information

l TcxTreeListNode.AddChild

Page 734 of 1199


TcxTreeListNode.AllowGrayed
TcxTreeListNode

Specifies the check mode of the node check box.

Syntax

property AllowGrayed: Boolean;

Description
If the AllowGrayed property is True, the check box is used as a three-state check box – it can have the checked, unchecked or
grayed states.
Otherwise, the check box can only be checked or unchecked.
The AllowGrayed property only affects end-user actions and the CheckClick method, and doesn't affect the CheckState
property.
The property is in effect if the tree list's OptionsView.CheckGroups option is active and the node's CheckGroupType property is
not ncgNone.

Related Information

l TcxTreeListNode.Checked
l TcxTreeListNode.CheckGroupType
l TcxTreeListNode.CheckState
l TcxTreeListNode.Enabled

Page 735 of 1199


TcxTreeListNode.AlphaSort
TcxTreeListNode

Sorts the node's child nodes.

Syntax

procedure AlphaSort(ARecurse: Boolean = False);

Description
The order in which the AlphaSort method sorts nodes is dependent upon the column's SortOrder property. Note that if the
column's SortOrder property is soNone, nodes are sorted by the indexes of the corresponding records.
In order to sort nodes starting from a tree list top level, use the tree list Root's AlphaSort method.
ARecurse specifies whether sorting is to be performed recursively (in all children). If ARecurse is False, only the node's
immediate children are sorted.

Related Information

l TcxTreeListColumn.SortOrder
l TcxTreeListNode.CustomSort

Page 736 of 1199


TcxTreeListNode.AssignValues
TcxTreeListNode

Assigns the node's column values.

Syntax

procedure AssignValues(const AValues: array of Variant);

Description
Use the AssignValues method to assign the node's column values. You can access all the node's column values via the Values
property.

Note: when using a data-aware TreeList (cxDBTreeList), only call the AssignValues method for the focused node in edit mode.

Related Information

l TcxTreeListNode.Texts
l TcxTreeListNode.ValueCount
l TcxTreeListNode.Values

Page 737 of 1199


TcxTreeListNode.CanCollapse
TcxTreeListNode

Indicates whether the node can be collapsed.

Syntax

function CanCollapse: Boolean;

Description
Use the CanCollapse method to determine whether the node can collapse. If this method returns True, the node can be
collapsed by clicking the expand button or by calling the Collapse method. Use TreeList.FullCollapse to collapse all expanded
TreeList nodes.
This method call fires the OnCollapsing event.

Related Information

l TcxCustomTreeList.FullCollapse
l TcxCustomTreeList.FullExpand
l TcxTreeListNode.CanExpand
l TcxTreeListNode.Collapse
l TcxTreeListNode.Expand

Page 738 of 1199


TcxTreeListNode.CanExpand
TcxTreeListNode

Indicates whether the node can be expanded.

Syntax

function CanExpand: Boolean;

Description
Use the CanExpand method to determine whether the current node can be expanded. If this method returns True, the node can
be expanded by clicking the expand button or by calling the Expand method. Use TreeList.FullExpand to expand all collapsed
TreeList nodes.
This method call fires the OnExpanding event.

Related Information

l TcxCustomTreeList.FullCollapse
l TcxCustomTreeList.FullExpand
l TcxTreeListNode.CanCollapse
l TcxTreeListNode.Collapse
l TcxTreeListNode.Expand

Page 739 of 1199


TcxTreeListNode.CanMove
TcxTreeListNode

Indicates whether the node can be moved to the location specified within the TreeList.

Syntax

function CanMove(ADest: TcxTreeListNode; AMode: TcxTreeListNodeAttachMode): Boolean;

Description
Use the CanMove method to determine whether the node can be moved to the location specified within the TreeList control.
ADest specifies the destination.
AMode specifies the manner in which the current node is moved.

Page 740 of 1199


TcxTreeListNode.CheckClick
TcxTreeListNode

Changes the state of the node check box.

Syntax

procedure CheckClick;

Description
In two-state check mode (the AllowGrayed property is False), successive calls to the CheckClick method change a check box
between two states – either checked or unchecked.
In three-state check mode (the AllowGrayed property is True), successive calls to the CheckClick method change a check box
between three states – checked, unchecked or grayed.
If a check box is disabled (the Enabled property is False), the method does nothing.
To respond to changes made to the node check box's state, handle the tree list's OnNodeCheckChanged event.

Related Information

l TcxTreeListNode.AllowGrayed
l TcxTreeListNode.Checked
l TcxTreeListNode.CheckState
l TcxTreeListNode.Enabled

Page 741 of 1199


TcxTreeListNode.Checked
TcxTreeListNode

Specifies the node's checked state.

Syntax

property Checked: Boolean;

Description
Set this property to True, to mark the node as checked. Otherwise, it will be unchecked.
A node indicates its checked state using a control set by the parent node's CheckGroupType property. The parent node keeps
track of child states, and automatically changes its state to unchecked (if the two-state mode is enabled) or grayed (if the three-
state mode is enabled), if one of its checked children has been unchecked or grayed. To specify the grayed state, use the
CheckState property instead.

To respond to changes made to the node's checked state, handle the tree list's OnNodeCheckChanged event.

Related Information

l TcxTreeListNode.Enabled

Page 742 of 1199


TcxTreeListNode.CheckState
TcxTreeListNode

Specifies the state of the control (check box or radio button) used to indicate the node's checked state.

Syntax

type
TcxCheckBoxState = (cbsUnchecked, cbsChecked, cbsGrayed);
property CheckState: TcxCheckBoxState;

Description
Along with the checked and unchecked states, this property also allows you to specify the control's grayed state, regardless of
the AllowGrayed property setting. If no control is set (the parent node's CheckGroupType property is set to ncgNone), the
CheckState property always returns cbsUnchecked.
To learn about values that represent all the available control states, refer to the TcxCheckBoxState enumeration.

The parent node keeps track of child states, and automatically changes its state to unchecked (if the two-state mode is enabled)
or grayed (if the three-state mode is enabled), if one of its checked children has been unchecked or grayed. To respond to
changes made to the node control's state, handle the tree list's OnNodeCheckChanged event.

Note:   A parent node's CheckState property value is not automatically updated when any of the following takes place:
l A parent node's CheckGroupType property value is changed.
l A parent node's collection of child nodes is changed (for instance, by adding or removing child nodes).

Related Information

l TcxTreeListNode.Enabled

Page 743 of 1199


TcxTreeListNode.ChildVisibleCount
TcxTreeListNode

Returns the number of the node's children available in the View.

Syntax

property ChildVisibleCount: Integer;

Description
Filtered out children (whose Visible property is False) are not taken into account.

ReadOnly Property

Page 744 of 1199


TcxTreeListNode.Collapse
TcxTreeListNode

Collapses the TreeList node.

Syntax

procedure Collapse(Recurse: Boolean);

Description
Use the Collapse method to collapse the TreeList node. The Recurse parameter identifies whether all child nodes are collapsed
recursively. If this parameter value is True, all children of the node are displayed collapsed when the node is expanded again.
Otherwise, children retain their current state.

Related Information

l TcxTreeListNode.CanCollapse
l TcxTreeListNode.CanExpand
l TcxTreeListNode.Expand
l TcxTreeListNode.Expanded

Page 745 of 1199


TcxTreeListNode.Count
TcxTreeListNode

Returns the number of child nodes.

Syntax

property Count: Integer;

Description
Use the Count property to obtain the number of child nodes owned by the node. You can access all child nodes of the node via
the Items property.

ReadOnly Property

Page 746 of 1199


TcxTreeListNode.CustomSort
TcxTreeListNode

Custom sorts the node's children.

Syntax

type
TcxTreeListCompareFunc = function(AItem1, AItem2: TcxTreeListNode): Integer;
procedure CustomSort(ASortProc: TcxTreeListCompareFunc; ARecurse: Boolean = False);

Description
Use the CustomSort method to custom sort the node's children. The ASortProc parameter specifies the comparison routine.
If ASortProc is nil, a default comparison routine is used. The default routine uses the OnCompare event handler, if defined. If the OnCo
In the comparison routine, the AItem1 and AItem2 parameters refer to two. The return value of the comparison routine indicates the rela

return value > 0 AItem1 comes before AItem2

return value is 0 AItem1 and AItem2 are equivalent

return value < 0 AItem2 comes before AItem1

The optional ARecurse parameter specifies that sorting should recursively descend the node tree and sort each sub-tree in turn.

The following code shows use of the CustomSort method. The MyCustomSort function compares nodes by two last symbols of PHON

[Delphi]
function MyCustomSort(AItem1, AItem2: TcxTreeListNode): Integer;
begin
Result := AnsiCompareStr(AnsiRightStr(AItem1.Texts[SimpleTreeDemoMainForm.cxDBTreeListPHONE.It
end;
procedure TSimpleTreeDemoMainForm.Button1Click(Sender: TObject);
begin
cxdbtreelist.FocusedNode.CustomSort(MyCustomSort, True);
end;

Related Information

l TcxTreeListNode.AlphaSort

Page 747 of 1199


TcxTreeListNode.Data
TcxTreeListNode

Specifies the pointer to data associated with the node.

Syntax

property Data: Pointer;

Description
Use the Data property to associate data with the node. If you assigned data to this property, it must be released manually before
a node is deleted. To accomplish this, handle the TreeList control's OnDeletion event.

Page 748 of 1199


TcxTreeListNode.Delete
TcxTreeListNode

Removes the node and all its children from the TreeList control.

Syntax

procedure Delete;

Description
Use the Delete method to remove the node from the TreeList control. This method is in effect even if the OptionsData.Deleting
option is deactivated.
Note that this method removes the node and all its children.
The TreeList.OnDeletion event occurs before deleting a node.

Related Information

l Deleting Nodes
l TcxTreeListNode.DeleteChildren
l TcxTreeListNode.Deleting

Page 749 of 1199


TcxTreeListNode.DeleteChildren
TcxTreeListNode

Removes the node's children.

Syntax

procedure DeleteChildren;

Description
Use the DeleteChildren method to remove the node's children. After this method executes, the node's Items collection is
empty.
The TreeList.OnDeletion event occurs before deleting each node.

Related Information

l Deleting Nodes
l TcxTreeListNode.Delete
l TcxTreeListNode.Deleting
l TcxTreeListOptionsData.Deleting

Page 750 of 1199


TcxTreeListNode.Deleting
TcxTreeListNode

Indicates whether a node's Delete method has been called and if the node is being deleted.

Syntax

property Deleting: Boolean;

Description
The Deleting property returns true if the node object is in the process of being deleted. Use Deleting to prevent infinite recursion
in event handlers.

ReadOnly Property

Related Information

l TcxCustomTreeList.OnDeletion

Page 751 of 1199


TcxTreeListNode.DisplayRect
TcxTreeListNode

Returns the node's bounding rectangle.

Syntax

function DisplayRect(AEntryOnly: Boolean): TRect;

Description
Use the DisplayRect method to obtain the node's bounding rectangle. The AEntryOnly parameter specifies whether the whole
node area is included in the returned rectangle or only the node's cells area. If AEntryOnly is True, the bounding rectangle
contains the cells area only.
The red rectangles on the following image represent the node's DisplayRect when AEntryOnly is False, while the blue rectangles
represent the cells area bounding rectangles:

Page 752 of 1199


TcxTreeListNode.Enabled
TcxTreeListNode

Specifies whether an end-user can change the node check box's state.

Syntax

property Enabled: Boolean;

Description
Set the Enabled property to True, to enable state change. Otherwise, the check box is displayed grayed and doesn't respond to
end-user actions.

Related Information

l TcxTreeListNode.Checked
l TcxTreeListNode.CheckGroupType
l TcxTreeListNode.CheckState

Page 753 of 1199


TcxTreeListNode.EndEdit
TcxTreeListNode

Switches the node from edit to browse mode.

Syntax

procedure EndEdit(Cancel: Boolean);

Description
Use the EndEdit method to finish editing the node. If the Cancel parameter is True, changes made to the node's contents are
not saved. Otherwise, the node's contents are updated and the OnEdited event is fired.

Page 754 of 1199


TcxTreeListNode.Expand
TcxTreeListNode

Expands the node.

Syntax

procedure Expand(Recurse: Boolean);

Description
Use the Expand method to expand the node. The Recurse parameter identifies whether all child nodes are expanded recursively.
If this parameter value is True, all children of the node are expanded when the node is expanded. Otherwise, children retain their
current state.

Page 755 of 1199


TcxTreeListNode.Expanded
TcxTreeListNode

Specifies whether the node is expanded.

Syntax

property Expanded: Boolean;

Description
Use the Expanded property to determine whether the node is expanded or collapsed. Setting this property to True expands a
node.
You can call the Expand method to expand a particular node.
Handle the TreeList.OnExpanded and TreeList.OnExpanding events to process nodes' expansion.

Page 756 of 1199


TcxTreeListNode.Focused
TcxTreeListNode

Determines whether the node has focus.

Syntax

property Focused: Boolean;

Description
Use the Focused property to determine whether the node has focus. Setting this property to True moves focus to the node.
The TreeList.FocusedNode property identifies the focused node.

Examples

l Example: Column.Focused, Node.Focused, Node.GetPrevVisible, Node.GetPrev, Node.GetNextVisible, Node.GetNext

Related Information

l TcxCustomTreeList.FocusedColumn
l TcxCustomTreeList.FocusedNode
l TcxTreeListOptionsView.FocusRect

Page 757 of 1199


TcxTreeListNode.FooterSummaryCount
TcxTreeListNode

Returns the number of node summaries.

Syntax

property FooterSummaryCount: Integer;

Description
For the root node, the property returns the number of footer summaries. For all other nodes, the number of group summaries is
returned.

For indexed access to the node's summary values, use the node's FooterSummaryValues property.
For indexed access to display values of the node's summaries, use the node's FooterSummaryTexts property.

ReadOnly Property

Page 758 of 1199


TcxTreeListNode.FooterSummaryTexts
TcxTreeListNode

Provides indexed access to display values of the node's summaries.

Syntax

property FooterSummaryTexts[Index: Integer]: string;

Description
For the root node, the property provides access to footer summaries. For all other nodes, provides access to group summaries.
Index specifies the summary's position in the collection.

For indexed access to the node's summary values, use the node's FooterSummaryValues property instead.
The total number of the node's summaries can be obtained using the FooterSummaryCount property.

ReadOnly Property

Page 759 of 1199


TcxTreeListNode.FooterSummaryValues
TcxTreeListNode

Provides indexed access to the node's summary values.

Syntax

property FooterSummaryValues[Index: Integer]: Variant;

Description
For the root node, the property provides access to footer summaries. For all other nodes, provides access to group summaries.
Index specifies the summary's position in the collection.

For indexed access to display values of the node's summaries, use the node's FooterSummaryTexts property instead.
The total number of the node's summaries can be obtained using the FooterSummaryCount property.

Page 760 of 1199


TcxTreeListNode.getFirstChild
TcxTreeListNode

Returns the node's first child.

Syntax

function getFirstChild: TcxTreeListNode;

Description
The method returns the first child from the node's Items collection. The method ignores node filtering by the Visible property. If
the node is not a parent, nil will be returned.

To obtain the first visible child, use the GetFirstChildVisible method instead.

Related Information

l TcxTreeListNode.GetLastChild
l TcxTreeListNode.GetNextChild
l TcxTreeListNode.GetPrevChild
l TcxTreeListNode.HasChildren

Page 761 of 1199


TcxTreeListNode.GetFirstChildVisible
TcxTreeListNode

Returns a node's first child that is available in the View.

Syntax

function GetFirstChildVisible: TcxTreeListNode;

Description
The method returns the first child (from the node's Items collection) whose Visible property is True. If all children are filtered out,
nil will be returned.

In order to obtain a first child from the child collection, independent of the visibility status, use the getFirstChild method instead.

Related Information

l TcxTreeListNode.GetNextVisible
l TcxTreeListNode.GetPrevVisible

Page 762 of 1199


TcxTreeListNode.GetLastChild
TcxTreeListNode

Returns the node's last child.

Syntax

function GetLastChild: TcxTreeListNode;

Description
The method returns the first child from the node's Items collection. The method ignores node filtering by the Visible property. If
the node is not a parent, nil will be returned.

To obtain the last visible child, use the GetLastChildVisible method instead.

Related Information

l TcxTreeListNode.getFirstChild
l TcxTreeListNode.GetPrevChild
l TcxTreeListNode.HasChildren

Page 763 of 1199


TcxTreeListNode.GetLastChildVisible
TcxTreeListNode

Returns a node's last child that is available in the View.

Syntax

function GetLastChildVisible:

Description
The method returns the last child (from the node's Items collection) whose Visible property is True. If all children are filtered out,
nil will be returned.

In order to obtain a last child from the child collection, independent of the visibility status, use the GetLastChild method instead.

Related Information

l TcxTreeListNode.GetNextVisible
l TcxTreeListNode.GetPrevVisible

Page 764 of 1199


TcxTreeListNode.GetNext
TcxTreeListNode

Returns the node next to the current one within the tree structure.

Syntax

function GetNext: TcxTreeListNode;

Description
Use the GetNext method to obtain the node that follows the current one within the tree structure. The next node has an
AbsoluteIndex property value one greater than this node. If this method is used for the last node within the tree structure, this
method returns nil.

Examples

l Example: Column.Focused, Node.Focused, Node.GetPrevVisible, Node.GetPrev, Node.GetNextVisible, Node.GetNext

Related Information

l TcxTreeListNode.getFirstChild
l TcxTreeListNode.GetLastChild
l TcxTreeListNode.GetNextChild
l TcxTreeListNode.getNextSibling
l TcxTreeListNode.GetNextVisible
l TcxTreeListNode.GetPrev

Page 765 of 1199


TcxTreeListNode.GetNextChild
TcxTreeListNode

Returns the next child node after the node specified.

Syntax

function GetNextChild(ANode: TcxTreeListNode): TcxTreeListNode;

Description
Use the GetNextChild method to obtain the next child node after the node specified via the ANode parameter. If the node
specified via the ANode parameter has no children, this method returns nil.

Related Information

l TcxTreeListNode.getFirstChild
l TcxTreeListNode.GetLastChild
l TcxTreeListNode.GetNext
l TcxTreeListNode.getNextSibling
l TcxTreeListNode.GetNextVisible
l TcxTreeListNode.GetPrevChild

Page 766 of 1199


TcxTreeListNode.getNextSibling
TcxTreeListNode

Returns the next node at the current nesting level.

Syntax

function getNextSibling: TcxTreeListNode;

Description
If the method is called on the last node at the current level, nil is returned.

To obtain the next visible sibling, use the GetNextSiblingVisible method instead.

Related Information

l TcxTreeListNode.getFirstChild
l TcxTreeListNode.GetLastChild
l TcxTreeListNode.GetNext
l TcxTreeListNode.GetNextChild
l TcxTreeListNode.GetNextVisible
l TcxTreeListNode.getPrevSibling

Page 767 of 1199


TcxTreeListNode.GetNextSiblingVisible
TcxTreeListNode

Returns the next node available in the View at the current nesting level.

Syntax

function GetNextSiblingVisible: TcxTreeListNode;

Description
The method returns the next sibling whose Visible property is True.
If the method is called on the last node at the current level, nil is returned.

To obtain the next node, independent of the visibility status, use the getNextSibling method instead.

Page 768 of 1199


TcxTreeListNode.GetNextVisible
TcxTreeListNode

Returns the next visible node.

Syntax

function GetNextVisible: TcxTreeListNode;

Description
Use the GetNextVisible method to obtain the next visible node. The node's index is specified via the VisibleIndex property.
If this method is called on the last visible node within the tree structure, nil is returned.

Examples

l Example: Column.Focused, Node.Focused, Node.GetPrevVisible, Node.GetPrev, Node.GetNextVisible, Node.GetNext

Related Information

l TcxTreeListNode.GetNext
l TcxTreeListNode.GetNextChild
l TcxTreeListNode.getNextSibling
l TcxTreeListNode.GetPrevVisible
l TcxTreeListNode.VisibleIndex

Page 769 of 1199


TcxTreeListNode.GetPrev
TcxTreeListNode

Returns the node previous to the current one.

Syntax

function GetPrev: TcxTreeListNode;

Description
Use the GetPrev method to obtain the node previous to the current one. The previous node has an AbsoluteIndex property value
one less than this node. If this method is used for the first node within the tree structure, this method returns nil.

Examples

l Example: Column.Focused, Node.Focused, Node.GetPrevVisible, Node.GetPrev, Node.GetNextVisible, Node.GetNext

Related Information

l TcxTreeListNode.getFirstChild
l TcxTreeListNode.GetLastChild
l TcxTreeListNode.GetNext
l TcxTreeListNode.GetPrevChild
l TcxTreeListNode.getPrevSibling
l TcxTreeListNode.GetPrevVisible

Page 770 of 1199


TcxTreeListNode.GetPrevChild
TcxTreeListNode

Returns the previous child of the node specified.

Syntax

function GetPrevChild(ANode: TcxTreeListNode): TcxTreeListNode;

Description
Use the GetPrevChild method to obtain the previous child of the node specified via the ANode parameter. If this node has no
children, the method returns nil.

Related Information

l TcxTreeListNode.getFirstChild
l TcxTreeListNode.GetLastChild
l TcxTreeListNode.GetNextChild
l TcxTreeListNode.GetPrev
l TcxTreeListNode.getPrevSibling
l TcxTreeListNode.GetPrevVisible
l TcxTreeListNode.HasChildren

Page 771 of 1199


TcxTreeListNode.getPrevSibling
TcxTreeListNode

Returns the previous node at the current nesting level.

Syntax

function getPrevSibling: TcxTreeListNode;

Description
Use the getPrevSibling to obtain the previous node at the current nesting level. If this method is used for the first node within
the tree structure, this method returns nil.

Related Information

l TcxTreeListNode.getFirstChild
l TcxTreeListNode.GetLastChild
l TcxTreeListNode.getNextSibling
l TcxTreeListNode.GetPrevChild
l TcxTreeListNode.GetPrevVisible

Page 772 of 1199


TcxTreeListNode.GetPrevSiblingVisible
TcxTreeListNode

Returns the previous node available in the View at the current nesting level.

Syntax

function GetPrevSiblingVisible: TcxTreeListNode;

Description
The method returns the previous sibling whose Visible property is True.
If the method is called on the first node at the current level, nil is returned.

To obtain the previous node, independent of the visibility status, use the getPrevSibling method instead.

Page 773 of 1199


TcxTreeListNode.GetPrevVisible
TcxTreeListNode

Returns the previous visible node.

Syntax

function GetPrevVisible: TcxTreeListNode;

Description
Use the GetPrevVisible method to obtain the previous visible node. The node's index among visible nodes is specified via the
VisibleIndex property.
If this method is called for the first node within the tree structure, this method returns nil.

Examples

l Example: Column.Focused, Node.Focused, Node.GetPrevVisible, Node.GetPrev, Node.GetNextVisible, Node.GetNext

Related Information

l TcxTreeListNode.getFirstChild
l TcxTreeListNode.GetLastChild
l TcxTreeListNode.GetNextVisible
l TcxTreeListNode.GetPrev
l TcxTreeListNode.GetPrevChild
l TcxTreeListNode.getPrevSibling

Page 774 of 1199


TcxTreeListNode.HasAsParent
TcxTreeListNode

Checks whether the specified node is the parent of this node.

Syntax

function HasAsParent(ANode: TcxTreeListNode): Boolean;

Description
Use the HasAsParent method to determine whether the specified node is the parent node of the current one.

Related Information

l TcxTreeListNode.Parent

Page 775 of 1199


TcxTreeListNode.HasCheckbox
TcxTreeListNode

Checks whether the node contains a check box (radio button).

Syntax

property HasCheckbox: Boolean;

Description
The property returns True, if the node contains a check box (the tree list's OptionsView.CheckGroups option is active and the
node's CheckGroupType property is not ncgNone).

ReadOnly Property

Related Information

l TcxCustomTreeList.OnNodeCheckChanged
l TcxTreeListNode.Checked
l TcxTreeListNode.CheckGroupType
l TcxTreeListNode.CheckState
l TcxTreeListNode.Enabled

Page 776 of 1199


TcxTreeListNode.HasChildren
TcxTreeListNode

Specifies whether the node's expand button is to be displayed if the node has no children.

Syntax

property HasChildren: Boolean;

Description
If the HasChildren property and the tree list's OptionsView.Buttons property are True, expand buttons will be displayed in the
node, even if this node has no children. This can be used in situations when it is necessary to add children on demand. For this
purpose, handle the tree list's OnExpanding event to add child nodes (see the node's Items property). At runtime, child nodes will
be dynamically added to the parent when an end-user clicks the node's expand button.
Alternatively, you may prefer to use the built-in smart load capability, which requires no coding. If this feature is enabled, the tree
list is only populated with child nodes at the time when the parent node is being expanded.

If the node has child nodes and the HasChildren property is set to False, this assignment has no effect.

Related Information

l TcxCustomTreeList.OnCollapsed
l TcxCustomTreeList.OnCollapsing
l TcxCustomTreeList.OnExpanded
l TcxCustomTreeList.OnExpanding
l TcxTreeListNode.CanCollapse
l TcxTreeListNode.CanExpand
l TcxTreeListNode.Count
l TcxTreeListNode.Expand
l TcxTreeListNode.Expanded

Page 777 of 1199


TcxTreeListNode.HasVisibleChildren
TcxTreeListNode

Checks whether the node has children available in the View.

Syntax

property HasVisibleChildren: Boolean;

Description
The property returns True, if at least one child's Visible property is True.

ReadOnly Property

Related Information

l TcxTreeListNode.HasChildren

Page 778 of 1199


TcxTreeListNode.Height
TcxTreeListNode

Specifies the node's height, in pixels.

Syntax

property Height: Integer;

Description
The property is used to specify the height of a particular node. If specified, it overrides the tree list's DefaultRowHeight property.
The Height property's value is automatically changed by the control, if the node is resized by an end-user (node resizing is
allowed if the tree list's OptionsCustomizing.NodeSizing option is active).
To specify the height for all nodes, use the tree list's DefaultRowHeight property instead.

Page 779 of 1199


TcxTreeListNode.HotTrack
TcxTreeListNode

Determines whether the node is hot-tracked.

Syntax

property HotTrack: Boolean;

Description
The HotTrack property indicates whether the node is hot-tracked. You can handle the TreeList.OnHotTrackNode event to
process node hot-tracking within the TreeList control.

ReadOnly Property

Related Information

l TcxCustomTreeList.OnHotTrackNode

Page 780 of 1199


TcxTreeListNode.ImageIndex
TcxTreeListNode

Specifies the node's select image.

Syntax

type
{$IFDEF DELPHI17}
TcxImageIndex = System.UITypes.TImageIndex;
{$ELSE}
TcxImageIndex = ImgList.TImageIndex;
{$ENDIF}
property ImageIndex: TcxImageIndex;

Description
Node select images are stored in the Images collections.
For different tree list controls, images are specified in the following ways:
l The TcxVirtualTreeList control – handle the tree list's OnGetNodeImageIndex event to apply node images.
l The TcxDBTreeList control – images can be specified using either the tree list's DataController.ImageIndexField property or
the OnGetNodeImageIndex event.
l The TcxTreeList control – images can be specified directly via the ImageIndex property, or using the tree list's
OnGetNodeImageIndex event.

Related Information

l TcxDBTreeListDataController.ImageIndexField
l TcxTreeListOptionsView.UseImageIndexForSelected

Page 781 of 1199


TcxTreeListNode.Index
TcxTreeListNode

Returns the node index within its parent node's Items collection.

Syntax

property Index: Integer;

Description
Use the Index property of a node to obtain its position among child nodes of its parent. Use the node's Parent property to
access its parent.
The AbsoluteIndex property returns the node's index within the tree structure.

ReadOnly Property

Page 782 of 1199


TcxTreeListNode.IndexOf
TcxTreeListNode

Returns the specified node's index among this node's children.

Syntax

function IndexOf(ANode: TcxTreeListNode): Integer;

Description
Use the IndexOf method to obtain the specified node index among this node's children. If the node specified via the ANode
parameter is not among this node's children, the IndexOf method returns –1. You can also use the node's Index property to
obtain its index among its parent's child collection.

Related Information

l TcxTreeListNode.AbsoluteIndex
l TcxTreeListNode.Index

Page 783 of 1199


TcxTreeListNode.InsertChild
TcxTreeListNode

Inserts a child node into the node's child collection.

Syntax

function InsertChild(ABeforeNode: TcxTreeListNode): TcxTreeListNode; virtual;

Description
Use the InsertChild method to insert a new node into the child collection of this node. The ABeforeNode parameter specifies the
node, before which the new node is inserted. This method returns the node added.
You can call the AddChildFirst method to insert a node as the first of the node's children.

Note: only use this method when working with the cxTreeList control (unbound mode of the TreeList control).

Related Information

l TcxTreeListNode.AddChild
l TcxTreeListNode.AddChildFirst

Page 784 of 1199


TcxTreeListNode.Invalidate
TcxTreeListNode

Informs the control that the node needs to be repainted.

Syntax

procedure Invalidate;

Description
Use the method if, for some reason, the node is to be repainted.

Page 785 of 1199


TcxTreeListNode.IsFirst
TcxTreeListNode

Indicates whether the node is the first child node of its parent's Items collection.

Syntax

property IsFirst: Boolean;

Description
Use the IsLast property to determine whether the node is the parent's last child node.

ReadOnly Property

Related Information

l TcxTreeListNode.Count
l TcxTreeListNode.getNextSibling
l TcxTreeListNode.getPrevSibling
l TcxTreeListNode.Index
l TcxTreeListNode.IsFirstVisible

Page 786 of 1199


TcxTreeListNode.IsFirstVisible
TcxTreeListNode

Indicates whether the node is the first visible node within the TreeList control.

Syntax

property IsFirstVisible: Boolean;

Description
Use the IsFirstVisible property to determine whether the node is the first visible node within the TreeList control. Usually, the
first visible node within the TreeList is the top-most node at the root hierarchy level. The node's index among visible nodes is
returned by the VisibleIndex property. The AbsoluteIndex property specifies the node's position within the tree structure.

Note: this property value is affected when the node order is changed.

ReadOnly Property

Related Information

l TcxTreeListNode.GetNextVisible
l TcxTreeListNode.GetPrevVisible
l TcxTreeListNode.IsLastVisible
l TcxTreeListNode.MakeVisible

Page 787 of 1199


TcxTreeListNode.IsGroupNode
TcxTreeListNode

Indicates whether the node is a group node.

Syntax

property IsGroupNode: Boolean;

Description
This property returns True for group nodes.
Note:   This property is in effect only when the categorized paint style is enabled.

ReadOnly Property

Related Information

l TcxCustomTreeList.OnIsGroupNode
l TcxTreeListOptionsView.CategorizedColumn
l TcxTreeListOptionsView.PaintStyle

Page 788 of 1199


TcxTreeListNode.IsHidden
TcxTreeListNode

Indicates if the node is hidden in the View (filtered out).

Syntax

property IsHidden: Boolean;

Description
This property returns True if any of the following conditions are met:
l The node's or its parents' Visible property is set to False;
l The node is filtered out via the TreeList control's Filter property or the OnFilterNode event.

Hidden nodes return –1 as their VisibleIndex property value.

ReadOnly Property

Related Information

l TcxTreeListNode.IsVisible

Page 789 of 1199


TcxTreeListNode.IsLast
TcxTreeListNode

Indicates whether the node is the last child node of its parent's Items collection.

Syntax

property IsLast: Boolean;

Description
Use the IsFirst property to determine whether the node is the parent's first child node.

ReadOnly Property

Related Information

l TcxTreeListNode.Count
l TcxTreeListNode.getNextSibling
l TcxTreeListNode.getPrevSibling
l TcxTreeListNode.Index
l TcxTreeListNode.IsLastVisible

Page 790 of 1199


TcxTreeListNode.IsLastVisible
TcxTreeListNode

Indicates whether the node is the last visible node within the TreeList control.

Syntax

property IsLastVisible: Boolean;

Description
Use the IsLastVisible property to determine whether the node is the last visible node within the TreeList control. The node's
index among visible nodes is returned by the VisibleIndex property. The AbsoluteIndex property specifies the node's position
within the tree structure.

Note: this property value is affected when the node order is changed.

ReadOnly Property

Related Information

l TcxTreeListNode.GetNextVisible
l TcxTreeListNode.GetPrevVisible
l TcxTreeListNode.IsFirstVisible
l TcxTreeListNode.MakeVisible

Page 791 of 1199


TcxTreeListNode.IsSibling
TcxTreeListNode

Checks whether the specified node is a sibling of the current node.

Syntax

function IsSibling(ANode: TcxTreeListNode): Boolean;

Description
The method returns True, if the current node and ANode are siblings.

Page 792 of 1199


TcxTreeListNode.IsVisible
TcxTreeListNode

Indicates if the node is hidden within collapsed parents.

Syntax

property IsVisible: Boolean;

Description
This property returns True if any of the following conditions are met:
l All the node's parents are visible and expanded;
l The node is a root level node.

Call the MakeVisible method to expand parent nodes to display their particular child node.

Note:   Unlike the IsHidden property, IsVisible only checks the expanded state of the node's parents, ignoring the following:
l The node's Visible property value;
l The filtering applied via the TreeList control's Filter property and/or the OnFilterNode event.

ReadOnly Property

Related Information

l TcxTreeListNode.IsFirst
l TcxTreeListNode.IsLast
l TcxTreeListNode.Parent

Page 793 of 1199


TcxTreeListNode.Items
TcxTreeListNode

Provides indexed access to the node's child nodes.

Syntax

property Items[Index: Integer]: TcxTreeListNode;

Description
Use the Items property to access the child nodes by the node's index. The node index within its parent's Items collection is
specified via the Index property.

Page 794 of 1199


TcxTreeListNode.Level
TcxTreeListNode

Specifies the node's nesting level.

Syntax

property Level: Integer;

Description
Use the Level property to obtain the nesting level of the node. The Level value for root level nodes is 0. This property indicates
the number of nodes to expand to reach the node.

ReadOnly Property

Page 795 of 1199


TcxTreeListNode.LoadChildren
TcxTreeListNode

Loads the node's children, if any exist.

Syntax

procedure LoadChildren;

Description
The method does nothing if the node is expanded (see the Expanded property), or if children have already been loaded.

This method is used internally.

Page 796 of 1199


TcxTreeListNode.MakeVisible
TcxTreeListNode

Ensures that the node is displayed.

Syntax

procedure MakeVisible;

Description
Use the MakeVisible method to display the node. If the node is scrolled out of view, the TreeList control is scrolled until the
node appears. The node can be hidden because one or all of its parent nodes are collapsed. In this case, calling the
MakeVisible method expands TreeList nodes as necessary.

Related Information

l TcxTreeListNode.GetNextVisible
l TcxTreeListNode.GetPrevVisible
l TcxTreeListNode.VisibleIndex

Page 797 of 1199


TcxTreeListNode.MoveTo
TcxTreeListNode

Moves the node to the location specified within the TreeList control.

Syntax

procedure MoveTo(ADestNode: TcxTreeListNode; AMode: TcxTreeListNodeAttachMode); virtual;

Description
Use the MoveTo method to move the node to the location provided by the ADestNode parameter.
AMode specifies the manner in which the current node is moved.

Related Information

l TcxTreeListNode.CanMove

Page 798 of 1199


TcxTreeListNode.OverlayIndex
TcxTreeListNode

Specifies an additional image that is overlaid on the node select image.

Syntax

type
{$IFDEF DELPHI17}
TcxImageIndex = System.UITypes.TImageIndex;
{$ELSE}
TcxImageIndex = ImgList.TImageIndex;
{$ENDIF}
property OverlayIndex: TcxImageIndex;

Description
Node select images are stored in the Images collections.
Use the OverlayIndex property to display an additional image above the node select image.

For different tree list controls, images are specified in the following ways:
l The TcxVirtualTreeList or TcxDBTreeList control – handle the tree list's OnGetNodeImageIndex event to specify node
images.
l The TcxTreeList control – images can be specified directly via the OverlayIndex property or using the tree list's
OnGetNodeImageIndex event.

Related Information

l TcxTreeListOptionsView.UseImageIndexForSelected

Page 799 of 1199


TcxTreeListNode.OverlayStateIndex
TcxTreeListNode

Specifies an additional image that is overlaid on the node specific state image.

Syntax

type
{$IFDEF DELPHI17}
TcxImageIndex = System.UITypes.TImageIndex;
{$ELSE}
TcxImageIndex = ImgList.TImageIndex;
{$ENDIF}
property OverlayStateIndex: TcxImageIndex;

Description
State images are stored in the StateImages collections.
Use the OverlayStateIndex property to display an additional image above the node state image.
For different tree list controls, images are specified in the following ways:
l The TcxVirtualTreeList or TcxDBTreeList control – handle the tree list's OnGetNodeImageIndex event to specify node
images.
l The TcxTreeList control – images can be specified directly via the OverlayStateIndex property or using the tree list's
OnGetNodeImageIndex event.

Related Information

l TcxTreeListOptionsView.UseImageIndexForSelected

Page 800 of 1199


TcxTreeListNode.Parent
TcxTreeListNode

Returns the node's parent node.

Syntax

property Parent: TcxTreeListNode;

Description
Use the Parent property to obtain the node's TreeList node parent. The property value for a root node is nil.

ReadOnly Property

Related Information

l TcxTreeListNode.getFirstChild
l TcxTreeListNode.GetLastChild
l TcxTreeListNode.GetNextChild
l TcxTreeListNode.GetPrevChild
l TcxTreeListNode.HasAsParent

Page 801 of 1199


TcxTreeListNode.Repaint
TcxTreeListNode

Redraws the node.

Syntax

procedure Repaint(ARecalculate: Boolean); virtual;

Description
Use the Repaint method to redraw the node. The ARecalculate parameter identifies whether the node's graphical information
should be recalculated.

Page 802 of 1199


TcxTreeListNode.Root
TcxTreeListNode

Provides access to the virtual node that roots all the tree list nodes.

Syntax

property Root: TcxTreeListNode;

Description
Since this node is a root node, its Parent property returns nil, and the Level property returns –1. A root node is a parent of root
level nodes.

ReadOnly Property

Page 803 of 1199


TcxTreeListNode.Selected
TcxTreeListNode

Specifies whether a node is selected.

Syntax

property Selected: Boolean;

Description
Set this property to True to select the node and deselect the previously selected node. This is in effect in both select modes –
multi-select (the OptionsSelection.MultiSelect property is set to True) and single-select (the OptionsSelection.MultiSelect
property is set to False).

Examples

l Example: Node.Selected, TreeList.GetSelections, OptionSelection.MultiSelect

Related Information

l TcxCustomTreeList.ClearSelection
l TcxCustomTreeList.Select
l TcxCustomTreeList.SelectAll
l TcxCustomTreeList.SelectionCount
l TcxCustomTreeList.Selections
l TcxTreeListNode.SelectedIndex

Page 804 of 1199


TcxTreeListNode.SelectedIndex
TcxTreeListNode

Specifies the image for the selected node.

Syntax

type
{$IFDEF DELPHI17}
TcxImageIndex = System.UITypes.TImageIndex;
{$ELSE}
TcxImageIndex = ImgList.TImageIndex;
{$ENDIF}
property SelectedIndex: TcxImageIndex;

Description
Node select images are stored in the Images collections.
For different tree list controls, images are specified in the following ways:
l The TcxVirtualTreeList control – handle the tree list's OnGetNodeImageIndex event to apply node images.
l The TcxDBTreeList control – images can be specified using the tree list's OnGetNodeImageIndex event.
l The TcxTreeList control – images can be specified directly via the SelectedIndex property or using the tree list's
OnGetNodeImageIndex event.

Related Information

l TcxTreeListOptionsView.UseImageIndexForSelected

Page 805 of 1199


TcxTreeListNode.StateIndex
TcxTreeListNode

Specifies the state image for the node.

Syntax

type
{$IFDEF DELPHI17}
TcxImageIndex = System.UITypes.TImageIndex;
{$ELSE}
TcxImageIndex = ImgList.TImageIndex;
{$ENDIF}
property StateIndex: TcxImageIndex;

Description
State images are used to specify the application-specific states of the node.
These images are stored in the StateImages collections.

For different tree list controls, images are specified in the following ways:
l The TcxVirtualTreeList control – handle the tree list's OnGetNodeImageIndex event to apply node images.
l The TcxDBTreeList control – images can be specified using either the tree list's DataController.StateIndexField property or
the OnGetNodeImageIndex event.
l The TcxTreeList control – images can be specified directly via the StateIndex property or using the tree list's
OnGetNodeImageIndex event.

Related Information

l TcxDBTreeListDataController.StateIndexField
l TcxTreeListOptionsView.DynamicFocusedStateImages

Page 806 of 1199


TcxTreeListNode.Texts
TcxTreeListNode

Provides indexed access to the string representation of the node's column values.

Syntax

property Texts[Index:Integer]: string;

Description
Use the Texts property to access the string representation of column values within the node. The Index parameter specifies the
column index.
Note: this property returns column values regardless of columns' visibility.

Related Information

l TcxTreeListColumn.DisplayTexts

Page 807 of 1199


TcxTreeListNode.TreeList
TcxTreeListNode

Returns the TreeList control owning the node.

Syntax

property TreeList: TcxCustomTreeList;

Description
Use the TreeList property to access the TreeList control owning the node.

ReadOnly Property

Page 808 of 1199


TcxTreeListNode.ValueCount
TcxTreeListNode

Returns the number of values displayed within the node.

Syntax

property ValueCount: Integer;

Description
Use the ValueCount property to obtain the number of column values within the node. The column values displayed within the
node can be accessed via the Values property.

ReadOnly Property

Related Information

l TcxTreeListNode.Values

Page 809 of 1199


TcxTreeListNode.Values
TcxTreeListNode

Provides indexed access to column values within the node.

Syntax

property Values[Index:Integer]: Variant;

Description
Use the Values property to access column values displayed within the node. The Index parameter represents the column index
within the TreeList control's Columns collection.
To access the string representation of column values, use the node's Texts or the column's DisplayTexts properties.

Related Information

l TcxTreeListNode.ValueCount

Page 810 of 1199


TcxTreeListNode.Visible
TcxTreeListNode

Specifies the node's availability in the tree list.

Syntax

property Visible: Boolean;

Description
Set this property to True to make the node available for display in the tree list. Otherwise, the node is hidden.
You can filter out specific nodes using the TreeList control's Filter property and/or the OnFilterNode event. The TreeList control
first uses these members to filter nodes and then hides those whose Visible property is set to False.

Note:   The Visible property value has no effect on the IsVisible property.

Related Information

l TcxCustomTreeList.AbsoluteVisibleItems
l TcxTreeListNode.GetNextVisible
l TcxTreeListNode.GetPrevVisible
l TcxTreeListNode.IsFirstVisible
l TcxTreeListNode.IsLastVisible
l TcxTreeListNode.IsVisible
l TcxTreeListNode.VisibleIndex

Page 811 of 1199


TcxTreeListNode.VisibleIndex
TcxTreeListNode

Returns the node's index among visible nodes.

Syntax

property VisibleIndex: Integer;

Description
If a node is not visible, its VisibleIndex property returns –1. You can navigate through visible nodes using the node
GetNextVisible and GetPrevVisible functions.

ReadOnly Property

Page 812 of 1199


TcxTreeListOptionsBehavior.AutoDragCopy
TcxTreeListOptionsBehavior

Specifies whether nodes are copied during drag-and-drop operations.

Syntax

property AutoDragCopy: Boolean;

Description
If this property is set to True, end-users can copy nodes by dragging them while holding down the Ctrl key.
You can display specially designed drop indicators to assist end-users during drag-and-drop operations. To enable these
indicators, set the tree list's OptionsView.DropNodeIndicator property to True.
Important Note: In bound mode, a dataset must be indexed by the ParentField field in order to use this functionality.

The default value of the AutoDragCopy property is False.

Concepts

l Implementing Drag-And-Drop Functionality

Related Information

l TcxTreeListOptionsBehavior.DragCollapse
l TcxTreeListOptionsBehavior.DragExpand
l TcxTreeListOptionsBehavior.DragFocusing

Page 813 of 1199


TcxTreeListOptionsBehavior.BestFitMaxRecordCount
TcxTreeListOptionsBehavior

Specifies the number of nodes whose contents will be taken into account in calculating the column's best-fit width.

Syntax

property BestFitMaxRecordCount: Integer;

Description
This property is used by the ApplyBestFit method to check the contents of the specified number of visible nodes (starting from the
top node in the View), so that columns will be adjusted to the widest contents of those nodes. Contents of other nodes will be
ignored.
If the BestFitMaxRecordCount property is –1, then contents of all visible nodes will be checked (see the tree list's
AbsoluteVisibleItems property).

The default value of the BestFitMaxRecordCount property is -1.

Related Information

l TcxTreeListBand.ApplyBestFit
l TcxTreeListColumn Object
l TcxTreeListColumn.ApplyBestFit

Page 814 of 1199


TcxTreeListOptionsBehavior.ChangeDelay
TcxTreeListOptionsBehavior

Specifies the delay (in milliseconds) before the TreeList control's OnChange event is raised.

Syntax

property ChangeDelay: Integer;

Description
If this property is set to 0, the OnChange event fires immediately after the TreeList control has been updated.

The default value of the ChangeDelay property is 0.

Page 815 of 1199


TcxTreeListOptionsBehavior.ConfirmDelete
TcxTreeListOptionsBehavior

Specifies whether the confirmation dialog is displayed when an end-user deletes a node by pressing the Ctrl+Del key
combination.

Syntax

property ConfirmDelete: Boolean;

Description
Set this property to False, to disable the confirmation dialog:

The default value of the ConfirmDelete property is True.

Related Information

l TcxTreeListOptionsData.Deleting

Page 816 of 1199


TcxTreeListOptionsBehavior.DragCollapse
TcxTreeListOptionsBehavior

Specifies whether an expanded node located under the mouse pointer is automatically collapsed during drag-and-drop
operations.

Syntax

property DragCollapse: Boolean;

Description
Set this property to True, to enable automatic node collapse when the mouse pointer is positioned over an expanded node's
expand button for the time period specified via the WaitForExpandNodeTime property.
Use the DragExpand property to enable automatic node expansion during drag-and-drop operations.

Note:   You can display specially designed drop indicators to assist end-users during drag-and-drop operations. To enable these
indicators, set the tree list's OptionsView.DropNodeIndicator property to True.

The default value of the DragCollapse property is True.

Concepts

l Implementing Drag-And-Drop Functionality

Related Information

l TcxTreeListOptionsBehavior.AutoDragCopy
l TcxTreeListOptionsBehavior.DragExpand
l TcxTreeListOptionsBehavior.DragFocusing

Page 817 of 1199


TcxTreeListOptionsBehavior.DragExpand
TcxTreeListOptionsBehavior

Specifies whether a collapsed node located under the mouse pointer is automatically expanded during drag-and-drop operations.

Syntax

property DragExpand: Boolean;

Description
Set this property to True, to enable automatic node expansion when the mouse pointer is positioned over a collapsed node's
expand button for the time period specified via the WaitForExpandNodeTime property.
Use the DragCollapse property to enable automatic node collapse during drag-and-drop operations.

Note:   You can display specially designed drop indicators to assist end-users during drag-and-drop operations. To enable these
indicators, set the tree list's OptionsView.DropNodeIndicator property to True.

The default value of the DragExpand property is True.

Concepts

l Implementing Drag-And-Drop Functionality

Related Information

l TcxTreeListOptionsBehavior.AutoDragCopy
l TcxTreeListOptionsBehavior.DragCollapse
l TcxTreeListOptionsBehavior.DragFocusing

Page 818 of 1199


TcxTreeListOptionsBehavior.DragFocusing
TcxTreeListOptionsBehavior

Specifies whether a node located under the mouse pointer is automatically focused during drag-and-drop operations.

Syntax

property DragFocusing: Boolean;

Description
Set this property to True, to enable automatic node focusing during drag-and-drop operations.
To enable automatic node expansion or collapse during drag-and-drop operations, use the DragCollapse and DragExpand
properties.

Note:   You can display specially designed drop indicators to assist end-users during drag-and-drop operations. To enable these
indicators, set the tree list's OptionsView.DropNodeIndicator property to True.

The default value of the DragFocusing property is False.

Concepts

l Implementing Drag-And-Drop Functionality

Related Information

l TcxCustomTreeList.FocusedNode
l TcxTreeListOptionsBehavior.AutoDragCopy
l TcxTreeListOptionsBehavior.DragCollapse
l TcxTreeListOptionsBehavior.DragExpand

Page 819 of 1199


TcxTreeListOptionsBehavior.EditAutoHeight
TcxTreeListOptionsBehavior

Specifies the manner in which a multi-line in-place editor is sized.

Syntax

type
TcxInplaceEditAutoHeight = (eahNone, eahEditor, eahRow);
property EditAutoHeight: TcxInplaceEditAutoHeight;

Description
Values include:

Value Meaning Sample

eahNone No sizing. The in-place editor's height


remains unchanged – it occupies an entire
cell. An editor automatically wraps and
vertically scrolls its content.

eahEditor In-place editor sizing. In the edited data cell,


an editor is sized vertically to fit the entered
content. When an end-user has finished
editing, the height of the containing node is
automatically changed to fit the new data.
You can emphasize the border of the editor
displayed in this mode via the tree list's
OptionsView.EditAutoHeightBorderColor
property.

eahRow Node sizing. The entire node being edited is


dynamically sized when wrapping to the next
line within the editor. This option is in effect if
the tree list's OptionsView.CellAutoHeight
property is True.

A column's Options.EditAutoHeight property overrides the EditAutoHeight property.

Important Note: Auto sizing is not supported by drop-down editors, non-text editors, editors with embedded buttons, or input
mask text editors.

The default value of the EditAutoHeight property is eahNone.

Page 820 of 1199


TcxTreeListOptionsBehavior.ExpandOnDblClick
TcxTreeListOptionsBehavior

Specifies whether double-clicking a node changes its expansion state.

Syntax

property ExpandOnDblClick: Boolean;

Description
Set this property to True, to allow end-users to double-click within a node to change its expansion state without having to click
the node's expand button.

The default value of the ExpandOnDblClick property is True.

Related Information

l TcxTreeListOptionsBehavior.DragExpand
l TcxTreeListOptionsBehavior.ExpandOnIncSearch

Page 821 of 1199


TcxTreeListOptionsBehavior.ExpandOnIncSearch
TcxTreeListOptionsBehavior

Specifies whether collapsed nodes are automatically expanded during an incremental search.

Syntax

property ExpandOnIncSearch: Boolean;

Description
Set this property to True, to enable automatic node expansion when locating a node that contains the search entry. Otherwise,
the search is performed in expanded nodes only.
To enable incremental searching, use the IncSearch and IncSearchItem properties.

The default value of the ExpandOnIncSearch property is False.

Examples

l Example: Searching, Behavior.IncSearch, Behavior.IncSearchItem, Behavior.ExpandOnIncSearching, SearchingText,


CancelSearching

Related Information

l TcxTreeListOptionsBehavior.DragExpand
l TcxTreeListOptionsBehavior.ExpandOnDblClick

Page 822 of 1199


TcxTreeListOptionsBehavior.FooterHints
TcxTreeListOptionsBehavior

Specifies whether hints are displayed for footer cells and group footer cells with truncated content.

Syntax

property FooterHints: Boolean;

Description
Set this property to True, to display hints for footer cells and group footer cells with truncated content.

The default value of the FooterHints property is False.

Related Information

l TcxTreeListOptionsBehavior.HeaderHints
l ExpressEditors: TcxControlOptionsBehavior.CellHints

Page 823 of 1199


TcxTreeListOptionsBehavior.HeaderHints
TcxTreeListOptionsBehavior

Specifies whether hints are displayed for band headers and column headers with truncated captions.

Syntax

property HeaderHints: Boolean;

Description
Set this property to True, to display hints for band and column headers with truncated captions.

The default value of the HeaderHints property is False.

Related Information

l TcxTreeListOptionsBehavior.FooterHints
l ExpressEditors: TcxControlOptionsBehavior.CellHints

Page 824 of 1199


TcxTreeListOptionsBehavior.HotTrack
TcxTreeListOptionsBehavior

Specifies whether nodes are hot-tracked when the mouse pointer is located over them.

Syntax

property HotTrack: Boolean;

Description
Set this property to True, to emphasize (hot-track) a node that is currently located under the mouse pointer. By default, hot-
tracked nodes are painted using the clHighLightText text color. To customize their appearance, set the Styles.HotTrack
property or handle the Styles.OnGetHotTrackStyle event.

To respond to hot-tracking nodes, handle the TreeList control's OnHotTrackNode event.

The default value of the HotTrack property is False.

Page 825 of 1199


TcxTreeListOptionsBehavior.IncSearchItem
TcxTreeListOptionsBehavior

Specifies the column against which incremental searching is performed.

Syntax

property IncSearchItem: TcxTreeListColumn;

Description
To enable incremental searching for the specified column, set the IncSearch property to True. If the IncSearchItem property is
not specified, the incremental search is performed against the currently focused column.

The default value of the IncSearchItem property is nil.

Examples

l Example: Searching, Behavior.IncSearch, Behavior.IncSearchItem, Behavior.ExpandOnIncSearching, SearchingText,


CancelSearching

Related Information

l TcxTreeListColumn Object

Page 826 of 1199


TcxTreeListOptionsBehavior.MultiSort
TcxTreeListOptionsBehavior

Specifies whether nodes can be sorted by multiple columns.

Syntax

property MultiSort: Boolean;

Description
Set this property to True, to allow nodes to be sorted by multiple columns. Otherwise, nodes can only be sorted by one column.
End-users can sort nodes by multiple columns by clicking column headers while holding down the Shift key. To
programmatically sort nodes, use a column's SortOrder property or call a node's CustomSort method.

The default value of the MultiSort property is True.

Related Information

l TcxCustomTreeList.ClearSorting
l TcxCustomTreeList.Sorted
l TcxCustomTreeList.SortedColumnCount
l TcxCustomTreeList.SortedColumns
l TcxTreeListColumn Object
l TcxTreeListNode Object
l TcxTreeListOptionsBehavior.Sorting
l TcxTreeListOptionsData.MultiThreadedSorting
l TcxUnboundTreeListNode Object
l TcxVirtualTreeListNode Object

Page 827 of 1199


TcxTreeListOptionsBehavior.RecordScrollMode
TcxTreeListOptionsBehavior

Specifies the active content scroll mode.

Syntax

type
TcxRecordScrollMode = (rsmDefault, rsmByRecord, rsmByPixel);
property RecordScrollMode: TcxRecordScrollMode

Description
Set this property to rsmByPixel or rsmByRecord to explicitly enable or disable the per-pixel content scroll mode. Refer to the
TcxRecordScrollMode type description for detailed information on all available options.

The default RecordScrollMode property value is rsmDefault.

Page 828 of 1199


TcxTreeListOptionsBehavior.ShowHourGlass
TcxTreeListOptionsBehavior

Specifies if a control displays the hourglass cursor during time-consuming operations.

Syntax

property ShowHourGlass: Boolean;

Description
Set this property to False to hide the hourglass cursor during time-consuming operations (for instance, when a TreeList control
loads its content from a file, stream, or bound dataset).

The default ShowHourGlass property value is True.

Page 829 of 1199


TcxTreeListOptionsBehavior.Sorting
TcxTreeListOptionsBehavior

Specifies whether end-users can sort nodes by clicking column headers.

Syntax

property Sorting: Boolean;

Description
Set this property to False, to prohibit end-users from changing the sort order by clicking column headers. To prohibit end-users
from changing the sort order of a specific column, use the column's Sorting property. A column's Sorting property value is ignored
if the TreeList control's Sorting property is set to False.
To enable sorting nodes by multiple columns, set the MultiSort property to True.

Note:   The Sorting property value has no effect when sorting is applied programmatically.

The default value of the Sorting property is True.

Related Information

l TcxCustomTreeList.Sorted
l TcxCustomTreeList.SortedColumnCount
l TcxCustomTreeList.SortedColumns
l TcxTreeListColumn Object
l TcxTreeListColumn.SortOrder
l TcxTreeListNode.CustomSort
l TcxTreeListOptionsBehavior.MultiSort
l TcxTreeListOptionsData.MultiThreadedSorting

Page 830 of 1199


TcxTreeListOptionsBehavior.WaitForExpandNodeTime
TcxTreeListOptionsBehavior

Specifies the delay (in milliseconds) before a node under the mouse pointer is automatically expanded/collapsed during drag-and-drop
operations.

Syntax

property WaitForExpandNodeTime: Integer;

Description
This property is in effect if the DragExpand or the DragCollapse option is active. During drag-and-drop operations, a node's expansion
state is automatically changed if the mouse pointer is located under the expand button for the period of time specified by the
WaitForExpandNodeTime property value.

The default value of the WaitForExpandNodeTime property is 500.

Related Information

l TcxTreeListOptionsBehavior.AutoDragCopy
l TcxTreeListOptionsBehavior.DragCollapse
l TcxTreeListOptionsBehavior.DragExpand

Page 831 of 1199


TcxTreeListOptionsCustomizing.BandCustomizing
TcxTreeListOptionsCustomizing

Specifies the manner in which end-users can change the visibility of bands.

Syntax

property BandCustomizing: Boolean;

Description
Set this property to False, to prohibit end-users from changing the visibility of bands using any of the following methods:
l Dragging band headers from the band header panel or customization form.
l Clicking items within the Quick Band Customization dropdown.

If the BandCustomizing property is set to True, you can specify the manner in which end-users can change the visibility of
individual bands via a band's Options.Customizing property.

Note:   Dragging bands is enabled only when a band's Options.Moving property and the TreeList control's
OptionsCustomizing.BandMoving property are set to True. Fixed bands cannot be moved. Use the TreeList control's
OptionsCustomizing.BandHiding property to customize the manner in which end-users can hide bands using drag-and-drop
operations.

The default value of the BandCustomizing property is True.

Related Information

l TcxCustomTreeList.OnBandPosChanged
l TcxTreeListOptionsCustomizing.BandsQuickCustomization
l TcxTreeListOptionsCustomizing.ColumnCustomizing

Page 832 of 1199


TcxTreeListOptionsCustomizing.BandHiding
TcxTreeListOptionsCustomizing

Specifies the manner in which end-users can hide bands in the TreeList control.

Syntax

property BandHiding: Boolean;

Description
End-users can hide bands by dragging their headers from the band header panel to the customization form. If the BandHiding
property is set to True, end-users can also hide bands by dropping their headers, even if the customization form is not displayed.

Note:   The BandHiding property is in effect only if the TreeList control's OptionsCustomizing.BandCustomizing property is set
to True.

The default value of the BandHiding property is False.

Related Information

l TcxCustomTreeList.OnBandPosChanged
l TcxTreeListOptionsCustomizing.BandCustomizing
l TcxTreeListOptionsCustomizing.BandMoving
l TcxTreeListOptionsCustomizing.ColumnHiding

Page 833 of 1199


TcxTreeListOptionsCustomizing.BandHorzSizing
TcxTreeListOptionsCustomizing

Specifies whether end-users can horizontally resize bands by dragging their right edges.

Syntax

property BandHorzSizing: Boolean;

Description
Set this property to False, to prohibit end-users from horizontally resizing bands. To prevent a particular band from being
horizontally resized by end-users, set its Options.Sizing property to False.
To horizontally resize a band in code, use the band's Width property.
Changing a band's width fires the TreeList control's OnBandSizeChanged, OnLayoutChanged, and OnChange events.
To enable instant visualization of band sizing, set the OptionsCustomizing.DynamicSizing property to True.

Note:   Resizing a band resizes all its visible columns proportionally to their display widths.

The default value of the BandHorzSizing property is True.

Related Information

l TcxCustomTreeList.OnBandSizeChanged
l TcxTreeListOptionsCustomizing.BandVertSizing
l TcxTreeListOptionsCustomizing.ColumnHorzSizing
l TcxTreeListOptionsCustomizing.DynamicSizing

Page 834 of 1199


TcxTreeListOptionsCustomizing.BandMoving
TcxTreeListOptionsCustomizing

Specifies whether end-users can move bands by dragging their headers.

Syntax

property BandMoving: Boolean;

Description
Set this property to False, to prohibit end-users from moving bands. If the BandMoving property is set to True, you can specify
whether end-users can move individual bands via a band's Options.Moving property.
To programmatically move a band, use its Position property.

Note:   Fixed bands cannot be moved. If the BandMoving property is set to False the TreeList control's
OptionsCustomizing.BandCustomizing property value is ignored.

The default value of the BandMoving property is True.

Related Information

l TcxCustomTreeList.OnBandPosChanged
l TcxTreeListOptionsCustomizing.BandCustomizing
l TcxTreeListOptionsCustomizing.ColumnMoving

Page 835 of 1199


TcxTreeListOptionsCustomizing.BandsQuickCustomiza
TcxTreeListOptionsCustomizing

Specifies whether the Quick Band Customization button is displayed.

Syntax

property BandsQuickCustomization: Boolean;

Description
Set this property to True to display the Quick Band Customization button. This automatically makes the node indicator visible if it is n
displayed.

The default value of the BandsQuickCustomization property is False.

Related Information

l TcxCustomTreeList.OnBandPosChanged
l TcxTreeListOptionsCustomizing.BandHiding
l TcxTreeListOptionsCustomizing.BandsQuickCustomizationMaxDropDownCount
l TcxTreeListOptionsCustomizing.ColumnsQuickCustomization

Page 836 of 1199


TcxTreeListOptionsCustomizing.BandsQuickCustomiza
TcxTreeListOptionsCustomizing

Specifies the maximum number of band captions displayed in the Quick Band Customization dropdown list at a time.

Syntax

property BandsQuickCustomizationMaxDropDownCount: Integer;

Description
Set this property to 0 to make the dropdown list's visible portion display the captions of all bands whose Options.Hidden property is se
displays no more than the specified number of band captions.

The default value of the BandsQuickCustomizationMaxDropDownCount property is 0.

Related Information

l TcxTreeListOptionsCustomizing.BandsQuickCustomization
l TcxTreeListOptionsCustomizing.ColumnsQuickCustomizationMaxDropDownCount

Page 837 of 1199


TcxTreeListOptionsCustomizing.BandsQuickCustomiza
TcxTreeListOptionsCustomizing

Switches the visibility of the (All) and (Sorted) check boxes in the Quick Band Customization dropdown list.

Syntax

property BandsQuickCustomizationShowCommands: Boolean;

Description
These check boxes allow end-users to toggle the checked state of all band captions in the dropdown list and alphabetically sort them.

The following table lists available property values.

Value Meaning Example

True The
dropdown
list pins
these
check
boxes to
its top so
that
scrolling
doesn't
take them
out of
view and
separates
them from
band
captions
with a
line.

False The check


boxes are
hidden.

The default value of the BandsQuickCustomizationShowCommands property is True.

Related Information

l TcxTreeListOptionsCustomizing.BandsQuickCustomization
l TcxTreeListOptionsCustomizing.ColumnsQuickCustomizationShowCommands

Page 838 of 1199


TcxTreeListOptionsCustomizing.BandsQuickCustomiza
TcxTreeListOptionsCustomizing

Specifies if band captions are sorted alphabetically in the Quick Band Customization dropdown list.

Syntax

property BandsQuickCustomizationSorted: Boolean;

Description
Set this property to True to sort band captions alphabetically. Otherwise, they appear in the order the TreeList control displays them.
property value via the (Sorted) check box displayed in the dropdown list when the BandsQuickCustomizationShowCommands property

The following table illustrates how BandsQuickCustomizationSorted property values affect the order of band captions.

Value Example

True

False

Note:   Sorting is case-insensitive and ANSI ordered to avoid confusion with captions that include diacritical marks or use characters in

The default value of the BandsQuickCustomizationSorted property is False.

Related Information

l TcxTreeListOptionsCustomizing.BandsQuickCustomization
l TcxTreeListOptionsCustomizing.BandsQuickCustomizationMaxDropDownCount
l TcxTreeListOptionsCustomizing.ColumnsQuickCustomizationSorted

Page 839 of 1199


TcxTreeListOptionsCustomizing.BandVertSizing
TcxTreeListOptionsCustomizing

Specifies whether end-users can vertically resize bands by dragging their bottom edges.

Syntax

property BandVertSizing: Boolean;

Description
Set this property to False, to prohibit end-users from vertically resizing bands. To prevent a particular band from being vertically
resized by end-users, set its Options.VertSizing property to False.
To specify the band height in code, use the TreeList control's OptionsView.BandLineHeight property.
Changing a band's height fires the TreeList control's OnBandSizeChanged, OnLayoutChanged, and OnChange events.

The default value of the BandVertSizing property is True.

Related Information

l TcxCustomTreeList.OnBandSizeChanged
l TcxTreeListOptionsCustomizing.BandHorzSizing
l TcxTreeListOptionsCustomizing.ColumnVertSizing
l TcxTreeListOptionsCustomizing.DynamicSizing

Page 840 of 1199


TcxTreeListOptionsCustomizing.ColumnCustomizing
TcxTreeListOptionsCustomizing

Specifies the manner in which end-users can change the visibility of columns.

Syntax

property ColumnCustomizing: Boolean;

Description
Set this property to False, to prohibit end-users from changing the visibility of columns using any of the following methods:
l Dragging column headers from the column header panel or customization form.
l Clicking items within the Quick Column Customization dropdown.

If the ColumnCustomizing property is set to True, you can specify the manner in which end-users can change the visibility of
individual columns via a column's Options.Customizing property.

Note:   Dragging columns is enabled only when a column's Options.Moving property and the TreeList control's
OptionsCustomizing.ColumnMoving property are set to True. Use the TreeList control's OptionsCustomizing.ColumnHiding
property to customize the manner in which end-users can hide columns using drag-and-drop operations.

The default value of the ColumnCustomizing property is True.

Related Information

l TcxCustomTreeList.OnColumnPosChanged
l TcxTreeListColumn Object
l TcxTreeListOptionsCustomizing.BandCustomizing
l TcxTreeListOptionsCustomizing.ColumnHiding
l TcxTreeListOptionsCustomizing.ColumnsQuickCustomization

Page 841 of 1199


TcxTreeListOptionsCustomizing.ColumnHiding
TcxTreeListOptionsCustomizing

Specifies the manner in which end-users can hide columns in the TreeList control.

Syntax

property ColumnHiding: Boolean;

Description
End-users can hide columns by dragging their headers from the column header panel to the customization form. If the
ColumnHiding property is set to True, end-users can also hide columns by dropping their headers, even if the customization
form is not displayed.

Note:   The ColumnHiding property is in effect only if the TreeList control's OptionsCustomizing.ColumnCustomizing property
is set to True.

The default value of the ColumnHiding property is False.

Related Information

l TcxCustomTreeList.OnColumnPosChanged
l TcxTreeListColumn Object
l TcxTreeListOptionsCustomizing.BandHiding
l TcxTreeListOptionsCustomizing.ColumnCustomizing
l TcxTreeListOptionsCustomizing.ColumnMoving

Page 842 of 1199


TcxTreeListOptionsCustomizing.ColumnHorzSizing
TcxTreeListOptionsCustomizing

Specifies whether end-users can horizontally resize columns by dragging their right edges.

Syntax

property ColumnHorzSizing: Boolean;

Description
Set this property to False, to prohibit end-users from horizontally resizing columns. To prevent a particular column from being
resized by end-users, set its Options.Sizing property to False.
To horizontally resize a column in code, use the column's Width property.
Changing a column's width fires the TreeList control's OnColumnSizeChanged, OnLayoutChanged, and OnChange events.
To enable instant visualization of column sizing, set the OptionsCustomizing.DynamicSizing property to True.

The default value of the ColumnHorzSizing property is True.

Related Information

l TcxCustomTreeList.OnColumnSizeChanged
l TcxTreeListColumn Object
l TcxTreeListOptionsCustomizing.BandHorzSizing
l TcxTreeListOptionsCustomizing.ColumnVertSizing
l TcxTreeListOptionsCustomizing.DynamicSizing
l TcxTreeListOptionsView.ColumnAutoWidth

Page 843 of 1199


TcxTreeListOptionsCustomizing.ColumnMoving
TcxTreeListOptionsCustomizing

Specifies whether end-users can move columns by dragging their headers.

Syntax

property ColumnMoving: Boolean;

Description
Set this property to False, to prohibit end-users from moving columns. If the ColumnMoving property is set to True, you can
specify whether end-users can move individual columns via a column's Options.Moving property.
To programmatically move a column, use its Position property.
To prohibit end-users from stacking columns using drag and drop, set the TreeList control's
OptionsCustomizing.StackedColumns property to False.

Note:   If the ColumnMoving property is set to False, the TreeList control's OptionsCustomizing.ColumnCustomizing property
value is ignored.

The default value of the ColumnMoving property is True.

Related Information

l TcxCustomTreeList.OnColumnPosChanged
l TcxTreeListColumn Object
l TcxTreeListOptionsCustomizing.BandMoving
l TcxTreeListOptionsCustomizing.ColumnCustomizing
l TcxTreeListOptionsCustomizing.StackedColumns

Page 844 of 1199


TcxTreeListOptionsCustomizing.ColumnsQuickCustom
TcxTreeListOptionsCustomizing

Specifies whether the Quick Column Customization button is displayed.

Syntax

property ColumnsQuickCustomization: Boolean;

Description
Set this property to True to display the Quick Column Customization button. This automatically makes the node indicator visible if it is
displayed.

The default value of the ColumnsQuickCustomization property is False.

Related Information

l TcxCustomTreeList.OnColumnPosChanged
l TcxTreeListOptionsCustomizing.BandsQuickCustomization
l TcxTreeListOptionsCustomizing.ColumnHiding
l TcxTreeListOptionsCustomizing.ColumnsQuickCustomizationMaxDropDownCount

Page 845 of 1199


TcxTreeListOptionsCustomizing.ColumnsQuickCustom
TcxTreeListOptionsCustomizing

Specifies the maximum number of column captions displayed in the Quick Column Customization dropdown list at a time.

Syntax

property ColumnsQuickCustomizationMaxDropDownCount: Integer;

Description
Set this property to 0 to make the dropdown list's visible portion display the captions of all columns whose Options.Hidden property is
no more than the specified number of column captions.

The default value of the ColumnsQuickCustomizationMaxDropDownCount property is 0.

Related Information

l TcxTreeListOptionsCustomizing.BandsQuickCustomizationMaxDropDownCount
l TcxTreeListOptionsCustomizing.ColumnsQuickCustomization

Page 846 of 1199


TcxTreeListOptionsCustomizing.ColumnsQuickCustom
TcxTreeListOptionsCustomizing

Switches the visibility of the (All) and (Sorted) check boxes in the Quick Column Customization dropdown list.

Syntax

property ColumnsQuickCustomizationShowCommands: Boolean;

Description
These check boxes allow end-users to toggle the checked state of all column captions in the dropdown list and alphabetically sort them

The following table lists available property values.

Value Meaning Example

True The
dropdown
list pins
these
check
boxes to
its top so
that
scrolling
doesn't
take them
out of
view and
separates
them from
column
captions
with a
line.

False The check


boxes are
hidden.

The default value of the ColumnsQuickCustomizationShowCommands property is True.

Related Information
Page 847 of 1199
l TcxTreeListOptionsCustomizing.BandsQuickCustomizationShowCommands
TcxTreeListOptionsCustomizing.ColumnsQuickCustom
TcxTreeListOptionsCustomizing

Specifies if column captions are sorted alphabetically in the Quick Column Customization dropdown list.

Syntax

property ColumnsQuickCustomizationSorted: Boolean;

Description
Set this property to True to sort column captions alphabetically. Otherwise, they appear in the order the TreeList control displays the
property value via the (Sorted) check box displayed in the dropdown list when the ColumnsQuickCustomizationShowCommands prope

The following table illustrates how ColumnsQuickCustomizationSorted property values affect the order of column captions.

Value Example

True

False

Note:   Sorting is case-insensitive and ANSI ordered to avoid confusion with captions that include diacritical marks or use characters in

The default value of the ColumnsQuickCustomizationSorted property is False.


Page 848 of 1199
Related Information
TcxTreeListOptionsCustomizing.ColumnVertSizing
TcxTreeListOptionsCustomizing

Specifies whether end-users can vertically resize columns by dragging their bottom edges.

Syntax

property ColumnVertSizing: Boolean;

Description
Vertically resizing columns automatically adjusts the corresponding column cell heights. To prohibit end-users from vertically
resizing columns, set the ColumnVertSizing property to False.
To programmatically specify a column header's height, use the column's Position.LineCount property. To make column cells
occupy as many lines as necessary to entirely display their contents, enable the OptionsView.CellAutoHeight option.
Changing a column's height fires the TreeList control's OnColumnSizeChanged, OnLayoutChanged, and OnChange events.

The default value of the ColumnVertSizing property is True.

Related Information

l TcxCustomTreeList.OnColumnSizeChanged
l TcxTreeListColumn Object
l TcxTreeListOptionsCustomizing.BandVertSizing
l ExpressEditors: TcxControlOptionsView.CellAutoHeight
l ExpressEditors: TcxControlOptionsView.CellTextMaxLineCount

Page 849 of 1199


TcxTreeListOptionsCustomizing.DynamicSizing
TcxTreeListOptionsCustomizing

Specifies whether band and column widths, and node heights are immediately updated when end-users resize them.

Syntax

property DynamicSizing: Boolean;

Description
By default, a node height, and band or column width are updated once an end-user stops dragging the sizing edge of the
indicator cell, band or column header and releases the left mouse button. To enable instant visualization of the resulting sizes,
set the DynamicSizing property to True. Note that this may affect painting performance.

The default value of the DynamicSizing property is False.

Related Information

l TcxCustomTreeList.OnBandSizeChanged
l TcxCustomTreeList.OnColumnSizeChanged
l TcxTreeListColumnOptions.Sizing
l TcxTreeListOptionsCustomizing.BandHorzSizing
l TcxTreeListOptionsCustomizing.ColumnHorzSizing
l TcxTreeListOptionsCustomizing.NodeSizing
l TcxTreeListOptionsCustomizing.RowSizing

Page 850 of 1199


TcxTreeListOptionsCustomizing.NestedBands
TcxTreeListOptionsCustomizing

Specifies whether end-users can arrange bands as nested bands using drag and drop.

Syntax

property NestedBands: Boolean;

Description
Set this property to False, to prohibit end-users from nesting bands. Setting this property to False doesn't collapse the existing
nested bands.

End-users can drag and drop bands only if the TreeList control's OptionsCustomizing.BandMoving property is set to True. You
can programmatically nest bands via a band's Position.BandIndex property, regardless of the NestedBands property value.

The default value of the NestedBands property is True.

Related Information

l TcxTreeListOptionsCustomizing.BandMoving
l TcxTreeListOptionsCustomizing.StackedColumns

Page 851 of 1199


TcxTreeListOptionsCustomizing.NodeSizing
TcxTreeListOptionsCustomizing

Specifies whether end-users can vertically resize individual nodes by dragging the bottom edge of corresponding indicator cells.

Syntax

property NodeSizing: Boolean;

Description
Set this property to True, to allow end-users to vertically resize individual nodes.

To programmatically specify a node's height, use its Height property. To enable instant visualization of node sizing, set the
OptionsCustomizing.DynamicSizing property to True.
Note:   Setting the NodeSizing property to True automatically assigns False, to the TreeList control's
OptionsCustomizing.RowSizing property, and vice versa.

The default value of the NodeSizing property is False.

Page 852 of 1199


TcxTreeListOptionsCustomizing.RowSizing
TcxTreeListOptionsCustomizing

Specifies whether end-users can specify the default height for all nodes.

Syntax

property RowSizing: Boolean;

Description
Set this property to True, to allow end-users to change the default height for all nodes by dragging the bottom edge of the
indicator cell that corresponds to the first visible node. Resizing in this manner is equivalent to setting the TreeList control's
DefaultRowHeight property. To enable instant visualization of node sizing, set the OptionsCustomizing.DynamicSizing property to
True.
Note:   Setting the RowSizing property to True automatically assigns False, to the TreeList control's
OptionsCustomizing.NodeSizing property, and vice versa.

The default value of the RowSizing property is False.

Page 853 of 1199


TcxTreeListOptionsCustomizing.StackedColumns
TcxTreeListOptionsCustomizing

Specifies whether end-users can stack columns using drag and drop.

Syntax

property StackedColumns: Boolean;

Description
Set this property to False, to prohibit end-users from stacking columns. Setting this property to False doesn't collapse the
existing stacked columns.

End-users can drag and drop columns only if the TreeList control's OptionsCustomizing.ColumnMoving property is set to True.
You can programmatically stack columns via a column's Position.RowIndex property or Position.SetPosition and
Position.SetPositionEx methods, regardless of the StackedColumns property value.

The default value of the StackedColumns property is True.

Related Information

l TcxTreeListOptionsCustomizing.ColumnMoving
l TcxTreeListOptionsCustomizing.NestedBands

Page 854 of 1199


TcxTreeListOptionsCustomizing.TreeList
TcxTreeListOptionsCustomizing

Provides access to the TreeList control that owns the current option set.
ReadOnly Property

Syntax

property TreeList: TcxCustomTreeList;

Page 855 of 1199


TcxTreeListOptionsData.AnsiSort
TcxTreeListOptionsData

Specifies whether string comparisons use Windows locale settings when sorting string cell values.

Syntax

property AnsiSort: Boolean;

Description
Set this property to True, to use Windows locale settings when comparing strings during sorting operations. Otherwise, strings
are compared based on the 8-bit ordinal value of each character.
Enabling this property sets the dcoAnsiSort flag in a data controller's Options property.

The default value of the AnsiSort property is False.

Related Information

l TcxTreeListOptionsData.CaseInsensitive
l TcxTreeListOptionsData.MultiThreadedSorting

Page 856 of 1199


TcxTreeListOptionsData.CaseInsensitive
TcxTreeListOptionsData

Determines whether sorting is case-insensitive.

Syntax

property CaseInsensitive: Boolean;

Description
Set this property to True, to make sorting case-insensitive.
Enabling this property sets the dcoCaseInsensitive flag in a data controller's Options property.

The default value of the CaseInsensitive property is False.

Related Information

l TcxTreeListOptionsData.AnsiSort
l TcxTreeListOptionsData.MultiThreadedSorting

Page 857 of 1199


TcxTreeListOptionsData.Deleting
TcxTreeListOptionsData

Specifies whether end-users can delete nodes.

Syntax

property Deleting: Boolean;

Description
Set this property to True, to allow end-users to delete nodes using the Ctrl+Del key combination or the cxNavigator linked to the
TreeList control.
Use the OptionsBehavior.ConfirmDelete property to specify whether the confirmation dialog is displayed before deleting nodes.

The default value of the Deleting property is True.

Related Information

l ExpressEditors: TcxDBNavigator Object

Page 858 of 1199


TcxTreeListOptionsData.Inserting
TcxTreeListOptionsData

Specifies whether end-users can insert or append new nodes.

Syntax

property Inserting: Boolean;

Description
Set this property to True, to allow end-users to:
l Insert nodes using the Ins key. Nodes are inserted before the currently focused node, at the same nesting level.
l Append nodes using the Ctrl+Ins key combination. Nodes are appended at the same nesting level as the currently focused
node.
l Insert or append nodes using the cxNavigator linked to the TreeList control

The default value of the Inserting property is False.

Related Information

l ExpressEditors: TcxDBNavigator Object

Page 859 of 1199


TcxTreeListOptionsData.MultiThreadedSorting
TcxTreeListOptionsData

Specifies whether or not nodes are sorted using multi-threaded algorithms.

Syntax

type
TdxDefaultBoolean = (bFalse, bTrue, bDefault);
property MultiThreadedSorting: TdxDefaultBoolean;

Description
This property is initialized with bDefault which indicates that the algorithm to be used is specified by the
dxDefaultMultiThreadedSorting global constant setting. In order to override this setting, you can assign either bTrue or bFalse to
the MultiThreadedSorting property to enable or disable multi-threaded algorithms for node sorting operations.

Note:   We recommend that you disable the use of multi-threaded algorithms for node sorting operations only if the tree list's
OnCompare event handler implementation is not thread-safe.

Related Information

l TcxTreeListOptionsData.AnsiSort
l TcxTreeListOptionsData.CaseInsensitive

Page 860 of 1199


TcxTreeListOptionsData.SummaryNullIgnore
TcxTreeListOptionsData

Specifies whether NULL values are ignored during summary calculations.

Syntax

property SummaryNullIgnore: Boolean;

Description
Set this property to True, to calculate only the non-null values.

The default value of the SummaryNullIgnore property is False.

Page 861 of 1199


TcxTreeListOptionsSelection.CellSelect
TcxTreeListOptionsSelection

Specifies whether individual cells can be selected instead of entire nodes.

Syntax

property CellSelect: Boolean;

Description
Set this property to False, to disable the selection of individual cells and editing within the TreeList control.

The default value of the CellSelect property is True.

Related Information

l TcxTreeListOptionsSelection.MultiSelect

Page 862 of 1199


TcxTreeListOptionsSelection.HideFocusRect
TcxTreeListOptionsSelection

Specifies whether the focus rectangle is displayed around the focused cell when the TreeList control loses focus.

Syntax

property HideFocusRect: Boolean;

Description
Set this property to True, to hide the focus rectangle drawn around the focused cell, when the TreeList control becomes inactive
(loses focus).

The default value of the HideFocusRect property is True.

Related Information

l TcxCustomTreeList.FocusedColumn
l TcxCustomTreeList.FocusedNode
l TcxTreeListOptionsSelection.HideSelection
l TcxTreeListOptionsView.FocusRect
l ExpressEditors: TcxCustomControlStyles.Inactive

Page 863 of 1199


TcxTreeListOptionsSelection.HideSelection
TcxTreeListOptionsSelection

Specifies whether the selected cell remains highlighted when the TreeList control loses focus.

Syntax

property HideSelection: Boolean;

Description
Set this property to True, to turn off the highlighting of the selected cell when the TreeList control becomes inactive (loses
focus).

The default value of the HideSelection property is False.

Related Information

l TcxTreeListOptionsSelection.HideFocusRect
l ExpressEditors: TcxCustomControlStyles.Inactive

Page 864 of 1199


TcxTreeListOptionsSelection.InvertSelect
TcxTreeListOptionsSelection

Specifies whether a single cell within the focused node or the whole node is highlighted when focused.

Syntax

property InvertSelect: Boolean;

Description
Set this property to True, to highlight the whole node when focused. Otherwise, only the focused cell is highlighted.

Value Example

True

False

The default value of the InvertSelect property is True.

Related Information

l TcxCustomTreeList.FocusedColumn

Page 865 of 1199


TcxTreeListOptionsSelection.MultiSelect
TcxTreeListOptionsSelection

Specifies whether multiple cells can be selected by end-users.

Syntax

property MultiSelect: Boolean;

Description
Set this property to True, to allow end-users to select more than one cell at a time while holding down the Shift or Ctrl key.

To prohibit end-users from selecting individual cells, set the CellSelect property to False.

The default value of the MultiSelect property is False.

Concepts

l Focusing and Selecting Nodes

Examples

l Example: Node.Selected, TreeList.GetSelections, OptionSelection.MultiSelect

Page 866 of 1199


TcxTreeListOptionsSelection.TreeList
TcxTreeListOptionsSelection

Provides access to the TreeList control that owns the current option set.
ReadOnly Property

Syntax

property TreeList: TcxCustomTreeList;

Page 867 of 1199


TcxTreeListOptionsView.BandLineHeight
TcxTreeListOptionsView

Specifies the line height of the band header panel, in pixels.

Syntax

property BandLineHeight: Integer;

Description
Use this property to customize the band header panel's height. If the BandLineHeight property is set to 0, the height is
calculated automatically, based on the minimum height required to display a single line of text within a band header.
The following table shows the effects of two custom BandLineHeight property values on the band header appearance:

Value Example

19

57

The BandLineHeight property automatically updates by multiplying its current value by the form's scaling factor every time it
changes at design-time or runtime.

Set both the TreeList control's OptionsCustomizing.BandVertSizing property and the band's Options.VertSizing property to True
to allow end-users to adjust the band header height by dragging the header's bottom edge.

The default value of the BandLineHeight property is 0.

Page 868 of 1199


TcxTreeListOptionsView.Bands
TcxTreeListOptionsView

Specifies if band headers are visible within the TreeList control.

Syntax

property Bands: Boolean;

Description
Set this property to True or False to show or hide band headers:

Value Example

True

False

Note:   The Customization Form does not display the Bands tab if the Bands property is set to False.

The default value of the Bands property is False.

Related Information

l TcxTreeListOptionsView.ExtPaintStyle

Page 869 of 1199


TcxTreeListOptionsView.Buttons
TcxTreeListOptionsView

Specifies the visibility of expand buttons within TreeList parent nodes.

Syntax

property Buttons: Boolean;

Description
Set this property to False, to hide expand buttons within the TreeList control. In this instance, end-users can expand or collapse
nodes by double-clicking them.
The following table shows examples of using the Buttons property.

Value Example

True

False

The default value of the Buttons property is True.

Page 870 of 1199


TcxTreeListOptionsView.CategorizedColumn
TcxTreeListOptionsView

Specifies a categorized column.

Syntax

property CategorizedColumn: TcxTreeListColumn;

Description
Use this property to specify the column providing values for categories within the TreeList control. To enable the categorized
paint style, set the PaintStyle property to tlpsCategorized.

If the categorized style is enabled and the CategorizedColumn property is not assigned, the first visible column is used as a
categorized column. Use the GetCategorizedColumn function to access the categorized column.

Related Information

l TcxTreeListColumn Object

Page 871 of 1199


TcxTreeListOptionsView.CheckGroups
TcxTreeListOptionsView

Specifies whether check boxes or radio buttons can be used in nodes.

Syntax

property CheckGroups: Boolean;

Description
Set this property to True to allow adding check boxes or radio buttons to nodes (see a node's CheckGroupType property).

Note that check boxes (radio buttons) can only be used in an unbound control (see the TcxTreeList).

The default value of the CheckGroups property is False.

Page 872 of 1199


TcxTreeListOptionsView.ColumnAutoWidth
TcxTreeListOptionsView

Determines whether column widths are automatically adjusted to display all data cells without using the horizontal scrollbar.

Syntax

property ColumnAutoWidth: Boolean;

Description
To enable this mode, set the ColumnAutoWidth property to True.
To specify how truncated content is displayed within band and column headers and data cells, use the Caption.ShowEndEllipsis
and Options.CellEndEllipsis properties.

The default value of the ColumnAutoWidth property is False.

Related Information

l TcxTreeListOptionsCustomizing.ColumnHorzSizing
l TcxTreeListOptionsView.Headers

Page 873 of 1199


TcxTreeListOptionsView.DropArrowColor
TcxTreeListOptionsView

Specifies the color of arrows indicating a band or column header's potential position during drag operations.

Syntax

property DropArrowColor: TColor;

Description
The following table shows examples of using this property.

Value Example

clRed

clLime

The default value of the DropArrowColor property is specified by the cxTreeListDefDropArrowColor global constant.

Related Information

l TcxTreeListOptionsCustomizing.BandMoving
l TcxTreeListOptionsCustomizing.ColumnMoving
l TcxTreeListOptionsView.Headers

Page 874 of 1199


TcxTreeListOptionsView.DropNodeIndicator
TcxTreeListOptionsView

Specifies the visibility of indicators that assist end-users during drag-and-drop operations.

Syntax

property DropNodeIndicator: Boolean;

Description
Set this property to True, to display assisting indicators at the left edge of a node located under the mouse pointer, during drag-
and-drop operations. The indicators suggest the resulting drop position for a node being dragged, relative to a node under the
mouse pointer, as shown in the following table.

Indicator Context Sample Meaning

Dragging over the top half A node being dragged will be


of a node's indent or positioned before a node located
indicator cell. under the mouse pointer, at the
same nesting level.

Dragging over the bottom A node being dragged will be


half of a node's indent or positioned after a node located
indicator cell. under the mouse pointer, at the
same nesting level.

Dragging over a node's A node being dragged will be


data cell or preview positioned as a child of a node
section. located under the mouse pointer.

The default value of the DropNodeIndicator property is False.

Concepts

l Implementing Drag-And-Drop Functionality