Copyright: Copyright © 1998-2007 Developer Express Inc. ALL RIGHTS RESERVED


Preview

ExpressQuantumTreeList4 is able to display a Preview Section.  This section is the area within a row suitable for displaying large memo field values.  The TreeList control publishes the Preview property, thus providing a set of options to manage the preview section.  These options determine the preview section’s visibility, preview text position, column values to be displayed within the preview and the number of text lines displayed within the preview, etc.

Note:  If column values are displayed within the preview, this column is not displayed with the other TreeList columns.


Self-Referenced Dataset

A data-aware TreeList control is able to connect to any VCL dataset, however only self-referenced datasets are suitable for ExpressQuantumTreeList4.  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

…


Categorized Column

The TreeList control supports two methods of data representation: standard and categorized.  Standard data representation means that TreeList data is arranged in columns and nodes.  With categorized data representation, some column values occupy whole nodes.

The following image shows a TreeList control with its Editor Name column set as a categorized column:

Categorized data representation is enabled via the CategorizedColumn and PaintStyle properties.


Options

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

There are several option sets available for the TreeList control.  These options include:

•	OptionsBehavior – options defining the TreeList’s response to user actions, i.e. via the mouse and keyboard.

•	OptionsCustomizing – options 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.  If horizontal sizing of columns is deactivated by setting the OptionsCustomizing.ColumnHorzSizing property to False, a column width can be changed via the Column.Width property.

•	OptionsData – options controlling data manipulation within the TreeList control.  These options control editing, inserting, deleting records, etc.

•	OptionsSelection – options managing selection within the TreeList control.  These options determine whether the selection bar is visible, whether the selection bar’s bounding rectangle is visible, whether multiple rows can be selected, whether individual cells can be focused instead of rows, 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.

•	OptionsView – options controlling the appearance of the TreeList control.  This option set defines the visibility, color, width and other appearance settings of control elements.

•	Preview – options 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.  For more information on the ExpressQuantumTreeList4 preview feature, see the Preview topic.

TreeList elements (columns, bands) have their own option sets.  These option sets are similar to the TreeList‘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.Options.Moving property.


TcxTreeListNode
TcxTreeListNode Object

Hierarchy          Properties          Methods

Represents a TreeList node.

Unit

cxTL

TcxTreeListNode = class(TPersistent)

Description

TreeList 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.

The TreeList.Nodes property maintains the node collection.

TreeList nodes can be expanded to display the next level of child nodes.  A user can expand a TreeListNode 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.  When a node is expanded or collapsed, the following events are generated: TreeList.OnExpanding, TreeList.OnExpanded, TreeList.OnCollapsing, TreeList.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.OptionsView property contains the ViewOptions.ShowButtons flag).  A user can press it and thus generate the TreeList.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.Images and TreeList.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, GetNextVisible, GetPrev, GetPrevChild, GetPrevSibling, GetPrevVisible method descriptions.  Note that using these methods improves performance during recursive navigation through the tree structure.  Thus, using these methods is better than a linear search via the Nodes collection.

The TreeList control provides drag-and-drop functionality which enables you to move nodes to another position, to another TreeList control or even to the third party control.  If the TreeList.DragMode property is set to dmAutomatic, dragging occurs automatically.  You can control drag-and-drop operations by handling the TreeList.OnDragOver and TreeList.OnDragDrop events.


TcxTreeListNode Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxTreeListNode
TcxTreeListNode Properties

TcxTreeListNode          Legend

In TcxTreeListNode

AbsoluteIndex

Count

Data

Deleting

Expanded

Focused

HasChildren

HotTrack

ImageIndex

Index

IsFirst

IsFirstVisible

IsGroupNode

IsLast

IsLastVisible

IsVisible

Items

Level

Owner

Parent

RecordIndex

Selected

SelectedIndex

StateIndex

Texts

TreeList

ValueCount

Values

VisibleIndex


Methods for TcxTreeListNode
TcxTreeListNode Methods

TcxTreeListNode          Legend

In TcxTreeListNode

 AddChild

 AddChildFirst

 AlphaSort

 AssignValues

 CanCollapse

 CanExpand

 CanMove

 Collapse

 CustomSort

 Delete

 DeleteChildren

 DisplayRect

 EndEdit

 Expand

 GetFirstChild

 GetLastChild

 GetNext

 GetNextChild

 GetNextSibling

 GetNextVisible

 GetPrev

 GetPrevChild

 GetPrevSibling

 GetPrevVisible

 HasAsParent

 IndexOf

 InsertChild

 MakeVisible

 MoveTo

 Repaint


TcxTreeListNode.AbsoluteIndex

TcxTreeListNode          See Also

Returns the node’s index within the control.

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 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


TcxTreeListNode.Count

TcxTreeListNode

Returns the number of child nodes.

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


TcxTreeListNode.Data

TcxTreeListNode          See Also

Specifies the pointer to data associated with the node.

property Data: Pointer;

Description

Use the Data property to associate data with the node.

Note: you should never use the Data property in bound and provider modes. Use an additional field in a data store instead when working in these modes.


TcxTreeListNode.Deleting

TcxTreeListNode

Indicates whether a node's Delete method has been called and if the node is being deleted.

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


TcxTreeListNode.Expanded

TcxTreeListNode

Specifies whether the node is expanded.

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.


TcxTreeListNode.Focused

TcxTreeListNode          See Also           Example

Determines whether the node has focus.

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.


TcxTreeListNode.HasChildren

TcxTreeListNode          See Also

Specifies whether the node has child nodes.

property HasChildren: Boolean;

Description

Use the HasChildren property to specify whether the node has child nodes.  If the node’s HasChildren property value is True and the OptionsView.Buttons property is True, expand buttons are displayed beside each node, even if that node has no children.   And, on the contrary, if the node has child nodes, setting the HasChildren property to False has no effect.

The expand button indicates visually that the node contains children, but it is not necessary for the Items property to contain entries.  For instance, this can be used to display child nodes dynamically. To do so, set the HasChildren property to True and implement adding child nodes within a TreeList.OnExpanding event handler. Thus, child nodes will be added only on user demand.


TcxTreeListNode.HotTrack

TcxTreeListNode          See Also

Determines whether the node is hot-tracked.

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


TcxTreeListNode.ImageIndex

TcxTreeListNode          See Also

Specifies the index of the image associated with the node.

property ImageIndex: TImageIndex;

Description

Use the ImageIndex property to associate an image with the node.  Node images are stored within the Images and StateImages image lists.

You can handle the TreeList.OnGetNodeImageIndex event to assign images to nodes.  This is the only way to customize images assigned to nodes when working with a data-aware TreeList (cxDBTreeList).  For cxTreeList and cxVirtualTreeList nodes, images can be assigned directly via the ImageIndex property.


TcxTreeListNode.Index

TcxTreeListNode          See Also

Returns the node index within its parent node’s Items collection.

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


TcxTreeListNode.IsFirst

TcxTreeListNode          See Also

Indicates whether the node is the first node within its parent node’s Items collection.

property IsFirst: Boolean;

Description

Use the IsFirst property to determine whether the node is the first within the child nodes collection of its parent.  The IsLast property indicates whether the node is the last child node of its parent.

Note: this property value is affected when the node order is changed.

ReadOnly Property


TcxTreeListNode.IsFirstVisible

TcxTreeListNode          See Also

Indicates whether the node is the first visible node within the TreeList control.

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 TreeList nodes is specified via 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


TcxTreeListNode.IsGroupNode

TcxTreeListNode          See Also

Indicates whether the node is a group node.

property IsGroupNode: Boolean;

Description

Use the IsGroupNode property to determine whether the node is a group node.

A group node is a node (with children) that only contains a category column value.  The following screenshot shows group nodes:

ReadOnly Property


TcxTreeListNode.IsLast

TcxTreeListNode          See Also

Indicates whether the node is the last child node of its parent.

property IsLast: Boolean;

Description

Use the IsLast property to determine whether the node is the last child node.  Use the IsFirst property to determine whether the node is the first child node.  You can access all a node’s child nodes via its Items property.

Note: this property value is affected when the node order is changed.

ReadOnly Property


TcxTreeListNode.IsLastVisible

TcxTreeListNode          See Also

Indicates whether the node is the last visible node within the TreeList control.

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 TreeList nodes is specified via 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


TcxTreeListNode.IsVisible

TcxTreeListNode          See Also

Indicates whether the node is visible.

property IsVisible: Boolean;

Description

Use the IsVisible property to determine whether the node is visible.  The node is visible if its parent node (and its parent’s parent etc.) is visible and expanded or if it is located at the root nesting level.  Call the MakeVisible method if you wish to expand a particular node.

ReadOnly Property


TcxTreeListNode.Items

TcxTreeListNode

Provides indexed access to the node’s child nodes.

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.


TcxTreeListNode.Level

TcxTreeListNode

Specifies the node’s nesting level.

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


TcxTreeListNode.Owner

TcxTreeListNode

Provides access to the TcxTreeListNodes collection containing the node.

property Owner: TcxTreeListNodes;

Description

Use the Owner property to access the TcxTreeListNodes object containing the node.  This object represents a TreeList.Nodes collection.

ReadOnly Property


TcxTreeListNode.Parent

TcxTreeListNode          See Also

Returns the nodes’s parent node.

property Parent: TcxTreeListNode;

Description

Use the Parent property to obtain the nodes’s TreeList node parent.  The value for a root node is nil.

ReadOnly Property


TcxTreeListNode.RecordIndex

TcxTreeListNode          See Also

Specifies the node’s index within the data controller.

property RecordIndex: Integer;

Description

Use the RecordIndex property to obtain a value that uniquely identifies the node among data set records.  Unlike the AbsoluteIndex and Index properties, the RecordIndex value does not depend on the sort order applied to the TreeList control.

When the TreeList control works in unbound mode, this property designates the loading order of the node.

You can use the RecordIndex property to access values or display text of a particular column


TcxTreeListNode.Selected

TcxTreeListNode          See Also           Example

Determines whether the node is selected.

property Selected: Boolean;

Description

Use the Selected property to select the node.  If the OptionsSelection.MultiSelect option is active, setting the node’s Selected property to True adds the node to the selection.


TcxTreeListNode.SelectedIndex

TcxTreeListNode

If the node is selected, it specifies the index of the image displayed beside the node.

property SelectedIndex: TImageIndex;

Description

Use the SelectedIndex property to specify the index of the image displayed beside the node when it is selected.  This property represents the image index from the Images ImageList.  If this property value is –1, no image is assigned to the node.

You can handle the TreeList.OnGetNodeImageIndex event to assign images to nodes.  This is the only way to customize images assigned to nodes when working with a data-aware TreeList (cxDBTreeList).  For cxTreeList and cxVirtualTreeList nodes, images can be assigned directly via the SelectedIndex property.


TcxTreeListNode.StateIndex

TcxTreeListNode

Specifies the state image index for the node.

property StateIndex: TImageIndex;

Description

Use the StateIndex property to specify the index of the state image displayed beside the node.  This property represents the image index from the StateImages ImageList.  If this property value is –1, no image is assigned to the current node.

You can handle the TreeList.OnGetNodeImageIndex event to assign images to nodes.  This is the only way to customize images assigned to nodes when working with a data-aware TreeList (cxDBTreeList).  For cxTreeList and cxVirtualTreeList nodes, images can be assigned directly via the StateIndex property.


TcxTreeListNode.Texts

TcxTreeListNode          See Also

Provides indexed access to the string representation of the node’s column values.

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.


TcxTreeListNode.TreeList

TcxTreeListNode

Returns the TreeList control owning the node.

property TreeList: TcxCustomTreeListControl;

Description

Use the TreeList property to access the TreeList control owning the node.  The Owner property of the node provides access to the TcxTreeListNodes collection that contains the node.

ReadOnly Property


TcxTreeListNode.ValueCount

TcxTreeListNode          See Also

Returns the number of values displayed within the node.

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


TcxTreeListNode.Values

TcxTreeListNode          See Also

Provides indexed access to column values within the node.

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 CustomTreeListControl.Columns collection.

To access the string representation of column values, use the Texts or the Column.DisplayTexts properties.  The Column.DisplayTexts property is indexed via the RecordIndex property value.


TcxTreeListNode.VisibleIndex

TcxTreeListNode

Returns the node’s index among visible nodes.

property VisibleIndex: Integer;

Description

Use the VisibleIndex property to obtain the node’s index among visible nodes.  You can navigate through visible TreeList nodes using the GetNextVisible and GetPrevVisible properties.  If the current node is not visible, the VisibleIndex property value is –1.

ReadOnly Property


TcxTreeListNode.AddChild

TcxTreeListNode          See Also           Example

Adds a child node.

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 cxTreeList (unbound mode of the TreeList control).


TcxTreeListNode.AddChildFirst

TcxTreeListNode          See Also           Example

Inserts a child node.

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.


TcxTreeListNode.AlphaSort

TcxTreeListNode          See Also

Sorts the node’s children.

procedure AlphaSort(ARecurse: Boolean = False);

Description

Use the AlphaSort method to sort the node’s child nodes.  The ARecurse parameter specifies that sorting should recursively descend the node tree and sort each sub-tree in turn. By default, only the node’s immediate children are sorted.

In order to sort all TreeList nodes, use the TreeList.Nodes.Root.AlphaSort method.


TcxTreeListNode.AssignValues

TcxTreeListNode          See Also

Assigns the node’s column values.

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.


TcxTreeListNode.CanCollapse

TcxTreeListNode          See Also

Indicates whether the node can be collapsed.

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.


TcxTreeListNode.CanExpand

TcxTreeListNode          See Also

Indicates whether the node can be expanded.

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.


TcxTreeListNode.CanMove

TcxTreeListNode

Indicates whether the node can be moved to the location specified within the TreeList.

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.  The ADest parameter identifies the destination and the AMode parameter specifies the manner in which the current node is moved:

AMode	Description
tlamAdd	Adds a node at the same level as the existing node and makes the new node the last.
tlamAddFirst	Adds a node at the same level as the existing node and makes the new node the first.
tlamAddChild	Adds a child node to the existing node and makes the new node the last.
tlamAddChildFirst	Adds a child node to the existing node and makes the new node the first.
tlamInsert	Inserts a node at the same level just before the existing node.


TcxTreeListNode.Collapse

TcxTreeListNode          See Also

Collapses the TreeList node.

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.


TcxTreeListNode.CustomSort

TcxTreeListNode          See Also

Custom sorts the node’s children.

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 OnCompare event handler is not defined, the default routine uses a simple case-sensitive comparison of node captions.

In the comparison routine, the AItem1 and AItem2 parameters refer to two. The return value of the comparison routine indicates the relative sort order of AItem1 and AItem2:

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 PHONE column values:

//Delphi

function MyCustomSort(AItem1, AItem2: TcxTreeListNode): Integer;

begin

  Result := AnsiCompareStr(AnsiRightStr(AItem1.Texts[SimpleTreeDemoMainForm.cxDBTreeListPHONE.ItemIndex], 2), AnsiRightStr(AItem2.Texts[SimpleTreeDemoMainForm.cxDBTreeListPHONE.ItemIndex], 2));

end;

procedure TSimpleTreeDemoMainForm.Button1Click(Sender: TObject);

begin

  cxdbtreelist.FocusedNode.CustomSort(MyCustomSort, True);

end;


TcxTreeListNode.Delete

TcxTreeListNode          See Also

Removes the node and all its children from the TreeList control.

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.


TcxTreeListNode.DeleteChildren

TcxTreeListNode          See Also

Removes the node’s children.

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.


TcxTreeListNode.DisplayRect

TcxTreeListNode

Returns the node’s bounding rectangle.

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:


TcxTreeListNode.EndEdit

TcxTreeListNode

Switches the node from edit to browse mode.

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.


TcxTreeListNode.Expand

TcxTreeListNode

Expands the node.

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.


TcxTreeListNode.GetFirstChild

TcxTreeListNode          See Also

Returns the node’s first child.

function GetFirstChild: TcxTreeListNode;

Description

Use the GetFirstChild method to obtain the first child of the node.


TcxTreeListNode.GetIsFirstVisible

TcxTreeListNode          See Also

Indicates whether the node is the first visible node within the TreeList control.

function GetIsFirstVisible: Boolean; virtual;

Description

Use the GetIsFirstVisible method to determine whether the node is the first visible node within the TreeList control.


TcxTreeListNode.GetIsLastVisible

TcxTreeListNode

Indicates whether the node is the last visible node within the TreeList control.

function GetIsLastVisible: Boolean; virtual;

Description

Use the GetIsLastVisible method to determine whether the node is the last visible node within the TreeList control.


TcxTreeListNode.GetLastChild

TcxTreeListNode

Returns the node’s last child.

function GetLastChild: TcxTreeListNode;

Description

Use the GetLastChild method to obtain the last child of the node.


TcxTreeListNode.GetNext

TcxTreeListNode          Example

Returns the node next to the current one within the tree structure.

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.


TcxTreeListNode.GetNextChild

TcxTreeListNode

Returns the next child node after the node specified.

function GetNextChild(Value: TcxTreeListNode): TcxTreeListNode;

Description

Use the GetNextChild method to obtain the next child node after the node specified via the Value parameter.  If the node specified via the Value parameter has no children, this method returns nil.


TcxTreeListNode.GetNextSibling

TcxTreeListNode

Returns the next node at the current nesting level.

function GetNextSibling: TcxTreeListNode;

Description

Use the GetNextSibling method to obtain the next node at the current nesting level.  If this method is used for the last node within the tree structure, this method returns nil.


TcxTreeListNode.GetNextVisible

TcxTreeListNode          See Also           Example

Returns the next visible node.

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 for the last node within the tree structure, it returns nil.


TcxTreeListNode.GetPrev

TcxTreeListNode          See Also           Example

Returns the node previous to the current one.

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.


TcxTreeListNode.GetPrevChild

TcxTreeListNode          See Also

Returns the previous child of the node specified.

function GetPrevChild(Value: TcxTreeListNode): TcxTreeListNode;

Description

Use the GetPrevChild method to obtain the previous child of the node specified via the Value parameter.  If this node has no children, the method returns nil.


TcxTreeListNode.GetPrevSibling

TcxTreeListNode          See Also

Returns the previous node at the current nesting level.

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.


TcxTreeListNode.GetPrevVisible

TcxTreeListNode          See Also           Example

Returns the previous visible node.

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.


TcxTreeListNode.HasAsParent

TcxTreeListNode          See Also

Indicates that the node specified is the parent of this node.

function HasAsParent(Value: TcxTreeListNode): Boolean;

Description

Use the HasAsParent method to determine whether the specified node is the parent node of the current one.


TcxTreeListNode.IndexOf

TcxTreeListNode          See Also

Returns the specified node’s index among this node’s children.

function IndexOf(Value: TcxTreeListNode): Integer;

Description

Use the IndexOf method to obtain the specified node index among this node’s children.  If the node specified via the Value 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.


TcxTreeListNode.InsertChild

TcxTreeListNode          See Also

Inserts a child node into the node’s child collection.

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).


TcxTreeListNode.MakeVisible

TcxTreeListNode          See Also

Ensures that the node is displayed.

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.


TcxTreeListNode.MoveTo

TcxTreeListNode          See Also

Moves the node to the location specified within the TreeList control.

procedure MoveTo(ADestNode: TcxTreeListNode; AMode: TcxTreeListNodeAttachMode); virtual;

Description

Use the MoveTo method to move the node to the location provided by the ADestNode parameter.  The AMode parameter specifies the manner in which the current node is moved:

AMode	Description
tlamAdd	Adds a node at the same level as the existing node and makes the new node the last.
tlamAddFirst	Adds a node at the same level as the existing node and makes the new node the first.
tlamAddChild	Adds a child node to the existing node and makes the new node the last.
tlamAddChildFirst	Adds a child node to the existing node and makes the new node the first.
tlamInsert	Inserts a node at the same level just before the existing node.


TcxTreeListNode.Repaint

TcxTreeListNode

Redraws the node.

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.


TcxTreeListDataNode
TcxTreeListDataNode Object

Hierarchy          Properties          Methods

Represents a node of the cxDBTreeList or the cxVirtualTreeList control.

Unit

cxTLData

TcxTreeListDataNode = class(TcxTreeListNode)

Description

The TcxTreeListDataNode object represents a node within the cxDBTreeList or the cxVirtualTreeList control.  It inherits all basic functionality from its ancestor (TcxTreeListNode).  It also declares two properties: KeyValue and ParentValue.  They identify the node’s position within the TreeList control.

The node’s  KeyValue and ParentValue properties are changed automatically during drag-and-drop operations.  Avoid manual changes to these properties when working with cxDBTreeList, as it can cause unpredictable results.


TcxTreeListDataNode Hierarchy
Hierarchy

TPersistent

     |

TcxTreeListNode

     |


Properties for TcxTreeListDataNode
TcxTreeListDataNode Properties

TcxTreeListDataNode          Legend

In TcxTreeListDataNode

KeyValue

ParentValue

Derived from TcxTreeListNode

AbsoluteIndex

Count

Data

Deleting

Expanded

Focused

HasChildren

HotTrack

ImageIndex

Index

IsFirst

IsFirstVisible

IsGroupNode

IsLast

IsLastVisible

IsVisible

Items

Level

Owner

Parent

RecordIndex

Selected

SelectedIndex

StateIndex

Texts

TreeList

ValueCount

Values

VisibleIndex


Methods for TcxTreeListDataNode
TcxTreeListDataNode Methods

TcxTreeListDataNode          Legend

Derived from TcxTreeListNode

 AddChild

 AddChildFirst

 AlphaSort

 AssignValues

 CanCollapse

 CanExpand

 CanMove

 Collapse

 CustomSort

 Delete

 DeleteChildren

 DisplayRect

 EndEdit

 Expand

 GetFirstChild

 GetLastChild

 GetNext

 GetNextChild

 GetNextSibling

 GetNextVisible

 GetPrev

 GetPrevChild

 GetPrevSibling

 GetPrevVisible

 HasAsParent

 IndexOf

 InsertChild

 MakeVisible

 MoveTo

 Repaint


TcxTreeListDataNode.KeyValue

TcxTreeListDataNode          See Also

Specifies the node’s key field value.

property KeyValue: Variant;

Description

Use the KeyValue property to specify the key field value for the node.

KeyField field values identify records.  The ParentField property designates the dataset field whose value defines the record’s position within the tree-structure.  The value of the ParentField specifies the KeyField value of the record (node in the tree structure), owning this 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 values.

The KeyValue property value changes automatically during drag-and-drop operations.

Note: do not modify the KeyValue property value for cxDBTreeList nodes manually, as this may cause unpredictable results.


TcxTreeListDataNode.ParentValue

TcxTreeListDataNode          See Also

Specifies the node’s parent field value.

property ParentValue: Variant;

Description

Use the ParentValue property to specify the parent field value for the node.

KeyField field values identify records.  The ParentField property designates the dataset field whose values define the record’s position within the tree-structure.  The values of the 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, 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 values.

The ParentValue property value changes automatically during drag-and-drop operations.

Note: do not modify the ParentValue property value for cxDBTreeList nodes manually, as may cause unpredictable results.


TcxTreeListNodes
TcxTreeListNodes Object

Hierarchy          Properties          Methods

Represents the node collection.

Unit

cxTL

TcxTreeListNodes = class(TPersistent)

Description

The TreeList control owns a collection of nodes.  This collection can be accessed via the TreeList.Nodes property and this property represents a TcxTreeListNodes class instance.

The Nodes.AbsoluteItems property provides access to nodes via their absolute position within the TreeList control.  The number of visible nodes within the control is returned via the VisibleCount property, while the Count property returns the total number of nodes within the control.

The Nodes.Root property provides access to the TreeList root.  The TreeList root is an invisible node, which has no Values, but owns the child collection (accessed via the TreeList.Nodes.Root.Items property).  The children of the TreeList root are nodes displayed at the top-most hierarchy level.


TcxTreeListNodes Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxTreeListNodes
TcxTreeListNodes Properties

TcxTreeListNodes          Legend

In TcxTreeListNodes

AbsoluteItems

Count

Items

MaxLevel

Root

TopVisibleNode

TreeList

VisibleCount


Methods for TcxTreeListNodes
TcxTreeListNodes Methods

TcxTreeListNodes          Legend

In TcxTreeListNodes

 Clear


TcxTreeListNodes.AbsoluteItems

TcxTreeListNodes          See Also

Provides indexed access to TreeList nodes by their absolute position within the TreeList control.

property AbsoluteItems[AbsoluteIndex:Integer]: TcxTreeListNode;

Description

Use the AbsoluteItems property to access TreeList nodes via their AbsoluteIndex property value.  The AbsoluteIndex property specifies the absolute node position within the TreeList.  The first node within the TreeList control has the AbsoluteIndex property set to 0.  Other nodes are indexed consequently.

Avoid using this property during recursive navigation through the tree list nodes because of the performance drop.  Use the GetPrev, GetPrevVisible, GetNext, GetNextVisible, GetNextChild, GetNextSibling, GetPrevChild, GetPrevSibling methods instead.  See the example of using these methods.


TcxTreeListNodes.Count

TcxTreeListNodes

Returns the number of nodes within the TreeList control.

property Count: Integer;

Description

Use the Count property to obtain the number of nodes within the TreeList control.  You can use the Items or the AbsoluteItems property to access TreeList nodes.

ReadOnly Property


TcxTreeListNodes.Items

TcxTreeListNodes

Provides indexed access to TreeList nodes.

property Items[Index:Integer]: TcxTreeListNode;

Description

Use the Items property for indexed access to TreeList nodes.  Nodes in this list are sorted by their RecordIndex property values.  If you need to access nodes in the same order as they appear within the TreeList control, use the AbsoluteItems property.


TcxTreeListNodes.MaxLevel

TcxTreeListNodes          See Also

Returns the maximum nesting level currently displayed.

property MaxLevel: Integer;

Description

Use the MaxLevel property to read the maximum nesting level currently displayed within the TreeList control.  The nesting level of a specific node can be obtained via its Node.Level property.  The node’s level indicates the number of parent nodes to expand to reach the current node.

ReadOnly Property


TcxTreeListNodes.Root

TcxTreeListNodes

Provides access to the TreeList root.

property Root: TcxTreeListNode;

Description

Use the Root property to access the virtual TreeList node.  This node is the parent for all nodes, located at the root hierarchy level.  It is invisible and has no Values, but the Items and Count properties provide access to the root level nodes (those whose Level property value is 0).

ReadOnly Property


TcxTreeListNodes.TopVisibleNode

TcxTreeListNodes          See Also

Returns the top-most visible TreeList node.

property TopVisibleNode: TcxTreeListNode;

Description

Use the TopVisibleNode to access the top-most visible node within the TreeList control.  This node’s AbsoluteIndex property value is 0.  The GetIsFirstVisible method returns True for this node.

ReadOnly Property


TcxTreeListNodes.TreeList

TcxTreeListNodes

Returns the TreeList control that owns the current node collection.

property TreeList: TcxCustomTreeListControl;

Description

Use the TreeList property to access the TreeList control owning the current node collection.  Use the TreeList.Nodes property to work with the node collection.

ReadOnly Property


TcxTreeListNodes.VisibleCount

TcxTreeListNodes

Returns the number of nodes currently visible.

property VisibleCount: Integer;

Description

Use the VisibleCount property to obtain the number of currently visible nodes.  A node is visible when all preceding parent nodes are expanded.

ReadOnly Property


TcxTreeListNodes.Clear

TcxTreeListNodes

Clears the TreeList node collection.

procedure Clear;

Description

Use the Clear method to remove all nodes from the TreeList control.  You can remove individual nodes from the TreeList control by calling the Node.Delete method.

Calling this method raises the TreeList.OnDeletion event.


Bands

Let’s create a cxTreeList with the following bands and columns layout:

First, drop a treelist control on a form.  Call 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 the bands within ExpressQuantumTreeList4. By default, this property is set to False.

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.  Call 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 treelist when adding columns, a new band will be created automatically.

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.BandLineCount property to 2 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

  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;

  // 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 ExpressQuantumTreeList4 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.

In this case, band(s) become non-scrollable.  This feature does not make sense if OptionsView.ColumnAutoWidth is set to True.

For the data-aware cxTreeList designed to work in bound mode you can use the CreateAllItems method declared in the control’s 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.


Connecting to Data

This topic explains how to connect ExpressQuantumTreeList4 to a dataset.

 A data-aware cxTreeList control is able to connect to any VCL dataset but only self-referenced datasets are suitable for ExpressQuantumTreeList4.  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

•	Place TTable and TDataSource components on a form (or DataModule).

•	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 ExpressQuantumTreeList4 Suite, the TableName property to "departments.db" and the Active property to True.

•	Set up the TDataSource component via the Object Inspector: Set its DataSet property to a TTable class instance (normally Table1).

2.	ADO

•	Place TADOConnection, TADOTable and TDataSource components on a form.

•	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:

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.

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:

Now the ADO Connection is ready to use.

•	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.

•	Set up the TDataSource component via the Object Inspector: Set its DataSet property to a TADOTable class instance (normally ADOTable1).

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:

•	Set the DataSource property of the data controller to a TDataSource class instance (normally DataSource1):

•	Set the KeyField property to the key field in a self-referenced dataset:

•	Set the ParentField property to the parent field in the self-referenced dataset:

•	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.

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();

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:


Creating And Deleting Columns

This topic covers the steps required to create and delete columns within the TreeList control.

Bound, unbound and virtual treelist controls provide a Columns property maintaining the collection of columns within the control.  The Columns property returns:

•	a TcxTreeListColumn object for unbound and virtual treelist controls

•	a TcxDBTreeListColumn object for a bound treelist control.

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, call the Component Editor, go to the Columns tab and press the CreateAllFields button.

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. Use the multi-select feature to delete several columns at once.


Creating Summaries

ExpressQuantumTreeList4 supports footer summaries.  Footer summaries are calculated against all nodes in the TreeList control.

Here are the steps to add the footer summary feature to your TreeList control:

•	Enable the OptionsView.Footer property.

•	Call the Component Editor, go to the Columns tab and select the column where a summary will be displayed.

•	Set Options.Footer for the selected column to True.

•	Set the required type of the summary using the SummaryFooter.Kind property.

If you are using a data-aware TreeList control, you may calculate summaries by another field bound to a column. To achieve this, set the SummaryFooter.FieldName property to the required field name.

In most cases you will want to leave this property empty.

Use the SummaryFooter.Format property to specify the pattern for displaying a summary string.  For instance, by setting the SummaryFooter.Format property value to ‘SUM = $,0.00;-$,0.00’ for a currency field, you will get the following display text in the footer cell:

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 footer cell will display the ‘‘SUM = $23.01" string.

See the SummariesDemo provided with the ExpressQuantumTreeList4 installation to learn how to use the onSummary and onAfterSummary events

You can use the onSummary event to change the default calculated summary value.  For example, you may use only selected nodes in the summary calculation or do other calculations.

Here is a code snippet taken from SummariesDemo. This code calculates summaries for orders made with Visa only.

//Delphi

procedure TSummariesDemoMainForm.tlOrdersSummary(

  ASender: TcxDataSummaryItems; Arguments: TcxSummaryEventArguments;

  var OutArguments: TcxSummaryEventOutArguments);

begin

  // If the payment type is not Visa, leave OutArguments.Value empty

  // prohibit automatic calculation

  if ASender.DataController.Values[Arguments.RecordIndex, tlOrdersPaymentType.ItemIndex] <> 'Visa'   then

    OutArguments.Done := True;

end;


Deleting Nodes

To delete nodes at runtime, set the OptionsData.Deleting property to True and press the Ctrl+Del keys 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.


Implementing the Drag-And-Drop Functionality
Implementing Drag-And-Drop Functionality

Drag-and-drop allows end users to drag one control (or its items) to another within the same application or rearrange items within the same control.  There are four different situations when you may need to implement the drag-and-drop feature within the TreeList control:

•	rearranging nodes within the TreeList control by changing their parent nodes;

•	drag-and-drop from a VCL control onto a TreeList control;

•	drag-and-drop from a TreeList control onto a VCL control;

•	drag-and-drop between two TreeList controls.

In this topic we will discuss all four types of drag-and-drop.

Drag-and-drop within the TreeList control

This is the easiest case, because it can be implemented automatically by setting the DragMode property of the TreeList control to dmAutomatic in the Object Inspector:

Additionally at the very least you will have to provide an empty implementation of the onDragOver event to enable drag-and-drop within the TreeList control.

If you are working with a data-aware TreeList control, DBTreeList changes parent field values during drag-and-drop operations automatically.  Set the 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.  The end-user will be able to drag items from the Listbox onto the 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.

5)	Write the following code for the onDragOver event of the TreeList control to show that the TreeList can accept items from the ListBox control.

// Delphi

procedure TForm1.cxTreeList1DragOver(Sender, Source: TObject; X,

  Y: Integer; State: TDragState; var Accept: Boolean);

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 screenshot 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.

Drag-and-drop from a TreeList control onto a VCL control

Let’s use the TreeList and Listbox controls again.

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)	Call the TreeList control’s Items Editor and add several nodes.

4)	Disable the TreeList’s OptionsBehavior.ImmediateEditor and OptionsBehavior.AlwaysShowEditor properties and set DragMode to dmAutomatic.

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 Accept: Boolean);

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 cxTreeList1

  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 screenshot shows the application while dragging:

And the following image shows the TreeList control after dropping:

Drag-and-drop between two TreeList controls

Dragging one TreeList control to another has one major difference from the examples above: the tree structure must be recreated on the target TreeList control.

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)	Call Items Editor and add several nodes.

4)	Disable the OptionsBehavior.ImmediateEditor and OptionsBehavior.AlwaysShowEditor properties and set DragMode to dmAutomatic.

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 both controls.

// Delphi

procedure TForm1.cxTreeList1DragOver(Sender, Source: TObject; X,

  Y: Integer; State: TDragState; var Accept: Boolean);

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

          Result := ADestTreeList.Nodes.Items[I];

      end;

    if Result = nil then

      Result := AParentNode;

  end;

var

  ANode, ASelectedNode: TcxTreeListNode;

  I: Integer;

begin

  if not (Source is TcxTreeList) then exit;

  ASourceTreeList := TcxTreeList(Source);

  ADestTreeList := TcxTreeList(Sender);

  AParentNode := ADestTreeList.HitTest.HitNode;

  // 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 screenshot shows the resulting application while dragging:

And the following image shows the drag-and-drop result:

There are additional TreeList control properties dealing with drag-and-drop which you may find

useful:  OptionsBehavior.AutoDragCopy, OptionsBehavior.DragCollapse and OptionsBehavior.DragExpand


Implement Sorting

ExpressQuantumTreeList4 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;


Importing ExpressQuantumTreeList3
Importing the ExpressQuantumTreeList3

At design time, ExpressQuantumTreeList4 provides an Import dialog for importing settings from ExpressQuantumTreeList3 controls and converting them to the native properties of ExpressQuantumTreeList4.

To invoke the Import dialog, right-click the import target TcxTreeList control and select the Import… option from the context menu.  The panel located to the left of the dialog lists all the supported TreeList components found in the current form.

The easiest way to perform the conversion is to double-click the source TreeList in this list or select the source TreeList and click the Import button.

To show the Options panel to the right of the Import dialog, click the Options >> button.  This panel provides the Styles page that allows you to alter the import process.

The ExpressQuantumTreeList4’s appearance is maintained by a number of style properties.  Usually, you create style objects (TcxStyle) via a style repository and assign them to style properties thus specifying the look & feel of the required elements.  The converter will do this for you.  It converts color and font attributes to style objects while adding them to the style repository.  Styles are assigned to the corresponding style properties of the target TreeList control.  Styles are not created for font and color attributes, which are set to default values.

Importing styles is optional.  You can disable importing styles by deselecting the Import Styles check box.  In this case, only the properties affecting data representation are imported.

By default, the import of styles is enabled.  You can choose between creating styles either within a new style repository or within an existing one.  Selecting the Create New StyleRepository option enables the edit box.  Use it to specify the name of a new style repository.  The Use Existing StyleRepository option is a combo-box listing all style repositories that can be found on the form.

You can refer to the tutorials shipped with ExpressQuantumTreeList4 for step-by-step instructions on how to work with the Import dialog.


Obtain And Set Cell Values
Obtaining And Setting Cell Values

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:

•	the column’s Options.Editing property specifies whether a user can edit its cells (provided that any cell can be edited, see OptionsData.Editing)

•	the column’s Options.Focusing enables/disables focusing its cells

•	the control’s OptionsData.Editing enables/disables editing all columns within this TreeList control

•	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.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';

cxDBTreeList1.DataController.Post;

// C++ Builder

cxDBTreeList1->DataController->Edit();

cxDBTreeList1->FocusedNode->Values[col1.ItemIndex] := 'New Value';

cxDBTreeList1->DataController->Post();


Setting The cxTreeList Appearance

The TreeList control provides several ways to modify its appearance.

Look And Feel

Changes the look & feel of the entire TreeList control.

Styles

Affects the appearance of the TreeList elements that support the Styles technology.

Custom Draw

Can change the appearance of many of the TreeList elements.

Let’s explore each option in detail.

Look And Feel

ExpressQuantumTreeList4 has a LookAndFeel property, which provides 3 options:

1.	Standard

2.	Flat

3.	UltraFlat

You can switch between them via the TcxLookAndFeel.Kind property.

Implement the following code 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 operating system, you can make your TreeList look like a Windows XP native control.  Just set the TcxLookAndFeel.NativeStyle property to True.

Implement the following code to make the TreeList control look like a Windows XP native control:

cxTreeList1.LookAndFeel.NativeStyle := True;

Note: The NativeStyle property has a higher priority than the Kind property.  Thus, if the NativeStyle property is set, the Kind property has no effect.

Styles

Styles allow you to customize the appearance of particular TreeList elements such as bands and columns, etc. A style affects the element’s background, font and text color.  Some styles have events that occur when a style is about to change.  You can write code in these event handlers to implement conditional style changes etc.

The following code sets different styles for different group rows:

//Delphi

var

  cxMyStyle1, cxMyStyle2: TcxStyle;

  //...

  //Put the following code into the form’s constructor

  cxMyStyle1 := TcxStyle.Create(Self);

  cxMyStyle1.Color := $0042D7FF;

  cxMyStyle2 := TcxStyle.Create(Self);

  cxMyStyle2.Color := $0073E1FF;

procedure TForm1.TreeListStylesGetContentStyle(Sender, AItem: TObject;

  ANode: TcxTreeListNode; var AStyle: TcxStyle);

begin

  if ANode.AbsoluteIndex mod 2 = 0 then

    AStyle := cxMyStyle1

  else AStyle := cxMyStyle2;

end;

//C++ Builder

  TcxStyle *cxMyStyle1, *cxMyStyle2;

  //...

  //Put the following code into the form’s constructor

  cxMyStyle1 = new TcxStyle(this);

  cxMyStyle1->Color = 0x0042D7FF;

  cxMyStyle2 = new TcxStyle(this);

  cxMyStyle2->Color = 0x0073E1FF;

void __fastcall TForm1:: TreeListStylesGetContentStyle (

      TObject *Sender, AItem, TcxTreeListNode * ANode, TcxStyle *AStyle) {

  if (ANode->AbsoluteIndex % 2 == 0)

    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 technology.  Every customizable TreeList element provides a set 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 view info;

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 explanation though.  Generally, the TcxCanvas class (passed by the 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 element’s bounding rectangle manually. However, the AViewInfo parameter contains a Bounds property representing the current element’s bounding rectangle.

Implement the code below to draw an image as a cell background.

//Delphi

procedure TForm1.TreeListCustomDrawCell (Sender: TObject;

  ACanvas: TcxCanvas; AViewInfo: TcxTreeListEditCellViewInfo;

  var ADone: Boolean);

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

void __fastcall TForm1::TreeListCustomDrawCell(

      TObject *Sender, TcxCanvas *ACanvas,

      TcxTreeListEditCellViewInfo *AViewInfo, bool &ADone)

{

  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;

}

The result of the above code is shown in the image below:


Unbound Mode

Although at the first look there is not a big difference working with nodes for ExpressQuantumTreeList4 and ExpressQuantumTreeList3 and most of the methods that you were using in the previous version will work correctly in the version 4. Internally, however, we have made dramatic changes. First of all, ExpressQuantumTreeList4 uses the Express DataController to work with data unlike previous versions used string collections. The code update achieves two tasks: a small memory footprint and fast access to the data.

There are some other improvements. For example, in the previous version it was hard to work with cell values with types other than string. Now you can use the DataBinding.ValueType property to specify the type of data displayed within a column. The default data type is string.  If you are using different types of data in one column, you can set DataBinding.ValueType property to Variant.

Let’s explore an example from the ExpressQuantumTreeList4 web demo, module Bands.  In this demo, a TreeList control is populated in unbound mode with data relating to corporate offices.

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.  You can refer to the Create And Delete Columns topic for details.

If a TreeList is not connected to a data source, columns need to be created manually.  Additionally, you must set the appropriate data type for each column.  Use the DataBinding.ValueTypeClass property for this purpose.  See the TcxValueType class topic for the types available.  The following code 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 cell.  It requires a column index to be supplied. However on initialization you may use the node’s 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 using the AssignValues method.

//Delphi

procedure TForm1.InitData;

   function AddNode(AParent: TcxTreeListNode; const AValues: Array of Variant; AImageIndex: Integer): TcxTreeListNode;

   begin

     Result := TreeList.AddChild(AParent);

     Result.AssignValues(AValues);

     Result.Imageindex := AImageIndex;

     Result.Values[]

   end;

var

  ARootNode, ASalesMarketingNode: TcxTreeListNode;

begin

  ARootNode := AddNode(nil, ['Corporate Headquarters', 1000000, 'Monterey', '(408) 555-1234', '(408) 555-1234'], 8);

  ASalesMarketingNode := AddNode(ARootNode, ['Sales and Marketing', 22000, 'San Francisco', '(415) 555-1234', '(415) 555-1234'], 1);

  AddNode(ASalesMarketingNode, ['Field Office: Canada', 500000, 'Toronto', '(416) 677-1000', '(416) 555-1234'], 4);

  AddNode(ASalesMarketingNode, ['Field Office: East Coast', 500000, 'Boston', '(617) 555-1234', '(415) 555-1234'], 4);

end;

When executing this code, the TreeList control will display four nodes as follows:


Introduction To Provider Mode


Using Virtual cxTreeList

ExpressQuantumTreeList4 uses the ExpressDataController to work with data.  The DataController object manages the TreeList connection to a TDataSet or to its descendants.  If you need to populate the TreeList control with data from a custom data source, you should use a cxVirtualTreeList control.  The virtual TreeList control uses the ExpressDataController’s provider mode.

Implementing provider mode for ExpressQuantumTreeList4 implies writing a custom data source class by overriding the TcxTreeListCustomDataSource class.  This custom data source must provide a self-referenced relationship between records (nodes).  When creating a custom data source, usually you only need to override the methods responsible for getting/setting data and for item (column) identification.

Let’s review the code that we are using in the ExpressQuantumTreeList4 web demo, module Provider Mode.  In that demo, the TreeList displays more than one million nodes within 3 columns.  Users are able to modify the node values.  Values are calculated on the fly, however the list of modified nodes is kept in memory.  Adding and deleting nodes is not implemented to keep the code as simple as possible.  At design time we have dropped a TcxVirtualTreeList on a form.  Now we create 3 columns with the following data types: Integer, String and DateTime.

type

  // the class where we store data for modified records

  TcxProviderDataSourceRecord = class

    Key: Integer;  // a key value

    Id: Integer;

    Text: string;

    Date: TDateTime;

  end;

  // a custom data source class

  TcxProviderDataSource = class(TcxTreeListCustomDataSource)

  private

    FValueList: TList; // the list of TcxProviderDataSourceRecord objects, representing modified nodes

    FTreeList: TcxVirtualTreeList; // the link to a virtual treelist

  // returns the default value of the node cell. It is calculated on the fly

    function GetDefaultValue(ARecordHandle: TcxDataRecordHandle; AItemIndex: Integer): Variant;

  // returns the column index in the data controller by the treelist column handle

    function GetItemIndex(AItemHandle: TcxDataItemHandle): Integer;

   //returns the stored data for modified nodes. Returns null if a node has  not been changed

    function GetProviderDataSourceRecord(Key: Integer): TcxProviderDataSourceRecord;

  protected

    //returns the level where a specific record is located

    function GetLevel(ARecordHandle: TcxDataRecordHandle): Integer;

    // returns the number of nodes in the TreeList control. Since we use smart record load, it returns 0

    function GetRecordCount: Integer; override;

    // returns the value for a node cell

    function GetValue(ARecordHandle: TcxDataRecordHandle;

      AItemHandle: TcxDataItemHandle): Variant; override;

   // set the value for a node cell

    procedure SetValue(ARecordHandle: TcxDataRecordHandle;

      AItemHandle: TcxDataItemHandle; const AValue: Variant); override;

  protected

    // returns the key value for the node

    function GetKeyValue(ARecordHandle: TcxDataRecordHandle): Variant; override;

   // returns the parent key value for the node

    function GetParentKeyValue(ARecordHandle: TcxDataRecordHandle): Variant; override;

   //returns the child nodes count for the node

    function GetChildCount(AParentHandle: TcxDataRecordHandle): Integer; override;

   //returns the child node handle by the parent node and the child node index

    function GetChildRecordHandle(AParentHandle: TcxDataRecordHandle;

      AChildIndex: Integer): TcxDataRecordHandle; override;

  public

    constructor Create(ATreeList: TcxVirtualTreeList);

    destructor Destroy; override;

  end;

  TfrmTreeListProvider = class(TForm)

    TreeList: TcxVirtualTreeList;

    clnId: TcxTreeListColumn;

    clnName: TcxTreeListColumn;

    clnDate: TcxTreeListColumn;

  public

    constructor Create(AOwner: TComponent); override;

    destructor Destroy; override;

  end;

implementation

{$R *.dfm}

const

  // the number of levels

  ProviderLevelCount = 3;

  // the number of nodes in the level

  ProviderRecordCountPerLevel = 100;

{ TcxProviderDataSource }

// a custom data source contructor

constructor TcxProviderDataSource.Create(ATreeList: TcxVirtualTreeList);

begin

  FTreeList := ATreeList;

  // create a modified node storage

  FValueList := TList.Create;

end;

destructor TcxProviderDataSource.Destroy;

var

  I: Integer;

begin

  // clear and destroy the modified node storage

  for I := 0 to FValueList.Count - 1 do

    TcxProviderDataSourceRecord(FValueList[I]).Free;

  FValueList.Free;

  inherited Destroy;

end;

function TcxProviderDataSource.GetKeyValue(

  ARecordHandle: TcxDataRecordHandle): Variant;

begin

  // RecordHandle and KeyValue are the same

  Result := Integer(ARecordHandle);

end;

// The largest method in the unit. There are 3 levels and 100 nodes in every level.

// Thus the total node count is 100 + 10,000 +  1,000,000 = 1,100,100.

function TcxProviderDataSource.GetParentKeyValue(

  ARecordHandle: TcxDataRecordHandle): Variant;

var

  ALevel, ALevelCount, APrevLevelCount, APrevPrevLevelCount: Integer;

begin

  Result := Integer(ARecordHandle);

  if Result < ProviderRecordCountPerLevel then

  begin

    Result := -1;

    exit;

  end;

  ALevelCount := ProviderRecordCountPerLevel;

  APrevPrevLevelCount := 0;

  for ALevel := 1 to ProviderLevelCount do

  begin

    APrevLevelCount := ALevelCount;

    ALevelCount := ALevelCount * ProviderRecordCountPerLevel + ALevelCount;

    if (ALevel > 1) then

      APrevPrevLevelCount := (ALevel - 1) * ProviderRecordCountPerLevel;

      if (Result <= ALevelCount) then

    begin

      Result := (Result - APrevLevelCount - 1) div ProviderRecordCountPerLevel + APrevPrevLevelCount;

      exit;

    end;

  end;

end;

function TcxProviderDataSource.GetChildCount(

  AParentHandle: TcxDataRecordHandle): Integer;

begin

  // if the last level – returns no children, otherwise returns 100

  if GetLevel(AParentHandle) = ProviderLevelCount then

    Result := 0

  else

    Result := ProviderRecordCountPerLevel;

end;

// makes the callback calculation for the GetParentKeyValue method to get the correct child record handle

function TcxProviderDataSource.GetChildRecordHandle(

  AParentHandle: TcxDataRecordHandle; AChildIndex: Integer): TcxDataRecordHandle;

var

  AParentId, ARes, ARemain, I: Integer;

begin

  AParentId := Integer(AParentHandle);

  if AParentId < 0 then

  begin

    Integer(Result) := AChildIndex + 1;

    exit;

  end;

  ARes := 0;

  I := 1;

  repeat

    ARes := ARes  + Round(Power(ProviderRecordCountPerLevel, I));

    ARemain := ARes;

    Inc(I);

  until ARes >= AParentId;

  ARes := ARes + AParentId * ProviderRecordCountPerLevel - ARemain;

  Integer(Result) := ARes + AChildIndex + 1;

end;

// based on the record handle / key value returns the node level

function TcxProviderDataSource.GetLevel(ARecordHandle: TcxDataRecordHandle): Integer;

var

  I: Integer;

begin

  Result := -1;

  I := 1;

  while Integer(ARecordHandle) > 0 do

  begin

    Integer(ARecordHandle) := Integer(ARecordHandle) - Round(Power(ProviderRecordCountPerLevel, I));

    Inc(I);

    Inc(Result);

  end;

end;

// say that we do not know about the record count, so a virtual treelist uses smart record load

// and does not build a tree for all nodes at once

function TcxProviderDataSource.GetRecordCount: Integer;

begin

  Result := 0;

end;

function TcxProviderDataSource.GetValue(ARecordHandle: TcxDataRecordHandle;

  AItemHandle: TcxDataItemHandle): Variant;

var

  ARecord: TcxProviderDataSourceRecord;

begin

  // check if the node has been modified

  ARecord := GetProviderDataSourceRecord(Integer(ARecordHandle));

  // if ARecord is not null, then the node has been modified and we have to take data from the storage

  if ARecord <> nil then

  begin

    case GetItemIndex(AItemHandle) of

      0: Result := ARecord.Id;

      1: Result := ARecord.Text;

      2: Result := ARecord.Date;

    end;

   // return the data calculated on the fly

  end else Result := GetDefaultValue(ARecordHandle, GetItemIndex(AItemHandle));

end;

function TcxProviderDataSource.GetDefaultValue(ARecordHandle: TcxDataRecordHandle;

  AItemIndex: Integer): Variant;

var

  AIndex: Integer;

begin

  // calculate data on the fly

  AIndex := Integer(ARecordHandle);

  case AItemIndex of

    0: Result := AIndex;

    1: Result := 'Text' + IntToStr(AIndex);

    2: Result := Now + AIndex * 0.001;

  end;

end;

procedure TcxProviderDataSource.SetValue(ARecordHandle: TcxDataRecordHandle;

  AItemHandle: TcxDataItemHandle; const AValue: Variant);

var

  ARecord: TcxProviderDataSourceRecord;

begin

  ARecord := GetProviderDataSourceRecord(Integer(ARecordHandle));

  // if the node has not been modified before, then create a storage class for it

  if ARecord = nil then

  begin

    ARecord := TcxProviderDataSourceRecord.Create;

    FValueList.Add(ARecord);

    ARecord.Key := Integer(ARecordHandle);

    ARecord.Id := GetDefaultValue(ARecordHandle, 0);

    ARecord.Text := GetDefaultValue(ARecordHandle, 1);

    ARecord.Date := GetDefaultValue(ARecordHandle, 2);

  end;

  // set a value for the storage class

  case GetItemIndex(AItemHandle) of

    0: ARecord.Id := AValue;

    1: ARecord.Text := AValue;

    2: ARecord.Date := AValue;

  end;

end;

// returns the column index in the data controller by the treelist column handle

function TcxProviderDataSource.GetItemIndex(AItemHandle: TcxDataItemHandle): Integer;

begin

  Result := FTreeList.Columns[Integer(AItemHandle)].ItemIndex;

end;

//returns the stored data for modified nodes. Returns null if the node has not been changed

function TcxProviderDataSource.GetProviderDataSourceRecord(Key: Integer): TcxProviderDataSourceRecord;

var

  I: Integer;

begin

  Result := nil;

  for I := 0 to FValueList.Count - 1 do

    if TcxProviderDataSourceRecord(FValueList[I]).Key = Key then

    begin

      Result := TcxProviderDataSourceRecord(FValueList[I]);

      break;

    end;

end;

{ TfrmTreeListProvider }

constructor TfrmTreeListProvider.Create(AOwner: TComponent);

begin

  inherited Create(AOwner);

  // enable smart record load

  TreeList.OptionsData.SmartLoad := True;

  // create a custom data source

  TreeList.DataController.CustomDataSource := TcxProviderDataSource.Create(TreeList);

end;

destructor TfrmTreeListProvider.Destroy;

begin

  // destroy the custom data source

  TreeList.DataController.CustomDataSource.Free;

  inherited Destroy;

end;


Using Lookup Column
Using a Lookup Column

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 ExpressQuantumTreeList4 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:

//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:


Selecting Nodes

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.Nodes.Count - 1 do

    cxTreeList1.Nodes.Items[I].Selected := cxTreeList1.Nodes.Items[I].AbsoluteIndex mod 2 = 0;

end;

// C++ Builder {

  for (int i = 0; i < cxTreeList1.Nodes.Count; i++)

    cxTreeList1->Nodes->Items[I]->Selected = cxTreeList1->Nodes->Items[I]->AbsoluteIndex % 2 == 0;

}

Use the SelectAll method to select all nodes in the TreeList control:

// Delphi

cxTreeList1.SelectAll;

// C++ Builder

cxTreeList1->SelectAll();


Classes

TcxTreeListOptionsBehavior

TcxTreeListOptionsCustomizing

TcxTreeListOptionsData

TcxTreeListOptionsSelection

TcxTreeListOptionsView

TcxTreeListPreview


TcxTreeListOptionsBehavior
TcxTreeListOptionsBehavior Object

Hierarchy          Properties

Contains options determining the TreeList control’s response to user actions.

Unit

cxTL

TcxTreeListOptionsBehavior = class(TcxControlOptionsBehavior)

Description

The TcxTreeListOptionsBehavior object contains settings determining the TreeList control’s response to keyboard and mouse events.  Its properties determine the TreeList’s reaction to incremental searching, whether its cell editors are always active, whether focus can be moved using the Tab and Enter keys, etc.

Use the OptionsBehavior property to access this set of options.


TcxTreeListOptionsBehavior Hierarchy
Hierarchy

TPersistent

     |

TcxOwnedPersistent

     |

TcxControlOptionsBehavior

     |


Properties for TcxTreeListOptionsBehavior
TcxTreeListOptionsBehavior Properties

TcxTreeListOptionsBehavior          Legend

In TcxTreeListOptionsBehavior

AutoDragCopy

AutomateLeftMostIndent

ConfirmDelete

DragCollapse

DragExpand

ExpandOnDblClick

ExpandOnIncSearch

HotTrack

MultiSort

ShowHourGlass

Sorting

WaitForExpandNodeTime

Derived from TcxControlOptionsBehavior

AlwaysShowEditor

CellHints

DragDropText

FocusCellOnCycle

FocusFirstCellOnNewRecord

GoToNextCellOnEnter

GoToNextCellOnTab

ImmediateEditor

IncSearch

IncSearchItem


TcxTreeListOptionsBehavior.AutoDragCopy

TcxTreeListOptionsBehavior          See Also

Determines whether TreeList nodes are copied during drag-and-drop operations.

property AutoDragCopy: Boolean;

Description

If the AutoDragCopy property value is True, TreeList nodes can be copied during drag-and-drop operations.  Copying nodes is implemented by dragging them with the Ctrl key pressed.

The default value of the AutoDragCopy property is False.


TcxTreeListOptionsBehavior.AutomateLeftMostIndent

TcxTreeListOptionsBehavior

Determines whether the column width is restored when collapsing nodes.

property AutomateLeftMostIndent: Boolean;

Description

When the left-most column width is not enough to fit expanded nodes’ indents, it is enlarged to match the increasing indent width.  If the AutomateLeftMostIndent property is True, the left-most column width is decreased when collapsing nodes.

The default value of the AutomateLeftMostIndent property is True.


TcxTreeListOptionsBehavior.ConfirmDelete

TcxTreeListOptionsBehavior          See Also

Specifies whether the confirmation dialog is displayed when a user deletes a node.

property ConfirmDelete: Boolean;

Description

A user can delete TreeList nodes at runtime by pressing the Ctrl + Del key combination.  If the ConfirmDelete option is active, the confirmation dialog is displayed before deleting a node:

The default value of the ConfirmDelete property is True.


TcxTreeListOptionsBehavior.DragCollapse

TcxTreeListOptionsBehavior

Determines whether expanded nodes are collapsed during drag-and-drop operations.

property DragCollapse: Boolean;

Description

The DragCollapse option determines whether expanded nodes are collapsed during drag-and-drop operations.  If this property value is True, the expanded node is collapsed when the mouse pointer is positioned over the node’s expand button.

The delay between positioning the mouse pointer and collapsing a node is specified via the WaitForExpandNodeTime property.

The default value of the DragCollapse property is True.


TcxTreeListOptionsBehavior.DragExpand

TcxTreeListOptionsBehavior          See Also

Determines whether collapsed nodes are expanded during drag-and-drop operations.

property DragExpand: Boolean;

Description

The DragExpand option determines whether collapsed nodes are expanded during drag-and-drop operations.  If this property value is True, the collapsed node is expanded when the mouse pointer is positioned over the node’s expand button.

The delay between positioning the mouse pointer and expandig a node is specified via the WaitForExpandNodeTime property.

The default value of the DragExpand property is True.


TcxTreeListOptionsBehavior.ExpandOnDblClick

TcxTreeListOptionsBehavior

Specifies whether nodes in the treelist control are expanded or collapsed when the user double-clicks them.

property ExpandOnDblClick: Boolean;

Description

If the ExpandOnDblClick property is set to True a collapsed node is expanded or an expanded node is collapsed when the user double-clicks it. Otherwise no actions are performed if the user double-clicks the node.

The default value of the ExpandOnDblClick property is True.


TcxTreeListOptionsBehavior.ExpandOnIncSearch

TcxTreeListOptionsBehavior          See Also

Determines whether collapsed nodes are expanded during the incremental search.

property ExpandOnIncSearch: Boolean;

Description

The cxTreeList control supports the incremental search feature.  It is enabled by the IncSearch option.  If the ExpandOnIncSearch option is enabled, collapsed nodes are expanded to locate the required node.  Otherwise, the search is performed by expanded nodes only.

The default value of the ExpandOnIncSearch property is False.


TcxTreeListOptionsBehavior.HotTrack

TcxTreeListOptionsBehavior

Determines whether the nodes can be hottracked.

property HotTrack: Boolean;

Description

Use the HotTrack option to specify whether the TreeList nodes can be hottracked.  The hottracked node appearance changes when the mouse pointer passes over that node at runtime.

You can handle the TreeList.OnHotTrackNode event to respond to nodes hottracking at runtime.

The default value of the HotTrack property is False.


TcxTreeListOptionsBehavior.MultiSort

TcxTreeListOptionsBehavior          See Also

Determines whether the end user can sort the TreeList control against multiple columns.

property MultiSort: Boolean;

Description

The cxTreeList control supports sorting against multiple columns.  If the MultiSort option is active, the multi sort feature is available to the end-user at runtime.  Otherwise, the cxTreeList control can only be sorted against a single column.

Note that sorting can be applied to any number of columns using code, regardless of the MultiSort property value.

The default value of the MultiSort property is True.


TcxTreeListOptionsBehavior.ShowHourGlass

TcxTreeListOptionsBehavior

Specifies whether the hourglass cursor is displayed when performing long operations.

property ShowHourGlass: Boolean;

Description

If the ShowHourGlass option is activated, the hourglass cursor is displayed while the cxTreeList control performs long operations, for instance, sorting by large datasets.

The default value of the ShowHourGlass property is True.


TcxTreeListOptionsBehavior.Sorting

TcxTreeListOptionsBehavior          See Also

Specifies whether the end-user is able to sort cxTreeList data.

property Sorting: Boolean;

Description

The cxTreeList control supports sorting against multiple columns.  If the Sorting property value is False, the end user cannot sort cxTreeList data by clicking column headers.

Note that sorting can be applied to any number of columns by code, regardless of the Sorting property value.

The default value of the Sorting property is True.


TcxTreeListOptionsBehavior.WaitForExpandNodeTime

TcxTreeListOptionsBehavior          See Also

Specifies the delay (in milliseconds) before collapsing/expanding nodes during drag-and-drop operations.

property WaitForExpandNodeTime: Integer;

Description

Use the WaitForExpandNodeTime property to specify the delay (in milliseconds) before collapsing/expanding nodes during drag-and-drop operations.  This property is in effect if the DragExpand or the DragCollapse option is active.   The node’s state is inverted if its expand button is located under the mouse pointer during the drag-and-drop operation.

The default value of the WaitForExpandNodeTime property is cxTreeListDefWaitExpandTime.


TcxTreeListOptionsCustomizing
TcxTreeListOptionsCustomizing Object

Hierarchy          Properties

Contains settings determining whether a user can customize the TreeList control by modifying its columns and bands at runtime.

Unit

cxTL

TcxTreeListOptionsCustomizing = class(TcxOwnedPersistent)

Description

The end user can customize the TreeList control by modifying its columns and bands at runtime.  Bands and columns can be resized and moved.  This can be performed by code as well.  The properties of the TcxTreeListOptionsCustomize object control the availability of column and band features to end users.

Note: the TcxTreeListOptionsCustomize options settings can be overridden by code.  For instance, if column resizing is disabled (the ColumnHorzSizing property value is False), the column width can be changed via the Column.Width property value.

Use the OptionsCustomizing property to access this set of options.


TcxTreeListOptionsCustomizing Hierarchy
Hierarchy

TPersistent

     |

TcxOwnedPersistent

     |


Properties for TcxTreeListOptionsCustomizing
TcxTreeListOptionsCustomizing Properties

TcxTreeListOptionsCustomizing          Legend

In TcxTreeListOptionsCustomizing

BandCustomizing

BandHorzSizing

BandMoving

BandVertSizing

ColumnCustomizing

ColumnHorzSizing

ColumnMoving

ColumnSorting

ColumnVertSizing

DynamicSizing


TcxTreeListOptionsCustomizing.BandCustomizing

TcxTreeListOptionsCustomizing          See Also

Determines the manner in which TreeList bands can be customized by the end user.

property BandCustomizing: Boolean;

Description

When the BandCustomizing option is active, the end user can remove bands from the TreeList control even when the customization form is not visible.  Click and drag the required band header away from the bands region.

If this property is set to False, bands cannot be removed from the TreeList control unless the customization form is visible.

The default value of the BandCustomizing property is True.


TcxTreeListOptionsCustomizing.BandHorzSizing

TcxTreeListOptionsCustomizing          See Also

Determines whether TreeList bands can be resized by dragging their edges.

property BandHorzSizing: Boolean;

Description

The BandHorzSizing option determines whether TreeList bands can be resized by dragging their edges.  If this option is activated, the end user is able to resize bands.  If the BandHorzSizing property value is False, the band width can only be changed via the Band.Width property.

The default value of the BandHorzSizing property is True.


TcxTreeListOptionsCustomizing.BandMoving

TcxTreeListOptionsCustomizing          See Also

Determines whether bands can be moved within the TreeList control.

property BandMoving: Boolean;

Description

The BandMoving property determines whether bands can be moved within the TreeList control.  If this property value is True, the end user can move bands within the control by clicking and dragging the band header to the required position.

The default value of the BandMoving property is True.


TcxTreeListOptionsCustomizing.BandVertSizing

TcxTreeListOptionsCustomizing          See Also

Determines whether the band height can be changed by the end user.

property BandVertSizing: Boolean;

Description

The BandVertSizing property determines whether the band height can be changed by the end user.  If this property value is True, the band height can be changed by clicking and dragging the band’s bottom edge.  If this property value is False, use the OptionsView.BandLineCount property to modify the height.

The default value of the BandVertSizing property is True.


TcxTreeListOptionsCustomizing.ColumnCustomizing

TcxTreeListOptionsCustomizing          See Also

Determines the manner in which TreeList columns can be customized by the end user.

property ColumnCustomizing: Boolean;

Description

When the ColumnCustomizing option is active, the end user can remove columns from the TreeList control even when the customization form is not visible.  Click and drag the required column header away from the column panel.

If this property is set to False, columns cannot be removed from the TreeList control when the customization form is not visible.

The default value of the ColumnCustomizing property is True.


TcxTreeListOptionsCustomizing.ColumnHorzSizing

TcxTreeListOptionsCustomizing          See Also

Determines whether TreeList columns can be resized by dragging their edges.

property ColumnHorzSizing: Boolean;

Description

The ColumnHorzSizing option determines whether TreeList columns can be resized by dragging their edges.  If this option is activated, the end user is able to resize TreeList columns.  If the ColumnHorzSizing property value is False, the column width can only be changed via the Column.Width property.

The default value of the ColumnHorzSizing property is True.


TcxTreeListOptionsCustomizing.ColumnMoving

TcxTreeListOptionsCustomizing          See Also

Determines whether columns can be moved within the TreeList control.

property ColumnMoving: Boolean;

Description

The ColumnMoving property determines whether columns can be moved within the TreeList control.  If this property value is True, the end user can move columns by clicking and dragging the column header to the required position.

The default value of the ColumnMoving property is True.


TcxTreeListOptionsCustomizing.ColumnSorting

TcxTreeListOptionsCustomizing

Specifies whether the end user can sort the TreeList control.

property ColumnSorting: Boolean;

Description

If the ColumnSorting property is True, the end user can sort the TreeList control by clicking column headers.  If the ColumnSorting property is False, sorting is disabled for the TreeList control.

Note that sorting can be implemented regardless of the ColumnSorting option’s state by using the Column.SortOrder property.

The default value of the ColumnSorting property is True.


TcxTreeListOptionsCustomizing.ColumnVertSizing

TcxTreeListOptionsCustomizing          See Also

Determines whether the column height can be changed by the end user.

property ColumnVertSizing: Boolean;

Description

The ColumnVertSizing property determines whether the column height can be changed by the end user.  If this property value is True, the column height can be changed by clicking and dragging the column’s bottom edge.  If this property value is False, use the OptionsView.CellTextMaxLineCount property to specify the maximum number of text lines for columns.

The default value of the ColumnVertSizing property is True.


TcxTreeListOptionsCustomizing.DynamicSizing

TcxTreeListOptionsCustomizing          See Also

Determines whether column and band sizes are updated immediately.

property DynamicSizing: Boolean;

Description

By default, when the end user resizes a column or a band, the element size is updated after releasing the left mouse button.  If the DynamicSizing property is set to True, sizes ares updated while sizing.

The default value of the DynamicSizing property is False.


TcxTreeListOptionsData
TcxTreeListOptionsData Object

Hierarchy          Properties

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

Unit

cxTL

TcxTreeListOptionsData = class(TcxControlOptionsData)

Description

The properties of the TcxTreeListOptionsData object are used to determine which actions can be performed by the TreeList dataset (inserting, editing and deleting records).

Use the OptionsData property to access this set of options.


TcxTreeListOptionsData Hierarchy
Hierarchy

TPersistent

     |

TcxOwnedPersistent

     |

TcxControlOptionsData

     |


Properties for TcxTreeListOptionsData
TcxTreeListOptionsData Properties

TcxTreeListOptionsData          Legend

In TcxTreeListOptionsData

Deleting

Inserting

SummaryNullIgnore

Derived from TcxControlOptionsData

CancelOnExit

Editing


TcxTreeListOptionsData.Deleting

TcxTreeListOptionsData

Determines whether the end user can delete nodes within the cxTreeList control.

property Deleting: Boolean;

Description

If the Deleting property value is True, the end user can delete nodes within the cxTreeList control by pressing the Ctrl+Del key combination.

The default value of the Deleting property is False.


TcxTreeListOptionsData.Inserting

TcxTreeListOptionsData

Determines whether the end user can insert nodes into the cxTreeList control.

property Inserting: Boolean;

Description

If the Inseting property is set to True, the end user can insert nodes into the cxTreeList control by pressing the Insert key.

The default value of the Inserting property is False.


TcxTreeListOptionsData.SummaryNullIgnore

TcxTreeListOptionsData

Specifies whether NULL values are ignored during summary calculations.

property SummaryNullIgnore: Boolean;

Description

Use the SummaryNullIgnore property to determine whether NULL values are ignored during summary calculations.

The default value of the SummaryNullIgnore property is False.


TcxTreeListOptionsSelection
TcxTreeListOptionsSelection Object

Hierarchy          Properties

Contains selection settings for the TreeList control.

Unit

cxTL

TcxTreeListOptionsSelection = class(TcxOwnedPersistent)

Description

The properties of the TcxTreeListOptionsSelection object determine selection options for the TreeList control.  Its properties indicate whether to select individual cells or the whole node, whether the focus rectangle is displayed around the focused node and whether multiple nodes can be selected, etc.

Use the OptionsSelection property to access this set of options.


TcxTreeListOptionsSelection Hierarchy
Hierarchy

TPersistent

     |

TcxOwnedPersistent

     |


Properties for TcxTreeListOptionsSelection
TcxTreeListOptionsSelection Properties

TcxTreeListOptionsSelection          Legend

In TcxTreeListOptionsSelection

CellSelect

HideFocusRect

HideSelection

InvertSelect

MultiSelect


TcxTreeListOptionsSelection.CellSelect

TcxTreeListOptionsSelection

Determines whether individual cells are selected instead of whole nodes.

property CellSelect: Boolean;

Description

Use the CellSelect property to determine whether individual cells are selected instead of whole nodes.  Setting this property to False disables editing within the TreeList control.

The default value of the CellSelect property is True.


TcxTreeListOptionsSelection.HideFocusRect

TcxTreeListOptionsSelection

Determines whether a focus rectangle is displayed around the focused node within the TreeList control.

property HideFocusRect: Boolean;

Description

Use the HideFocusRect property to specify the focus rectangle visibility within the TreeList control.  If this property value is False, the focused node is not highlighted but the focus rectangle is displayed around it.

The default value of the HideFocusRect property is True.


TcxTreeListOptionsSelection.HideSelection

TcxTreeListOptionsSelection

Specifies how selected nodes are displayed when focus leaves the cxTreeList control.

property HideSelection: Boolean;

Description

Use the HideSelection property to specify how selected nodes are displayed when focus leaves the TreeList control.  If this property value is True, selected nodes look like other nodes.  Otherwise, selected nodes are highlighted within the TreeList control.

The default value of the HideSelection property is False.


TcxTreeListOptionsSelection.InvertSelect

TcxTreeListOptionsSelection

Determines whether the focused cell is highlighted instead of the whole node.

property InvertSelect: Boolean;

Description

Use the InvertSelect property to specify the manner in which the selection appears within the TreeList control.  If this property value is True, only the focused cell is highlighted.  Otherwise, the node containing the focused cell is highlighted.

InvertSelect is True	InvertSelect is False

The default value of the InvertSelect property is True.


TcxTreeListOptionsSelection.MultiSelect

TcxTreeListOptionsSelection          Example

Determines whether multiple nodes can be selected within the cxTreeList control.

property MultiSelect: Boolean;

Description

Use the MultiSelect property to enable multiple selections within the cxTreeList control.  The end user can select multiple nodes that are not located contiguously within the control by navigating with the Ctrl key pressed.  To select a range of nodes, click them with the Shift key pressed.  Multiple selections can be implemented both via the keyboard and the mouse.

The following screenshot demonstrates the TreeList control with several selected records:

The default value of the MultiSelect property is False.


TcxTreeListOptionsView
TcxTreeListOptionsView Object

Hierarchy          Properties

Contains the cxTreeList control’s appearance options.

Unit

cxTL

TcxTreeListOptionsView = class(TcxControlOptionsView)

Description

The properties of the TcxTreeListOptionsView object specify the TreeList’s appearance options.  Its properties specify the visibility, color and dimensions of control elements.  Some appearance options affect the control’s behavior.  For instance, if the Headers option is deactivated, column sorting is not available to the end user.

Use the OptionsView property to access this set of options.


TcxTreeListOptionsView Hierarchy
Hierarchy

TPersistent

     |

TcxOwnedPersistent

     |

TcxControlOptionsView

     |


Properties for TcxTreeListOptionsView
TcxTreeListOptionsView Properties

TcxTreeListOptionsView          Legend

In TcxTreeListOptionsView

BandLineCount

Bands

Buttons

CategorizedColumn

ColumnAutoWidth

DropArrowColor

FixedSeparatorColor

FixedSeparatorWidth

Footer

GridLineColor

GridLines

Headers

Indicator

IndicatorWidth

PaintStyle

ShowRoot

SimpleCustomizeBox

TreeLineColor

TreeLineStyle

UseImageIndexForSelected

UseNodeColorForIndent

Derived from TcxControlOptionsView

CellAutoHeight

CellEndEllipsis

CellTextMaxLineCount

ScrollBars

ShowEditButtons


TcxTreeListOptionsView.BandLineCount

TcxTreeListOptionsView          See Also

Specifies the height of the band’s headers panel (in text lines).

property BandLineCount: Integer;

Description

Use the BandLineCount property to specify the height of the band’s headers panel in text lines.

The BandLineCount property value is 1	The BandLineCount property value is 3

The default value of the BandLineCount property is cxTreeListDefBandHeaderLineCount.


TcxTreeListOptionsView.Bands

TcxTreeListOptionsView

Specifies the band’s headers visibility within the TreeList control.

property Bands: Boolean;

Description

Use the Bands property to specify the band’s headers visibility within the TreeList control.  If this property value is False, bands are not visible.  In this case, the columns arrangement remains the same as if the band headers were visible within the control.

The Bands property is set to True	The Bands property is set to False

The default value of the Bands property is cxTreeListDefBands.


TcxTreeListOptionsView.Buttons

TcxTreeListOptionsView

Specifies the expand buttons’ visibility within the TreeList control.

property Buttons: Boolean;

Description

Use the Buttons property to specify the expand buttons’ visibility within the TreeList control.

The Buttons property is set to True	The Buttons property is set to False

If the Buttons property is set to False, the end user can expand or collapse nodes by double-clicking them with the mouse.

The default value of the Buttons property is True.


TcxTreeListOptionsView.CategorizedColumn

TcxTreeListOptionsView          See Also

Specifies a category column.

property CategorizedColumn: TcxTreeListColumn;

Description

Use the CategorizedColumn property to specify a category column for the TreeList control.

The following screenshot demonstrates the TreeList control with the Editor Name column assigned as categorized:

The categorized paint style is enabled when the PaintStyle property is set to tlpsCategorized.  If the PaintStyle property is set to tlpsCategorized but without a CategorizedColumn property value already assigned, the first TreeList column within the Columns collection (index = 0) is set as the CategorizedColumn.


TcxTreeListOptionsView.ColumnAutoWidth

TcxTreeListOptionsView          See Also

Determines whether column widths are changed automatically to display all columns without using the horizontal scrollbar.

property ColumnAutoWidth: Boolean;

Description

Use the ColumnAutoWidth property to determine whether column widths are changed to display all columns without using the horizontal scrollbar.

The default value of the ColumnAutoWidth property is cxTreeListDefColumnAutoWidth.


TcxTreeListOptionsView.DropArrowColor

TcxTreeListOptionsView          See Also

Specifies the color of the drop arrow.

property DropArrowColor: TColor;

Description

Use the DropArrowColor property to specify the color of the arrow marking the end point of a drag-and-drop operation.

DropArrowColor is clRed	DropArrowColor is clLime

The default value of the DropArrowColor property is cxTreeListDefDropArrowColor.


TcxTreeListOptionsView.FixedSeparatorColor

TcxTreeListOptionsView          See Also

Specifies the color of the fixed band separator.

property FixedSeparatorColor: TColor;

Description

The cxTreeList control supports a fixed bands feature.  Bands can be fixed to the left or to the right side of the control.  Columns located within fixed bands are not involved in horizontal scrolling.

Use the FixedSeparatorColor property to specify the fixed band separator color.

The default value of the FixedSeparatorColor property is clDefault.


TcxTreeListOptionsView.FixedSeparatorWidth

TcxTreeListOptionsView          See Also

Specifies the width of the fixed band separator.

property FixedSeparatorWidth: Integer;

Description

The cxTreeList control supports a fixed bands feature.  Bands can be fixed to the left or to the right side of the control.  Columns located within fixed bands are not involved in horizontal scrolling.

Use the FixedSeparatorWidth property to specify the width of this separator.

The default value of the FixedSeparatorWidth property is cxTreeListDefSeparatorWidth.


TcxTreeListOptionsView.Footer

TcxTreeListOptionsView

Specifies the footer summary visibility within the TreeList control.

property Footer: Boolean;

Description

Use the Footer property to specify the summary footer visibility within the TreeList control.  If this property value is False, the footer summary is not shown.

If this option is deactivated but the TreeListColumn.Options.Footer option is enabled, summary is still calculated.

The default value of the Footer property is False.


TcxTreeListOptionsView.GridLineColor

TcxTreeListOptionsView          See Also

Specifies the color of grid lines.

property GridLineColor: TColor;

Description

Use the GridLineColor property to specify the grid lines color.  Grid lines are displayed within the TreeList control unless the GridLines property value is tlglNone or the GridLineColor is the same with the control background.

The default value of the GridLineColor property is clDefault.


TcxTreeListOptionsView.GridLines

TcxTreeListOptionsView          See Also

Specifies the visibility of grid lines within the TreeList control.

type

  TcxTreeListGridLines = (tlglNone, tlglHorz, tlglVert, tlglBoth);

property GridLines: TcxTreeListGridLines;

Description

Use the GridLines property to specify the grid lines visibility within the TreeList control.  The list of available values is given below:

Value	Meaning
tlglNone	There are no grid lines within the TreeList control.
tlglHorz	Only horizontal grid lines are displayed within the TreeList control.
tlglVert	Only vertical grid lines are displayed within the TreeList control.
tlglBoth	Both vertical and horizontal grid lines are displayed within the TreeList control.

The default value of the GridLines property is tlglNone.


TcxTreeListOptionsView.Headers

TcxTreeListOptionsView          See Also

Determines whether column headers are visible within the TreeList control.

property Headers: Boolean;

Description

Use the Headers property to specify whether column headers are displayed.  If column headers are not visible, the end user cannot sort and move columns.  However, you can manipulate TreeList columns by code, regardless of the Headers property value.

The Headers property is set to True	The Headers property is set to False

The default value of the Headers property is cxTreeListDefColumnHeaders.


TcxTreeListOptionsView.Indicator

TcxTreeListOptionsView          See Also

Determines whether the node indicator is displayed.

property Indicator: Boolean;

Description

Use the Indicator property to specify whether the node indicator is displayed.  If the node indicator is visible, its width can be adjusted via the IndicatorWidth property.  If that property value is 0, the node indicator is not visible.

The node indicator displays the selected cell’s state.

The default value of the Indicator property is False.


TcxTreeListOptionsView.IndicatorWidth

TcxTreeListOptionsView          See Also

Specifies the node indicator’s width.

property IndicatorWidth: Integer;

Description

Use the IndicatorWidth property to specify the node indicator’s width.  If this property value is 0, the node indicator is not visible.  Another way to specify the node indicator’s visibility is to use the Indicator property.

The default value of the IndicatorWidth property is cxTreeListDefIndicatorWidth.


TcxTreeListOptionsView.PaintStyle

TcxTreeListOptionsView          See Also

Specifies the manner in which the TreeList control displays data.

type

  TcxTreeListPaintStyle = (tlpsStandard, tlpsCategorized);

property PaintStyle: TcxTreeListPaintStyle;

Description

The PaintStyle property defines the data representation manner for the TreeList control.  If the PaintStyle property is set to tlpsCategorized, the CategorizedColumn property identifies the category column.  If the PaintStyle property is set to tlpsCategorized but without a CategorizedColumn property value already assigned, the first TreeList column (Columns collection index is 0) is set as the CategorizedColumn.

The following screenshot shows a TreeList control with the Editor Name column set as a categorized column:

If the PaintStyle property value is tlpsStandard, the CategorizedColumn property value is ignored and the TreeList control appears as shown in the following screenshot:

The default value of the PaintStyle property is tlpsStandard.


TcxTreeListOptionsView.ShowRoot

TcxTreeListOptionsView          See Also

Determines whether lines are displayed between root nodes.

property ShowRoot: Boolean;

Description

Use the ShowRoot property to display lines between root nodes.

The ShowRoot value is True	The ShowRoot value is False

The default value of the ShowRoot property is True.


TcxTreeListOptionsView.SimpleCustomizeBox

TcxTreeListOptionsView          Example

Specifies the appearance of the customize box.

property SimpleCustomizeBox: Boolean;

Description

By default, the cxTreeList customization box contains two pages: Bands and Columns:

The Bands page is displayed when the Bands option is active.  If the SimpleCustomizeBox property value is False, the TreeList customize box only contains the Columns page, regardless of the Bands property value:

The default value of the SimpleCustomizeBox property is False.


TcxTreeListOptionsView.TreeLineColor

TcxTreeListOptionsView          See Also

Specifies the color of lines displayed between root nodes.

property TreeLineColor: TColor;

Description

Use the TreeLineColor property to specify the color of lines displayed between root nodes.  Note that if the ShowRoot property value is False, root lines are not displayed.

TreeLineColor is clDefault	TreeLineColor is clRed

The default value of the TreeLineColor property is clBtnShadow.


TcxTreeListOptionsView.TreeLineStyle

TcxTreeListOptionsView          See Also

Specifies the paint style for root lines.

type

  TcxTreeListTreeLineStyle = (tllsNone, tllsDot, tllsSolid);

property TreeLineStyle: TcxTreeListTreeLineStyle;

Description

Use the TreeLineStyle property to specify the paint style for root lines.  These lines are enabled via the ShowRoot property and are displayed between root nodes.  The list of available values is given below:

Value	Meaning	Picture
tllsNone	Root lines are not displayed.
tllsDot	Root lines are dotted.
tllsSolid	Root lines are solid.

The default value of the TreeLineStyle property is tllsDot.


TcxTreeListOptionsView.UseImageIndexForSelected

TcxTreeListOptionsView

When active, the ImageIndex property value is used instead of the SelectedIndex property.

property UseImageIndexForSelected: Boolean;

Description

Use the UseImageIndexForSelected property to determine which property is used to identify the index of an image displayed beside the selected nodes.  If this property value is True, then the ImageIndex property values are used to identify the images assigned to the selected nodes.  Otherwise, the SelectedIndex property identifies the the images assigned to the selected nodes.

The default value of the UseImageIndexForSelected property is True.


TcxTreeListOptionsView.UseNodeColorForIndent

TcxTreeListOptionsView

Specifies whether the node indent is painted with the node’s background color.

property UseNodeColorForIndent: Boolean;

Description

The UseNodeColorForIndent property specifies whether the node’s background color is used for painting the node indent.

UseNodeColorForIndent is True	UseNodeColorForIndent is False

The default value of the UseNodeColorForIndent property is True.


TcxTreeListPreview
TcxTreeListPreview Object

Hierarchy          Properties

Contains preview options.

Unit

cxTL

TcxTreeListPreview = class(TcxOwnedPersistent)

Description

The properties of the TcxTreeListPreview class represent preview options.  These options define the preview section’s visibility, the preview text margins, the column used for display within the preview, the number of text lines displayed, etc.


TcxTreeListPreview Hierarchy
Hierarchy

TPersistent

     |

TcxOwnedPersistent

     |


Properties for TcxTreeListPreview
TcxTreeListPreview Properties

TcxTreeListPreview          Legend

In TcxTreeListPreview

AutoHeight

Column

LeftIndent

MaxLineCount

Place

RightIndent

Visible


TcxTreeListPreview.AutoHeight

TcxTreeListPreview          See Also

Determines whether the preview section’s height is calculated automatically.

property AutoHeight: Boolean;

Description

If the AutoHeight property is set to True, the preview section’s height (in text lines) is calculated automatically.  This property setting is overridden by the MaxLineCount property.  For instance, if the AutoHeight option is active and the MaxLineCount property value is 1, the preview section’s height is only one text line, regardless of the preview section’s height and AutoHeight value.

The default value of the AutoHeight property is True.


TcxTreeListPreview.Column

TcxTreeListPreview

Specifies the column whose values are displayed within the preview section.

property Column: TcxTreeListColumn;

Description

Use the Column property to specify the column whose values are displayed within the preview section.  If this property value is assigned, this TreeList column is not displayed with the other columns.  The preview column re-appears within the TreeList control when the Column property value is cleared.


TcxTreeListPreview.LeftIndent

TcxTreeListPreview

Specifies the space between the preview text and the left side of the preview section.

property LeftIndent: Integer;

Description

Use the LeftIndent property to specify the left margin for the preview text.

Note: The preview text is affected by the LeftIndent and RightIndent values.  If these values overlap, the preview text is not displayed.

The default value of the LeftIndent property is cxTreeListDefPreviewMaxLineCount.


TcxTreeListPreview.MaxLineCount

TcxTreeListPreview          See Also

Specifies the maximum number of text lines displayed within the preview section.

property MaxLineCount: Integer;

Description

Use the MaxLineCount property to specify the maximum number of text lines displayed within the preview section.  Setting the AutoHeight property to True enables automatic calculation of the preview section’s height.  However, the MaxLineCount property has a higher priority than the AutoHeight property.  For instance, if the AutoHeight option is active and the MaxLineCount property value is 1, the preview section height is only one text line, regardless of the preview section’s height and AutoHeight value.

The default value of the MaxLineCount property is cxTreeListDefPreviewMaxLineCount.


TcxTreeListPreview.Place

TcxTreeListPreview

Specifies the preview section’s position within the TreeList control.

type

  TcxTreeListPreviewPlace = (tlppBottom, tlppTop);

property Place: TcxTreeListPreviewPlace;

Description

Use the Place property to specify the preview section position’s relative to the node for which it is displayed.  The list of possible values:

Value	Meaning
ppBottom	The preview is displayed at the bottom of the node.
ppTop	The preview is displayed at the top of the node.

The default value of the Place property is tlppBottom.


TcxTreeListPreview.RightIndent

TcxTreeListPreview

Specifies the space between the preview text and the right side of the preview section.

property RightIndent: Integer;

Description

Use the RightIndent property to specify the right margin for the preview text.

Note: The preview text is affected by the LeftIndent and RightIndent values.  If these values overlap, the preview text is not displayed.

The default value of the RightIndent property is cxTreeListDefPreviewIndent.


TcxTreeListPreview.Visible

TcxTreeListPreview          See Also

Specifies the preview section’s visibility.

property Visible: Boolean;

Description

Use the Visible property to specify the preview section’s visibility.  If this property value is True, but there is no Column property value assigned, the preview section is not visible.  Also, the section is not displayed if the MaxLineCount property value is set to 0.

The default value of the Visible property is False.


TcxTreeListHitTest
TcxTreeListHitTest Object

Hierarchy          Properties

Provides general information for TreeList elements under the supplied coordinates.

Unit

cxTL

TcxTreeListHitTest = class(TcxCustomHitTestController)

Description

The TcxCustomTreeListControl enables you to identify its elements that contain a specified point by using the TcxCustomTreeListControl.HitTest. property  This property references a TcxTreeListHitTest class instance.  The TcxTreeListHitTest class implements facilities for TreeList point investigation.  It provides the HitX, HitY and HitPojnt methods that allow you to specify the coordinates (in pixels relative to the upper left corner of the TreeList control).

Note that if you use the HitX and HitY properties you should call the Recalculate method to update the HitTest information.

After you specify the point, you can use the HitTest properties.  They enable you to determine the TreeList elements that contain the point tested.  There is a property for every TreeList element type that indicates whether the point belongs to the element.  Also there is are properties (HitBand, HitColumn, HitNode) that enable you to access the properties and methods of the elements that contain the point tested.

You shouldn't create any HitTest class instances.  They are created automatically on demand.


TcxTreeListHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomHitTestController

     |

TcxTreeListHitTest


Properties for TcxTreeListHitTest
TcxTreeListHitTest Properties

TcxTreeListHitTest          Legend

In TcxTreeListHitTest

CurrentCursor

HitAtBand

HitAtBandContainer

HitAtBandHeader

HitAtButton

HitAtColumn

HitAtColumnHeader

HitAtFooter

HitAtFooterItem

HitAtImage

HitAtImages

HitAtIndent

HitAtIndicator

HitAtNode

HitAtNodePreview

HitAtSeparator

HitAtSizingHorz

HitAtSizingVert

HitAtStateImage

HitBand

HitColumn

HitNode

TreeList

Derived from TcxCustomHitTestController

HitCode

HitPoint

HitState

HitX

HitY


TcxTreeListHitTest.CurrentCursor

TcxTreeListHitTest

Contains the cursor corresponding to the current position within the TreeList control.

property CurrentCursor: TCursor;

Description

Use the CurrentCursor property to obtain the cursor corresponding to the current position within the TreeList control.

ReadOnly Property


TcxTreeListHitTest.HitAtBand

TcxTreeListHitTest

Indicates whether the point tested belongs to a TreeList band.

property HitAtBand: Boolean;

Description

Use the HitAtBand property to determine whether the point tested belongs to a TreeList band (the band area is shown in the image below).  The property is set to True if the point belongs to any band.

Note that the node preview area is not included in the band area.

ReadOnly Property


TcxTreeListHitTest.HitAtBandContainer

TcxTreeListHitTest

Indicates whether the point tested belongs to a TreeList band container.

property HitAtBandContainer: Boolean;

Description

Use the HitAtBandContainer property to determine whether the point tested belongs to a TreeList band container (the band container area is shown in the image below).  The property is set to True if the point belongs to any band container.

ReadOnly Property


TcxTreeListHitTest.HitAtBandHeader

TcxTreeListHitTest

Indicates whether the point tested belongs to a TreeList band header.

property HitAtBandHeader: Boolean;

Description

Use the HitAtBandHeader property to determine whether the point tested belongs to a TreeList band header (the band header is shown in the image below).  The property is set to True if the point belongs to any band header.

ReadOnly Property


TcxTreeListHitTest.HitAtButton

TcxTreeListHitTest

Indicates whether the point tested belongs to the TreeList node expand button.

property HitAtButton: Boolean;

Description

Use the HitAtButton property to determine whether the point tested belongs to a TreeList node expand button (this button is shown in the image below).  The property contains True if the point belongs to any node expand button.

ReadOnly Property


TcxTreeListHitTest.HitAtColumn

TcxTreeListHitTest

Indicates whether the point tested belongs to the TreeList column.

property HitAtColumn: Boolean;

Description

Use the HitAtColumn property to determine whether the point tested belongs to a TreeList column (TreeList columns are shown in the image below).  The property is set to True if the point belongs to any column.

ReadOnly Property


TcxTreeListHitTest.HitAtColumnHeader

TcxTreeListHitTest

Indicates whether the point tested belongs to a TreeList column header.

property HitAtColumnHeader: Boolean;

Description

Use the HitAtColumnHeader property to determine whether the point tested belongs to a TreeList column header (column headers are shown in the image below).  The property is set to True if the point belongs to any column header.

ReadOnly Property


TcxTreeListHitTest.HitAtFooter

TcxTreeListHitTest

Indicates whether the point tested belongs to the TreeList footer.

property HitAtFooter: Boolean;

Description

Use the HitAtFooter property to determine whether the point tested belongs to the TreeList footer (the footer is shown in the image below).  The property is set to True if the point belongs to the footer.

ReadOnly Property


TcxTreeListHitTest.HitAtFooterItem

TcxTreeListHitTest

Indicates whether the point tested belongs to a TreeList footer item.

property HitAtFooterItem: Boolean;

Description

Use the HitAtFooterItem property to determine whether the point tested belongs to the TreeList footer item (footer items are shown in the image below).  The property contains True if the point belongs to any footer item.

ReadOnly Property


TcxTreeListHitTest.HitAtImage

TcxTreeListHitTest

Indicates whether the point tested belongs to a TreeList node image.

property HitAtImage: Boolean;

Description

Use the HitAtImage property to determine whether the point tested belongs to a TreeList node image (node images are shown in the image below).  The property is set to True if the point belongs to any node image area.

ReadOnly Property


TcxTreeListHitTest.HitAtImages

TcxTreeListHitTest

Indicates whether the point tested belongs to a TreeList node images area (state image or node image).

property HitAtImages: Boolean;

Description

Use the HitAtImages property to determine whether the point tested belongs to a TreeList images area (node images are shown in the image below).  The property is set to True if the point belongs to any node images area.

ReadOnly Property


TcxTreeListHitTest.HitAtIndent

TcxTreeListHitTest

Indicates whether the point tested belongs to a TreeList node indent area.

property HitAtIndent: Boolean;

Description

Use the HitAtIndent property to determine whether the point tested belongs to a TreeList node indent area (an area is shown on the image below).  The property is set to True if the point belongs to any node indent area.

ReadOnly Property


TcxTreeListHitTest.HitAtIndicator

TcxTreeListHitTest

Indicates whether the point tested belongs to the TreeList indicator.

property HitAtIndicator: Boolean;

Description

Use the HitAtIndicator property to determine whether the point tested belongs to the TreeList indicator (the indicator is shown in the image below).  The property is set to True if the point belongs to the indicator.

ReadOnly Property


TcxTreeListHitTest.HitAtNode

TcxTreeListHitTest

Indicates whether the point tested belongs to a TreeList node.

property HitAtNode: Boolean;

Description

Use the HitAtNode property to determine whether the point tested belongs to a TreeList node (as shown on the image below).  The property is set to True if the point belongs to any node.

Note that the node preview area is not included in the node area.

ReadOnly Property


TcxTreeListHitTest.HitAtNodePreview

TcxTreeListHitTest

Indicates whether the point tested belongs to a TreeList node preview section.

property HitAtNodePreview: Boolean;

Description

Use the HitAtNodePreview property to determine whether the point tested belongs to a TreeList node preview section (as shown in the image below).  The property is set to True if the point belongs to any node preview section.

ReadOnly Property


TcxTreeListHitTest.HitAtSeparator

TcxTreeListHitTest

Indicates whether the point tested belongs to a TreeList band separator.

property HitAtSeparator: Boolean;

Description

Use the HitAtSeparator property to determine whether the point tested belongs to a TreeList band separator (as shown in the image below).  The property is set to True if the point belongs to any band separator.

Note that band separators are only visible when there are fixed band(s) within the TreeList.

ReadOnly Property


TcxTreeListHitTest.HitAtSizingHorz

TcxTreeListHitTest

Indicates whether the point tested belongs to a TreeList column or a band’s horizontal sizing edge.

property HitAtSizingHorz: Boolean;

Description

Use the HitAtSizingHorz property to determine whether the point tested belongs to a TreeList column or a band’s horizontal sizing edge (sizing edges are shown in the image below).  The property is set to True if the point belongs to any column or band horizontal sizing edge.

ReadOnly Property


TcxTreeListHitTest.HitAtSizingVert

TcxTreeListHitTest

Indicates whether the point tested belongs to a TreeList column or a band’s vertical sizing edge.

property HitAtSizingVert: Boolean;

Description

Use the HitAtSizingVert property to determine whether the point tested belongs to a TreeList column or a band’s vertical sizing edge (sizing edges are shown in the image below).  The property is set to True if the point belongs to any column or band vertical sizing edge.

ReadOnly Property


TcxTreeListHitTest.HitAtStateImage

TcxTreeListHitTest

Indicates whether the point tested belongs to a TreeList node’s state image.

property HitAtStateImage: Boolean;

Description

Use the HitAtStateImage property to determine whether the point tested belongs to a TreeList node’s state image (node images are shown in the image below).  The property is set to True if the point belongs to any node’s state image area.

ReadOnly Property


TcxTreeListHitTest.HitBand

TcxTreeListHitTest

Provides the TreeList band that contains the point tested.

property HitBand: TcxTreeListBand;

Description

Use the HitBand property to access properties and methods of the TreeList band that contains the point tested.  If this point does not belong to any band within the TreeList, the property contains nil.  You can determine whether the point belongs to any band by using the TcxTreeListHitTest.HitAtBand property.

ReadOnly Property


TcxTreeListHitTest.HitColumn

TcxTreeListHitTest

Provides the TreeList column that contains the point tested.

property HitColumn: TcxTreeListColumn;

Description

Use the HitColumn property to access properties and methods of the TreeList column that contains the point tested.  If this point does not belong to any column within the TreeList, the property contains nil.  You can determine whether the point belongs to any column by using the TcxTreeListHitTest.HitAtColumn property.

ReadOnly Property


TcxTreeListHitTest.HitNode

TcxTreeListHitTest

Provides the TreeList node that contains the point tested.

property HitNode: TcxTreeListNode;

Description

Use the HitColumn property to access properties and methods of the TreeList node that contains the point tested.  If this point does not belong to any node within the TreeList, the property contains nil.  You can determine whether the point belongs to any node by using the TcxTreeListHitTest.HitAtNode property.

ReadOnly Property


TcxTreeListHitTest.TreeList

TcxTreeListHitTest

Provides access the TreeList control that contains the point tested.

property TreeList: TcxCustomTreeListControl;

Description

Use the TreeList property to access properties and methods of the TreeList control that contains the point tested.

ReadOnly Property


Data Loading Modes

Data loading in ExpressQuantumTreeList4 is implemented via a data controller.  The data controller is a core module implementing data related operations.  Its main purpose is to connect the TreeList control to data storage.  In addition, the data controller provides summary calculations.

Every type of TreeList control has a DataController property providing access to a data source.

There are three main modes of data loading provided by the data controller:

•	bound mode

The DataController is connected to a TDataSet by means of a TDataSource object.  When working in bound mode there is an option to use the smart load feature (see the TcxVirtualTreeListOptionsData.SmartLoad property). Smart load mode allows data to be loaded into the nodes when their parent node is being expanded. Thus, smart load mode improves the application’s performance. Please note that if smart load mode is enabled (the TcxVirtualTreeListOptionsData.SmartLoad property is set to True), the underlying dataset should be sorted by the TcxDBTreeListDataController.ParentField field and then by the TcxDBTreeListDataController.KeyField field.

•	provider mode

The DataController is connected to a user-defined (custom) data source and data is requested as needed.

•	unbound mode

The data controller is not connected to a data source and is pre-populated with records manually.

There are three types of TreeList: cxTreeList, cxDBTreeList, cxVirtualTreeList.

cxDBTreeList is a data-aware control, connected to a TDataSource via a data-aware data controller represented by the TcxDBDataController class or descendant.  Data-aware TreeList controls function in bound mode.  They are linked to data via a TDataSet component or a descendant.  Refer to the Connecting to Data topic for more information.

Non data-aware TreeList controls (cxTreeList and cxVirtualTreeList) are designed to work in unbound and provider modes.

In provider mode, data is retrieved from a user-defined data source.  This mode can be used, for instance, when you need to display structured data within your grid control.  The TcxCustomDataSource class provides an interface, which must be overridden to implement a data source that can interact with the data controller.  Usually, creating a custom data source only requires code in two methods.  See the Using Virtual cxTreeList topic to learn more.

In unbound mode, the data controller must be populated manually.  First, you should set the number of records in your data controller and then set item values for each record.  The Unbound Mode section provides more information on the implementation of unbound mode.


cxTLData Unit Overview
cxTLData Unit

Classes

TcxCustomDataTreeList

TcxCustomVirtualTreeList

TcxTreeListCustomDataSource

TcxVirtualTreeList

TcxVirtualTreeListDataController

TcxVirtualTreeListOptionsData


TcxCustomDataTreeList
TcxCustomDataTreeList Object

Hierarchy          Properties          Methods

Represents the base class for the TreeList control when working in provider mode.

Unit

cxTLData

TcxCustomDataTreeList = class(TcxCustomTreeListControl)

Description

TcxCustomDataTreeList is the base class for the TreeList control for it to work in provider mode.  Provider mode allows the control to display information not stored within a standard database and thus cannot be connected using a TDataSource object.  In this case, you need to create a custom data source by overriding the TcxCustomDataSource class.

TcxCustomDataTreeList descendants obtain data from the DataController.CustomDataSource property once it is assigned to a TcxCustomDataSource class instance.


TcxCustomDataTreeList Hierarchy
Hierarchy

TcxControl

     |

TcxEditingControl

     |

TcxExtEditingControl

     |

TcxCustomTreeListControl

     |

TcxCustomDataTreeList


Properties for TcxCustomDataTreeList
TcxCustomDataTreeList Properties

TcxCustomDataTreeList          Legend

In TcxCustomDataTreeList

OptionsData

Derived from TcxCustomTreeListControl

BandPanelHeight

Bands

ColumnCount

Columns

Count

Customizing

DefaultLayout

DefaultRowHeight

FocusedColumn

FocusedNode

FooterPanelHeight

HeaderHeight

HeaderPanelHeight

HitTest

Images

InplaceColumnIndex

InplaceEditor

IsActive

IsEditing

Items

LastNode

LevelIndentWidth

Nodes

OptionsBehavior

OptionsCustomizing

OptionsData

OptionsSelection

OptionsView

Preview

Searching

SearchingText

SelectionCount

Selections

Sorted

SortedColumnCount

SortedColumns

StateImages

Styles

TopNode

TopVisibleIndex

TopVisibleNode

VisibleBandCount

VisibleBands

VisibleColumnCount

VisibleColumns

VisibleCount

Derived from TcxExtEditingControl

OptionsBehavior

OptionsData

OptionsView

Derived from TcxEditingControl

BufferedPaint

LockUpdate

Styles

Derived from TcxControl

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel


Methods for TcxCustomDataTreeList
TcxCustomDataTreeList Methods

TcxCustomDataTreeList          Legend

In TcxCustomDataTreeList

 FullRefresh

Derived from TcxCustomTreeListControl

 AdjustColumnsWidth

 ApplyBestFit

 CancelEdit

 CancelSearching

 CellRect

 Clear

 ClearSelection

 ColumnByName

 CopyAllToClipboard

 CopySelectedToClipboard

 Create

 CreateColumn

 DeleteAllColumns

 DeleteSelection

 Deselect

 Destroy

 Find

 FindNext

 FindNodeByText

 FullCollapse

 FullExpand

 FullRefresh

 GotoBOF

 GotoEOF

 GotoNext

 GotoNextPage

 GotoPrev

 GotoPrevPage

 HideEdit

 IsBOF

 IsEOF

 MakeDefaultLayout

 RestoreColumnsDefaults

 RestoreColumnsWidths

 RestoreFromIniFile

 RestoreFromRegistry

 RestoreFromStream

 Select

 SelectAll

 ShowEdit

 ShowEditByKey

 ShowEditByMouse

 StoreToIniFile

 StoreToRegistry

 StoreToStream

 Subselect

Derived from TcxEditingControl

 BeginUpdate

 CancelUpdate

 EndUpdate

 LayoutChanged

Derived from TcxControl

 Create

 Destroy

 InvalidateRect


TcxCustomDataTreeList.OptionsData

TcxCustomDataTreeList

Contains settings determining the TreeList functionality in provider mode.

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.


TcxCustomDataTreeList.FindNodeByKeyValue

TcxCustomDataTreeList

Locates a treelist node by its key field value.

function FindNodeByKeyValue(const AKeyValue: Variant; AColumn: TcxTreeListColumn; AStartNode: TcxTreeListNode = nil; AExpandedOnly: Boolean = False; AForward: Boolean = True): TcxTreeListNode;

Description
Use the FindNodeByKeyValue method to locate the treelist node by its key field value.  The required key field value is specified via the AKeyValue parameter.  The node’s cell containing the key field value is identified via the AColumn parameter.  The treelist node from which the search starts is specified via the AStartNode parameter.  The AExpandOnly parameter determines whether the expanded child nodes of the expanded parents are involved into search.  The AForward parameter specifies the search direction.

The return value of this method is the located node.  If this method cannot locate node by the specified text, it returns nil.


TcxCustomDataTreeList.FullRefresh

TcxCustomDataTreeList

Completely reloads TreeList data.

procedure FullRefresh;

Description

Use the FullRefresh method when it is necessary to completely reload TreeList data. The method destroys all nodes and then recreates them.


TcxCustomVirtualTreeList
TcxCustomVirtualTreeList Object

Hierarchy          Properties          Methods

Represents the base class for the virtual TreeList control.

Unit

cxTLData

TcxCustomVirtualTreeList = class(TcxCustomDataTreeList)

Description

The TcxCustomVirtualTreeList class inherits all TcxCustomDataTreeList functionality and implements the provider mode’s data controller and custom data source features.  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 datasource class derived from the TcxTreeListCustomDataSource class. For detailed information, please refer to the Provider Mode topic.


TcxCustomVirtualTreeList Hierarchy
Hierarchy

TcxControl

     |

TcxEditingControl

     |

TcxExtEditingControl

     |

TcxCustomTreeListControl

     |

TcxCustomDataTreeList

     |


Properties for TcxCustomVirtualTreeList
TcxCustomVirtualTreeList Properties

TcxCustomVirtualTreeList          Legend

In TcxCustomVirtualTreeList

CustomDataSource

DataController

Derived from TcxCustomTreeListControl

BandPanelHeight

Bands

ColumnCount

Columns

Count

Customizing

DefaultLayout

DefaultRowHeight

FocusedColumn

FocusedNode

FooterPanelHeight

HeaderHeight

HeaderPanelHeight

HitTest

Images

InplaceColumnIndex

InplaceEditor

IsActive

IsEditing

Items

LastNode

LevelIndentWidth

Nodes

OptionsBehavior

OptionsCustomizing

OptionsData

OptionsSelection

OptionsView

Preview

Searching

SearchingText

SelectionCount

Selections

Sorted

SortedColumnCount

SortedColumns

StateImages

Styles

TopNode

TopVisibleIndex

TopVisibleNode

VisibleBandCount

VisibleBands

VisibleColumnCount

VisibleColumns

VisibleCount

Derived from TcxExtEditingControl

OptionsBehavior

OptionsData

OptionsView

Derived from TcxEditingControl

BufferedPaint

LockUpdate

Styles

Derived from TcxControl

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel


Methods for TcxCustomVirtualTreeList
TcxCustomVirtualTreeList Methods

TcxCustomVirtualTreeList          Legend

In TcxCustomVirtualTreeList

 HandleFromNode

 NodeFromHandle

Derived from TcxCustomDataTreeList

 FullRefresh

Derived from TcxCustomTreeListControl

 AdjustColumnsWidth

 ApplyBestFit

 CancelEdit

 CancelSearching

 CellRect

 Clear

 ClearSelection

 ColumnByName

 CopyAllToClipboard

 CopySelectedToClipboard

 Create

 CreateColumn

 DeleteAllColumns

 DeleteSelection

 Deselect

 Destroy

 Find

 FindNext

 FindNodeByText

 FullCollapse

 FullExpand

 FullRefresh

 GotoBOF

 GotoEOF

 GotoNext

 GotoNextPage

 GotoPrev

 GotoPrevPage

 HideEdit

 IsBOF

 IsEOF

 MakeDefaultLayout

 RestoreColumnsDefaults

 RestoreColumnsWidths

 RestoreFromIniFile

 RestoreFromRegistry

 RestoreFromStream

 Select

 SelectAll

 ShowEdit

 ShowEditByKey

 ShowEditByMouse

 StoreToIniFile

 StoreToRegistry

 StoreToStream

 Subselect

Derived from TcxEditingControl

 BeginUpdate

 CancelUpdate

 EndUpdate

 LayoutChanged

Derived from TcxControl

 Create

 Destroy

 InvalidateRect


TcxCustomVirtualTreeList.CustomDataSource

TcxCustomVirtualTreeList

Represents a user-defined data source for the virtual TreeList control.

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 datasource class derived from the TcxTreeListCustomDataSource class.  For detailed information, please refer to the Provider Mode topic. The   TcxCustomVirtualTreeList.CustomDataSource property lets you access this data source via the TreeList control.


TcxCustomVirtualTreeList.DataController

TcxCustomVirtualTreeList

Specifies the data controller which obtains records from the TreeList data source.

property DataController: TcxVirtualTreeListDataController;

Description

Use the DataController property to access the data controller object which retrieves data from the TreeList data source.

ReadOnly Property


TcxCustomVirtualTreeList.HandleFromNode

TcxCustomVirtualTreeList

Gets the TreeList node handle.

function HandleFromNode(ANode: TcxTreeListNode): TcxDataRecordHandle; virtual;

Description

Use the HandleFromNode method to get the TreeList node’s handle.  The ANode parameter specifies the node inspected.  Handles are used as parameters by the TcxCustomDataSource methods.


TcxCustomVirtualTreeList.NodeFromHandle

TcxCustomVirtualTreeList

Gets the TreeList node using its handle.

function NodeFromHandle(ARecordHandle: TcxDataRecordHandle): TcxTreeListNode; virtual;

Description

Use the NodeFromHandle method to get the TreeList node when you know its handle.  The ARecordHandle parameter specifies the node handle inspected.  Handles are used as parameters by the TcxCustomDataSource methods.


TcxTreeListCustomDataSource
TcxTreeListCustomDataSource Object

Hierarchy          Methods

Represents a custom data source for the virtual TreeList control.

Unit

cxTLData

TcxTreeListCustomDataSource = class(TcxCustomDataSource)

Description

The TcxTreeListCustomDataSource 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.  To do so, several methods must be overridden.  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.

In addition to the methods of the TcxCustomDataSource class, you should override the following methods of the TcxTreeListCustomDataSource:

•	DeleteChildItems

•	GetChildCount

•	GetChildRecordHandle

•	GetKeyValue

•	GetParentKeyValue

•	GetRootRecordHandle

•	NodeMoveTo

For more information on provider mode, see the Provider Mode topic.


TcxTreeListCustomDataSource Hierarchy
Hierarchy

TcxCustomDataSource

     |

TcxTreeListCustomDataSource


Methods for TcxTreeListCustomDataSource
TcxTreeListCustomDataSource Methods

TcxTreeListCustomDataSource          Legend

In TcxTreeListCustomDataSource

 DeleteChildItems

 GetChildCount

 GetChildRecordHandle

 GetKeyValue

 GetParentKeyValue

 GetRootRecordHandle

 NodeMoveTo


TcxTreeListCustomDataSource.DeleteChildItems

TcxTreeListCustomDataSource

Deletes all child nodes of a specific node.

procedure DeleteChildItems(AParentHandle: TcxDataRecordHandle); virtual;

Description

The DeleteChildItems method deletes all child nodes of the node whose handle is passed as the AParentHandle parameter.  You may override this method to provide your own functionality.  You only need to implement this method if you are going to use the smart load feature.


TcxTreeListCustomDataSource.GetChildCount

TcxTreeListCustomDataSource

Counts a node’s child nodes.

function GetChildCount(AParentHandle: TcxDataRecordHandle): Integer; virtual;

Description

The GetChildCount method returns the number of child nodes of a parent node.  The parent node handle is passed as the AParentHandle parameter.  As this ancestor class does not implement the method, you should override it, but you only need to do this if you are going to use the smart load feature.


TcxTreeListCustomDataSource.GetChildRecordHandle

TcxTreeListCustomDataSource

Gets the handle of a child node.

function GetChildRecordHandle(AParentHandle: TcxDataRecordHandle; AChildIndex: Integer): TcxDataRecordHandle; virtual;

Description

The GetChildRecordHandle method returns the handle of the child node (whose parent node and index are specified by the AParentHandle and AChildIndex parameters respectively).  As this ancestor class does not implement the method, you should override it, but you only need to do this if you are going to use the smart load feature.


TcxTreeListCustomDataSource.GetKeyValue

TcxTreeListCustomDataSource

Gets a node’s key value.

function GetKeyValue(ARecordHandle: TcxDataRecordHandle): Variant; virtual;

Description

The GetKeyValue method returns the key value of the node whose handle is passed as the ARecordHandle parameter.  As this ancestor class does not implement the method, you should override it, but you only need to do this if you are going to use the smart load feature.


TcxTreeListCustomDataSource.GetParentKeyValue

TcxTreeListCustomDataSource

Gets a specified node’s parent key value.

function GetParentKeyValue(ARecordHandle: TcxDataRecordHandle): Variant; virtual;

Description

The GetParentKeyValue method returns the parent key value of the node whose handle is passed as the ARecordHandle parameter.  As this class does not implement this method, you should override it.


TcxTreeListCustomDataSource.GetRootRecordHandle

TcxTreeListCustomDataSource

Gets a root’s record handle.

function GetRootRecordHandle: TcxDataRecordHandle ; virtual;

Description

The GetRootRecordHandle method returns the handle of the root node.  The handle identifies the record’s position in the list. You can override it, but you only need to do this if you are going to use the smart load feature.


TcxTreeListCustomDataSource.NodeMoveTo

TcxTreeListCustomDataSource

Moves or copies a node within the TreeList control relative to another.

procedure NodeMoveTo(ARecordHandle, AttachRecordHandle: TcxDataRecordHandle; AttachMode: TcxTreeListNodeAttachMode; IsCopy: Boolean); virtual;

Description

The NodeMoveTo method relocates the node identified by the ARecordHandle parameter.  The specified node is moved or copied depending on the IsCopy parameter value.  If set to True, the node is copied, otherwise, it is moved.  The ARecordHandle parameter identifies the destination point for the node relocation.  The position of the moved node relative to the destination node is determined by the AttachMode parameter.  As this method is not implemented by this class, you should override it.


TcxVirtualTreeList
TcxVirtualTreeList Object

Hierarchy          Properties          Methods          Events

Represents the TreeList control working in provider mode.

Unit

cxTLData

TcxVirtualTreeList = class(TcxCustomVirtualTreeList)

Description

TcxVirtualTreeList inherits all the TcxCustomVirtualTreeList class functionality.  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 datasource class derived from the TcxTreeListCustomDataSource class. For detailed information, please refer to the Provider Mode topic.


TcxVirtualTreeList Hierarchy
Hierarchy

TcxControl

     |

TcxEditingControl

     |

TcxExtEditingControl

     |

TcxCustomTreeListControl

     |

TcxCustomDataTreeList

     |

TcxCustomVirtualTreeList

     |

TcxVirtualTreeList


Properties for TcxVirtualTreeList
TcxVirtualTreeList Properties

TcxVirtualTreeList          Legend

Derived from TcxCustomVirtualTreeList

CustomDataSource

DataController

Derived from TcxCustomDataTreeList

OptionsData

Derived from TcxCustomTreeListControl

BandPanelHeight

Bands

ColumnCount

Columns

Count

Customizing

DefaultLayout

DefaultRowHeight

FocusedColumn

FocusedNode

FooterPanelHeight

HeaderHeight

HeaderPanelHeight

HitTest

Images

InplaceColumnIndex

InplaceEditor

IsActive

IsEditing

Items

LastNode

LevelIndentWidth

Nodes

OptionsBehavior

OptionsCustomizing

OptionsData

OptionsSelection

OptionsView

Preview

Searching

SearchingText

SelectionCount

Selections

Sorted

SortedColumnCount

SortedColumns

StateImages

Styles

TopNode

TopVisibleIndex

TopVisibleNode

VisibleBandCount

VisibleBands

VisibleColumnCount

VisibleColumns

VisibleCount

Derived from TcxExtEditingControl

OptionsBehavior

OptionsData

OptionsView

Derived from TcxEditingControl

BufferedPaint

LockUpdate

Styles

Derived from TcxControl

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel


Methods for TcxVirtualTreeList
TcxVirtualTreeList Methods

TcxVirtualTreeList          Legend

Derived from TcxCustomVirtualTreeList

 HandleFromNode

 NodeFromHandle

Derived from TcxCustomDataTreeList

 FullRefresh

Derived from TcxCustomTreeListControl

 AdjustColumnsWidth

 ApplyBestFit

 CancelEdit

 CancelSearching

 CellRect

 Clear

 ClearSelection

 ColumnByName

 CopyAllToClipboard

 CopySelectedToClipboard

 Create

 CreateColumn

 DeleteAllColumns

 DeleteSelection

 Deselect

 Destroy

 Find

 FindNext

 FindNodeByText

 FullCollapse

 FullExpand

 FullRefresh

 GotoBOF

 GotoEOF

 GotoNext

 GotoNextPage

 GotoPrev

 GotoPrevPage

 HideEdit

 IsBOF

 IsEOF

 MakeDefaultLayout

 RestoreColumnsDefaults

 RestoreColumnsWidths

 RestoreFromIniFile

 RestoreFromRegistry

 RestoreFromStream

 Select

 SelectAll

 ShowEdit

 ShowEditByKey

 ShowEditByMouse

 StoreToIniFile

 StoreToRegistry

 StoreToStream

 Subselect

Derived from TcxEditingControl

 BeginUpdate

 CancelUpdate

 EndUpdate

 LayoutChanged

Derived from TcxControl

 Create

 Destroy

 InvalidateRect


Events for TcxVirtualTreeList
TcxVirtualTreeList Events

TcxVirtualTreeList          Legend

Derived from TcxCustomTreeListControl

 OnAfterSummary

 OnCollapsed

 OnCollapsing

 OnCompare

 OnCustomDrawBackground

 OnCustomDrawBandHeader

 OnCustomDrawCell

 OnCustomDrawCellsGroup

 OnCustomDrawFooter

 OnCustomDrawFooterCell

 OnCustomDrawHeader

 OnCustomDrawHeaderCell

 OnCustomDrawIndentCell

 OnCustomDrawIndicatorCell

 OnCustomDrawPreview

 OnCustomizationFormVisibleChanged

 OnDeletion

 OnEdited

 OnEditing

 OnExpanded

 OnExpanding

 OnFocusedNodeChanged

 OnGetNodeImageIndex

 OnGetNodePreviewHeight

 OnHotTrackNode

 OnIsGroupNode

 OnMoveTo

 OnNodeChanged

 OnSelectionChanged

 OnSummary

 OnTopRecordIndexChanged

 StylesEvents

Derived from TcxEditingControl

 OnCustomDrawCell

 OnEditChanged

 OnEdited

 OnEditing

 OnEditValueChanged

 OnInitEdit


TcxVirtualTreeListDataController
TcxVirtualTreeListDataController Object

Hierarchy          Properties          Methods           Events

Represents a data controller that supports the custom data source feature.

Unit

cxTLData

TcxVirtualTreeListDataController = class(TcxControlDataController)

Description

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


TcxVirtualTreeListDataController Hierarchy
Hierarchy

TPersistent

     |

TcxCustomDataController

     |

TcxDataController

     |

TcxControlDataController

     |


Properties for TcxVirtualTreeListDataController
TcxVirtualTreeListDataController Properties

TcxVirtualTreeListDataController          Legend

In TcxVirtualTreeListDataController

CustomDataSource

TreeList

Derived from TcxCustomDataController

CustomDataSource

DisplayTexts

EditOperations

EditState

Filter

FilteredIndexByRecordIndex

FilteredRecordCount

FilteredRecordIndex

FocusedRecordIndex

FocusedRowIndex

Groups

IsEditing

IsPattern

MultiSelect

Options

RecordCount

RowCount

Search

Summary

Values


Methods for TcxVirtualTreeListDataController
TcxVirtualTreeListDataController Methods

TcxVirtualTreeListDataController          Legend

Derived from TcxCustomDataController

 Append

 AppendRecord

 BeginFullUpdate

 BeginUpdate

 BeginUpdateFields

 Cancel

 ChangeDetailExpanding

 ChangeRowSelection

 CheckFocusedSelected

 ClearBookmark

 ClearDetailLinkObject

 ClearDetails

 ClearSelection

 ClearSorting

 CollapseDetails

 DeleteFocused

 DeleteRecord

 DeleteSelection

 Edit

 EndUpdateFields

 EndFullUpdate

 EndUpdate

 FindRecordIndexByText

 ForEachRow

 FocusDetails

 GetDetailDataController

 GetMasterDataController

 GetMasterRecordIndex

 GetPatternDataController

 GetRowDisplayText

 GetRowIndexByRecordIndex

 GetRowInfo

 GetRowValue

 GetSelectedCount

 GetSelectedRowIndex

 GotoBookmark

 GotoFirst

 GotoLast

 GotoNext

 GotoPrev

 Insert

 InsertRecord

 IsBOF

 IsBookmarkAvailable

 IsDetailMode

 IsEOF

 IsGridMode

 IsRowSelected

 LoadFromStream

 MakeRecordVisible

 Post

 RefreshExternalData

 SaveBookmark

 SaveToStream

 SelectAll

 SelectRows

 SetEditValue

 SetValue

 SyncSelected


Events for TcxVirtualTreeListDataController
TcxVirtualTreeListDataController Events

TcxVirtualTreeListDataController          Legend

Derived from TcxCustomDataController

 OnAfterCancel

 OnAfterDelete

 OnAfterInsert

 OnAfterPost

 OnBeforeCancel

 OnBeforeDelete

 OnBeforeInsert

 OnBeforePost

 OnCompare

 OnDataChanged

 OnDetailCollapsed

 OnDetailCollapsing

 OnDetailExpanded

 OnDetailExpanding

 OnFilterRecord

 OnGroupingChanged

 OnNewRecord

 OnRecordChanged

 OnSortingChanged


TcxVirtualTreeListDataController.CustomDataSource

TcxVirtualTreeListDataController

Provides access to a user defined data source.

property CustomDataSource: TcxTreeListCustomDataSource;

Description

The CustomDataSource 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.


TcxVirtualTreeListDataController.TreeList

TcxVirtualTreeListDataController

Provides access to the owner TreeList control.

property TreeList: TcxCustomDataTreeList;

Description

The TreeList property enables you to access the properties and methods of the TreeList control to which the data controller belongs.

ReadOnly Property


TcxVirtualTreeListOptionsData
TcxVirtualTreeListOptionsData Object

Hierarchy          Properties

Contains settings determining the TreeList’s functionality working in provider mode.

Unit

cxTLData

TcxVirtualTreeListOptionsData = class(TcxTreeListOptionsData)

Description

TcxVirtualTreeListOptionsData inherits all properties from the TcxTreeListOptionsData option collection and implements the SmartLoad property.

The SmartLoad property enables you to set the virtual TreeList control in smart load mode.  When in smart load mode, TreeList nodes are loaded as they are expanded.


TcxVirtualTreeListOptionsData Hierarchy
Hierarchy

TcxControlOptionsData

     |

TcxTreeListOptionsData

     |

TcxVirtualTreeListOptionsData


Properties for TcxVirtualTreeListOptionsData
TcxVirtualTreeListOptionsData Properties

TcxVirtualTreeListOptionsData          Legend

In TcxVirtualTreeListOptionsData

SmartLoad

Derived from TcxTreeListOptionsData

Deleting

Inserting

SummaryNullIgnore


TcxVirtualTreeListOptionsData.SmartLoad

TcxVirtualTreeListOptionsData          See Also

Indicates whether the virtual TreeList control is operating in smart load mode.

property SmartLoad: Boolean;

Description

Use the SmartLoad property to switch smart load mode of the virtual TreeList control (True – enabled, False - disabled).  When in smart load mode, not all node data is loaded at once.  First, all root nodes are loaded.  After a user expands a particular node, its child nodes are loaded.  This allows a user to improve the TreeList loading speed and decrease the amount of memory used when working with large data structures.

Note: if the cxDBTreeList control’s SmartLoad feature is enabled, the underlying dataset should be sorted by the ParentField field and then by the KeyField field.

The default value of the SmartLoad property is False.


TcxTreeListNodeAttachMode
TcxTreeListNodeAttachMode type

Represents the manner in which one node is attached to another.

Unit

cxTL

type

  TcxTreeListNodeAttachMode = (tlamAdd, tlamAddFirst, tlamAddChild, tlamAddChildFirst, tlamInsert);

Description

TcxTreeListNodeAttachMode determines how one node is attached to another.  There are several ways to do it:

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.


Introduction

This help system provides you with information on ExpressQuantumTreeList4 – a powerful control used for displaying tree-like structures.  This introduction guides you through the list of documents included.

The documents listed below provide you with the basic information on the TreeList features:

•	Categorized Column – describes the categorized paint style of the TreeList control;

•	Custom Draw – explains the custom draw concept, implemented via a number of OnCustomDraw… events;

•	Data Loading Modes – gives an overview of TreeList DataController work modes;

•	Export – provides basic information on exporting the TreeList control to HTML, Excel, XML and text formats;

•	Inplace Editors – describes the in-place editors and editors repository concepts;

•	Options – gives the basic information on the different sets of options for the TreeList control;

•	Preview – provides basic information on the TreeList preview feature;

•	Self-Referenced Dataset – explains the structure of datasets suitable for using with the TreeList control;

•	TreeList Elements – describes TreeList elements: bands, columns and nodes, and explains their interaction.

The following documents represent the How To… section explaining the implementation of different TreeList features:

•	Bands – contains a step-by-step example of setting up TreeList bands and columns. This topic covers both design and runtime approaches;

•	Connecting To Data – explains how to connect the TreeList control to BDE and ADO datasets;

•	Creating And Deleting Columns - demonstrates creation and deletion of TreeList columns both at design time and by code;

•	Creating Summaries – provides a step-by-step explanation of creating the TreeList summary and demonstrates the OnSummary event handler for performing custom summary calculations;

•	Deleting Nodes – considers deletion of nodes by code;

•	Implement Sorting – considers data sorting. This topic touches upon sorting implemented both by the end-user and by code;

•	Implementing Drag-And-Drop Functionality – this topic considers three possible cases of drag-and-drop: within a single TreeList control, from the TreeList control to a third-party control and from a third-party control to the TreeList control;

•	Importing ExpressQuantumTreeList3 – provides information on importing ExpressQuantumTreeList3 controls to ExpressQuantumTreeList4;

•	Obtaining And Setting Cell Values – explains how to get and set cell values of data-aware and unbound TreeList controls. This topic also discusses the options of the TreeList which affect its editing capabilities;

•	Selecting Nodes – discusses focus and selection related aspects of the TreeList functionality;

•	Setting The cxTreeList appearance - demonstrates setting up the ExpressQuantumTreeList4 appearance using the three concepts: LookAndFeel, Styles and Custom Draw;

•	Unbound Mode – discusses using the TreeList control in unbound mode (cxTreeList);

•	Using Lookup Column – considers setting up a lookup column within the TreeList control;

•	Using Virtual cxTreeList – describes using the cxVirtualTreeList control (provider mode of the TreeList DataController).


Getting Started

This topic describes the basics of a treelist and the fastest way for beginners to get started with the treelist control.

The treelist 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 treelist 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 treelist every parent node can be expanded or collapsed.

To begin working with the treelist control, consider an example for the TcxDBTreeList [image] 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 tell 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. Go to the Columns page in the Component Editor and then click the Create all fields button:

Or you can right-click the treelist control and select the Create all columns item from the pop-up menu to perform the same action.

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 topic.

This is the result when the application is run:


Custom Draw

How a Custom Draw Event Works

Each custom draw event provides a set of parameters that supply information necessary for drawing TreeList element types.

The Sender parameter specifies the element to be repainted.  Usually, it is a TreeList element that owns this event.  The following table lists all available custom draw events and their owners:

Event	Description
OnCustomDrawBackground	Occurs when the control’s background needs repainting.
OnCustomDrawBandHeader	Occurs when a band’s header needs repainting.
OnCustomDrawCell	Occurs when a node cell needs repainting.
OnCustomDrawCellsGroup	Occurs when a cell group area needs repainting.
OnCustomDrawIndicatorCell	Occurs when an indicator cell needs repainting.
OnCustomDrawIndentCell	Occurs when a node indent needs repainting.
OnCustomDrawFooter	Occurs when the footer needs repainting.
OnCustomDrawFooterCell	Occurs when a footer cell needs repainting.
OnCustomDrawHeader	Occurs when a column header needs repainting.
OnCustomDrawHeaderCell	Occurs when a header cell needs repainting.
OnCustomDrawPreview	Occurs when a preview section needs repainting.

The ViewInfo parameter provides information necessary for painting elements.

Note:	generally, you will only need to use a small subset of the properties provided by the ViewInfo parameter.  Others are used internally by the control for painting purposes.

The most useful ViewInfo properties are:

•	The Bounds property.  Determines the repainted element’s bounding rectangle.  Each custom draw event provides the control’s canvas represented by the ACanvas parameter.  As the ACanvas parameter refers to the control’s canvas, you should use the AViewInfo.Bounds property to determine the current element’s position and size.  The rectangle contained within this property determines the top-left and bottom-right corners of the element within the TreeList control via the Bounds.Top, Bounds.Left, Bounds.Bottom and Bounds.Right fields respectively.

•	The Params property.  Contains a set of fields that determine the painted element’s style.  They are:

•	Color – specifies the element’s background.

•	TextColor – specifies the element’s text color (if it contains any).

•	Font – determines the element’s font (an instance of the TFont class) which has been used to calculate this ViewInfo.  To specify the font settings which will be used to paint the element, use the Font property of the ACanvas parameter.

•	The DisplayValue read-only property – specifies the value displayed by the element.

The ACanvas parameter provides the canvas where the element is painted.  Remember that this parameter provides the control’s canvas.  So you should use the AViewInfo.Bounds property to determine the repainted element’s bounding rectangle.  Although ACanvas is of the TcxCanvas type, it publishes all the most useful canvas methods.  If you want to access the standard VCL canvas, you should use the ACanvas.Canvas property.

The ADone parameter determines whether an event handler completely draws an appropriate element.  If ADone is set to True, the default drawing procedure is not called.


Inplace Editors

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.

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 ExpressQuantumLibrary.

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.

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 field 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:

When both Properties and RepositoryItem are assigned, the editor is determined by the RepositoryItem object.


TreeList Elements

Bands

Columns

Incremental Search

Nodes

Footer

The TreeList control doesn't represent data itself.  Data is represented by various TreeList elements.  These elements can be arranged in the following groups by functionality:

Data representation (Cells)

Navigation (Indicator, Expand Buttons)

Data arrangement (Bands, Columns)

Analysis and summary (Footer)

Description (Preview)

Look And Feel adjustment (Sizing Edges)

The following image represents TreeList elements and their location within the control.

The main control elements are Bands, Columns, Nodes and Footer.

Let’s discuss them in detail:

Band

Bands are used to create logical groups of TreeList columns.  A single band is visually represented by its header placed over column headers:

At runtime, TreeList bands can be moved and resized.  Bands can be moved within the control by clicking and dragging their headers and can be resized by clicking and dragging their edges.  Band moving and sizing is controlled by the band or TreeList options (the Band.Options and TreeList.OptionsCustomizing properties respectively).  Bands can be hidden at runtime.  To do this, click a band header and then drag it to the TreeList’s customization form, thus removing the band and its associated columns from the control.  To make it visible again, drag the band header from the customization form back to the TreeList control.  Remember that the customization form can be shown by setting the TreeList.Customizing.Visible property to True.

You can also fix bands within the TreeList control so that band columns are not horizontally scrolled.  Fixed bands cannot be moved within the control.  Use the FixedKind property to specify the control’s edge to which the band is fixed.

Column

Columns are used to represent data of the same logical type.  A single column is represented visually by its header:

At runtime, TreeList columns can be moved and resized.  Columns can be moved within the TreeList control by clicking and dragging their headers and can be resized by clicking and dragging their edges.  Columns can be moved and sized both horizontally and vertically:

Each TreeList column has a Position property that contains information about the column’s position within the control.  The Position.ColIndex and Position.RowIndex properties determine the column’s header position within the band.

Footer cell positions correspond to column header positions:

Node cells in the above image have the same background color as the corresponding column header.

Column moving and sizing is controlled by column or TreeList options (the Column.Options and TreeList.OptionsCustomizing properties respectively).  Columns can be hidden at runtime.  To do this, click a column header and then drag it to the TreeList’s customization form, thus removing the column from the control.  To make it visible again, drag the column header from the customization form back to the control.  Remember that the customization form can be shown by setting the TreeList.Customizing.Visible property to True.

TreeList columns always belong to a band.  When you create the first column within the control, a band is automatically created (if none already exist) and it becomes the column’s owner.  If there were any existing bands, the band with index=0 within the TreeList.Bands collection becomes the column’s owner.

Column values can be easily navigated by using the Incremental Search feature.

The Incremental Search feature allows a user to locate records in the TreeList control by column values.

To search a record by a field value, focus a record cell within the appropriate column and type the search text.  If the TreeList control contains a record value that starts with the search text, the record is focused.

The ‘re’ characters are pressed.  As a result, the first ‘Requisitioning Development’ value is located and the record containing it is focused:

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

When the first record is located, you can continue searching.  To search forward and backward, press the Ctrl+DownArrow and Ctrl+UpArrow keys respectively.

By default, incremental search is disabled.  To enable it, set the TreeList’s OptionsBehavior.IncSearch property to True.  The column’s Options.IncSearch attribute controls whether incremental search can be applied to this column.

If a user is unable to focus cells within the control when its TreeList.OptionsSelection.CellSelect property is set to False, the search column can be specified explicitly using the TreeList.OptionsBehavior.IncSearchItem property.  Note that this property is not in effect if cell selection is enabled (the TreeList.OptionsSelection.CellSelect property is True).

The TreeList control supports two data representation methods: standard and categorized.  Standard data representation means that TreeList data is arranged in columns and nodes.  With categorized data representation, some column values occupy whole nodes.

The following image shows a TreeList control whose Editor Name column is assigned as a categorized column:

Categorized data representation is enabled via the CategorizedColumn and PaintStyle properties.

Node

The TreeList control displays associated data source records by means of nodes.

Nodes represent records from the associated data source.  Each node is represented by an object providing access to the associated record data and allows a user to operate with the node.  Since the TreeList control represents data in a tree-like structure, these objects are stored as nested collections.  The collection of root level nodes can be accessed via the property.  Each node in the collection has its own child nodes collection available via the property.  These child nodes have their own children, etc.

Tree branches are called levels:

The TreeList node level can be obtained via the TcxTreeListNode.Level property.

Each node consists of several elements:

Node cells represent data and can contain in-place editors.  The node’s image section contains a descriptive image and a select image that indicates whether the node is selected.

To provide images for the TreeList control, you should set the TcxCustomTreeListControl.Images property for node images and the TcxCustomTreeListControl.StateImages property for state images.

The most flexible way of assigning images to nodes at runtime is to use the TcxCustomTreeListControl.OnGetNodeImageIndex event, but in unbound mode you can simply use the TcxTreeListNode.ImageIndex, TcxTreeListNode.StateIndex and TcxTreeListNode.SelectedIndex properties.

The node’s expand button allows a user to expand/collapse the node with children and indicates whether the node is collapsed or expanded.  To do it, press ‘+’ or ‘-‘ on the keyboard or press its expand button.  It is also possible to expand/collapse nodes by using the TcxTreeListNode.Expand/TcxTreeListNode.Collapse methods.

The preview section of a TreeList node allows a user to display large memo field values across the whole node.  The TreeList control has the TcxCustomTreeListControl.Preview property, thus providing a set of options to manage the preview section.  These options determine the preview section’s visibility, text position, column values to be displayed within the preview and the number of text lines displayed within the preview, etc.

See the Preview topic for detailed information.

To select a node, click it and the node will become both focused and selected (the TcxTreeListNode.Focused and TcxTreeListNode.Selected properties are True).

The TreeList control also allows a user to multi-select nodes.  To enable the multi-select feature, you should set TreeList.OptionsSelection.MultiSelect to True.  To multi-select nodes, use the left mouse button and either the Ctrl or the Shift key or both.

To select nodes in a random order, you should hold down the Ctrl key and click the desired nodes.  After completing node selection, you can release the Ctrl key.  The image below shows the TreeList control with every other node selected:

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

You can also select multiple series of nodes and single nodes at a time.  First you need to hold down the Ctrl key.  Now if you want to select contiguous nodes, click the first node you want to select and hold down the Shift key (while holding down the Ctrl key), click the last node you want to select and release the Shift key.  Repeat this action as many times as you need.  Additionally, you can add single nodes to this selection.  To add a single node, click it when holding down the Ctrl key.  After selecting all desired nodes and node series, you can release the Ctrl key.

The TreeList indicator displays selected and focused records with circles and triangles respectively. (see the above image).

In bound and provider modes, a data controller (the DataController property) provides data loaded from the storage as an array of records.  The data controller allows you to read and write values, append, insert, delete, navigate through records and perform other operations.  To access a particular value, you just need to supply the record index and the column index.

The TreeList control does not store all records itself.  Instead, it obtains them from the data controller as necessary.

Records are retrieved from the data controller in the order determined by the record index (the TcxTreeListNode.RecordIndex property).  Record indexes are not changed as a result of sorting or moving data.  They always refer to the same data.  Unlike the record index, the index (the TcxTreeListNode.Index property) defines a visible record’s position and it changes after sorting and moving data.

A dataset must have a particular structure to be displayed correctly in the TreeList control.  Each dataset record has to contain a unique key value field that will identify the node within the control and a parent key value field that will determine its parent node.

When in unbound mode, you need to create, delete and edit nodes manually.  Nodes are added by using the TcxCustomTreeListControl.AddNode method.  See the TcxTreeListNode and TcxTreeListNodes classes for more information.

Footer

The TreeList control footer is used for displaying summaries.  Summaries allow you to calculate totals against a group of records or all records and display the results in a convenient format.

You can create multiple summaries both at runtime via code and at design time using the Component Editor and Object Inspector.

The TreeList control provides the ability to calculate five built-in summaries:

Sum

Average value

The number of records

Maximum value

Minimum value

However, it is also possible to calculate more complex summaries that combine values of several columns.  This can be done by handling the TreeList’s OnSummary and OnAfterSummary events.  Thus you can exclude particular rows (containing NULL, for instance) and change the summary results on the fly.  To set up a summary item, use the TcxTreeListColumn.SummaryFooter property.

Summaries are calculated by the data controller.  Its main purpose is to connect to the data storage (custom data source or dataset).  To access summaries of a particular view, use the view’s DataController.Summary object.

For more information, see the summary related topics in the Task Based Help section.


Legend

 Protected

 Published

 ReadOnly


cxTL Unit Overview
cxTL Unit

Classes

TcxCustomTreeListControl

TcxTreeList

TcxTreeListBand

TcxTreeListBandOptions

TcxTreeListBands

TcxTreeListBandStyles

TcxTreeListCaption

TcxTreeListColumn

TcxTreeListColumnOptions

TcxTreeListColumnPosition

TcxTreeListColumnStyles

TcxTreeListColumnSummaryFooter

TcxTreeListCustomizing

TcxTreeListHitTest

TcxTreeListNode

TcxTreeListNodes

TcxTreeListOptionsBehavior

TcxTreeListOptionsCustomizing

TcxTreeListOptionsData

TcxTreeListOptionsSelection

TcxTreeListOptionsView

TcxTreeListPreview

TcxTreeListStyles

TcxTreeListStyleSheet

Other Types

TcxTreeListNodeAttachMode


TcxCustomTreeListControl
TcxCustomTreeListControl Object

Hierarchy          Properties          Methods          Events         See Aslo

Represents the base class for the TreeList, Virtual TreeList, and DBTreeList controls.

Unit

cxTL

TcxCustomTreeListControl = class(TcxExtEditingControl);

Description

The TcxCustomTreeListControl class defines the basic functionality for the TreeList classes implementing a tree-like data representation.  This display method requires elements representing a tree structure - columns and nodes.

The main element of the tree-like data representation is a node.  Each node can have one or more child nodes.  Nodes are stored in the node collection exposed via the control’s Nodes property.

Nodes contain actual data.  A node can have one or more values which are accessible via the node’s Values property.  The number of values is determined by the ValueCount property.  Each node value belongs to a column.

Columns represent the second group of control elements.  Each column has a caption that allows the end user to uniquely identify the column within the control.  The column collection is accessible via the Columns property at the control level.  Columns allow the end user to sort their values by clicking a column's caption.  Columns can be hidden (see Visible).  Visible columns are stored in the collection exposed via the VisibleColumns property.  Additionally, a column value can be displayed within the preview section whose settings are accessible via the control’s Preview property.  Columns are arranged in bands.

Bands represent objects that are used to logically (and visually) group columns.  Each band can have as many columns as you wish.  Like columns, bands also have captions to provide a user-friendly way of distinguishing them from each other.  Each band manages a collection of columns it owns, exposed by the band’s Columns property.  Thus, a column can be accessed at two levels: owner band level (see Columns) and at TreeList control level (see ItemIndex).  Bands can be hidden.  Visible bands are stored within a collection accessible via the VisibleBands property.  By default, bands are invisible.  To enable bands, you should activate the Bands option.

Besides the above elements, the TreeList control contains a footer located at the bottom and this is used to display summary values. The footer is disabled by default. You can enable it using the Footer option.

The TreeList control has several sets of options that control different aspects of its behavior and appearance. These include:

•	OptionsBehavior, settings which determine the control's response to user actions;

•	OptionsCustomizing, settings that allow a user to manipulate view items at runtime;

•	OptionsData, determining the functionality of a data-aware view;

•	OptionsSelection, settings relating to selections within a view;

•	OptionsView, containing appearance options.

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


TcxCustomTreeListControl Hierarchy
Hierarchy

TcxExtEditingControl

     |


Properties for TcxCustomTreeListControl
TcxCustomTreeListControl Properties

TcxCustomTreeListControl          Legend

In TcxCustomTreeListControl

BandPanelHeight

Bands

ColumnCount

Columns

Count

Customizing

DefaultLayout

DefaultRowHeight

FocusedColumn

FocusedNode

FooterPanelHeight

HeaderHeight

HeaderPanelHeight

HitTest

Images

InplaceColumnIndex

InplaceEditor

IsActive

IsEditing

Items

LastNode

LevelIndentWidth

Nodes

OptionsBehavior

OptionsCustomizing

OptionsData

OptionsSelection

OptionsView

Preview

Searching

SearchingText

SelectionCount

Selections

Sorted

SortedColumnCount

SortedColumns

StateImages

Styles

TopNode

TopVisibleIndex

TopVisibleNode

VisibleBandCount

VisibleBands

VisibleColumnCount

VisibleColumns

VisibleCount

Derived from TcxExtEditingControl

OptionsBehavior

OptionsData

OptionsView

Derived from TcxEditingControl

BufferedPaint

LockUpdate

Styles

Derived from TcxControl

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel


Methods for TcxCustomTreeListControl
TcxCustomTreeListControl Methods

TcxCustomTreeListControl          Legend

In TcxCustomTreeListControl

 AdjustColumnsWidth

 ApplyBestFit

 CancelEdit

 CancelSearching

 CellRect

 Clear

 ClearSelection

 ColumnByName

 CopyAllToClipboard

 CopySelectedToClipboard

 Create

 CreateColumn

 DeleteAllColumns

 DeleteSelection

 Deselect

 Destroy

 Find

 FindNext

 FindNodeByText

 FullCollapse

 FullExpand

 FullRefresh

 GotoBOF

 GotoEOF

 GotoNext

 GotoNextPage

 GotoPrev

 GotoPrevPage

 HideEdit

 IsBOF

 IsEOF

 MakeDefaultLayout

 RestoreColumnsDefaults

 RestoreColumnsWidths

 RestoreFromIniFile

 RestoreFromRegistry

 RestoreFromStream

 Select

 SelectAll

 ShowEdit

 ShowEditByKey

 ShowEditByMouse

 StoreToIniFile

 StoreToRegistry

 StoreToStream

 Subselect

Derived from TcxEditingControl

 BeginUpdate

 CancelUpdate

 EndUpdate

 LayoutChanged

Derived from TcxControl

 Create

 Destroy

 InvalidateRect


Events for TcxCustomTreeListControl
TcxCustomTreeListControl Events

TcxCustomTreeListControl          Legend

In TcxCustomTreeListControl

 OnAfterSorting

 OnAfterSummary

 OnCollapsed

 OnCollapsing

 OnCompare

 OnCustomDrawBackground

 OnCustomDrawBandHeader

 OnCustomDrawCell

 OnCustomDrawCellsGroup

 OnCustomDrawFooter

 OnCustomDrawFooterCell

 OnCustomDrawHeader

 OnCustomDrawHeaderCell

 OnCustomDrawIndentCell

 OnCustomDrawIndicatorCell

 OnCustomDrawPreview

 OnCustomizationFormVisibleChanged

 OnDeletion

 OnEdited

 OnEditing

 OnExpanded

 OnExpanding

 OnFocusedNodeChanged

 OnGetNodeImageIndex

 OnGetNodePreviewHeight

 OnHotTrackNode

 OnIsGroupNode

 OnMoveTo

 OnNodeChanged

 OnSelectionChanged

 OnSorting

 OnSummary

 OnTopRecordIndexChanged

 StylesEvents

Derived from TcxEditingControl

 OnCustomDrawCell

 OnEditChanged

 OnEdited

 OnEditing

 OnEditValueChanged

 OnInitEdit


TcxCustomTreeListControl.BandPanelHeight

TcxCustomTreeListControl

Returns the band panel’s height.

property BandPanelHeight: Integer;

Description

The band panel is the area at the top of the TreeList control, which contains bands (if Bands is True).  Use this property to determine the vertical size of the band panel.  The value returned depends on the height of band rows and the number of rows within the band (see BandLineCount).

ReadOnly Property


TcxCustomTreeListControl.Bands

TcxCustomTreeListControl          Example

Represents a collection of bands within the control.

property Bands: TcxTreeListBands;

Description

Use the Bands property to get access to the TcxTreeListBands object representing the collection of bands within the control.


TcxCustomTreeListControl.ColumnCount

TcxCustomTreeListControl          Example

Returns the number of columns within the control.

property ColumnCount: Integer;

Description

Use the ColumnCount property to determine the number of columns within the control.  Additionally, you can determine the number of columns within a particular band using the band’s ColumnCount method.

To get access to a particular column at the control level, you should use the Columns property.  To get access to a column at the band level, you should use the band’s Columns property.

ReadOnly Property


TcxCustomTreeListControl.Columns

TcxCustomTreeListControl          See Also           Example

Provides indexed access to a particular column within the control’s column collection.

property Columns[Index: Integer]: TcxTreeListColumn;

Description

Use the Columns property to get access to a particular column at the control level using index notation. The Index parameter represents a zero-based index of the desired column within the collection.  You can get access to a column via the Band.Columns property.

Additionally, you can determine the number of columns within the control’s column collection using either the TreeList.ColumnCount or the Band.ColumnCount property.


TcxCustomTreeListControl.Count

TcxCustomTreeListControl          Example

Returns the number of first level nodes within the control.

property Count: Integer;

Description

Read the Count property to determine the number of the first level nodes within the control.  All nodes at the first level return 0 in their Level property.  To determine the total number of nodes within the control, you should use the TreeList.Nodes.Ñount property.

ReadOnly Property


TcxCustomTreeListControl.Customizing

TcxCustomTreeListControl          Example

Returns the object that manages the appearance and behavior of the customization form.

property Customizing: TcxTreeListCustomizing;

Description

Using methods and properties of the object exposed via Customizing, you can display the customization form (see Visible), specify which sheet of the form is visible (see MakeBandSheetVisible, MakeColumnSheetVisible), determine the number of rows within the form (RowCount), and perform other operations.

The following screenshot displays a customization form, containing several columns:


TcxCustomTreeListControl.DefaultLayout

TcxCustomTreeListControl

Specifies whether the default layout is applied to the control.

property DefaultLayout: Boolean;

Description

Read the DefaultLayout property to determine whether the control is in the default layout.  Set the property to True, to apply the default layout to the control (see MakeDefaultLayout).

The default value of the DefaultLayout property is False.


TcxCustomTreeListControl.DefaultRowHeight

TcxCustomTreeListControl

Returns the default height of a TreeList node.

property DefaultRowHeight: Integer;

Description

Read the DefaultRowHeight property to determine the default height of a control node.  Change the property value to modify the default height.


TcxCustomTreeListControl.FocusedColumn

TcxCustomTreeListControl          See Also           Example

Returns the column currently focused.

property FocusedColumn: TcxTreeListColumn;

Description

Read this property value to determine the column currently focused within the control.  Set the property to a column to move focus to that column.

Note: the property returns nil when OptionsSelection.CellSelect is False or if no column is focused.

Assignments to the FocusedColumn property are not possible if the column is invisible (its Visible property returns False) or its Focusing option is disabled.  Column options are exposed via the column’s  Options property.

Additionally, you can determine the node currently focused by using the FocusedNode property.

You can move focus to a column by using the Column.Focused property.  You can prohibit the end user from focusing the column by using the Options.Focusing property.  Finally, you can prevent the TreeList control from being focused via the Tab key, by setting its TabStop property to False.


TcxCustomTreeListControl.FocusedNode

TcxCustomTreeListControl          See Also           Example

Returns the node currently focused.

property FocusedNode: TcxTreeListNode;

Description

Read this property value to determine the node currently focused.  Set the property to a node, to move focus to it.

Note:	The property returns nil if the control is empty or there isn’t a node focused.

To determine the number of nodes within the control, you should use the TreeList.Nodes.Count property.

Additionally, you can determine the column currently focused by using the FocusedColumn property.


TcxCustomTreeListControl.FooterPanelHeight

TcxCustomTreeListControl

Returns the footer panel’s height.

property FooterPanelHeight: Integer;

Description

Read the FooterPanelHeight property to determine the footer panel’s height in pixels.  The property returns 0 when the footer is disabled (see OptionsView.Footer).

Also, you can determine the header panel’s height by using the HeaderPanelHeight property.

ReadOnly Property


TcxCustomTreeListControl.HeaderHeight

TcxCustomTreeListControl

Returns the height of a single column header.

property HeaderHeight: Integer;

Description

Read the HeaderHeight property to determine the height of a single column header.  The property returns 0 when column headers are disabled (see OptionsView.Headers); otherwise, the actual header height is returned.

Also, you can determine the header panel height using the HeaderPanelHeight property.

ReadOnly Property


TcxCustomTreeListControl.HeaderPanelHeight

TcxCustomTreeListControl

Returns the header panel’s height.

property HeaderPanelHeight: Integer;

Description

Read the HeaderPanelHeight property to determine the height of the header panel.  The header panel is comprised of all the band and column headers within the control.

Also, you can determine the height of a single column header using the HeaderHeight property.

ReadOnly Property


TcxCustomTreeListControl.HitTest

TcxCustomTreeListControl

Represents a class containing information about what is located at the current point within the control.

property HitTest: TcxTreeListHitTest;

Description

You can use members of the TcxTreeListHitTest object exposed via the HitTest property to obtain information about the objects located at a specific point within the control.

ReadOnly Property


TcxCustomTreeListControl.Images

TcxCustomTreeListControl          See Also          Example

Represents an object for managing a collection of images.

property Images: TCustomImageList;

Description

Use the Images property to obtain an object of the TCustomImageList type to manage a collection of images within the control.

You can assign images to individual nodes within the control using the ImageIndex and SelectedIndex properties of each node.  Alternatively, you can use the OnGetNodeImageIndex event.


TcxCustomTreeListControl.InplaceColumnIndex

TcxCustomTreeListControl

Determines the index of the column edited by an in-place editor.

property InplaceColumnIndex: Integer;

Description

Returns the index of the column for which an in-place editor has been called.  The property returns –1 if no column is currenly being edited (see IsEditing); otherwise, the column index is returned (see ItemIndex).

ReadOnly Property


TcxCustomTreeListControl.InplaceEditor

TcxCustomTreeListControl

Returns the active in-place editor.

property InplaceEditor: TcxCustomEdit;

Description

Read the InplaceEditor property to determine the active in-place editor used to edit cell values.

Note: the property returns nil when CellSelect is False, cell value editing is prohibited, the control is empty or the IsEditing property returns False.

ReadOnly Property


TcxCustomTreeListControl.IsActive

TcxCustomTreeListControl          See Also

Indicates whether the control has focus or if an in-place editor is opened and focused.

property IsActive: Boolean;

Description

Read the IsActive property to determine whether the control has focus or ifan in-place editor is opened and focused.  If this property returns True, you can determine the focus position via the FocusedColumn and FocusedNode properties.

ReadOnly Property


TcxCustomTreeListControl.IsEditing

TcxCustomTreeListControl

Indicates whether the control is in edit mode.

property IsEditing: Boolean;

Description

Read this property value to determine whether a node is being edited currently.  To cease editing node values by code, you can use the Node.EndEdit method.

Also, you can display the in-place editor for the cell currently focused by using the ShowEdit method.

ReadOnly Property


TcxCustomTreeListControl.Items

TcxCustomTreeListControl          Example

Provides indexed access to the collection of root level nodes within the control.

property Items[Index: Integer]: TcxTreeListNode;

Description

Use the Items property to obtain indexed access to the collection of root level nodes within the control.  A root level node is one whose Node.Level property returns 0.

The Index parameter represents the zero-based index of the node required.

To determine the number of root level nodes within the control, use the Count property.

Also, you can obtain access to the collection of all nodes using the Nodes property. The total number of nodes can be determined by using the Nodes.Count property.

ReadOnly Property


TcxCustomTreeListControl.LastNode

TcxCustomTreeListControl          See Also

Returns the last visible node within the control.

property LastNode: TcxTreeListNode;

Description

Read the LastNode property to obtain access to the last visible node within the control’s node collection.

Additionally, you can determine the first node displayed by using the TopNode property.

ReadOnly Property


TcxCustomTreeListControl.LevelIndentWidth

TcxCustomTreeListControl

Returns the width of the level’s indent space.

property LevelIndentWidth: Integer;

Description

Read the property’s value to determine the width of the level’s indent space.  The value returned is calculated automatically and depends on the current look and feel of the control and on the size of the images used.

ReadOnly Property


TcxCustomTreeListControl.Nodes

TcxCustomTreeListControl          Example

Returns an object representing the control’s node collection.

property Nodes: TcxTreeListNodes;

Description

Use the Nodes property to access the collection of TreeList nodes.  This collection is represented by a TcxTreeListNodes instance.  The object’s properties and methods provide you with the number of nodes within the control (Nodes.Count), the first visible node (Nodes.TopVisibleNode),  and access to nodes via their absolute position within the control (Nodes.AbsoluteItems), etc.


TcxCustomTreeListControl.OptionsBehavior

TcxCustomTreeListControl

Provides the settings determining the control’s behavior in response to user actions.

property OptionsBehavior: TcxTreeListOptionsBehavior;

Description

The property exposes an object of the TcxTreeListOptionsBehavior type whose properties determine such aspects of the control’s behavior as whether cell editors are always displayed, whether cell hints are displayed every time a user points to a cell with the mouse and whether the end user can move focus to the next cell using the Tab key.


TcxCustomTreeListControl.OptionsCustomizing

TcxCustomTreeListControl

Represents the settings determining whether the end user can customize the TreeList control by manipulating its bands and columns.

property OptionsCustomizing: TcxTreeListOptionsCustomizing;

Description

This property exposes an object of the TcxTreeListOptionsCustomizing type whose properties determine how the TreeList control can be customized by the end user at runtime.  These options control moving and sizing of TreeList bands.


TcxCustomTreeListControl.OptionsData

TcxCustomTreeListControl

Represents the data-aware settings of the TreeList control.

property OptionsData: TcxTreeListOptionsData;

Description

The property exposes an object of the TcxTreeListOptionsData type whose properties allow you to determine which data operations are possible.  For instance, using these properties you can determine whether changes made to the cell’s contents should be canceled when focus position is changed and whether editing the cell’s contents is allowed at all.


TcxCustomTreeListControl.OptionsSelection

TcxCustomTreeListControl

Represents the selection settings of the TreeList control.

property OptionsSelection: TcxTreeListOptionsSelection;

Description

This property exposes an object of the TcxTreeListOptionsSelection type whose properties allow you to determine what can be selected and how selection is performed within the control.  For instance, using these properties, you can determine whether the end user can select individual cells within a node or the whole node is selected, whether several nodes can be selected or whether selection should be hidden whenever focus is moved to another control.


TcxCustomTreeListControl.OptionsView

TcxCustomTreeListControl

Represents the settings determining the look and feel of the TreeList control.

property OptionsView: TcxTreeListOptionsView;

Description

This property exposes an object of the TcxTreeListOptionsView type whose properties allow you to determine the look and feel aspects of the control.  For instance, using these properties, you can determine whether bands, indicator column and/or the footer are displayed and whether cell heights depend on their content.


TcxCustomTreeListControl.Preview

TcxCustomTreeListControl

Represents the settings of the preview section within the control.

property Preview: TcxTreeListPreview;

Description

This property exposes an object of the TcxTreeListPreview type whose properties allow you to specify the settings of the preview section.  For instance, you can specify the column whose contents are displayed within the preview section, determine the number of lines the preview section displays and/or specify its position within a node.

To display the preview section, you should enable the exposed object’s Visible option.


TcxCustomTreeListControl.Searching

TcxCustomTreeListControl          Example

Indicates whether the end user can perform incremental search within the control.

property Searching: Boolean;

Description

Read the Searching property to determine whether the end user is currently performing an incremental search.

To enable the incremental search, activate the OptionsBehavior.IncSearch option.

To determine the currently found value, you should use the SearchingText property.

ReadOnly Property


TcxCustomTreeListControl.SearchingText

TcxCustomTreeListControl          Example

Returns the value located by incremental search.

property SearchingText: string;

Description

Read the SearchingText property to obtain the text located by the incremental search.

Incremental search is enabled within the TreeList control via the OptionsBehavior.IncSearch option.


TcxCustomTreeListControl.SelectionCount

TcxCustomTreeListControl

Returns the number of nodes currently selected.

property SelectionCount: Integer;

Description

Read this property value to determine the number of nodes selected within the control.  To obtain a particular selected node by its index within the selected nodes collection, use the Selections property.

Enable the OptionsSelection.MultiSelect option to select several nodes simultaneously.

ReadOnly Property


TcxCustomTreeListControl.Selections

TcxCustomTreeListControl

Provides indexed access to selected nodes.

property Selections[Index: Integer]: TcxTreeListNode;

Description

Use the Selections property to get a selected node by its index.  The Index parameter represents the zero-based index of the selected node within the selected nodes collection.

To determine the number of nodes currently selected, use the SelectionCount property.

Note: to be able to select several nodes at once, you need to enable the OptionsSelection.MultiSelect option.

ReadOnly Property


TcxCustomTreeListControl.Sorted

TcxCustomTreeListControl          Example

Indicates whether column values are sorted.

property Sorted: Boolean;

Description

Read the Sorted property to determine whether column values are sorted.  If at least the values of one column are sorted, the property returns True.

Setting the property to True does not sort columns.  Setting the property to False removes sorting from all columns.

In order to sort column values, you should specify the sorting direction by setting the Column.SortOrder property to a value other than soNone.  To clear column sorting, you can either set the Column.SortOrder property to soNone or set the control’s Sorted property to False.

To determine the number of sorted columns, you should use the SortedColumnCount property.  To obtain indexed access to the collection of sorted columns, use the SortedColumns property.


TcxCustomTreeListControl.SortedColumnCount

TcxCustomTreeListControl          Example

Returns the number of sorted columns.

property SortedColumnCount: Integer;

Description

Read the SortedColumnCount property to determine the number of columns to sort.  To obtain indexed access to the sorted columns collection, use the SortedColumns property.

To determine whether column values within the control are sorted, use the Sorted property.

ReadOnly Property


TcxCustomTreeListControl.SortedColumns

TcxCustomTreeListControl          Example

Provides indexed access to the collection of sorted columns.

property SortedColumns[Index: Integer]: TcxTreeListColumn;

Description

Use the SortedColumns property to obtain indexed access to the collection of sorted columns.

The Index parameter represents the zero-based index of the column required.

A column is added to the SortedColumns collection by setting its Column.SortOrder property to a value other than soNone.

To determine whether column values are sorted, use the Sorted property.

To determine the number of columns sorted, use the SortedColumnCount property.

ReadOnly Property


TcxCustomTreeListControl.StateImages

TcxCustomTreeListControl          See Also          Example

Specifies the images that appear to the left of the node text.

property StateImages: TCustomImageList;

Description

Use this property to set or to access the image list that contains the images displayed to the left of the node text.  The index of the node’s image is stored in the Node.StateIndex property.

The following image demonstrates a node with both regular and state images:


TcxCustomTreeListControl.Styles

TcxCustomTreeListControl

Represents the set of styles defining the control’s appearance.

property Styles: TcxTreeListStyles;

Description

The Styles property exposes an object of the TcxTreeListStyles class, whose properties represent styles for the different elements of the control.  You can define style settings for the control’s background, band and column headers, the preview section, the footer and other elements.


TcxCustomTreeListControl.TopNode

TcxCustomTreeListControl          See Also

Returns the first node within the control.

property TopNode: TcxTreeListNode;

Description

Read the TopNode property to obtain access to the top node within the control.  The top node is the first node displayed within the control.

You can determine the last node using the LastNode property.

Also, you can determine the top visible node using the TopVisibleNode property, or its index using the TopVisibleIndex property.

ReadOnly Property


TcxCustomTreeListControl.TopVisibleIndex

TcxCustomTreeListControl          See Also

Returns the index of the top visible node within the control.

property TopVisibleIndex: Integer;

Description

Read the TopVisibleIndex property to determine the index of the top visible node.  To obtain direct access to the top visible node, you should use the TopVisibleNode property.

Assigning a new value to this property will scroll the control vertically.  Alternatively, you can use the TopVisibleNode property for this purpose.

Additionally, you can determine the last node within the control by using the LastNode property.


TcxCustomTreeListControl.TopVisibleNode

TcxCustomTreeListControl          See Also

Returns the top visible node within the control.

property TopVisibleNode: TcxTreeListNode;

Description

Read the TopVisibleNode to determine the first node displayed on the screen.  To determine the absolute top node, you should use the TopNode property.

You can assign a node to the property to make the node visible.  Alternatively, you can use the TopVisibleIndex property for this purpose.

The last node can be obtained using the LastNode property.


TcxCustomTreeListControl.VisibleBandCount

TcxCustomTreeListControl          See Also

Returns the number of visible bands within the control.

property VisibleBandCount: Integer;

Description

Use the VisibleBandCount property to determine the number of bands whose Band.Visible property returns True.  You can access individual visible bands by their indexes using the VisibleBands property.

ReadOnly Property


TcxCustomTreeListControl.VisibleBands

TcxCustomTreeListControl          See Also

Provides indexed access to visible bands.

property VisibleBands[Index: Integer]: TcxTreeListBand;

Description

Use the VisibleBands property to access individual visible bands within the control by their indexes.

The Index parameter represents the zero-based index of the desired band within the list of visible bands.  To determine the number of visible bands, use the VisibleBandCount property.


TcxCustomTreeListControl.VisibleColumnCount

TcxCustomTreeListControl          See Also          Example

Returns the number of visible columns within the control.

property VisibleColumnCount: Integer;

Description

Read the VisibleColumnCount property to determine the number of columns whose Column.Visible property is set to True.  To get indexed access to visible columns, use the VisibleColumns property.

ReadOnly Property


TcxCustomTreeListControl.VisibleColumns

TcxCustomTreeListControl          See Also          Example

Provides indexed access to visible columns within the control.

property VisibleColumns[Index: Integer]: TcxTreeListColumn;

Description

Use the VisibleColumns property to obtain indexed access to the list of columns whose Column.Visible property is set to True.

The Index parameter represents a zero-base index of the desired visible column.

To determine the number of visible columns within the control, use the VisibleColumnCount property.


TcxCustomTreeListControl.VisibleCount

TcxCustomTreeListControl          See Also

Returns the number of nodes visible on the screen.

property VisibleCount: Integer;

Description

Read the VisibleCount property to determine the number of visible nodes.  Nodes that are partially visible are not counted.  This can happen when the client area is too small to display all the nodes.

ReadOnly Property


TcxCustomTreeListControl.AddNode

TcxCustomTreeListControl          See Also

Adds a node to the control at a specific position.

function AddNode(ANode, ARelative: TcxTreeListNode; AData: Pointer; AttachMode: TcxTreeListNodeAttachMode): TcxTreeListNode; virtual;

Description

The AddNode method allows you to add a node to the TreeList control.  The method returns the node added.

The ANode parameter specifies the node to add.  If the parameter is set to nil, a new node is created.

The ARelative parameter specifies the parent node.  If this parameter is set to nil, the node becomes a child of the root node.

The AData parameter represents a pointer to custom data.

The AttachMode parameter specifies the position at which the node is added.  Using the AttachMode parameter you can, for instance, specify whether the node is inserted at the first or at the last position among other child nodes.

You can use other methods for adding nodes to the TreeList control, for instance, the Add, AddChild, AddChildFirst or AddFirst method.

Note: these methods are only used by the unbound TreeList (see TreeList), not by cxVirtualTreeList or TcxDBTreeList.  After any of these methods is used, the TreeList control is re-sorted if sorting is in effect.


TcxCustomTreeListControl.AdjustColumnsWidth

TcxCustomTreeListControl          See Also

Displays all visible columns within the client area of the TreeList control.

procedure AdjustColumnsWidth;

Description

Some columns can be outside the client area of the TreeList control.  To reach these columns, end users have to use the horizontal scrollbar.  The AdjustColumnsWidth method changes column widths to display all columns on screen without using the scrollbar.  You can also set the OptionsView.ColumnAutoWidth property to True for this purpose.


TcxCustomTreeListControl.ApplyBestFit

TcxCustomTreeListControl

Adjusts the width of all treelist columns to display their contents entirely.

procedure ApplyBestFit;

Description

Use the ApplyBestFit method to adjust the width of all treelist columns in order to display their full contents.  It is possible to adjust the column width within a treelist column by double-clicking the column’s right edge.

You can prevent a user from changing the column width either by setting the column’s Options.Sizing or the view’s OptionsCustomize.ColumnHorzSizing properties to False.


TcxCustomTreeListControl.CancelEdit

TcxCustomTreeListControl

Discards the changes made to a cell’s contents.

procedure CancelEdit;

Description

When the end user starts editing a cell within the control, the in-place editor displayed allows the end user to change the cell’s value.  Calling the CancelEdit method allows you to close the in-place editor and discard the any changes the end user has made to the cell value.


TcxCustomTreeListControl.CancelSearching

TcxCustomTreeListControl          See Also           Example

Stops the incremental search.

procedure CancelSearching;

Description

The CancelIncSearching method assigns an empty string to the SearchingText property and this stops the incremental search started either programmatically or by an end user.


TcxCustomTreeListControl.CellRect

TcxCustomTreeListControl

Returns the rectangle occupied by a cell.

function CellRect(ANode: TcxTreeListNode; AColumn: TcxTreeListColumn): TRect;

Description

Use the CellRect method to obtain the rectagle of the specified TreeList cell.

The ANode and AColumn parameters determine the TreeList node and the column to which the cell belongs.  CellRect returns the rectangle in the TreeList control’s coordinates.

Note: if the cell belongs to an invisible node (see Visible), the method returns TRect (-1;-1;-1;-1).


TcxCustomTreeListControl.Clear

TcxCustomTreeListControl          See Also

Deletes all nodes from the control.

procedure Clear;

Description

Use the Clear method to delete all nodes including their child nodes.  The method calls the Nodes.Clear method to perform the actual deletion.

To delete a particular node, you should use the Delete method of the node.

Alternatively, you can restrict the deletion to selected nodes by using the DeleteSelection method.

The OnDeletion event is fired when this method is called.


TcxCustomTreeListControl.ClearSelection

TcxCustomTreeListControl

Unselects all nodes within the control.

procedure ClearSelection(KeepPrimary: Boolean = False); virtual;

Description

Use the ClearSelection method to unselect all nodes within the control.  The KeepPrimary parameter indicates whether the first selected node should be kept selected.  Set the parameter to False to unselect all nodes.  Set it to True to unselect all nodes but the one from which the selection started.

Note:	This method does nothing when the OptionsSelection.MultiSelect option is disabled.

To unselect a particular node, use the Deselect method.  To determine the number of selected nodes within the control, use the SelectionCount property.  To obtain indexed access to selected nodes, use the object exposed via the Selections property.


TcxCustomTreeListControl.ColumnByName

TcxCustomTreeListControl          Example

Returns a column by its name.

function ColumnByName(const AName: string): TcxTreeListColumn;

Description

Use the ColumnByName method to obtain a column by its name.  The AName parameter specifies the name of the column required.

If there is no such column, the method returns nil.

To access columns via their indexes or visible indexes, use the Columns or the VisibleColumn property respectively.


TcxCustomTreeListControl.CopyAllToClipboard

TcxCustomTreeListControl

Copies all TreeList nodes to the clipboard.

procedure CopyAllToClipboard;

Description

Use this method to copy all TreeList nodes and column headers (if enabled, see Headers) to the clipboard.  Tabs delimit columns.

Note: this method copies all nodes regardless of their visibility.

Alternatively, you can copy selected nodes only to the clipboard using the CopySelectedToClipboard method.

The TreeList contents are stored within the clipboard as text.


TcxCustomTreeListControl.CopySelectedToClipboard

TcxCustomTreeListControl

Copies selected TreeList nodes to the clipboard.

procedure CopySelectedToClipboard;

Description

Use the CopySelectedToClipboard method to copy selected nodes only and all column headers (if enabled, see Headers) of the TreeList control to the clipboard.  Tabs delimit columns.

Alternatively, you can copy all nodes and column headers to the clipboard using the CopyAllToClipboard method.

The TreeList contents are stored within the clipboard as text.


TcxCustomTreeListControl.Create

TcxCustomTreeListControl

Creates and initializes an instance of the TcxCustomTreeListControl control.

constructor Create(AOwner: TComponent); override;

Description

You can use the Create method to create and initialize an instance of the TcxCustomTreeListControl control by code.  The constructor creates an empty list of nodes and assigns 250 and 150 pixels to the Width and Height properties respectively.


TcxCustomTreeListControl.CreateColumn

TcxCustomTreeListControl          Example

Creates a new column.

function CreateColumn(ABand: TcxTreeListBand = nil): TcxTreeListColumn; virtual;

Description

Use the CreateColumn method to create a new column within the control.  The ABand parameter represents the TcxTreeListBand to which the new column belongs.  When the ABand parameter is nil, the column is assigned to either the first visible band or to the first band within the band collection of the control.  If there are no existing bands, a new band is created.  If the ABand parameter points to an existing band, the new column is assigned to it.  The column is added to the end of the band’s Band.Columns collection.


TcxCustomTreeListControl.DeleteAllColumns

TcxCustomTreeListControl

Deletes all columns within the control.

procedure DeleteAllColumns; virtual;

Use the DeleteAllColumns method to remove all columns from the TreeList control.  When all columns are removed from the TreeList control, it displays nothing.


TcxCustomTreeListControl.DeleteSelection

TcxCustomTreeListControl          See Also

Deletes selected nodes from the control.

procedure DeleteSelection;

Description

Use the DeleteSelection method to delete selected nodes including their child nodes.

Alternatively, you can delete all nodes from the control using the Clear method.


TcxCustomTreeListControl.Deselect

TcxCustomTreeListControl

Unselects a node.

procedure Deselect(Node: TcxTreeListNode); virtual;

Description

Use the Deselect method to unselect the node specified via the Node parameter.

Additionally, you can unselect all nodes within the control using the ClearSelection method.  To determine the number of selected nodes within the control, use the SelectionCount property.  To obtain indexed access to selected nodes, use the object exposed via the Selections property.


TcxCustomTreeListControl.Destroy

TcxCustomTreeListControl

Destroys the control.

destructor Destroy; override;

Description

It is best to use the Free method instead of Destroy.


TcxCustomTreeListControl.Find

TcxCustomTreeListControl

Locates a treelist node.

type

    TcxTreeListFindFunc = function(ANode: TcxTreeListNode; AData: Pointer): Boolean;

function Find(AData: Pointer; AStart: TcxTreeListNode; AExpandedOnly, AForward: Boolean; AFilter: TcxTreeListFindFunc): TcxTreeListNode; virtual;

Description

Use the Find method to locate a treelist node.  The search starts from the node, specified via the AStart parameter.  The AExpandedOnly parameter specifies whether the child nodes of the expanded parents are included into the search. The AForward parameter specifies the search direction.  The AFilter parameter specifies the function performing the search.

Create your own implementation of the TcxTreeListFindFunc function to implement the required search criteria.

The return value of this method is the located node.  If this method cannot locate node by the specified text, it returns nil.


TcxCustomTreeListControl.FindNext

TcxCustomTreeListControl          Example

Locates the next node containing the search text.

function FindNext(AForward: Boolean): Boolean;

Description

The FindNext method lets you perform incremental search using code.  When the method is called, it tries to locate the next/previous node by searching cells in the focused column for one that contains a value that starts with the search string.

The AForward parameter specifies the search direction.  If set to True, a forward search is performed; otherwise, the collection is scanned backward.  If the search reaches the last node, it wraps to the first node.

The search string is defined by the SearchingText property.

If the method finds a match for a given search string, it returns True; otherwise, False is returned.

Note: if there is no column focused, the method returns False indicating that it failed to find a match.


TcxCustomTreeListControl.FindNodeByText

TcxCustomTreeListControl

Locates a treelist node by that node’s text.

function FindNodeByText(const AText: string; AColumn: TcxTreeListColumn; AStartNode: TcxTreeListNode = nil; AExpandedOnly: Boolean = False; AForward: Boolean = True): TcxTreeListNode;

Description

Use the FindNodeByText method to locate the treelist node by the text displayed in one of the node cells.  The text portion to locate is specified via the AText parameter.  The node’s cell containing the specified text is identified via the AColumn parameter.  The treelist node from which the search starts is specified via the AStartNode parameter.  The AExpandOnly parameter determines whether the expanded child nodes of the expanded parents are involved into search.  The AForward parameter specifies the search direction.

The return value of this method is the located node.  If this method cannot locate node by the specified text, it returns nil.


TcxCustomTreeListControl.FullCollapse

TcxCustomTreeListControl

Recursively collapses all nodes within the control.

procedure FullCollapse;

Description

Use the FullCollapse method to collapse all nodes recursively.

You can expand all nodes by using the FullExpand method.

Also, you can collapse a particular node using the Collapse method.


TcxCustomTreeListControl.FullExpand

TcxCustomTreeListControl

Recursively expands all nodes within the control.

procedure FullExpand;

Description

Use the FullExpand method to expand all nodes recursively.

You can collapse all nodes by using the FullCollapse method.

Also, you can expand a particular node using either the Expanded property or the Expand method.


TcxCustomTreeListControl.FullRefresh

TcxCustomTreeListControl

Refreshes data within the TreeList control.

procedure FullRefresh; virtual;

Description

Use the FullRefresh method when you need to refresh the control on screen.  Call this method to update the data representation after applying large changes to a dataset.


TcxCustomTreeListControl.GotoBOF

TcxCustomTreeListControl          See Also

Moves focus to the first visible node.

procedure GotoBOF;

Description

Use the GotoBOF method to move focus to the first visible node within the control.

Alternatively, you can move focus to the first node by assigning the first node to the FocusedNode property.  Doing so scrolls the vertical grid control until the first node becomes visible.

You can move focus to the last visible node within the control by using the GotoEOF method.


TcxCustomTreeListControl.GotoEOF

TcxCustomTreeListControl          See Also

Moves focus to the last visible node within the control.

procedure GotoEOF;

Description

Use the GotoEOF method to move focus to the last visible node within the control.

Also, you can move focus to the first visible node by using the GotoBOF method.


TcxCustomTreeListControl.GotoNext

TcxCustomTreeListControl          See Also

Moves focus to the next visible node.

procedure GotoNext;

Description

Use the GotoNext method to move focus to the next visible node.

Note: the method is only in effect if the control has a focused node, otherwise nothing happens.

Also, you can move focus to the previous visible node using the GotoPrev method.


TcxCustomTreeListControl.GotoNextPage

TcxCustomTreeListControl          See Also

Moves focus to the next page.

procedure GotoNextPage;

Description

Use the GotoNextPage method to move focus to the next page within the control.  This can be useful when you need to navigate the control quickly.  The page is the maximum number of whole nodes displayed on the screen.

To move focus to the previous page, use the GotoPrevPage method.

If you need to move focus to the first or to the last visible node, use the GotoBOF or the GotoEOF method.


TcxCustomTreeListControl.GotoPrev

TcxCustomTreeListControl          See Also

Moves focus to the previous visible node within the control.

procedure GotoPrev;

Description

Use the GotoPrev method to move focus to the previous visible node.  If there is no such node, this method does nothing.  To move focus to the next visible node, you should use the GotoNext method.


TcxCustomTreeListControl.GotoPrevPage

TcxCustomTreeListControl          See Also

Moves focus to the previous page.

procedure GotoPrevPage;

Description

Use the GotoPrevPage to move focus to the previous page within the control.  The page is the maximum umber of whole nodes displayed on the screen.  To move focus to the next page, use the GotoNextPage method.

If you need to move focus to the first or to the last visible node, use the GotoBOF or the GotoEOF method.


TcxCustomTreeListControl.HideEdit

TcxCustomTreeListControl

Hides the in-place editor.

procedure HideEdit;

Description

Use the HideEdit method to hide the in-place editor currently opened.  Any changes made by the end user are retained.

To determine whether a cell within the control is being edited, you can use the IsEditing property.

You can hide the in-place editor, thus canceling any changes by using the CancelEdit method.

Also, you can show the in-place editor for the cell currently active by using the ShowEdit method.


TcxCustomTreeListControl.IsBOF

TcxCustomTreeListControl          See Also

Indicates whether the first visible node is focused.

function IsBOF: Boolean;

Description

Use the IsBOF method to determine whether the first visible node within the control is focused.  To see if the last visible node is focused, use the IsEOF method.

To move focus to the first visible node within the control, use the GotoBOF method.

Note: when both the IsBOF and IsEOF methods return True, the TreeList does not contain any nodes.


TcxCustomTreeListControl.IsEOF

TcxCustomTreeListControl          See Also

Indicates whether the last visible node is focused.

function IsEOF: Boolean;

Description

Use the IsEOF method to determine whether the last visible node within the control is focused.  To see if the first node is focused, use the IsBOF method.

To move focus to the last visible node within the control, you should use, for instance, the GotoEOF method.

Note: when both the IsBOF and IsEOF methods return True, the TreeList does not contain any nodes.


TcxCustomTreeListControl.MakeDefaultLayout

TcxCustomTreeListControl          See Also

Restores the control’s default layout.

procedure MakeDefaultLayout; virtual;

Description

You can use this method when you need to restore the default sort order, the default width and options of Bands and Columns within the control.


TcxCustomTreeListControl.RestoreColumnsDefaults

TcxCustomTreeListControl

Restores all default column settings within the control.

procedure RestoreColumnsDefaults;

Description

Use the RestoreColumnsDefaults method to set the sort order (see SortOrder) to soNone, caption text alignment (horizontal and vertical) to taLeftJustify and vaTop respectively, and the width of each column within the control.  Additionally, default Column.Options settings are restored.

To restore default column widths, use the RestoreColumnsWidths method.


TcxCustomTreeListControl.RestoreColumnsWidths

TcxCustomTreeListControl

Restores column widths.

procedure RestoreColumnsWidths;

Description

Use the RestoreColumnsWidths method to restore all default column widths within the control.  Additionally, the RestoreDefaults method is called for each column.

To restore all default column settings, use the RestoreColumnsDefaults method.


TcxCustomTreeListControl.Select

TcxCustomTreeListControl

Selects a node emulating manual selection.

procedure Select(Node: TcxTreeListNode; ShiftState: TShiftState = []); virtual;

Description

Use this overloaded Select method to select a node or nodes emulating manual selection.  The number of nodes selected depends on the ShiftState parameter.

The Node parameter specifies the node to select.

The ShiftState parameter specifies which control buttons are considered to be pressed while selecting a node.

When the parameter is set to ssShift, the method selects a range of nodes starting from the focused node and ending at the node specified via the Node parameter.  This can be achieved at runtime by the end user selecting a node while holding the Shift key down.

When the parameter is set to ssCtrl, the method adds the node specified via the Node parameter to the current selection.  This can be achieved at runtime by the end user selecting a node while holding the Ctrl key down.

Other values of the ShiftState parameter have no effect.

procedure Select(const ANodes: array of TcxTreeListNode); virtual;

Description

Use this overloaded Select method to select nodes stored in an array.  This is equivalent to invoking the overloaded Select method several times with the ShiftState parameter set to ssCtrl.

procedure Select(ANodes: TList); virtual;

Description

Use this overloaded Select method to select nodes stored in a list of pointers.


TcxCustomTreeListControl.SelectAll

TcxCustomTreeListControl

Selects all nodes within the control.

procedure SelectAll;

Description

To select all nodes within the control, you need to enable the OptionsSelection.MultiSelect option.  In this case, the SelectAll method will recursively select all nodes within the control.

To select only the first level nodes, the OptionsSelection.MultiSelect option should be enabled.  If the OptionsSelection.MultiSelect option is disabled, the method will only select the focused node.

You can clear all node selection by using the ClearSelection method.


TcxCustomTreeListControl.ShowEdit

TcxCustomTreeListControl          See Also

Shows the in-place editor for the focused cell.

procedure ShowEdit;

Description

Use the ShowEdit method to enable the in-place editor of the currently active cell.

Note: the ShowEdit method is not in effect when either the OptionsData.Editing or the OptionsSelection.CellSelect option is disabled.

Additionally, you can hide the active in-place editor by using the HideEdit method.


TcxCustomTreeListControl.ShowEditByKey

TcxCustomTreeListControl

Activates the focused cell’s editor and passes the specified key to it.

procedure ShowEditByKey(AKey: Char);

Description

Use the ShowEditByKey method to activate the in-place editor of the focused cell and enter the char specified via the AKey parameter.

Also, you can activate the in-place editor by the mouse using the ShowEditByMouse method.


TcxCustomTreeListControl.ShowEditByMouse

TcxCustomTreeListControl

Emulates activating the focused cell’s in-place editor by using the mouse.

procedure ShowEditByMouse(X, Y: Integer; AShift: TShiftState);

Description

Use the ShowEditByMouse method to activate the focused cell’s in-place editor by code.  This method emulates activating the editor by the mouse.

The X and Y parameters specify the horizontal and vertical coordinates of the mouse cursor.  These coordinates are the control-related.

The AShift parameter specifies the shift state of the keyboard.

Alternatively, you can use the ShowEditByKey method to activate the in-place editor and pass the specified key to it.


TcxCustomTreeListControl.Subselect

TcxCustomTreeListControl

Adds a node to the selection.

procedure Subselect(Node: TcxTreeListNode); virtual;

Description

Use the Subselect method to add the node specified by the Node parameter to the current selection.

Note: the OptionsSelection.MultiSelect option must be enabled; otherwise an exception is raised.

Additionally, you can select all nodes at once by using the SelectAll method.  To unselect all nodes together, use the ClearSelection method.  To select a particular node, use the Select method. A node can be unselected using the Deselect method.

To determine the number of selected nodes, use the SelectionCount property.  To obtain indexed access to the list of selected nodes, use members of the object exposed via the Selections property.


TcxCustomTreeListControl.OnAfterSorting

TcxCustomTreeListControl          See Also

Fires after the TreeList has finished to sort nodes and check whether nodes should be displayed.

property OnAfterSorting: TNotifyEvent;

Description

Implement the OnAfterSorting event handler to provide custom behavior after nodes in the TreeList have been sorted.


TcxCustomTreeListControl.OnAfterSummary

TcxCustomTreeListControl          See Also

Occurs after all summaries have been calculated.

type

  TcxAfterSummaryEvent = procedure(ASender: TcxDataSummary) of object;

property OnAfterSummary: TcxAfterSummaryEvent;

Description

The OnAfterSummary event occurs after all summaries have been calculated.  You can read and change an individual summary value via the SummaryItem property.

The ASender parameter represents an object that can be used to obtain or to modify the summary value.  Read the Create Summaries topic for details.


TcxCustomTreeListControl.OnCollapsed

TcxCustomTreeListControl

Occurs after collapsing a node.

type

  TcxTreeListNodeChangedEvent = procedure(Sender: TObject; ANode: TcxTreeListNode) of object;

property OnCollapsed: TcxTreeListNodeChangedEvent;

Description

Write this event handler to perform actions after collapsing a node.

The Sender parameter represents the TreeList control that initiated the event.

The ANode parameter represents the node that has been collapsed.

In order to prevent a node from being collapsed, you should write an OnCollapsing event handler.

Note that the OnCollapsed event will not fire if the Allow parameter in the OnCollapsing event handler is set to False (which means that you prohibit collapsing the node).


TcxCustomTreeListControl.OnCollapsing

TcxCustomTreeListControl

Occurs before collapsing a node.

type

  TcxTreeListNodeChangingEvent = procedure(Sender: TObject; ANode: TcxTreeListNode; var Allow: Boolean) of object;

property OnCollapsing: TcxTreeListNodeChangingEvent;

Description

Write this event handler to perform actions before collapsing a node.  Also, you can prevent the node from being collapsed by using the Allow parameter.

The Sender parameter represents the TreeList control that initiated the event.

The ANode parameter represents the node that has been collapsed.

The Allow parameter specifies whether to allow the node to collapse.  Set the parameter to True to enable it.

To perform actions after collapsing a node, you should write an OnCollapsed event handler.

Note:	the OnCollapsed event will not fire if the OnCollapsing event handler’s Allow parameter is set to False.


TcxCustomTreeListControl.OnCompare

TcxCustomTreeListControl

Occurs when sorting records within the TreeList control.

type

  TcxTreeListNodeCompareEvent = procedure(Sender: TObject; ANode1, ANode2: TcxTreeListNode; var ACompare: Integer) of object;

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 parameter indicates that ANode1 is considered to be "less" than ANode2.  And vice versa, if the ACompare parameter is set to a positive value, ANode1 is considered to be "greater" than ANode2.  Two nodes are considered to be "equal" when the ACompare 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 values and place them at the bottom of all records, then group other rows according to their values (the same year, month) and so on.

The following sample code provides a handler for the OnCompare event.  Note that the TreeList contains integer values since comparing integer values is quite simple.

//Delphi

procedure TFormMain.tlMainCompare(Sender: TObject; ANode1,

  ANode2: TcxTreeListNode; var ACompare: Integer);

var

  val_ind : Integer;

begin

  val_ind := tlMain.FocusedColumn.ItemIndex;

  ACompare := ANode2.Values [val_ind] - ANode1.Values [val_ind];

end;


TcxCustomTreeListControl.OnCustomDrawBackground

TcxCustomTreeListControl

Occurs when the control’s background needs repainting.

type

  TcxCustomDrawBackgroundEvent = procedure(Sender: TObject; ACanvas: TcxCanvas; const R: TRect; var ADone: Boolean) of object;

property OnCustomDrawBackground: TcxCustomDrawBackgroundEvent;

Description

Write an OnCustomDrawBackground event handler to custom paint the control’s background.

The Sender parameter specifies the event sender, a TreeList control.

The ACanvas parameter specifies a TCanvas instance that provides the control’s background drawing surface.

The R parameter specifies the bounding rectangle of the control‘s background.

The ADone parameter specifies whether further background painting is needed.  Set the parameter to True to avoid default background painting; set it to False to enable the default painting routines.

The following sample code provides an OnCustomDrawBackground event handler that fills the control’s background with a bitmap.

//Delphi

//...

var

  b : TBitmap;

//...

procedure TFormMain.FormCreate(Sender: TObject);

begin

  b := TBitmap.Create;

  b.LoadFromFile('E:\EARTH16.BMP');

end;

//...

procedure TFormMain.tlMainCustomDrawBackground(Sender: TObject;

  ACanvas: TcxCanvas; const R: TRect; var ADone: Boolean);

begin

  ACanvas.FillRect(R, b); // fills the background rectangle with the bitmap specified

  ADone := True;

end;


TcxCustomTreeListControl.OnCustomDrawBandHeader

TcxCustomTreeListControl

Occurs when a band header needs repainting.

type

  TcxCustomDrawHeaderViewInfoEvent = procedure(Sender: TObject; ACanvas: TcxCanvas; AViewInfo: TcxTreeListHeaderViewInfo; var ADone: Boolean) of object;

property OnCustomDrawBandHeader: TcxCustomDrawHeaderViewInfoEvent;

Description

Write an OnCustomDrawBandHeader event handler to custom paint a band header.

The Sender parameter specifies the event sender, a TreeList control.

The ACanvas parameter specifies the TCanvas instance that provides the band header’s drawing surface.

The AViewInfo parameter specifies the TcxTreeListHeaderViewInfo instance that provides view information about the band header.  To get the bounding rectangle of the control’s background, you can use the BoundsRect property.

The ADone parameter specifies whether further painting is needed.  Set the parameter to True to avoid the default painting; set it to False to enable the default painting routines.

The following sample code provides simple drawing routines that paint the first visible band header.

//Delphi

procedure TFormMain.tlMainCustomDrawBandHeader(Sender: TObject;

  ACanvas: TcxCanvas; AViewInfo: TcxTreeListHeaderViewInfo;

  var ADone: Boolean);

begin

  if (Not AViewInfo.Band.IsMostLeft) then // draws the first visible band header within the control

    begin

      ADone := False; // default painting is not required

      Exit;

    end;

  cxApplyViewParams (ACanvas, AViewInfo.ViewParams); // applies the current font and color settings

  ACanvas.FillRect(AViewInfo.VisibleRect); // paints the band header’s background

  ACanvas.DrawTexT('CustomDrawBandHeader', AViewInfo.TextBounds, 0, True); // draws the band’s caption text

  ACanvas.FrameRect(AViewInfo.BoundsRect, clBlack); // draws the band’s borders

  ADone := True; // suppresses default painting routines

end;


TcxCustomTreeListControl.OnCustomDrawCell

TcxCustomTreeListControl

Occurs when a TreeList cell needs repainting.

type

  TcxCustomDrawEditCellViewInfoEvent = procedure(Sender: TObject; ACanvas: TcxCanvas; AViewInfo: TcxTreeListEditCellViewInfo; var ADone: Boolean) of object;

property OnCustomDrawCell: TcxCustomDrawEditCellViewInfoEvent;

Description

Write an OnCustomDrawCell event handler to custom draw a cell.

The Sender parameter specifies the event sender, a TreeList control.

The ACanvas parameter specifies the TCanvas instance that provides the cell’s drawing surface.

The AViewInfo parameter specifies the TcxTreeListEditCellViewInfo instance that provides view information about the cell being painted.  To get the cell’s bounding rectangle, you can use the BoundsRect property.

The ADone parameter specifies whether further painting is needed.  Set the parameter to True to avoid default cell painting; set it to False to enable the default painting routines.

The following sample code provides an OnCustomDrawCell event handler that applies currency formatting to values within the TreeList control.  Note that the TreeList control can contain only integer values (since the currency format cannot be applied to any other value type).

//Delphi

procedure TFormMain.tlMainCustomDrawCell(Sender: TObject;

  ACanvas: TcxCanvas; AViewInfo: TcxTreeListEditCellViewInfo;

  var ADone: Boolean);

begin

  AViewInfo.ViewParams.Font.Style := [fsBold];

  ACanvas.FillRect(AViewInfo.VisibleRect);

  ACanvas.DrawText(FormatCurr('$ 0.00', StrToInt(AViewInfo.DisplayValue)), AViewInfo.VisibleRect, 0, True);

  ADone := True;

end;


TcxCustomTreeListControl.OnCustomDrawCellsGroup

TcxCustomTreeListControl

Occurs when a cell group area needs repainting.

type

  TcxCustomDrawCellsGroupViewInfoEvent = procedure(Sender: TObject; ACanvas: TcxCanvas; AViewInfo: TcxTreeListCellsGroupViewInfo; var ADone: Boolean) of object;

property OnCustomDrawCellsGroup: TcxCustomDrawCellsGroupViewInfoEvent;

Description

Write an OnCustomDrawCellsGoup event handler to custom paint a cell group area.

The Sender parameter specifies the event sender, a TreeList control.

The ACanvas parameter specifies the TCanvas type instance that provides the drawing surface.

The AViewInfo parameter specifies the TcxTreeListEditCellsGroupViewInfo instance that provides view information about the cell group area being painted.  To get its bounding rectangle, you can use the BoundsRect property.

The ADone parameter specifies whether further painting is needed.  Set the parameter to True to avoid default cell group area painting; set it to False to enable the default painting routines.

The following picture demonstrates the TreeList control with cell group areas filled with red:


TcxCustomTreeListControl.OnCustomDrawFooter

TcxCustomTreeListControl

Occurs when the footer needs repainting.

type

  TcxCustomDrawBandViewInfoEvent = procedure(Sender: TObject; ACanvas: TcxCanvas; AViewInfo: TcxTreeListBandViewInfo; var ADone: Boolean) of object;

property OnCustomDrawFooter: TcxCustomDrawBandViewInfoEvent;

Description

Write an OnCustomDrawFooter event handler to custom paint the footer.

The Sender parameter specifies the event sender, a TreeList control.

The ACanvas parameter specifies the TCanvas instance that provides the footer’s drawing surface.

The AViewInfo parameter specifies the TcxTreeListBandViewInfo instance that provides view information about the footer.  To get its bounding rectangle, you can use the BoundsRect property.

The ADone parameter specifies whether further painting is needed.  Set the parameter to True to avoid default footer painting; set it to False to enable the default painting routines.

Note that if the footer is disabled (see Footer), the event is not fired.

Additionally, you can custom paint an individual footer cell by writing an OnCustomDrawFooterCell event handler.

//Delphi

procedure TFormMain.tlMainCustomDrawFooter(Sender: TObject;

  ACanvas: TcxCanvas; AViewInfo: TcxTreeListBandViewInfo;

  var ADone: Boolean);

begin

  cxApplyViewParams (ACanvas, AViewInfo.ViewParams);

  ACanvas.Brush.Color := $FAE6E6; // specifies the footer panel color (lavender)

  ACanvas.FillRect(AViewInfo.VisibleRect); // fills the footer panel’s background with the color previously specified

  ADone := True; // suppresses the default painting routines

end;


TcxCustomTreeListControl.OnCustomDrawFooterCell

TcxCustomTreeListControl

Occurs when an individual footer cell needs repainting.

type

  TcxCustomDrawFooterItemViewInfoEvent = procedure(Sender: TObject; ACanvas: TcxCanvas; AViewInfo: TcxTreeListFooterItemViewInfo; var ADone: Boolean) of object;

property OnCustomDrawFooterCell: TcxCustomDrawFooterItemViewInfoEvent;

Description

Write an OnCustomDrawFooterCell event handler to custom paint individual footer cells.

The Sender parameter specifies the event sender, a TreeList control.

The ACanvas parameter specifies the TCanvas instance that provides the footer cell’s drawing surface.

The AViewInfo parameter specifies the TcxTreeListFooterItemViewInfo instance that provides view information about the footer cell being painted.  To get its bounding rectangle, you can use the BoundsRect property.

The ADone parameter specifies whether further painting is needed.  Set the parameter to True to avoid default footer cell painting; set it to False to enable the default painting routines.

Note that if the footer is disabled (see Footer), the event is not fired.

Additionally, you can custom paint the footer by writing an OnCustomDrawFooter event handler.

The following sample code shows how to handle the OnCustomDrawFooterCell event to paint a column’s footer cell.

//Delphi

procedure TFormMain.tlMainCustomDrawFooterCell(Sender: TObject;

  ACanvas: TcxCanvas; AViewInfo: TcxTreeListFooterItemViewInfo;

  var ADone: Boolean);

begin

  cxApplyViewParams (ACanvas, AViewInfo.ViewParams); // specifies the default color and font settings

  ACanvas.Brush.Color := $FAE6E6; // specifies the background color (lavender)

  ACanvas.FillRect(AViewInfo.VisibleRect); // paints the footer cell’s background with the color specified

  ACanvas.DrawText(AViewInfo.Text, AViewInfo.VisibleRect, 0, True); // draws the formatted summary value

  ACanvas.FrameRect(AViewInfo.VisibleRect, clBlack, 1); // draws a frame around the footer cell

  ADone := True; // suppresses the default painting routines

end;


TcxCustomTreeListControl.OnCustomDrawHeader

TcxCustomTreeListControl          See Also

Occurs when a column header needs repainting.

type

  TcxCustomDrawBandViewInfoEvent = procedure(Sender: TObject; ACanvas: TcxCanvas; AViewInfo: TcxTreeListBandViewInfo; var ADone: Boolean) of object;

property OnCustomDrawHeader: TcxCustomDrawBandViewInfoEvent;

Description

Write an OnCustomDrawHeader event handler to custom paint column headers.

The Sender parameter specifies the event sender, a TreeList control.

The ACanvas parameter specifies the TCanvas instance that provides the drawing surface.

The AViewInfo parameter specifies the TcxTreeListBandViewInfo instance that provides view information about the header being painted.  To get its bounding rectangle, you can use the BoundsRect property.

The ADone parameter specifies whether further painting is needed.  Set the parameter to True to avoid default header painting; set it to False to enable the default painting routines.

//Delphi

procedure TFormMain.tlMainCustomDrawHeader(Sender: TObject;

  ACanvas: TcxCanvas; AViewInfo: TcxTreeListBandViewInfo;

  var ADone: Boolean);

begin

  ACanvas.Brush.Color := $FAE6E6; // specifies the header color

  ACanvas.FillRect(AViewInfo.VisibleRect); // paints the header

  ADone := True; // suppresses default painting routines

end;


TcxCustomTreeListControl.OnCustomDrawHeaderCell

TcxCustomTreeListControl          See Also

Occurs when a header cell needs repainting.

type

  TcxCustomDrawHeaderViewInfoEvent = procedure(Sender: TObject; ACanvas: TcxCanvas; AViewInfo: TcxTreeListHeaderViewInfo; var ADone: Boolean) of object;

property OnCustomDrawHeaderCell: TcxCustomDrawHeaderViewInfoEvent;

Description

Write an OnCustomDrawHeaderCell event handler to custom paint column headers.

The Sender parameter specifies the event sender, a TreeList control.

The ACanvas parameter specifies the TCanvas instance that provides the header cell’s drawing surface.

The AViewInfo parameter specifies the TcxTreeListHeaderViewInfo instance that provides view information about the header cell being painted.  To get its bounding rectangle, you can use the BoundsRect property.

The ADone parameter specifies whether further painting is needed.  Set the parameter to True to avoid default header cell painting; set it to False to enable the default painting routines.

The following sample code shows the use of the OnCustomDrawHeaderCell event.  The event handler paints the column header changing the font style to bold and the background color to lavender. Additionally, the handler paints a sorting mark within sorted column headers.

//Delphi

procedure TFormMain.tlMainCustomDrawHeaderCell(Sender: TObject;

  ACanvas: TcxCanvas; AViewInfo: TcxTreeListHeaderViewInfo;

  var ADone: Boolean);

begin

  cxApplyViewParams (ACanvas, AViewInfo.ViewParams); // specifies the default color and font settings

  AViewInfo.ViewParams.Font.Style := [fsBold]; // changes the font style to bold

  ACanvas.Brush.Color := $FAE6E6; // specifies the column header’s background color

  ACanvas.FillRect(AViewInfo.VisibleRect); // paints the column header

  ACanvas.DrawTexT(AViewInfo.Text, AViewInfo.VisibleRect, 0, True); // draws the column’s caption

  ACanvas.FrameRect(AViewInfo.VisibleRect, clBlack, 1); // draws a frame around the header

  with TcxTreeListColumnHeaderViewInfo(AViewInfo) do

    if (SortOrder <> soNone) then

        TcxTreeList(Sender).LookAndFeel.Painter.DrawSortingMark(ACanvas, SortMarkBounds, SortOrder = soAscending); // paints the sorting mark if sorting is applied

  ADone := True; // suppresses the default painting routines

end;


TcxCustomTreeListControl.OnCustomDrawIndentCell

TcxCustomTreeListControl

Occurs when node indents need repainting.

type

  TcxCustomDrawIndentViewInfoEvent = procedure(Sender: TObject; ACanvas: TcxCanvas; AViewInfo: TcxTreeListIndentViewInfo; var ADone: Boolean) of object;

property OnCustomDrawIndentCell: TcxCustomDrawIndentViewInfoEvent;

Description

Write an OnCustomDrawIndentCell event handler to custom paint node indents.  Note: node images also relate to the indent area.

The Sender parameter specifies the event sender, a TreeList control.

The ACanvas parameter specifies the TCanvas instance that provides the node indent’s drawing surface.

The AViewInfo parameter specifies the TcxTreeListIndentViewInfo instance that provides view information about the node indent area being painted.  To get its bounding rectangle, you can use the BoundsRect property.

The ADone parameter specifies whether further painting is needed.  Set the parameter to True to avoid default node indent area painting; set it to False to enable the default painting routines.

The following OnCustomDrawIndentCell event handler shows how to paint an indent. Additionally, the handler checks whether the indent contains an expand button, and if so, paints it (the InternalDrawExpandButton and InternalDrawExpandButtonCross procedures are used).

//Delphi

procedure TFormMain.tlMainCustomDrawIndentCell(Sender: TObject;

  ACanvas: TcxCanvas; AViewInfo: TcxTreeListIndentViewInfo;

  var ADone: Boolean);

  procedure InternalDrawExpandButtonCross(ACanvas: TcxCanvas; const R: TRect; AExpanded: Boolean; AColor: TColor);

  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: TColor = clDefault);

  begin

    ACanvas.FrameRect(R);

    if AColor <> clDefault then

    begin

      InflateRect(R, -1, -1);

      ACanvas.Brush.Color := AColor;

      ACanvas.FillRect(R);

      InflateRect(R, 1, 1);

    end;

    InternalDrawExpandButtonCross(ACanvas, R, AExpanded, clBtnText);

  end;

begin

  cxApplyViewParams (ACanvas, AViewInfo.ViewParams); // assignes the default font and color settings

  ACanvas.Brush.Color := $FAE6E6 - $000100; // specifies the indent cell color

  ACanvas.FillRect(AViewInfo.VisibleRect); // paints indent cells

  if (AViewInfo.HasButton) then

    begin

      InternalDrawExpandButton(ACanvas, AViewInfo.ButtonRect, AViewInfo.Node.Expanded); // if the current indent cell painted belongs to a group node then paint the expand button

    end;

  ADone := True; // suppresses default painting routines

end;


TcxCustomTreeListControl.OnCustomDrawIndicatorCell

TcxCustomTreeListControl

Occurs when an indicator cell needs repainting.

type

  TcxCustomDrawIndicatorViewInfoEvent = procedure(Sender: TObject; ACanvas: TcxCanvas; AViewInfo: TcxTreeListIndicatorViewInfo; var ADone: Boolean) of object;

property OnCustomDrawIndicatorCell: TcxCustomDrawIndicatorViewInfoEvent;

Description

Write an OnCustomDrawIndicatorCell event handler to custom paint an indicator cell.

The Sender parameter specifies the event sender, a TreeList control.

The ACanvas parameter specifies the TCanvas instance that provides the indicator cell’s drawing surface.

The AViewInfo parameter specifies the TcxTreeListIndicatorViewInfo instance that provides view information about the indicator cell area being painted.  To get its bounding rectangle, you can use the BoundsRect property.

The ADone parameter specifies whether further painting is needed.  Set the parameter to True to avoid default indicator cell painting; set it to False to enable the default painting routines.

The following sample code shows an OnCustomDrawIndicatorCell event handler that paints indicator cells within the indicator column and, in addition, draws an indicator image (against the focused node).

//Delphi

procedure TFormMain.tlMainCustomDrawIndicatorCell(Sender: TObject;

  ACanvas: TcxCanvas; AViewInfo: TcxTreeListIndicatorViewInfo;

  var ADone: Boolean);

var

  IndicatorKind: TcxIndicatorKind;

  procedure InternalDrawIndicatorImage(ACanvas: TcxCanvas;

    const R: TRect; AKind: TcxIndicatorKind); // paints the indicator image (arrow)

  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;

    cxIndicatorImages.Draw(ACanvas.Canvas, X, Y, Ord(AKind) - 1); // draws built-in indicator images

  end;

begin

  ACanvas.Brush.Color := $FAE6E6; // specifies the background color

  ACanvas.FillRect(AViewInfo.VisibleRect); // paints the background

  if (AViewInfo.Node <> nil) and (AViewInfo.Node.Focused) then

    IndicatorKind := ikArrow // the corresponding node is focused

  else

    IndicatorKind := ikNone; // the corresponding node is not focused

  InternalDrawIndicatorImage (ACanvas, AViewInfo.BoundsRect, IndicatorKind);

  ACanvas.FrameRect(AViewInfo.BoundsRect, clBlack, 1); // draws a frame around the indicator cell

  ADone := True; // suppresses the default painting routines

end;


TcxCustomTreeListControl.OnCustomDrawPreview

TcxCustomTreeListControl

Occurs when a preview section needs repainting.

type

  TcxCustomDrawEditCellViewInfoEvent = procedure(Sender: TObject; ACanvas: TcxCanvas; AViewInfo: TcxTreeListEditCellViewInfo; var ADone: Boolean) of object;

property OnCustomDrawPreview: TcxCustomDrawEditCellViewInfoEvent;

Description

Write a handler for the OnCustomDrawPreview event to custom paint a preview section.

The Sender parameter specifies the event sender, a TreeList control.

The ACanvas parameter specifies the TCanvas instance that provides the preview section’s drawing surface.

The AViewInfo parameter specifies the TcxTreeListEditCellViewInfo instance that provides view information about the preview section being painted.  To get its bounding rectangle, you can use the BoundsRect property.

The ADone parameter specifies whether further painting is needed.  Set the parameter to True to avoid default preview section painting; set it to False to enable the default painting routines.

The following sample code shows how to paint a preview section using an OnCustomDrawPreview event handler. The visual style of the preview section for the focused node differs from the other preview sections.

//Delphi

procedure TFormMain.tlMainCustomDrawPreview(Sender: TObject;

  ACanvas: TcxCanvas; AViewInfo: TcxTreeListEditCellViewInfo;

  var ADone: Boolean);

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;

  ACanvas.FillRect(AViewInfo.BoundsRect); // paints the preview section’s background

  ACanvas.Font.Style := [fsItalic]; // changes the font style to italic

  ACanvas.DrawTexT(AViewInfo.DisplayValue, AViewInfo.VisibleRect, 0, True); // draws the preview section’s contents

  ADone := True; // suppresses the default painting routines

end;


TcxCustomTreeListControl.OnCustomizationFormVisibleChanged

TcxCustomTreeListControl

Occurs after the customization form’s visibility changes.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnCustomizationFormVisibleChanged: TNotifyEvent;

Description

Write an event handler to perform action(s) after the customization form’s visibility changes.

To show the customization form, set its Visible property to True.

Note: the customization form will not be displayed:

1.	if headers are disabled using the Headers property

2.	if the control has no columns


TcxCustomTreeListControl.OnDeletion

TcxCustomTreeListControl

Occurs when a node is being deleted.

type

  TcxTreeListNodeChangedEvent = procedure(Sender: TObject; ANode: TcxTreeListNode) of object;

property OnDeletion: TcxTreeListNodeChangedEvent;

Description

Use the OnDeletion event handler to release all the resources associated with the current node’s data object (see the TcxTreeListNode.Data property) before the node is deleted. In fact, it should be done when working in unbound mode.

The Sender parameter specifies the TreeList control that initiated the event.

The ANode parameter specifies the node being deleted.

The following example shows how to deallocate the current node’s data object when the node is about to be deleted:

procedure TForm1.cxTreeListDeletion(Sender: TObject;

  ANode: TcxTreeListNode);

begin

  P := ANode.Data;

  if P <> nil then

    Dispose(P);

end;


TcxCustomTreeListControl.OnEdited

TcxCustomTreeListControl

Fires when the cell’s in-place editor closes.

type

  TcxTreeListColumnChangedEvent = procedure(Sender: TObject; AColumn: TcxTreeListColumn) of object;

property OnEdited: TcxTreeListColumnChangedEvent;

Description

Implement the OnEdited event handler to perform actions after the cell’s in-place editor is deactivated.

The Sender parameter specifies the TreeList control that initiated the event.

The AColumn parameter specifies the column to which the cell belongs.

In order to prohibit editing a node’s cell value, you should write an OnEditing event handler.


TcxCustomTreeListControl.OnEditing

TcxCustomTreeListControl

Occurs when the end user starts editing a node’s cell value.

type

  TcxTreeListEditingEvent = procedure(Sender: TObject; AColumn: TcxTreeListColumn; var Allow: Boolean) of object;

property OnEditing: TcxTreeListEditingEvent;

Description

Write an OnEditing event handler to perform actions when a node’s cell value is being edited.

The Sender parameter specifies the TreeList control that initiated the event.

The AColumn parameter specifies the column to which the cell belongs.

The Allow parameter specifies whether to allow the end user to edit the cell’s value.  Set the parameter to True (default) to enable cell value editing; set it to False, to prevent the cell value from being changed.

Handle the OnEdited event if you want to respond after the node‘s cell value has been edited.


TcxCustomTreeListControl.OnExpanded

TcxCustomTreeListControl

Occurs after a node has been expanded.

type

  TcxTreeListNodeChangedEvent = procedure(Sender: TObject; ANode: TcxTreeListNode) of object;

property OnExpanded: TcxTreeListNodeChangedEvent;

Description

Write an OnExpanded event handler to perform actions after a node has been expanded.

The Sender parameter specifies the TreeList control that initiated the event.

The ANode parameter specifies the node that has just been expanded.

If you want to respond before the node is actually expanded, use the OnExpanding event.


TcxCustomTreeListControl.OnExpanding

TcxCustomTreeListControl

Occurs before a node is expanded.

type

  TcxTreeListNodeChangingEvent = procedure(Sender: TObject; ANode: TcxTreeListNode; var Allow: Boolean) of object;

property OnExpanding: TcxTreeListNodeChangingEvent;

Description

Write an OnExpanding event handler to perform actions before a node is expanded.

The Sender parameter specifies the TreeList control that initiated the event.

The ANode parameter specifies the node to be expanded.

If you want to respond after the node is expanded, you should use the OnExpanded event.

Read the Dynamic Loading topic for example.


TcxCustomTreeListControl.OnFocusedNodeChanged

TcxCustomTreeListControl

Fires after an active node has been changed.

type

  TcxTreeListFocusedChangedEvent = procedure(Sender: TObject; APrevFocusedNode, AFocusedNode: TcxTreeListNode) of object;

property OnFocusedNodeChanged: TcxTreeListFocusedChangedEvent;

Description

Implement the OnFocusedNodeChanged event handler to provide custom code after focus has switched to another node.

The Sender parameter specifies the TreeList control generated this event.

The APrevFocusedNode parameter specifies the node that has lost focus. This parameter returns nil value if there was no focused node before.

The AFocusedNode parameter specifies the node that has gained focus.


TcxCustomTreeListControl.OnGetNodeImageIndex

TcxCustomTreeListControl          Example

Occurs when images need to be assigned to nodes.

type

  TcxTreeListGetNodeImageIndexEvent = procedure(Sender: TObject; ANode: TcxTreeListNode; AIndexType: TcxTreeListImageIndexType; var AIndex: TImageIndex) of object;

property OnGetNodeImageIndex: TcxTreeListGetNodeImageIndexEvent;

Description

Write an OnGetNodeImageIndex event handler to assign images to nodes.

The Sender parameter specifies the TreeList control that initiated the event.

The ANode parameter specifies the node whose images need to be assigned.

The AIndexType parameter specifies the type of the image currently assigned.

The AIndex parameter specifies the image index to assign to the node.  This refers to an image by its index within an ImageList object containing the required images.

You can analyze the AIndexType parameter value to determine which type of image is currently being processed and modify the AIndex parameter value to specify a new image for the node.


TcxCustomTreeListControl.OnGetNodePreviewHeight

TcxCustomTreeListControl

Occurs when the preview section’s height is calculated.

type

  TcxTreeListGetNodePreviewHeightEvent = procedure(Sender: TObject; ANode: TcxTreeListNode; const ADisplayValue: Variant; var AHeight: Integer) of object;

property OnGetNodePreviewHeight: TcxTreeListGetNodePreviewHeightEvent;

Description

Write an OnGetNodePreviewHeight event handler to change the preview section’s height.

The Sender parameter specifies the TreeList control that initiated the event.

The ANode parameter specifies the node whose preview section’s height is calculated.

The ADisplayValue represents the value displayed within the preview section.

The AHeight parameter defines the preview section’s height.

You can analyze the ADisplayValue parameter to determine the length of the preview section’s contents and make a decision whether the preview section’s height should be changed.  To determine the initial height of the preview section, you should use the AHeight parameter.  Set the AHeight parameter to a new value to change the preview section’s height.


TcxCustomTreeListControl.OnHotTrackNode

TcxCustomTreeListControl          Example

Occurs when the end user moves the mouse pointer over TreeList nodes.

type

  TcxTreeListOnHotTrackNodeEvent = procedure(Sender: TObject; ANode: TcxTreeListNode; AShift: TShiftState; var ACursor: TCursor) of object;

property OnHotTrackNode: TcxTreeListOnHotTrackNodeEvent;

Description

Write an event handler to perform actions when the end user moves the mouse pointer over TreeList nodes.

The Sender parameter represents the TreeList control (see TreeList) that initiated the event.

The ANode parameter returns the node being hot-tracked.  You can use this parameter to determine which node is currently under the mouse pointer and change the cursor (see the ACursor parameter) appropriately. For example, to crNo to indicate that no operations are allowed with the current node.

The AShift parameter specifies the keyboard’s shift state.

The ACursor parameter specifies the cursor.  You can use this parameter to change the cursor when it is over a particular node.


TcxCustomTreeListControl.OnIsGroupNode

TcxCustomTreeListControl          See Also           Example

Occurs for each group node within the control.

type

  TcxTreeListIsGroupNodeEvent = procedure(Sender: TObject; ANode: TcxTreeListNode; var IsGroup: Boolean) of object;

property OnIsGroupNode: TcxTreeListIsGroupNodeEvent;

Description

The OnIsGroupNode event occurs when the TreeList control’s OptionsView.PaintStyle is tlpsCategorized.  Categorized data representation means that column values occupy the whole nodes (if they have child nodes).

The Sender parameter represents the TreeList control that initiated the event.

The ANode parameter returns the node being processed.  The IsGroup parameter allows you to specify whether the node is a group node.  This parameter returns True for the nodes that have children.  Setting this parameter to False sets a group node back to standard.


TcxCustomTreeListControl.OnMoveTo

TcxCustomTreeListControl

Occurs when the end user drags nodes within the control.

type

  TcxTreeListMoveToEvent = procedure(Sender: TObject; AttachNode: TcxTreeListNode; AttachMode: TcxTreeListNodeAttachMode; Nodes: TList; var IsCopy, Done: Boolean) of object;

property OnMoveTo: TcxTreeListMoveToEvent;

Description

Write an event handler to perform actions when the end user drags nodes within the control.  The parameters passed to the event handler allow you to determine whether the node(s) being dragged should be copied or moved to a new location and whether default drag processing should be replaced by custom handling.

The Sender parameter provides access to the TreeList (see TreeList) control that initiated the event.

The AttachNode parameter represents the node to which the node(s) being dragged should be attached (these nodes will become children of that node).

The AttachMode parameter allows you to specify how the node(s) being dragged are attached to the target node.

The Nodes parameter contains a list of the nodes being dragged.

The IsCopy parameter specifies whether the node(s)being dragged should be copied to the new location.  Set the parameter to True to make a copy of the nodes being dragged.  Set it to False to move them to the new location.

The Done parameter allows you to suppress the default dragging logic.  Set the parameter to True to indicate that you are going to relocate or copy (see the IsCopy parameter) nodes manually instead of using the default processing.  Set the parameter to False to allow the control to move or to copy the nodes being dragged.

Note: the control’s DragMode property should be set to dmAutomatic to drag nodes automatically.

Additionally, to drag several nodes at once, the MultiSelect option should be enabled.


TcxCustomTreeListControl.OnNodeChanged

TcxCustomTreeListControl

Fires when the data has been changed in one of the current node's cells.

type

  TcxTreeListNodeDataChangedEvent = procedure(Sender: TObject; ANode: TcxTreeListNode; AColumn: TcxTreeListColumn) of object;

property OnNodeChanged: TcxTreeListNodeDataChangedEvent;

Description

Implement the OnNodeChanged event handler to perform post-processing after the data has been changed in one of the current node’s cells.

The Sender parameter represents the TreeList control;

The ANode parameter specifies the node in which the data has been changed;

The AColumn parameter specifies the node’s cell that the data was changed in.

Note: the OnNodeChanged event fires only when working in provider or unbound mode.


TcxCustomTreeListControl.OnSelectionChanged

TcxCustomTreeListControl

Occurs when selection is changed within the control.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnSelectionChanged: TNotifyEvent;

Description

Write an event handler to perform actions after selection has changed.

The Sender parameter gives access to the TreeList control that initiated the event.

You can determine the number of selected nodes using the SelectionCount property.  To get indexed access to a particular selected node within the collection, use the Selections property.  To select several nodes at once, you should enable the OptionsSelection.MultiSelect option.


TcxCustomTreeListControl.OnSorting

TcxCustomTreeListControl          See Also

Fires before the TreeList begins to sort nodes and check whether nodes should be displayed.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnSorting: TNotifyEvent;

Description

Implement the OnSorting event handler to provide custom behavior before nodes in the TreeList are being sorted.


TcxCustomTreeListControl.OnSummary

TcxCustomTreeListControl          See Also

Occurs when calculating a summary value.

type

  TcxSummaryEvent = procedure(ASender: TcxDataSummaryItems; Arguments: TcxSummaryEventArguments; var OutArguments: TcxSummaryEventOutArguments) of object;

property OnSummary: TcxSummaryEvent;

Description

Write an OnSummary event handler to change the summary calculation default behavior.

The Arguments and OutArguments parameters allow you to identify the summary currently calculated and to change its default behavior.

The ASender parameter specifies the summary item collection, which contains the TcxDataSummaryItem summary being calculated.

Consider the Create Summaries topic for details on modifying the summary value.


TcxCustomTreeListControl.OnTopRecordIndexChanged

TcxCustomTreeListControl

Occurs when scrolling the TreeList’s contents.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnTopRecordIndexChanged: TNotifyEvent;

Description

Write an event handler to perform actions when the end user scrolls the control’s contents.

The Sender parameter gives access to the TreeList control that initiated the event.

To determine the top visible node index, you should use the TopVisibleIndex property.  Alternatively, you can get access to the top visible node using the TopVisibleNode property.


TcxTreeList
TcxTreeList Object

Hierarchy          Properties          Methods          Events

Represents a control that allows data representation in a tree-like structure.

Unit

cxTL

TcxTreeList = class(TcxCustomTreeListControl)

Description

The TreeList control can be used to represent data in a tree-like structure.

The base element of the 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, the 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.

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.  Note: this feature needs to be enabled (see the MultiSort options description).  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.  The customization form is comprised of two sheets: the Bands sheet and the Columns sheet.   When the end user moves a band header to the customization form, the Bands sheet is displayed. Moving a column to the box results in the Columns sheet being displayed.  When a band or a column is moved to the customization form, it is removed from the 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.

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 panel.

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.  Sets of properties dealing with similar functionality are arranged in groups and are exposed by objects.  For instance, you can use the object exposed via the OptionsBehavior property to define the control’s user interaction behavior.   The OptionsData property can be used to specify which data operations are allowed, OptionsSelection determines the selection options for the control and so on.


TcxTreeList Hierarchy
Hierarchy

TcxExtEditingControl

     |

TcxCustomTreeListControl

     |


Properties for TcxTreeList
TcxTreeList Properties

TcxTreeList          Legend

Derived from TcxCustomTreeListControl

BandPanelHeight

Bands

ColumnCount

Columns

Count

Customizing

DefaultLayout

DefaultRowHeight

FocusedColumn

FocusedNode

FooterPanelHeight

HeaderHeight

HeaderPanelHeight

HitTest

Images

InplaceColumnIndex

InplaceEditor

IsActive

IsEditing

Items

LastNode

LevelIndentWidth

Nodes

OptionsBehavior

OptionsCustomizing

OptionsData

OptionsSelection

OptionsView

Preview

Searching

SearchingText

SelectionCount

Selections

Sorted

SortedColumnCount

SortedColumns

StateImages

Styles

TopNode

TopVisibleIndex

TopVisibleNode

VisibleBandCount

VisibleBands

VisibleColumnCount

VisibleColumns

VisibleCount

Derived from TcxExtEditingControl

OptionsBehavior

OptionsData

OptionsView

Derived from TcxEditingControl

BufferedPaint

LockUpdate

Styles

Derived from TcxControl

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel


Methods for TcxTreeList
TcxTreeList Methods

TcxTreeList          Legend

In TcxTreeList

 LoadFromFile

 LoadFromStream

 SaveToFile

 SaveToStream

Derived from TcxCustomTreeListControl

 AdjustColumnsWidth

 ApplyBestFit

 CancelEdit

 CancelSearching

 CellRect

 Clear

 ClearSelection

 ColumnByName

 CopyAllToClipboard

 CopySelectedToClipboard

 Create

 CreateColumn

 DeleteAllColumns

 DeleteSelection

 Deselect

 Destroy

 Find

 FindNext

 FindNodeByText

 FullCollapse

 FullExpand

 FullRefresh

 GotoBOF

 GotoEOF

 GotoNext

 GotoNextPage

 GotoPrev

 GotoPrevPage

 HideEdit

 IsBOF

 IsEOF

 MakeDefaultLayout

 RestoreColumnsDefaults

 RestoreColumnsWidths

 RestoreFromIniFile

 RestoreFromRegistry

 RestoreFromStream

 Select

 SelectAll

 ShowEdit

 ShowEditByKey

 ShowEditByMouse

 StoreToIniFile

 StoreToRegistry

 StoreToStream

 Subselect

Derived from TcxEditingControl

 BeginUpdate

 CancelUpdate

 EndUpdate

 LayoutChanged

Derived from TcxControl

 Create

 Destroy

 InvalidateRect


Events for TcxTreeList
TcxTreeList Events

TcxTreeList          Legend

Derived from TcxCustomTreeListControl

 OnAfterSorting

 OnAfterSummary

 OnCollapsed

 OnCollapsing

 OnCompare

 OnCustomDrawBackground

 OnCustomDrawBandHeader

 OnCustomDrawCell

 OnCustomDrawCellsGroup

 OnCustomDrawFooter

 OnCustomDrawFooterCell

 OnCustomDrawHeader

 OnCustomDrawHeaderCell

 OnCustomDrawIndentCell

 OnCustomDrawIndicatorCell

 OnCustomDrawPreview

 OnCustomizationFormVisibleChanged

 OnDeletion

 OnEdited

 OnEditing

 OnExpanded

 OnExpanding

 OnFocusedNodeChanged

 OnGetNodeImageIndex

 OnGetNodePreviewHeight

 OnHotTrackNode

 OnIsGroupNode

 OnMoveTo

 OnNodeChanged

 OnSelectionChanged

 OnSorting

 OnSummary

 OnTopRecordIndexChanged

 StylesEvents

Derived from TcxEditingControl

 OnCustomDrawCell

 OnEditChanged

 OnEdited

 OnEditing

 OnEditValueChanged

 OnInitEdit


TcxTreeListBand
TcxTreeListBand Object

Hierarchy          Properties          Methods

Represents a visual element within the control that is used to group columns.

Unit

cxTL

TcxTreeListBand = class(TcxInterfacedCollectionItem)

Description

The TcxTreeListBand object represents a visual TreeList element that is used to group columns.  All bands belong to the band collection accessible via the Bands property.

A band can contain a collection of associated columns accessible by the Columns property.  When a column belongs to a band, its caption is displayed within the band (assuming that column captions are not disabled via the control’s Headers property).  Columns can be relocated within bands manually or by using code.  To identify a band uniquely among the other bands within the control, you can determine its caption using its Caption property.  Since columns can be invisible, a band provides a collection of visible columns exposed via the TreeList.VisibleColumns property.  To determine the number of visible columns, you should use the TreeList.VisibleColumnCount property.

Like columns, bands can be invisible.  When a band is invisible, all its associated columns are invisible also. To change the band‘s visibility, you should use the Visible property.

A band can occupy a certain number of rows.  Each band row has at least one associated column (and therefore displays the column’s caption).  The band’s row collection is accessible via the BandRows property.

A band allows you to modify the width of its columns so that their captions occupy proportionally equal space within the band.  This can be done using the ApplyBestFit method.  Additionally, the band size can be changed by the end user and by code.

By default, bands are disabled.  To enable bands, you should activate the OptionsView.Bands option.


TcxTreeListBand Hierarchy
Hierarchy

TcxInterfacedCollectionItem

     |


Properties for TcxTreeListBand
TcxTreeListBand Properties

TcxTreeListBand          Legend

In TcxTreeListBand

Caption

ColumnCount

Columns

DisplayWidth

FixedKind

Index

IsMostLeft

IsMostRight

MinWidth

Options

Styles

Visible

VisibleColumnCount

VisibleColumns

VisibleIndex

Width


Methods for TcxTreeListBand
TcxTreeListBand Methods

TcxTreeListBand          Legend

In TcxTreeListBand

 ApplyBestFit

 Assign

 Create

 Destroy

 RestoreDefaults

 RestoreWidths


TcxTreeListBand.Caption

TcxTreeListBand

Provides access to the object representing the band’s caption.

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.


TcxTreeListBand.ColumnCount

TcxTreeListBand

Returns the number of columns associated with the band.

property ColumnCount: Integer;

Description

Read the ColumnCount property to determine the number of columns within the band.

You can get indexed access to individual columns by using the Columns property.  Additionally, you can obtain indexed access to all columns by using the TreeList.Columns property.

Additionally, you can determine the number of visible columns by using the VisibleColumnCount property.  To obtain indexed access to individual visible columns, use the VisibleColumns property.

ReadOnly Property


TcxTreeListBand.Columns

TcxTreeListBand

Provides indexed access to the collection of columns associated with the band.

property Columns[Index: Integer]: TcxTreeListColumn;

Description

Use the Columns property to obtain indexed access to individual columns within the band.

The Index parameter represents the column’s zero-based index within the band’s column collection.

To determine the number of columns within a band, use the ColumnCount property.

Additionally, you can obtain indexed access to a band’s visible columns by using the VisibleColumns property.  To determine the number of visible columns within a band, use the VisibleColumnCount property.


TcxTreeListBand.DisplayWidth

TcxTreeListBand

Returns the band’s actual width.

property DisplayWidth: Integer;

Description

Read the DisplayWidth property to obtain the band’s actual width in pixels.  To change the band’s width, you should use the Width property.

The main difference between the DisplayWidth property and the Width property is that the value returned by the first depends on several aspects, for instance, whether the automatic recalculation of column widths is enabled (see OptionsView.ColumnAutoWidth).

ReadOnly Property


TcxTreeListBand.FixedKind

TcxTreeListBand

Specifies whether the band is fixed to a TreeList edge.

type

  TcxTreeListBandFixedKind = (tlbfNone, tlbfLeft, tlbfRight);

property FixedKind: TcxTreeListBandFixedKind;

Description

Use the FixedKind property to specify that the band is not involved in horizontal scrolling.  The band can be fixed to the left or to the right.  Fixed bands cannot be moved within the control, but they can still be hidden by dragging onto the customization form.

Value	Meaning
tlbfNone	The band is not fixed
tlbfLeft	The band is fixed to the view’s left side
tlbfRight	The band is fixed to the view’s right side

For more detailed information about fixed bands, please read the Bands article.

The default value of the FixedKind property is tlbfNone.


TcxTreeListBand.Index

TcxTreeListBand

Returns the index of a given band.

property Index;

Description

Read the Index property to determine the band’s index within the collection of bands.  To obtain indexed access to individual bands within the collection, use the control’s Bands property.

Additionally, you can determine the band index within the visible bands collection by using the VisibleIndex property.  A band is visible when its Visible property is set to True.


TcxTreeListBand.IsMostLeft

TcxTreeListBand

Indicates whether the band is the left-most one displayed within the control.

property IsMostLeft: Boolean;

Description

When the band’s IsMostLeft property returns True, the band’s VisibleIndex returns 0.

To determine whether the band is the right-most one within the control, use the IsMostRight property.

ReadOnly Property


TcxTreeListBand.IsMostRight

TcxTreeListBand

Indicates whether the band is the right-most one displayed within the control.

property IsMostRight: Boolean;

Description

When the band’s IsMostRight property returns True, the band is located at the right of the control.

To determine whether the band is the left-most one within the control, use the IsMostLeft property.

ReadOnly Property


TcxTreeListBand.MinWidth

TcxTreeListBand

Returns the band’s minimum possible width.

property MinWidth: Integer;

Description

Read the MinWidth property to determine the minimum possible width of the band.  By default, the property returns 20.  The end user can change the band’s width by resizing it at runtime.  The MinWidth property ensures that the band will not be narrowed to a size less than that defined.

The default value of the MinWidth property is cxTreeListDefMinWidth.


TcxTreeListBand.Options

TcxTreeListBand

Specifies the ban’s various display and behavior properties.

property Options: TcxTreeListBandOptions;

Description

Using the object exposed via the Options property, you can specify whether the band can be customized, whether it can be sized or moved to another location and whether it can accept columns from other bands, etc.


TcxTreeListBand.Styles

TcxTreeListBand

Specifies the band’s various style settings.

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.


TcxTreeListBand.Visible

TcxTreeListBand

Indicates whether the band is visible.

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.


TcxTreeListBand.VisibleColumnCount

TcxTreeListBand          See Also

Returns the number of visible columns within the band.

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


TcxTreeListBand.VisibleColumns

TcxTreeListBand          See Also

Provides indexed access to individual visible columns.

property VisibleColumns[Index: Integer]: TcxTreeListColumn;

Description

The Index parameter specifies the zero-based index of the column within the list of visible columns.  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.


TcxTreeListBand.VisibleIndex

TcxTreeListBand          See Also

Represents the band’s index within the collection of visible bands.

property VisibleIndex: Integer;

Description

Read the VisibleIndex property to determine the band’s index within the collection of visible bands.

Additionally, you can determine the band’s index among all bands by using the Index property.


TcxTreeListBand.Width

TcxTreeListBand

Returns the band’s width.

property Width: Integer;

Description

Read the Width property to determine the band’s width.

Note that the actual width can differ from the Width property value.  This can happen when ColumnAutoWidth is enabled.

To determine the actual width, use the DisplayWidth property.

The default value of the Width property is cxTreeListDefWidth.


TcxTreeListBand.ApplyBestFit

TcxTreeListBand          Example

Adjusts the band’s width to display the content of all its columns.

procedure ApplyBestFit;

Description

Use the ApplyBestFit method to adjust the band’s width to display all its columns.

The ApplyBestFit method iterates through the columns and calculates the maximum width needed for column cells.  It also takes the width of the column caption (see the Caption property) and column footer cell (see Footer) into account.  By default, all data records are processed to calculate the best width.

It is possible to adjust the band’s width by double-clicking its right edge.  You can prevent a user from changing its width either by setting the band’s Sizing or the view’s BandHorzSizing property to False.


TcxTreeListBand.Assign

TcxTreeListBand

Copies the properties of another band.

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.


TcxTreeListBand.Create

TcxTreeListBand          See Also

Creates and initializes a TcxTreeListBand class instance.

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.


TcxTreeListBand.Destroy

TcxTreeListBand

Destroys the band.

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.


TcxTreeListBand.RestoreDefaults

TcxTreeListBand

Restores the band’s default settings.

procedure RestoreDefaults; virtual;

Description

This method calls the RestoreDefaults method of the Options object (exposed via the band’s Options property).  The method sets the Sizing, Customizing and Moving properties to True.  Also, the band’s RestoreWidths method is called and this restores the MinWidth, Width and DisplayWidth properties to their default values (20, 100 and 100 respectively).


TcxTreeListBand.RestoreWidths

TcxTreeListBand

Restores the band’s default width.

procedure RestoreWidths;

Description

Use the RestoreWidths method to restore the band’s default width.  The method sets the MinWidth property to the value provided by the cxTreeListDefMinWidth constant (20), the Width property to the cxTreeListDefWidth constant (100) and DisplayWidth to the Width property value.


TcxTreeListBandOptions
TcxTreeListBandOptions Object

Hierarchy          Properties

Provides a set of options controlling band manipulation.

Unit

cxTL

TcxTreeListBandOptions = class(TcxOwnedPersistent)

Description

The TcxTreeListBandOptions class is exposed via the band’s Options property and allows you to determine whether:

•	the band can be customized (see Customizing),

•	the band can be relocated using drag and drop functionality (see Moving),

•	the band can be resized (see Sizing),

•	the band can accept columns from other bands within the control (see OnlyOwnColumns).


TcxTreeListBandOptions Hierarchy
Hierarchy

TcxOwnedPersistent

     |


Properties for TcxTreeListBandOptions
TcxTreeListBandOptions Properties

TcxTreeListBandOptions          Legend

In TcxTreeListBandOptions

Customizing

Hidden

Moving

OnlyOwnColumns

Sizing


Methods for TcxTreeListBandOptions
TcxTreeListBandOptions Methods

TcxTreeListBandOptions          Legend

In TcxTreeListBandOptions

 RestoreDefaults


TcxTreeListBandOptions.Customizing

TcxTreeListBandOptions

Indicates whether the band can be dragged to the customization form.

property Customizing: Boolean;

Description

Set the option to True (the default) to allow the end user to drag the band to the customization form.  Set it to False to disable it.

Note: deactivating the Moving option prohibits the end user from moving a band within the control, thus preventing it from being dragged to the customization form.

Additionally, you can use members of the TcxTreeListOptionsCustomizing object exposed via the control’s OptionsCustomizing property to define customization settings for bands and columns.

For more detailed information on options, please read the Options article.

The default value of the Customizing property is True.


TcxTreeListBandOptions.Hidden

TcxTreeListBandOptions

Specifies whether the current band is visible in the customization form.

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.


TcxTreeListBandOptions.Moving

TcxTreeListBandOptions

Indicates whether the band can be relocated among other bands within the control.

property Moving: Boolean;

Description

Read the property to determine whether the band’s location can be changed (by the end user or by code).  The end user can drag the band to a new location among other bands within the control.  You can change the band’s position by code by setting its Index property to a new value.

Deactivating the option prohibits moving a band within the control, thus overriding the Customizing property setting.

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, please read the Options article.

The default value of the Moving property is True.


TcxTreeListBandOptions.OnlyOwnColumns

TcxTreeListBandOptions

Indicates whether the end user can drag columns to/from the band.

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, please read the Options article.

The default value of the OnlyOwnColumns property is False.


TcxTreeListBandOptions.Sizing

TcxTreeListBandOptions

Determines whether it is possible to change the band’s width.

property Sizing: Boolean;

Description

By default, Sizing is True and a user can change the band’s width by clicking and dragging the right edge of a band.

Set Sizing to False to prevent band resizing.

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, please read the Options article.

The default value of the Sizing property is True.


TcxTreeListBandOptions.RestoreDefaults

TcxTreeListBandOptions

Restores the default options settings.

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.


TcxTreeListBands
TcxTreeListBands Object

Hierarchy          Properties          Methods

Represents the band collection within the control.

Unit

cxTL

TcxTreeListBands = class(TCollection)

Description

Use members of the object to manipulate bands within the control.  The object is exposed via the TreeList.Bands property at the control level.

Bands are used to logically and visually group columns within the control.  Bands are disabled by default. To enable bands, you should activate the OptionsView.Bands option.


TcxTreeListBands Hierarchy
Hierarchy

TCollection

     |


Properties for TcxTreeListBands
TcxTreeListBands Properties

TcxTreeListBands          Legend

In TcxTreeListBands

FirstVisible

Items

LastVisible

TreeList


Methods for TcxTreeListBands
TcxTreeListBands Methods

TcxTreeListBands          Legend

In TcxTreeListBands

 Add

 Create

 GetAbsoluteIndex

 GetVisibleIndex

 RestoreDefaults

 RestoreWidths


TcxTreeListBands.FirstVisible

TcxTreeListBands

Returns the first visible band within the control.

property FirstVisible: TcxTreeListBand;

Description

Read the FirstVisible property to get access to the first visible band within the control.  The VisibleIndex property value of the band returned is 0.  A band is visible if its Visible property returns True.  You can get indexed access to visible bands using the TreeList.VisibleBands property.

For more detailed information on bands, please read the Bands article.

ReadOnly Property


TcxTreeListBands.Items

TcxTreeListBands

Returns indexed access to individual bands within the collection.

property Items[AIndex: Integer]: TcxTreeListBand;

Description

Use the Items property to get indexed access to individual bands within the control.

The AIndex parameter represents the zero-based index of the band.

To determine the number of bands within the collection, use the Count property.

For more detailed information on bands, please refer to the Band topic.


TcxTreeListBands.LastVisible

TcxTreeListBands

Returns the last visible band within the control.

property LastVisible: TcxTreeListBand;

Description

Read the LastVisible property to get access to the last visible band within the band collection.

Additionally, you can determine the first visible band using the FirstVisible property.

You can get indexed access to visible bands using the TreeList.VisibleBands property.

For detailed information on bands, please refer to the Bands topic.

ReadOnly Property


TcxTreeListBands.TreeList

TcxTreeListBands

Returns the TreeList control to which the band collection belongs.

property TreeList: TcxCustomTreeListControl;

Description

Read the TreeList property to get access to the TreeList control containing the band collection.

ReadOnly Property


TcxTreeListBands.Add

TcxTreeListBands          Example

Adds a new band to the collection.

function Add: TcxTreeListBand;

Description

Use the Add method to add a new band to the end of the band collection.

Additionally, you may wish to associate columns with the band by using the Column.OwnerBand property.

For more detailed information on bands, please refer to the Bands topic.


TcxTreeListBands.Create

TcxTreeListBands

Creates and initializes a TcxTreeListBands class instance.

constructor Create(AOwner: TcxCustomTreeListControl); virtual;

Description

The AOwner parameter specifies the TreeList control to which the collection belongs.

You do not have to use this constructor manually.


TcxTreeListBands.GetAbsoluteIndex

TcxTreeListBands

Returns the absolute index of a band by its visible index.

function GetAbsoluteIndex(VisibleIndex: Integer): Integer;

Description

The VisibleIndex parameter represents the zero-based index of the band within its collection of visible bands.

Alternatively, you can obtain a band’s visible index by its absolute index using the GetVisibleIndex method.

For more detailed information on bands, please refer to the Band topic.


TcxTreeListBands.GetVisibleIndex

TcxTreeListBands

Returns the visible index of a band by its absolute index.

function GetVisibleIndex(AbsoluteIndex: Integer): Integer;

Description

The AbsoluteIndex parameter represents the zero-based index of the band within its band collection.

Alternatively, you can obtain the absolute index of a band using the GetAbsoluteIndex property.

For more detailed information on bands, please refer to the Band topic.


TcxTreeListBands.RestoreDefaults

TcxTreeListBands

Restores the default settings for all bands.

procedure RestoreDefaults; virtual;

Description

Call the RestoreDefaults method to restore the default settings for band options. The Band.Options.Sizing, Band.Options.Customizing and Band.Options.Moving properties will be set to True and the default band widths restored (see Bands.RestoreWidths).


TcxTreeListBands.RestoreWidths

TcxTreeListBands          See Also

Restores the default widths of all bands within the control.

procedure RestoreWidths; virtual;

Description

Use the RestoreWidths method to restore the default widths of all bands within the control.  The method iterates through the band collection and calls the RestoreWidths method of each band.

Additionally, you can use the RestoreDefaults method that restores not the default widths of all bands and the default option settings.


TcxTreeListBandStyles
TcxTreeListBandStyles Object

Hierarchy          Properties

Represents a collection of style links for the various band elements.

Unit

cxTL

TcxTreeListBandStyles = class(TcxStyles)

Description

The TcxTreeListBandStyles 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.


TcxTreeListBandStyles Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomStyles

     |

TcxStyles

     |


Properties for TcxTreeListBandStyles
TcxTreeListBandStyles Properties

TcxTreeListBandStyles          Legend

In TcxTreeListBandStyles

Content

Footer

Header

HeaderBackground


TcxTreeListBandStyles.Content

TcxTreeListBandStyles

Specifies the style for the band’s content.

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.


TcxTreeListBandStyles.Footer

TcxTreeListBandStyles

Specifies the style for the band’s footer.

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.


TcxTreeListBandStyles.Header

TcxTreeListBandStyles

Specifies the style for the band header.

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.


TcxTreeListBandStyles.HeaderBackground

TcxTreeListBandStyles

Specifies the background of the band’s header.

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.


TcxTreeListCaption
TcxTreeListCaption Object

Hierarchy          Properties

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

Unit

cxTL

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.


TcxTreeListCaption Hierarchy
Hierarchy

TcxOwnedPersistent

     |


Properties for TcxTreeListCaption
TcxTreeListCaption Properties

TcxTreeListCaption          Legend

In TcxTreeListCaption

AlignHorz

AlignVert

Glyph

GlyphAlignHorz

GlyphAlignVert

MultiLine

ShowEndEllipsis

Text


TcxTreeListCaption.AlignHorz

TcxTreeListCaption

Specifies the horizontal alignment of the caption’s text.

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.


TcxTreeListCaption.AlignVert

TcxTreeListCaption

Specifies the vertical alignment of the caption’s text.

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.


TcxTreeListCaption.Glyph

TcxTreeListCaption

Defines the image displayed within the caption.

property Glyph: TBitmap;

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.


TcxTreeListCaption.GlyphAlignHorz

TcxTreeListCaption

Specifies the horizontal alignment of the image displayed within the caption.

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.


TcxTreeListCaption.GlyphAlignVert

TcxTreeListCaption

Specifies the vertical alignment of the image displayed within the caption.

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.


TcxTreeListCaption.MultiLine

TcxTreeListCaption

Specifies whether the caption’s text can be displayed in several lines.

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.

The default value of the MultiLine property is False.


TcxTreeListCaption.ShowEndEllipsis

TcxTreeListCaption

Specifies whether an end ellipsis is displayed when the caption’s width is insufficient to display its entire text.

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.


TcxTreeListCaption.Text

TcxTreeListCaption

Defines the caption text.

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.


TcxTreeListColumn
TcxTreeListColumn Object

Hierarchy          Properties          Methods          Events

Represents a single column within the TreeList control.

Unit

cxTL

TcxTreeListColumn = class(TcxCustomInplaceEditContainer)

Description

TcxTreeListColumn represents a column within the TreeList control.  The TreeList.Columns property provides indexed access to individual columns within the control.  The number of columns can be determined from the TreeList.ColumnCount property.

A column can be hidden by using the Visible property.  The TreeList.VisibleColumns property provides indexed access to the collection of visible columns.  To determine the number of visible columns, use the TreeList.VisibleColumnCount property.

Usually, columns are arranged in bands.  Each band exposes the ColumnCount and Columns properties to return the number of columns it contains and provide indexed access to individual columns.  Each band also contains a collection of visible columns (exposed via the VisibleColumns property) and returns the number of visible columns (via the VisibleColumnCount property).

The column’s Options property contains a set of options affecting the column’s behavior.  These options determine the possibility of editing the column’s contents, changing its width and height, moving a column within the TreeList control, etc.


TcxTreeListColumn Hierarchy
Hierarchy

TcxCustomInplaceEditContainer

     |


Properties for TcxTreeListColumn
TcxTreeListColumn Properties

TcxTreeListColumn          Legend

In TcxTreeListColumn

Caption

DataBinding

DisplayTexts

DisplayWidth

Editing

EditValue

Focused

IndentWidth

IsHidden

IsLeft

IsPreview

IsRight

ItemIndex

MinWidth

Options

OwnerBand

OwnerBandRow

Position

RealMinWidth

RepositoryItem

SortOrder

SummaryFooter

TreeList

Visible

VisibleIndex

VisibleIndexAtBand

Width

Derived from TcxCustomInplaceEditContainer

DataBinding

Editing

EditValue

ItemIndex

Options

Properties

PropertiesClass

PropertiesClassName

RepositoryItem

Styles


Methods for TcxTreeListColumn
TcxTreeListColumn Methods

TcxTreeListColumn          Legend

In TcxTreeListColumn

 ApplyBestFit

 Assign

 MakeVisible

 RestoreDefaults

 RestoreWidths


Events for TcxTreeListColumn
TcxTreeListColumn Events

TcxTreeListColumn          Legend

In TcxTreeListColumn

 OnGetDisplayText

 OnGetEditingProperties

 OnGetEditProperties

Derived from TcxCustomInplaceEditContainer

 OnGetEditProperties


TcxTreeListColumn.Caption

TcxTreeListColumn

Represents the column’s caption.

property Caption: TcxTreeListCaption;

Description

The Caption property represents a TcxTreeListCaption object.  This object’s properties can be used to define the settings of content displayed within the column caption.  The column caption can contain text and a glyph.  The caption properties allow you to modify the alignment (horizontally and vertically) of the caption’s text and glyph.


TcxTreeListColumn.DataBinding

TcxTreeListColumn

Represents an object linking a column to data storage.

property DataBinding: TcxItemDataBinding;

Description

The DataBinding property retrieves data from and posts it to a data storage.  You can use the DataBinding properties to specify the dataset field to which the column is connected and perform other operations.  The ValueType attribute of a DataBinding object allows you to associate arbitrary data with the column.


TcxTreeListColumn.DisplayTexts

TcxTreeListColumn

Provides indexed access to the text representation of column values.

property DisplayTexts[Index: Integer]: string;

Description

Use the DisplayTexts property to obtain the text representation of column values.  The number of values within a column can be obtained using the ValueCount property.

The Index parameter represents the Node.RecordIndex property value identifying a particular column value.

Alternatively, you can use the column’s Values property to obtain the actual values stored within column cells.

ReadOnly Property


TcxTreeListColumn.DisplayWidth

TcxTreeListColumn

Returns the column’s width on screen.

property DisplayWidth: Integer;

Description

Read the DisplayWidth property to determine the column’s width on screen.  The value returned by this property may differ from the Width property value.  The Width property returns the width assigned by code or at design time.  The DisplayWidth property returns the column width and this might have been changed by the end user.  This is True when the OptionsView.ColumnAutoWidth option is enabled.

Note: the property returns 0 when the column is not visible (see the Visible property description for details).

ReadOnly Property


TcxTreeListColumn.Editing

TcxTreeListColumn          See Also

Indicates that the column is being edited.

property Editing;

Description

Read the Editing property to determine whether a cell belonging to the column is currently being edited.

Note: the property returns False when the control’s Editing property is set to False.

If the column is in edit mode, you can determine the value of the cell being edited by using the EditValue property.


TcxTreeListColumn.EditValue

TcxTreeListColumn

Represents the value of the cell being edited.

property EditValue;

Description

Use the EditValue property to determine the cell value being edited.

Note: the property returns Null when the control’s OptionsData.Editing property is set to False.

To determine whether the column is in edit mode, you should read the OptionsData.Editing property.

If none of the column’s cells is edited, this property value returns an unassigned variant.


TcxTreeListColumn.Focused

TcxTreeListColumn          Example

Indicates whether the column is focused.

property Focused;

Description

Read the Focused property to determine whether the column is focused, i.e. contains the cell currently being edited.

Note: the property returns False when the OptionsSelection.CellSelect option is disabled (which indicates that the end user cannot select individual cells but whole nodes only).


TcxTreeListColumn.IndentWidth

TcxTreeListColumn

Returns the increment by which the leftmost column width is increased during nodes expansion.

property IndentWidth: Integer;

Description

The IndentWidth property returns the increment by which the width of the expanded leftmost (see IsMostLeft) column is increased if its width is less than the MinWidth property value.

ReadOnly Property


TcxTreeListColumn.IsHidden

TcxTreeListColumn

Indicates whether the column is hidden.

property IsHidden: Boolean;

Description

Read the IsHidden property to determine whether the column is hidden.  The property returns True when:

•	the column is not visible (the Visible property is set to False),

•	the column is not assigned to any band,

•	the owning band (the band to which the column belongs) is hidden (see the band’s  Visible property description),

•	column values are used within the preview section (see IsPreview).

ReadOnly Property


TcxTreeListColumn.IsLeft

TcxTreeListColumn

Indicates whether the column is the left-most visible one within the owning band.

property IsLeft: Boolean;

Description

The IsLeft property is used to determine whether the column is the first visible within the band that owns it. To determine whether the column is the first visible within the TreeList (when its VisibleIndex = 0), you should use the IsMostLeft property.

Additionally, you can check whether the column is the right-most visible one within its owning band by using the IsRight property.

ReadOnly Property


TcxTreeListColumn.IsMostLeft

TcxTreeListColumn

Indicates whether the column is the left-most one within the TreeList control.

property IsMostLeft: Boolean;

Description

The IsMostLeft property is used to determine whether the column is the first visible column (i.e. its VisibleIndex property returns 0) within the TreeList control.  To determine whether the column is the first visible within its owning band, use the IsLeft property.

Additionally, you can check whether the column is the right-most one within the TreeList control by using the IsMostRight property.

ReadOnly Property


TcxTreeListColumn.IsMostRight

TcxTreeListColumn

Indicates whether the column is the right-most one within the TreeList control.

property IsMostRight: Boolean;

Description

The IsMostRight property is used to determine whether the column is the last one (i.e. its VisibleIndex property returns VisibleBandCount - 1) within the band that owns it.  To determine whether the column is the first within its band, use the IsMostLeft property.

Additionally, you can check whether the column is the right-most visible one within its owning band by using the IsRight property.

ReadOnly Property


TcxTreeListColumn.IsPreview

TcxTreeListColumn

Specifies that the column’s values are used within the preview section.

property IsPreview: Boolean;

Description

The IsPreview property indicates whether the column’s values are used within the preview section.

The Preview section’s settings can be accessed via the TreeList.Preview property.  To enable the preview section, you need to assign a column to its Column property and set the preview’s Visible property to True.


TcxTreeListColumn.IsRight

TcxTreeListColumn

Indicates whether the column is the right-most visible one within its owning band.

property IsRight: Boolean;

Description

The IsRight property is used to determine whether the column is the last visible within the band that owns it. To determine whether the column is the first visible within the band, use the IsLeft property.

Additionally, you can check whether the column is the right-most one within the TreeList control by using the IsMostRight property.

ReadOnly Property


TcxTreeListColumn.ItemIndex

TcxTreeListColumn

Determines the column’s index within the TreeList’s column collection.

property ItemIndex: Integer;

Description

The ItemIndex property returns the column’s zero-based index within the column collection.

Changing the property value modifies the column’s position.

To obtain access to the column collection within the band, you should use the Band.Columns property.

To access the band to which the column belongs, you should use the OwnerBand property.

Additionally, you can determine the visible column index by using the VisibleIndex property.  The value returned by VisibleIndex may differ from the value returned by ItemIndex when the column is hidden (see Visible).

Since columns are usually associated with bands, you can determine the visible column index within the Band.Columns collection.  This can be done by using the VisibleIndexAtBand property.

Use the ItemIndex property to obtain a particular column value within the Node.Values property.


TcxTreeListColumn.MinWidth

TcxTreeListColumn

Returns the column’s minimum possible width.

property MinWidth: Integer;

Description

Read the MinWidth property to determine the minimum possible width of the column below which it cannot be reduced.

The default value of the MinWidth property is cxTreeListDefMinWidth.


TcxTreeListColumn.Options

TcxTreeListColumn

Specifies several column options.

property Options: TcxTreeListColumnOptions;

Description

The Options property exposes the TcxTreeListColumnOptions object, whose interface can be used to specify various options of the column.  Using the Options property you can specify whether:

•	an end ellipsis is displayed whenever the column caption’s text is wider than the caption rectangle,

•	column values can be edited by an end-user,

•	the column can be focused or moved or resized,

•	a footer cell is displayed for the column and other options.


TcxTreeListColumn.OwnerBand

TcxTreeListColumn

Returns the band owning the column.

property OwnerBand: TcxTreeListBand;

Description

The OwnerBand property is used to get access to the band to which the column belongs.

Additionally, you can get access to the band row in which the column resides by using the OwnerBandRow property.


TcxTreeListColumn.OwnerBandRow

TcxTreeListColumn

Returns the band row to which the column belongs.

property OwnerBandRow: TcxTreeListBandRow;

Description

The OwnerBandRow property can be used to determine the band row within the band that owns the column.

Additionally, you can determine the band to which the column belongs by using the OwnerBand property.

ReadOnly Property


TcxTreeListColumn.Position

TcxTreeListColumn

Specifies the column’s position within a band.

property Position: TcxTreeListColumnPosition;

Description

The Position property exposes an object of the TcxTreeListColumnPosition type whose members can be used to describe the column’s position within a band.  This property lets you specify the following column parameters relative to its position:

1)	the column’s location within a band (see ColIndex)

2)	the index of the band row to which the column belongs (see RowIndex)

3)	the index of the band to which the column belongs (see BandIndex)

4)	the number of lines occupied by the column caption (see LineCount)


TcxTreeListColumn.RealMinWidth

TcxTreeListColumn

Returns the width necessary to display a column.

property RealMinWidth: Integer;

Description

Read the RealMinWidth property to determine the width of the space necessary to display a column.  The result returned depends on the column’s minimum width (see MinWidth) and its indent space.

ReadOnly Property


TcxTreeListColumn.SortOrder

TcxTreeListColumn          Example

Determines the sort order of the column’s values.

property SortOrder: TcxDataSortOrder;

Description

Read the SortOrder property to determine the order in which column values are sorted.  Set the property to a TcxDataSortOrder enumeration value to sort the column values.

The soNone value leaves column values unsorted.  Setting the property to soAscending sorts its cell values in ascending order; setting the property to soDescending performs sorts in descending order.

The default value of the SortOrder property is soNone.


TcxTreeListColumn.Styles

TcxTreeListColumn

Specifies the styles of the various column elements.

property Styles: TcxTreeListColumnStyles;

Description

The Styles property exposes the TcxTreeListColumnStyles object, whose interface can be used to specify the style settings of the column’s header, content and footer.


TcxTreeListColumn.SummaryFooter

TcxTreeListColumn

Specifies the summary settings displayed within the control’s footer.

property SummaryFooter: TcxTreeListColumnSummaryFooter;

Description

The SummaryFooter property exposes the TcxTreeListColumnSummaryFooter object, whose interface can be used to specify the summary type (see Kind), its format (see Format), the horizontal & vertical alignment of summary values and to specify whether the summary result can occupy several lines.


TcxTreeListColumn.TreeList

TcxTreeListColumn

Returns the TreeList control to which the column belongs.

property TreeList: TcxCustomTreeListControl;

Description

The TreeList property can be used to get access to the TreeList control that owns the current column.

ReadOnly Property


TcxTreeListColumn.Visibility

TcxTreeListColumn

Indicates the column’s visibility.

property Visibility: Boolean;

Description

Read the Visibility property to determine whether the column is actually visible.  The property returns True when the column’s Visible property returns True and the column belongs to a band (see OwnerBand) and the band is also visible (see Visible).

Alternatively, you can determine the column’s visibility by using the IsHidden property.

Additionally, you can use the column’s Visible property to set its visibility.  Unlike the Visibility property, the Visible property is not read-only.

ReadOnly Property


TcxTreeListColumn.Visible

TcxTreeListColumn

Specifies whether the column is visible.

property Visible: Boolean;

Description

Use the Visible property to specify whether the column is visible.  Set the property to True to show the column and set it to False to hide it.

Additionally, you can determine the actual visibility of the column using the Visibility property.

The default value of the Visible property is True.


TcxTreeListColumn.VisibleIndex

TcxTreeListColumn

Returns the column’s index within the collection of visible columns.

property VisibleIndex: Integer;

Description

Use the VisibleIndex property to determine the column’s index within the collection of visible columns.  The property Contains –1 if the column is not visible.The number of visible columns can be obtained using the VisibleCount property.

Additionally, you can determine the column’s index within the TreeList’s column collection using the ItemIndex property.  To determine the visible column index within the owning band’s visible columns, use the VisibleIndexAtBand property.

ReadOnly Property


TcxTreeListColumn.VisibleIndexAtBand

TcxTreeListColumn

Returns the column’s visible index within its band.

property VisibleIndexAtBand: Integer;

Description

Use the VisibleIndexAtBand property to determine the column’s visible index within the band to which the column belongs.  To determine the number of visible columns within a band, you should use the VisibleColumnCount property.  To get indexed access to individual visible columns within a band, you should use the VisibleColumns property.

Additionally, you can determine the column index within the TreeList’s column collection by using the ItemIndex property. The number of columns within the control can be obtained via ColumnCount.  Indexed access to individual columns at the control level can be obtained by using the Columns property.

ReadOnly Property


TcxTreeListColumn.Width

TcxTreeListColumn

Determines the column’s width.

property Width: Integer;

Description

Read the Width property to determine the column width; set it to a new value to change its width.

Additionally, you can determine the actual width of the column as it is displayed on screen using the DisplayWidth property.

The default value of the Width property is cxTreeListDefWidth.


TcxTreeListColumn.ApplyBestFit

TcxTreeListColumn          Example

Adjusts the column’s width according to its cell contents.

procedure ApplyBestFit;

Description

Use the ApplyBestFit method to adjust the column width in order to display the entire cell contents.  This method iterates through nodes and calculates their maximum width.  This width is then assigned to the column’s Width property.

Note: ApplyBestFit takes into account the widths of the column caption (see Caption) and column footer cell if any (see Footer).

It is possible to adjust the column’s width by double-clicking the column’s right edge.  You can prevent the end user from changing the column width either by setting the column’s HorzSizing or the TreeList ColumnHorzSizing property to False.


TcxTreeListColumn.Assign

TcxTreeListColumn

Assigns properties of one column to another.

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 source column.

The method assigns the following properties:

1)	DisplayWidth which specifies the column’s width as it is displayed on screen

2)	MinWidth which specifies the minimum possible column width (while resizing)

3)	Width which represents the column’s width as defined at design time or by code

4)	Position which defines the column’s position within its band

5)	Caption which represents the object whose properties are used to define the column’s caption contents and layout

6)	SortOrder specifying the order in which column values are sorted

7)	Visible specifying the column’s visibility


TcxTreeListColumn.MakeVisible

TcxTreeListColumn

Scrolls the TreeList control to make the column visible.

procedure MakeVisible;

Description

If all columns cannot be completely visible within the TreeList control, a horizontal scrollbar is enabled.  In this case, some columns may not be seen by the end user (even though their Visible property is set to True).  The MakeVisible method performs horizontal scrolling until the column is displayed entirely.


TcxTreeListColumn.RestoreDefaults

TcxTreeListColumn

Restores the default column settings.

procedure RestoreDefaults; virtual;

Description

Use the RestoreDefaults method to restore the default options settings (exposed via the Options property), to set the SortOrder property to soNone, to set the vertical and horizontal alignment of the column’s caption to vaTop and taLeftJustify respectively and to restore the defaul width of the column (see Width).


TcxTreeListColumn.RestoreWidths

TcxTreeListColumn

Restores the default column width.

procedure RestoreWidths; virtual;

Description

Use the RestoreWidths method to restore the default column width.  The method sets the MinWidth property to the cxTreeListDefMinWidth constant and the Width & DisplayWidth values to the cxTreeListDefWidth value.


TcxTreeListColumn.OnGetDisplayText

TcxTreeListColumn         Example

Occurs when displaying a cell value.

type

  TcxTreeListOnGetDisplayValueEvent = procedure(Sender: TcxTreeListColumn; ANode: TcxTreeListNode; var Value: String) of object;

property OnGetDisplayText: TcxTreeListOnGetDisplayValueEvent;

Description

Write an OnGetDisplayText event handler to format cell values within the column.

The Sender parameter specifies the column to which the current cell belongs.

The ANode parameter specifies the node in which the cell resides.

The Value parameter specifies the current cell value.  Use this parameter to change the visual representation of this value.  When the event occurs, the Value parameter already contains the text, so you just need to format it as you wish.

Note: changing the Value parameter affects only the display of the cell’s value, not its actual value.  This is useful when, for instance, it is necessary to add strings to values (for example, the column may contain employee salaries and you want to display the "$" character before each value).


TcxTreeListColumn.OnGetEditingProperties

TcxTreeListColumn          See Also           Example

Occurs before an in-place editor is activated for a column cell.

type

  TcxTreeListGetEditPropertiesEvent = procedure(Sender: TcxTreeListColumn; ANode: TcxTreeListNode; var EditProperties: TcxCustomEditProperties) of object;

property OnGetEditingProperties: TcxTreeListGetEditPropertiesEvent;

Description

The OnGetEditingProperties event is raised before starting to edit a cell value and this lets you provide a different editor for the cell, thus you can provide different editors for a cell in browse and edit modes.

The Sender parameter specifies the TreeList column to which the cell belongs.

The ANode parameter specifies the node to which the cell belongs.

The EditProperties parameter specifies the in-place editor desired.  If nothing is assigned to this parameter, the default in-place editor is used (see RepositoryItem).

The Sender and ANode parameters can be used to identify the cell which is about to be edited.

Note that the editor assigned in the OnGetEditingProperties event handler is used for editing cell data only.  The browsing capabilities of the column cells are specified via the PropertiesClass property.  This property specifies the same editor for all column cells.  If you wish to assign different editors for browsing the cell data within the same column handle the OnGetEditProperties event.


TcxTreeListColumn.OnGetEditProperties

TcxTreeListColumn          See Also           Example

Occurs when specifying the in-place editor for a column.

type

  TcxTreeListGetEditPropertiesEvent = procedure(Sender: TcxTreeListColumn; ANode: TcxTreeListNode; var EditProperties: TcxCustomEditProperties) of object;

property OnGetEditProperties: TcxTreeListGetEditPropertiesEvent;

Description

The OnGetEditProperties event is raised for each cell when the control recalculates its view information. Handle the event if you need to assign different editors to cells within the same column. If you need the same editor for all column cells, use the PropertiesClass property instead.

The Sender parameter specifies the column for which the in-place editor is specified.

The ANode parameter specifies the node to which the column cell belongs.

The EditingProperties parameter specifies the in-place editor which will be used to edit the cell’s value.

Note that the editor assigned in the OnGetEditProperties event handler is used for displaying and editing cell data unless the OnGetEditingProperties event is handled. The latter event is raised before starting to edit a cell value and enables you to provide different editors for a cell in browse and edit modes.


TcxTreeListColumnOptions
TcxTreeListColumnOptions Object

Hierarchy          Properties          Methods

Contains column options.

Unit

cxTL

TcxTreeListColumnOptions = class(TcxCustomEditContainerItemOptions)

Description

The TcxTreeListColumnOptions class is exposed via the column’s Options property.  The class members allow you to:

1)	specify whether an end ellipsis is displayed within the cell if its width is insufficient to display its content completely (see CellEndEllipsis)

2)	specify whether column values can be edited (see Editing)

3)	specify whether the column can be focused (see Focusing )

4)	specify whether a footer cell can be displayed within the column (see Footer)

5)	specify whether incremental search is enabled for the column (see IncSearch)

6)	relocate the column among other columns (see Moving)

7)	specify whether edit buttons are displayed within column cells (see ShowEditButtons)

8)	change the column’s size or sort by its values (see Sizing and Sorting)


TcxTreeListColumnOptions Hierarchy
Hierarchy

TcxCustomEditContainerItemOptions

     |


Properties for TcxTreeListColumnOptions
TcxTreeListColumnOptions Properties

TcxTreeListColumnOptions          Legend

In TcxTreeListColumnOptions

CellEndEllipsis

Footer

Hidden

Sizing

Derived from TcxCustomEditContainerItemOptions

Customizing

Editing

Filtering

Focusing

IncSearch

Moving

ShowEditButtons

Sorting

TabStop


Methods for TcxTreeListColumnOptions
TcxTreeListColumnOptions Methods

TcxTreeListColumnOptions          Legend

In TcxTreeListColumnOptions

 RestoreDefaults


TcxTreeListColumnOptions.CellEndEllipsis

TcxTreeListColumnOptions

Specifies whether to display an end ellipsis within cell values.

property CellEndEllipsis: Boolean;

Description

When the cell width is insufficient to display its contents completely, the cell’s value is clipped to the cell’s boundaries.  You can use an end ellipsis within such cells to indicate that the cell contains more data than it actually displays.  To enable the end ellipsis, you should set the CellEndEllipsis property to True; set it to False to disable it and thus allow text clipping.

The default value of the CellEndEllipsis property is True.


TcxTreeListColumnOptions.Footer

TcxTreeListColumnOptions

Indicates whether the column has a cell within the TreeList footer.

property Footer: Boolean;

Description

Footer cells are used to display summary values of columns.  Set the property to True to enable the cell for the column within the control footer; set it to False, to disable the footer cell.

To specify whether the TreeList control footer is displayed, you should use the TreeList.OptionsView.Footer option.

The default value of the Footer property is False.


TcxTreeListColumnOptions.Hidden

TcxTreeListColumnOptions

Specifies whether the current column is visible in the customization form.

property Hidden: Boolean;

Description

If the Hidden property is set to True, the column 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 enable dragging any column within or outside the control set the TcxTreeListOptionsCustomizing.ColumnMoving property to True. To allow dragging the current column within the control or from the control to the customization form set the TcxTreeListColumnOptions.Moving and TcxTreeListColumnOptions.Customizing properties to True.

The default value of the Hidden property is False.


TcxTreeListColumnOptions.Sizing

TcxTreeListColumnOptions          See Also

Indicates whether the end user can resize the column.

property Sizing: Boolean;

Description

To resize the column, the end user drags its right or bottom edge by the mouse.  This is only possible if this property is set  to True; otherwise, the end user will not be able to resize the column.

Additionally, you can determine whether columns can be horizontally or vertically resized at the control level by using the ColumnHorzSizing or the ColumnVertSizing option.  These options override the behavior of the Sizing property.

The default value of the Sizing property is True.


TcxTreeListColumnOptions.RestoreDefaults

TcxTreeListColumnOptions

Restores the column’s default option settings.

procedure RestoreDefaults; virtual;

Description

Use the RestoreDefaults method to restore the default option settings of the column.  The method sets the column’s Sorting, Sizing, Customizing, Editing, TabStop, Focusing, and Moving options to True.


TcxTreeListColumnPosition
TcxTreeListColumnPosition Object

Hierarchy          Properties          Methods

Contains options defining the column’s position within the TreeList control.

Unit

cxTL

TcxTreeListColumnPosition = class(TPersistent)

Description

A TcxTreeListColumnPosition class instance is exposed via the column’s Position property.  The class members can be used to specify the index of the band to which the column belongs, the index of the column within other columns of the owning band, the number of lines column values occupy and the index of the row in which the column resides.


TcxTreeListColumnPosition Hierarchy
Hierarchy

TcxPersistent

     |


Properties for TcxTreeListColumnPosition
TcxTreeListColumnPosition Properties

TcxTreeListColumnPosition          Legend

In TcxTreeListColumnPosition

BandIndex

ColIndex

LineCount

RowIndex


Methods for TcxTreeListColumnPosition
TcxTreeListColumnPosition Methods

TcxTreeListColumnPosition          Legend

In TcxTreeListColumnPosition

 SetPosition

 SetPositionEx


TcxTreeListColumnPosition.BandIndex

TcxTreeListColumnPosition

Returns the index of the band to which the column belongs.

property BandIndex: Integer;

Description

Read the BandIndex property to determine the index of the band to which the column belongs.  Change the property value to move the column to the corresponding band.

Additionally, you can obtain an object reference to the band which owns the column by using the OwnerBand property.


TcxTreeListColumnPosition.ColIndex

TcxTreeListColumnPosition

Returns the column’s position within a band row.

property ColIndex: Integer;

Description

Read the ColIndex property to determine the column‘s position within a band row. Change the property value to move the column within the row.


TcxTreeListColumnPosition.LineCount

TcxTreeListColumnPosition

Returns the number of lines which the column occupies.

property LineCount: Integer;

Description

Read the LineCount property to determine the number of lines the column occupies.  You can change the property value to change the number of lines.

The default value of the LineCount property is 1.


TcxTreeListColumnPosition.RowIndex

TcxTreeListColumnPosition

Returns the index of the band row in which the column resides.

property RowIndex: Integer;

Description

Read the RowIndex property to determine the index of the band row within the owner band in which the column resides.  You can change the property value to move the column to a different row.


TcxTreeListColumnPosition.SetPosition

TcxTreeListColumnPosition          See Also

Defines the column’s position within the owner band.

procedure SetPosition(AColIndex, ARowIndex: Integer; IsInsertRow: Boolean = False);

Description

Use the SetPosition method to define the column’s position within the owner band.

The AColIndex parameter specifies the column’s location within the owner band.

The ARowInde parameter specifies the band row in which the column resides.

The IsInsertRow parameter specifies whether to add a new band row when the ARowIndex parameter value is greater than the number of rows within the band.

Additionally, you can specify the band to which the column should be moved by using the SetPositionEx method.


TcxTreeListColumnPosition.SetPositionEx

TcxTreeListColumnPosition          See Also

Defines the column’s position within the control.

procedure SetPositionEx(ABandIndex, AColIndex, ARowIndex: Integer; IsInsertRow: Boolean = False);

Description

Use the SetPositionEx method the define the column’s position within the control.

The ABandIndex parameter specifies the index of the band to which the column should be moved.

The AColIndex specifies the column’s location among the other columns within the band.

The ARowIndex parameter specifies the band row in which the column should reside.

If it is not necessary to move the column to a different band, you should use the SetPosition method instead.


TcxTreeListColumnStyles
TcxTreeListColumnStyles Object

Hierarchy          Properties

Contains the column’s style settings.

Unit

cxTL

TcxTreeListColumnStyles = class(TcxEditContainerStyles)

Description

A TcxTreeListColumnStyles class instance is exposed via the column’s Styles property.

Use properties of this class to define the style settings of the column header, content and footer.

It is also possible to define the styles of the column header and footer by using the following events: OnGetColumnHeaderStyle and OnGetColumnFooterStyle.


TcxTreeListColumnStyles Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomStyles

     |

TcxStyles

     |

TcxEditContainerStyles


Properties for TcxTreeListColumnStyles
TcxTreeListColumnStyles Properties

TcxTreeListColumnStyles          Legend

In TcxTreeListColumnStyles

Footer

Header

Derived from TcxEditContainerStyles

Content

Derived from TcxCustomStyles

StyleSheet


TcxTreeListColumnStyles.Footer

TcxTreeListColumnStyles

Specifies the styles for the column footer cell.

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.


TcxTreeListColumnStyles.Header

TcxTreeListColumnStyles

Specifies the styles for the column header.

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.


TcxTreeListColumnSummaryFooter
TcxTreeListColumnSummaryFooter Object

Hierarchy          Properties

Represents an object that allows you to specify the appearance of the column footer summary.

Unit

cxTL

TcxTreeListColumnSummaryFooter = class(TPersistent)

Description

The TcxTreeListColumnSummaryFooter class allows you to specify several aspects of the footer summary appearance.  You can specify the horizontal and vertical alignment of the value displayed within the column’s footer cell by using the AlignHorz and AlignVert properties.  The summary type can be specified via the Kind property.  To specify the column whose values are used to calculate the summary value, use the Column property.  To determine whether the summary value can occupy several lines within the column’s footer cell, use the MultiLine property.  To get access to the summary value or its text display, use the SummaryValue or the SummaryText property.  To get access the summary item, the SummaryItem property should be used.


TcxTreeListColumnSummaryFooter Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxTreeListColumnSummaryFooter
TcxTreeListColumnSummaryFooter Properties

TcxTreeListColumnSummaryFooter          Legend

In TcxTreeListColumnSummaryFooter

AlignHorz

AlignVert

Column

Format

Kind

MultiLine

SummaryText

SummaryValue


TcxTreeListColumnSummaryFooter.AlignHorz

TcxTreeListColumnSummaryFooter

Specifies the horizontal alignment of the footer summary value.

property AlignHorz: TAlignment;

Description

Read the AlignHorz property to determine the horizontal alignment of the footer summary value.  Set the property to a new value to change it.

Additionally, you can change the vertical alignment of the footer summary value by using the AlignVert property.

The default value of the AlignHorz property is taLeftJustify.


TcxTreeListColumnSummaryFooter.AlignVert

TcxTreeListColumnSummaryFooter

Specifies the vertical alignment of the footer summary value.

property AlignVert: TcxAlignmentVert;

Description

Read the AlignVert property to determine the vertical alignment of the footer summary value.  Set the property to a new value to change it.

Additionally, you can change the horizontal alignment of the footer summary value by using the AlignHorz property.

The default value of the AlignVert property is vaTop.


TcxTreeListColumnSummaryFooter.Column

TcxTreeListColumnSummaryFooter

Returns the column for which the summary is calculated.

property Column: TcxTreeListColumn;

Description

Read the Column property to determine the column whose values are used for calculating the summary.

ReadOnly Property


TcxTreeListColumnSummaryFooter.Format

TcxTreeListColumnSummaryFooter

Specifies the formatting string used to display a summary value.

property Format: string;

Description

Use the Format property to set the formatting pattern to control the manner in which a summary value is displayed.  If an empty string is specified, a default pattern is used.

The default formatting patterns are listed within the following table.

Summary Kind	Float values	Date/time values	Currency values
skSum	'0.00;-0.00'	‘’	'%s;-%s'
skMin	'MIN=0.00;MIN=-0.00'	'MIN='	'MIN=%s;MIN=-%s'
skMax	'MAX=0.00;MAX=-0.00'	'MAX='	'MAX=%s;MAX=-%s'
skCount	'0'	‘0’	'0'
skAverage	'AVG=0.00;AVG=-0.00'	'AVG='	'AVG=%s;AVG=-%s'


TcxTreeListColumnSummaryFooter.Kind

TcxTreeListColumnSummaryFooter

Specifies the type of summary to calculate.

property Kind: TcxSummaryKind;

Description

The Kind property defines the type of summary to calculate.  The following table lists the possible values.

Value	Meaning
skNone	Summary is not used.
skSum	Sums column values.
skMin	Retrieves the minimum value among column values.
skMax	Retrieves the maximum value among column values.
skCount	Displays the number of records within a column.
skAverage	Calculates the average column value against all records.

The default value of the Kind property is skNone.


TcxTreeListColumnSummaryFooter.MultiLine

TcxTreeListColumnSummaryFooter

Indicates whether the summary value can occupy several lines within the column’s footer cell.

property MultiLine: Boolean;

Description

Use the MultiLine property to specify whether the footer summary’s value can occupy several lines.

This property can be useful when the summary value contains too much text to be displayed completely within the column footer cell.

Note: to use this functionality, the column’s caption should contain several lines (see MultiLine).

The default value of the MultiLine property is False.


TcxTreeListColumnSummaryFooter.SummaryText

TcxTreeListColumnSummaryFooter

Returns the string displayed within the column footer cell.

property SummaryText: String;

Description

Read the SummaryText property to obtain the string displayed within the column footer cell.  The string is comprised of two parts : a format pattern (see Format) and a summary value (see SummaryValue).

You can change this property value to modify the text displayed within the column footer cell.

Additionally, you can obtain the summary value alone by using the SummaryValue property.

If the text is too long to be displayed completely within the column footer cell, you can make it occupy several lines by setting the MultiLine property to True.


TcxTreeListColumnSummaryFooter.SummaryValue

TcxTreeListColumnSummaryFooter

Returns the value calculated by the summary.

property SummaryValue: Variant;

Description

Read the SummaryValue property to determine the value calculated by the summary.  Assigning a new value to the property changes the summary result.

Additionally, you can determine the string which is displayed within the column footer cell by using the SummaryText property.  If you need to change how the summary result is displayed within the column footer cell, use the Format property, which allows you to apply formatting to the summary result.


TcxTreeListCustomizing
TcxTreeListCustomizing Object

Hierarchy          Properties          Methods

Represents an object which controls the behavior of the customization form.

Unit

cxTL

TcxTreeListCustomizing = class(TPersistent;

Description

The TcxTreeListCustomizing class exposes an interface which allows you to control the customization form. It contains two sheets: Bands and Columns.  Each sheet is comprised of rows, each of which displays a single header – either a band header or a column header.  Note: a sheet can only contain headers of the same type, i.e. the Bands sheet can only contain band headers while the Columns sheet deals with column headers.  When the SimpleCustomizeBox option is enabled, only the Columns sheet is available.

You can switch between sheets by using the methods MakeBandSheetVisible and MakeColumnSheetVisible.

The customization form’s height depends on the number of visible rows it displays.  This number is accessible via the RowCount property and can be changed if required.

The customization form can be used at runtime to remove bands and/or columns from the TreeList control.

To use the customization form, activate it by code by setting its Visible property to True.


TcxTreeListCustomizing Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxTreeListCustomizing
TcxTreeListCustomizing Properties

TcxTreeListCustomizing          Legend

In TcxTreeListCustomizing

RowCount

Visible


Methods for TcxTreeListCustomizing
TcxTreeListCustomizing Methods

TcxTreeListCustomizing          Legend

In TcxTreeListCustomizing

 MakeBandSheetVisible

 MakeColumnSheetVisible


TcxTreeListCustomizing.RowCount

TcxTreeListCustomizing

Determines the number of visible rows within the customization form.

property RowCount: Integer;

Description

Read the RowCount property to determine the number of visible rows within the customization form.  Set the property to a new value to change the number of rows.

Each row within the customization form can contain one header – either a band or a column header.  Changing this property value affects only the number of visible rows of the customization form, not the number of headers it can contain.  When the number of rows within the form is less than the number of headers it contains, a scrollbar is displayed.

The default value of the RowCount property is 10.


TcxTreeListCustomizing.Visible

TcxTreeListCustomizing

Indicates whether the customization form is visible.

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 the 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 OnCustomizationFormVisibleChanged event to track when the customization form’s visibility changes.


TcxTreeListCustomizing.MakeBandSheetVisible

TcxTreeListCustomizing          Example

Switches to the band tab within the customization form.

procedure MakeBandSheetVisible;

Description

The customization form contains two sheets: the Bands and Columns sheets (if not in "simple" mode when only the Columns sheet is displayed).  Each sheet can only contain elements of the same type – either band or column headers.

The MakeBandSheetVisible method allows you to switch to the Bands sheet programmatically.

Note that the method does nothing if the customization form is invisible (see Visible) or is in "simple" mode (see SimpleCustomizeBox).

Additionally, you can switch to the Columns sheet by using the MakeColumnSheetVisible method.


TcxTreeListCustomizing.MakeColumnSheetVisible

TcxTreeListCustomizing          Example

Switches to the column tab within the customization form.

procedure MakeColumnSheetVisible;

Description

The customization form contains two sheets: the Bands and Columns sheets (if not in "simple" mode when only the Columns sheet is displayed).  Each sheet can only contain elements of the same type – either band or column headers.

The MakeColumnSheetVisible method allows you to switch to the Columns sheet programmatically.

Note that the method does nothing if the customization form is invisible (see Visible) or is in "simple" mode (see SimpleCustomizeBox).

Additionally, you can switch to the Bands sheet by using the MakeBandSheetVisible method.


TcxTreeListStyles
TcxTreeListStyles Object

Hierarchy          Properties          Events

Represents settings controlling the style of control’s elements.

Unit

cxTL

TcxTreeListStyles = class(TcxCustomControlStyles)

Description

The TcxTreeListStyles class declares properties allowing you to customize the appearance of the TreeList control’s elements.  You can specify the style settings for:

•	the TreeList control (see Background) and its bands background (see BandBackground),

•	column headers (see ColumnHeader) and column footer cells (see ColumnFooter),

•	the control’s footer (see Footer),

•	the preview section (see Preview),

•	event and odd nodes (see ContentEven, ContentOdd) and other elements.


TcxTreeListStyles Hierarchy
Hierarchy

TPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomStyles

     |

TcxStyles

     |

TcxCustomControlStyles

     |


Properties for TcxTreeListStyles
TcxTreeListStyles Properties

TcxTreeListStyles          Legend

In TcxTreeListStyles

BandBackground

BandContent

BandHeader

ColumnFooter

ColumnHeader

ContentEven

ContentOdd

Footer

HotTrack

IncSearch

Indicator

Preview

StyleSheet

Derived from TcxCustomControlStyles

Background

Content

Inactive

Selection

StyleSheet

Derived from TcxCustomStyles

StyleSheet


Events for TcxTreeListStyles
TcxTreeListStyles Events

TcxTreeListStyles          Legend

In TcxTreeListStyles

 OnGetBandBackgroundStyle

 OnGetBandContentStyle

 OnGetBandHeaderStyle

 OnGetColumnFooterStyle

 OnGetColumnHeaderStyle

 OnGetContentStyle

 OnGetHotTrackStyle

 OnGetNodeIndentStyle

 OnGetPreviewStyle


TcxTreeListStyles.BandBackground

TcxTreeListStyles

Specifies the style for the bands’ background.

property BandBackground: TcxStyle;

Description

The BandBackground property allows you to define the style for the bands’ background.  It is possible to override these settings on the fly by using the OnGetBandBackgroundStyle event.


TcxTreeListStyles.BandContent

TcxTreeListStyles

Specifies the style for the bands’ content.

property BandContent: TcxStyle;

Description

Use the BandContent property to define the style settings common to the content of all bands within the control.  You can override these style settings at the band level via the Content property of the desired band.

Also, it is possible to override these settings on the fly by using the OnGetBandContentStyle event.


TcxTreeListStyles.BandHeader

TcxTreeListStyles          See Also

Specifies the style for band headers.

property BandHeader: TcxStyle;

Description

Use the BandHeader property to define the style common to all band headers within the TreeList control. You can override these style settings at the band level via the Header property of the desired band.

Also, it is possible to override these settings on the fly by using the OnGetBandHeaderStyle event.

Note that band headers are not visible by default.  You can enable them by using the Bands property.


TcxTreeListStyles.ColumnFooter

TcxTreeListStyles          See Also

Specifies the style for column footer cells.

property ColumnFooter: TcxStyle;

Description

Use the ColumnFooter property to define the style settings common to all column footer cells.  Column footer cells are used to display summary values.  By default, the footer is disabled.  You can enable it by using the Footer option.

It is possible to override these settings on the fly by using the OnGetColumnFooterStyle event.

Additionally, you can define the style settings for column headers via the ColumnHeader property.


TcxTreeListStyles.ColumnHeader

TcxTreeListStyles          See Also

Specifies the style settings of column headers.

property ColumnHeader: TcxStyle;

Description

Use the ColumnHeader property to define the style settings common to all column headers within the TreeList control.  You can override these settings at the column level via the Header property of the desired columns.

It is possible to override these settings on the fly by using the OnGetColumnHeaderStyle event.

Additionally, you can specify the style settings for column footer cells by using the ColumnFooter property.


TcxTreeListStyles.ContentEven

TcxTreeListStyles          See Also

Specifies the style settings for even nodes within the TreeList control.

property ContentEven: TcxStyle;

Description

Use the ContentEven property to define the style settings for even nodes within the control.  Additionally, you can use the ContentOdd property to define the settings for odd nodes.


TcxTreeListStyles.ContentOdd

TcxTreeListStyles          See Also

Specifies the style settings for odd nodes within the TreeList control.

property ContentOdd: TcxStyle;

Description

Use the ContentOdd property to define the style settings for odd nodes within the control.  Additionally, you can use the ContentEven property to define the settings for even nodes.


TcxTreeListStyles.Footer

TcxTreeListStyles          See Also

Specifies the style settings for the footer panel.

property Footer: TcxStyle;

Description

Use the Footer property to define the style settings for the footer panel.  Note: the footer panel is disabled by default.  To enable the footer, enable the Footer option.

Additionally, you can define the style settings for column footer cells by using the ColumnFooter property or the OnGetColumnFooterStyle event.


TcxTreeListStyles.HotTrack

TcxTreeListStyles

Specifies the style settings for the hottracked node.

property HotTrack: TcxStyle;

Description

Use the HotTrack property to define the style settings for the hottracked node.  This style is applied to a node when the mouse pointer hovers over it at runtime.  To enable nodes hottracking set the TreeList.OptionsBehavior.HotTrack property to True.


TcxTreeListStyles.IncSearch

TcxTreeListStyles          See Also

Specifies the style settings for the cell located by the incremental search facility.

property IncSearch: TcxStyle;

Description

Use the IncSearch property to define the style settings for the cell located by the incremental search.

The incremental search feature allows the end user to incrementally search a column for a value.  When incremental search is enabled, the end-user can locate the required text by typing within the TreeList control. By default, the feature is disabled.  You can enable it via the control’s IncSearch property.  Additionally, you can specify the column whose values are scanned by the incremental search via the IncSearchItem property.


TcxTreeListStyles.Indicator

TcxTreeListStyles          See Also

Specifies the style settings of the indicator column.

property Indicator: TcxStyle;

Description

Use the Indicator property to define the style settings of the indicator column.  The indicator column is displayed at the left of TreeList nodes and contains an arrow sign within the focused node.  The end user can click a cell within the indicator column to move focus to the corresponding node.  By default, the indicator column is disabled.  You can enable it by using the Indicator option.  Additionally, you can specify the indicator column’s width via the IndicatorWidth property.


TcxTreeListStyles.Preview

TcxTreeListStyles

Specifies the style settings of the preview section.

property Preview: TcxStyle;

Description

Use the Preview property to define the style settings of the preview section.  The preview section is a convenient means of displaying optional information.  You can use the control’s Preview property to specify the column whose values are to be displayed within the preview section, its position, visibility and other options.

It is possible to override these settings on the fly by handling the OnGetPreviewStyle event.


TcxTreeListStyles.StyleSheet

TcxTreeListStyles

Specifies the style sheet for the current style collection.

property StyleSheet: TcxTreeListStyleSheet;

Description

The StyleSheet property specifies the style sheet for the style collection provided by the current TcxTreeListStyles object.

The style collection provides multiple attributes that control the appearance of different control elements.  It contains, for instance, BandBackground, Content, Footer properties specifying the styles for the control’s background, cells and footer panel respectively.  Assigning a style directly to the TreeList element overrides the style sheet settings.  For instance, assigning the TreeList.Styles.BandBackground property overrides the TreeList.Styles.StyleSheet.BandBackground property settings.

 Thus, a style sheet represents another collection of styles to be assigned to TcxTreeListStyles.

Once a style sheet is created and modified as required, it can be used in different applications over and over again.  Style sheets can be saved to an INI file by the SaveStyleSheetsToIniFile procedure and can be loaded from this file via LoadStyleSheetsFromIniFile.

Generally, you create a style sheet via a style repository of class TcxStyleRepository.  At design time, you can create a style sheet via the style repository editor.  It provides the ability to create a style sheet of a specific type, modify its properties, add predefined style sheets, load from and save style sheets to an INI file.


TcxTreeListStyles.OnGetBandBackgroundStyle

TcxTreeListStyles          See Also

Occurs whenever the band’s background needs repainting.

type

  TcxtlOnGetItemStyleEvent = procedure(Sender: TObject; AItem: TObject; var AStyle: TcxStyle) of object;

property OnGetBandBackgroundStyle: TcxtlOnGetItemStyleEvent;

Description

The OnGetBandBackgroundStyle event occurs every time the TreeList band’s background is repainted.  This allows you to substitute the assigned band background style to another style.

To change the style, you should write an event handler that passes the existing instance of the TcxStyle class to the control via the AStyle parameter.  Note that the AStyle parameter doesn't represent any TcxStyle instance and is nil by default.  So you can't implement the following code:

AStyle.Assign(MyStyle) or AStyle.Color := clBlack

before you assign a TcxStyle instance to it.

The following code is not recommended either:

AStyle := TcxStyle.Create;

In this case, a TcxStyle instance will be created every time the event occurs and it will never be removed until application termination.  Implementing the above code creates excessive TcxStyle instances and excessive memory usage as the result.  The correct method is to create a TcxStyle instance outside the event handler and pass it to the control via the AStyle parameter within the event handler.  For instance, you can use the StyleRepository to create and store your custom styles.

The Sender parameter of the event contains the TreeList control instance that owns the style collection.

The AItem parameter contains the TreeList band whose background is being repainted.

Additionally, you can use the OnGetBandContentStyle and OnGetBandHeaderStyle events to redefine the style settings for a band’s content and header respectively.


TcxTreeListStyles.OnGetBandContentStyle

TcxTreeListStyles          See Also

Occurs for each node within a band whenever the band’s contents need repainting.

type

  TcxtlOnGetContentStyleEvent = procedure(Sender: TObject; AItem: TObject; ANode: TcxTreeListNode; var AStyle: TcxStyle) of object;

property OnGetBandContentStyle: TcxtlOnGetContentStyleEvent;

Description

The OnGetBandContentStyle event occurs every time the TreeList band’s content is repainted.  This allows you to substitute the assigned band content style by another style.

To change the style, you should write an event handler that passes the existing instance of the TcxStyle class to the control via the AStyle parameter.  Note that the AStyle parameter doesn't represent any TcxStyle instance and is nil by default. So you can't implement the following code:

AStyle.Assign(MyStyle) or AStyle.Color := clBlack

before you assign a TcxStyle instance to it.

The following code is not recommended either:

AStyle := TcxStyle.Create;

In this case, a TcxStyle instance will be created every time the event occurs and it will never be removed until application termination.  Implementing the above code creates excessive TcxStyle instances and excessive memory usage as the result.  The correct method is to create a TcxStyle instance outside the event handler and pass it to the control via the AStyle parameter within the event handler.  For instance, you can use the StyleRepository to create and store your custom styles.

The Sender parameter of the event contains the TreeList control instance that owns the style collection.

The AItem parameter contains the TreeList band whose content is being repainted.

The ANode parameter specifies the Tree list node whose content is defined.

The following sample code shows how to specify the band’s content color using the OnGetBandContentStyle event.  The handler only changes the color of the first visible band within the control (see IsMostLeft).

//Delphi

var

  InternalStyle: TcxStyle; // defines a global style variable

//...

procedure TFormMain.tlMainStylesGetBandContentStyle(Sender, AItem: TObject;

  ANode: TcxTreeListNode; var AStyle: TcxStyle);

begin

  if (not TcxTreeListBand(AItem).IsMostLeft) then Exit;

  if (InternalStyle = nil) then

  begin

    InternalStyle := TcxStyle.Create(nil);

    InternalStyle.Color := $E6F0FA;

  end;

  AStyle := InternalStyle;

end;

The initial style for the band’s content is determined by the TcxTreeListStyles.BandContent property.


TcxTreeListStyles.OnGetBandHeaderStyle

TcxTreeListStyles          See Also

Occurs whenever a band header needs repainting.

type

  TcxtlOnGetItemStyleEvent = procedure(Sender: TObject; AItem: TObject; var AStyle: TcxStyle) of object;

property OnGetBandHeaderStyle: TcxtlOnGetItemStyleEvent;

Description

The OnGetBandHeaderStyle event occurs every time a TreeList band header is repainted.  This allows you to substitute the assigned band header style by another style.

To change the style, you should write an event handler that passes the existing instance of the TcxStyle class to the control via the AStyle parameter.  Note that the AStyle parameter doesn't represent any TcxStyle instance and is nil by default.  So you can't implement the following code:

AStyle.Assign(MyStyle) or AStyle.Color := clBlack

before you assign a TcxStyle instance to it.

The following code is not recommended either:

AStyle := TcxStyle.Create;

In this case, a TcxStyle instance will be created every time the event occurs and will never be removed until application termination.  Implementing the above code creates excessive TcxStyle instances and excessive memory usage as the result.  The correct method is to create a TcxStyle instance outside the event handler and pass it to the control via the AStyle parameter within the event handler.  For instance, you can use the StyleRepository to create and store your custom styles.

The event’s Sender parameter contains the TreeList control instance that owns the style collection.

The AItem parameter contains the TreeList band whose header is being repainted.

The following sample code shows how to change the background color of the first visible band (see IsMostLeft) within the TreeList control.

//Delphi

procedure TFormMain.tlMainStylesGetBandHeaderStyle(Sender, AItem: TObject;

  var AStyle: TcxStyle);

begin

  if (not TcxTreeListBand(AItem).IsMostLeft) then Exit;

  if (InternalStyle = nil) then

  begin

    InternalStyle := TcxStyle.Create(nil);

    InternalStyle.Color := $E6F0FA;

  end;

  AStyle := InternalStyle;

end;

The initial style for column footer cells is determined by the TcxTreeListStyles.BandHeader property.


TcxTreeListStyles.OnGetColumnFooterStyle

TcxTreeListStyles          See Also

Occurs whenever a column’s footer cell needs repainting.

type

  TcxtlOnGetItemStyleEvent = procedure(Sender: TObject; AItem: TObject; var AStyle: TcxStyle) of object;

property OnGetColumnFooterStyle: TcxtlOnGetItemStyleEvent;

Description

The OnGetColumnFooterStyle event occurs every time a TreeList column footer cell is repainted.  This allows you to substitute the assigned column footer cell style by another style.

To change the style, you should write an event handler that passes the existing instance of the TcxStyle class to the control via the AStyle parameter.  Note that the AStyle parameter doesn't represent any TcxStyle instance and is nil by default.  So you can't implement the following code:

AStyle.Assign(MyStyle) or AStyle.Color := clBlack

before you assign a TcxStyle instance to it.

The following code is not recommended either:

AStyle := TcxStyle.Create;

In this case, a TcxStyle instance will be created every time the event occurs and will never be deleted until application termination.  Implementing the above code creates excessive TcxStyle instances and excessive memory usage as the result.  The correct method is to create a TcxStyle instance outside the event handler and pass it to the control via the AStyle parameter within the event handler.  For instance, you can use the StyleRepository to create and store your custom styles.

The event’s Sender parameter contains the TreeList control instance that owns the style collection.

The AItem parameter contains the TreeList column whose footer cell is being repainted.

The initial style for column footer cells is determined by the TcxTreeListStyles.ColumnFooter property.


TcxTreeListStyles.OnGetColumnHeaderStyle

TcxTreeListStyles          See Also

Occurs whenever a column header needs repainting.

type

  TcxtlOnGetItemStyleEvent = procedure(Sender: TObject; AItem: TObject; var AStyle: TcxStyle) of object;

property OnGetColumnHeaderStyle: TcxtlOnGetItemStyleEvent;

Description

Alternatively, you can use the Header property to define the style settings of a column header.

The OnGetColumnHeaderStyle event occurs every time a TreeList column header is repainted.  This allows you to substitute the assigned column header style by another style.

To change the style, you should write an event handler that passes the existing instance of the TcxStyle class to the control via the AStyle parameter.  Note that the AStyle parameter doesn't represent any TcxStyle instance and is nil by default.  So you can't implement the following code:

AStyle.Assign(MyStyle) or AStyle.Color := clBlack

before you assign a TcxStyle instance to it.

The following code is not recommended either:

AStyle := TcxStyle.Create;

In this case, a TcxStyle instance will be created every time the event occurs and will never be removed until application termination.  Implementing the above code creates excessive TcxStyle instances and excessive memory usage as the result.  The correct method is to create a TcxStyle instance outside the event handler and pass it to the control via the AStyle parameter within the event handler.  For instance, you can use the StyleRepository to create and store your custom styles.

The event’s Sender parameter contains the TreeList control instance that owns the style collection.

The AItem parameter contains the TreeList column whose header is being repainted.

The initial style for column headers is determined by the TcxTreeListStyles.ColumnHeader property.


TcxTreeListStyles.OnGetContentStyle

TcxTreeListStyles          See Also           Example

Occurs whenever a cell needs to be repainted.

type

  TcxtlOnGetContentStyleEvent = procedure(Sender: TObject; AItem: TObject; ANode: TcxTreeListNode; var AStyle: TcxStyle) of object;

property OnGetContentStyle: TcxtlOnGetContentStyleEvent;

Description

The OnGetContentStyle event occurs every time a TreeList cell is repainted.  This allows you to substitute the assigned cell style by another style.

To change the style, you should write an event handler that passes the existing instance of the TcxStyle class to the control via the AStyle parameter.  Note that the AStyle parameter doesn't represent any TcxStyle instance and is nil by default.  So you can't implement the following code:

AStyle.Assign(MyStyle) or AStyle.Color := clBlack

before you assign a TcxStyle instance to it.

The following code is not recommended either:

AStyle := TcxStyle.Create;

In this case, a TcxStyle instance will be created every time the event occurs and will never be removed until application termination.  Implementing the above code creates excessive TcxStyle instances and excessive memory usage as the result.  The correct method is to create a TcxStyle instance outside the event handler and pass it to the control via the AStyle parameter within the event handler.  For instance, you can use the StyleRepository to create and store your custom styles.

The event’s Sender parameter contains the TreeList control instance that owns the style collection.

The AItem parameter contains the TreeList column whose cell is being repainted.

The ANode parameter represents the cell’s node.

The initial style for node cells is determined by the TcxTreeListStyles.Content property.  You can also specify different styles for cells of even and odd nodes by using the ContentEven and ContentOdd properties.


TcxTreeListStyles.OnGetHotTrackStyle

TcxTreeListStyles          Example

Occurs whenever the end user hot-tracks a node.

type

  TcxtlOnGetContentStyleEvent = procedure(Sender: TObject; AItem: TObject; ANode: TcxTreeListNode; var AStyle: TcxStyle) of object;

property OnGetHotTrackStyle: TcxtlOnGetContentStyleEvent;

Description

The OnGetHotTrackStyle event occurs every time the TreeList node is hot-tracked (the mouse is over the node).  This allows you to substitute the assigned hot-track style by another style.

To change the style, you should write an event handler that passes the existing instance of the TcxStyle class to the control via the AStyle parameter.  Note that the AStyle parameter doesn't represent any TcxStyle instance and is nil by default.  So you can't implement the following code:

AStyle.Assign(MyStyle) or AStyle.Color := clBlack

before you assign a TcxStyle instance to it.

The following code is not recommended either:

AStyle := TcxStyle.Create;

In this case, a TcxStyle instance will be created every time the event occurs and will never be removed until application termination. Implementing the above code creates excessive TcxStyle instances and excessive memory usage as the result.  The correct method is to create a TcxStyle instance outside the event handler and pass it to the control via the AStyle parameter within the event handler.  For instance, you can use the StyleRepository to create and store your custom styles.

The event’s Sender parameter contains the TreeList control instance that owns the style collection.

The AItem parameter contains the TreeList column being hot-tracked.

The ANode parameter represents the node being hot-tracked.

Note: To enable hot-tracking, you should enable the HotTrack option.

The initial style for hot-tracked nodes is determined by the TcxTreeListStyles.HotTrack property.


TcxTreeListStyles.OnGetNodeIndentStyle

TcxTreeListStyles

Occurs whenever the node’s indent needs repainting.

type

  TcxtlOnGetNodeIndentStyleEvent = procedure(Sender: TObject; ANode: TcxTreeListNode; ALevel: Integer; var AStyle: TcxStyle) of object;

property OnGetNodeIndentStyle: TcxtlOnGetNodeIndentStyleEvent;

Description

The OnGetNodeIndentStyle event occurs every time a TreeList node’s indent is about to be painted.  This allows you to substitute the assigned style by another style.

To change the style, you should write an event handler that passes the existing instance of the TcxStyle class to the control via the AStyle parameter.  Note that the AStyle parameter doesn't represent any TcxStyle instance and is nil by default. So you can't implement the following code:

AStyle.Assign(MyStyle) or AStyle.Color := clBlack

before you assign a TcxStyle instance to it.

The following code is not recommended either:

AStyle := TcxStyle.Create;

In this case, a TcxStyle instance will be created every time the event occurs and will never be removed until application termination.  Implementing the above code creates excessive TcxStyle instances and excessive memory usage as the result.  The correct method is to create a TcxStyle instance outside the event handler and pass it to the control via the AStyle parameter within the event handler.  For instance, you can use the StyleRepository to create and store your custom styles.

The event’s Sender parameter contains the TreeList control instance that owns the style collection.

The ANode parameter contains the TreeList node instance whose indent is being repainted.


TcxTreeListStyles.OnGetPreviewStyle

TcxTreeListStyles          See Also

Occurs whenever the node preview section needs repainting.

type

  TcxtlOnGetItemStyleEvent = procedure(Sender: TObject; AItem: TObject; var AStyle: TcxStyle) of object;

property OnGetPreviewStyle: TcxtlOnGetItemStyleEvent;

Description

The OnGetPreviewStyle event occurs every time the TreeList node preview section is about to be painted.  This allows you to substitute the assigned style by another style.

To change the style, you should write an event handler that passes the existing instance of the TcxStyle class to the control via the AStyle parameter.  Note that the AStyle parameter doesn't represent any TcxStyle instance and is nil by default.  So you can't implement the following code:

AStyle.Assign(MyStyle) or AStyle.Color := clBlack

before you assign a TcxStyle instance to it.

The following code is not recommended either:

AStyle := TcxStyle.Create;

In this case, a TcxStyle instance will be created every time the event occurs and will never be removed until application termination.  Implementing the above code creates excessive TcxStyle instances and excessive memory usage as the result.  The correct method is to create a TcxStyle instance outside the event handler and pass it to the control via the AStyle parameter within the event handler.  For instance, you can use the StyleRepository to create and store your custom styles.

The event’s Sender parameter contains the TreeList control instance that owns the style collection.

The AItem parameter contains the TreeList column whose data is displayed within the node preview section.

Note: The node preview section is not visible by default.  To set up the preview section, use the Preview property.

The initial style for the preview section is determined by the TcxTreeListStyles.Preview property.


TcxTreeListStyleSheet
TcxTreeListStyleSheet Object

Hierarchy          Properties

Represents a style sheet for the TreeList control.

Unit

cxTL

TcxTreeListStyleSheet = class(TcxCustomStyleSheet)

Description

A StyleSheet 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.


TcxTreeListStyleSheet Hierarchy
Hierarchy

TComponent

     |

TcxComponent

     |

TcxCustomStyleSheet

     |


Properties for TcxTreeListStyleSheet
TcxTreeListStyleSheet Properties

TcxTreeListStyleSheet          Legend

In TcxTreeListStyleSheet

Styles

Derived from TcxCustomStyleSheet

BuiltIn

Caption

Index

StyleRepository

Derived from TcxComponent

FakeComponentLink1

FakeComponentLink2

FakeComponentLink3


TcxTreeListStyleSheet.Styles

TcxTreeListStyleSheet

Represents a set of styles managing the TreeList appearance.

property Styles: TcxTreeListStyles;

Description

The Styles property defines a set of properties and events that allow you to specify the appearance of all TreeList visual elements.  By handling the style events, it is possible to specify the style setting of these elements on the fly.


TcxTreeList.SaveToFile

TcxTreeList

Saves the TreeList control to a file.

procedure SaveToFile(const AFileName: string);

Description

Use the SaveToFile method to store the complete TreeList control (structure and data) to the file specified by the AFileName parameter.  This method is useful if you want to persist TreeList modifications made at runtime.

The TreeList control can later be reloaded from the file by using the LoadFromFile method.


TcxTreeList.SaveToStream

TcxTreeList

Saves the TreeList control to a stream.

procedure SaveToStream(AStream: TStream);

Description

Use the SaveToFile method to store the complete TreeList control (structure and data) to the stream specified by the AStream parameter.  This method is useful if you want to persist TreeList modifications made at runtime.

The TreeList control can later be reloaded from the stream by using the LoadFromStream method.


TcxTreeList.LoadFromFile

TcxTreeList

Loads the TreeList control from a file.

procedure LoadFromFile(const AFileName: string);

Description

Use the LoadFromFile method to retrieve the complete TreeList control (structure and data) from the stream specified by the AStream parameter.  The AStream parameter should reference the stream that was saved earlier by using the SaveToFile method.


TcxTreeList.LoadFromStream

TcxTreeList

Loads the TreeList control from a stream.

procedure LoadFromStream(AStream: TStream);

Description

Use the LoadFromFile method to retrieve the complete TreeList control (structure and data) from the file specified by the AFileName parameter.  The AFileName parameter should reference the file that was saved earlier by using the SaveToFile method.


TcxCustomTreeListControl.StoreToIniFile

TcxCustomTreeListControl

Saves TreeList-specific information to an INI file.

procedure StoreToIniFile(AStorageName: string; AReCreate: Boolean = True);

Description

Use the StoreToIniFile method to save TreeList-specific information to an INI file.  This information can be restored to keep changes applied to the TreeList control.  The TreeList structure is restored by a RestoreFromIniFile method call.  Before restoring the TreeList structure, ensure that the control contains all the columns connected to the dataset fields at the time the data was saved.

Stored structure information includes: instance names, bands and column settings.  Stored items’ (bands, columns) settings specify the position and visibility of items, 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 value is True, the existing INI file is deleted and then created again.  Otherwise, information is appended to the end of the existing file.


TcxCustomTreeListControl.StoreToRegistry

TcxCustomTreeListControl

Stores TreeList-specific information to the registry.

procedure StoreToRegistry(AStorageName: string; AReCreate: Boolean = True);

Description

Use the StoreToRegistry method to save TreeList-specific information to the registry.  This information can be restored after the changes have been applied to the TreeList control.  Use the RestoreFromRegistry 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, bands and column settings.  Stored items’ (bands, columns) settings specify the position and visibility of items, 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 value is True, the existing registry key is deleted and then created again.  Otherwise, information is appended to the existing key.


TcxCustomTreeListControl.StoreToStream

TcxCustomTreeListControl

Saves TreeList-specific information to a stream.

procedure StoreToStream(AStream: TStream);

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, bands and column settings.  Stored items’ (bands, columns) settings specify the position and visibility of items, 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.


TcxCustomTreeListControl.RestoreFromIniFile

TcxCustomTreeListControl

Restores TreeList-specific information from an INI file.

procedure RestoreFromIniFile(const AStorageName: string; AChildrenCreating: Boolean = False; AChildrenDeleting: Boolean = False);

Description

Use the RestoreFromIniFile method to restore TreeList-specific information from an INI file.  Restoring the TreeList structure can be useful after changes have been applied to the TreeList control.  Before restoring the TreeList structure, 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, bands and column settings.  Stored items’ (bands, columns) settings specify the position and visibility of items, captions, sort order, data binding etc.

The AStorageName parameter specifies the INI file path and name.

The AChildrenCreating parameter determines whether non-existent TreeList elements (bands, columns) present within an INI file are created within the control.  On the contrary, the AChildrenDeleting parameter determines whether existing TreeList elements not present within the INI file are deleted when restoring.


TcxCustomTreeListControl.RestoreFromRegistry

TcxCustomTreeListControl

Restores TreeList-specific information from the system registry.

procedure RestoreFromRegistry(const AStorageName: string; AChildrenCreating: Boolean = False; AChildrenDeleting: Boolean = False);

Description

Use the RestoreFromRegistry method to restore TreeList-specific information from the system registry.  Restoring the TreeList structure can be useful after changes have been applied to the TreeList control.  Before restoring the TreeList 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, bands and column settings.  Stored items’ (bands, columns) settings specify the position and visibility of items, captions, sort order, data binding etc.

The AStream parameter identifies an instance of the TStream class (or its descendant) where the TreeList information is stored.

The AChildrenCreating parameter determines whether non-existent TreeList elements (bands, columns) present within the stream are created within the control.  On the contrary, the AChildrenDeleting parameter determines whether existing TreeList elements not present within the stream file are deleted when restoring.


TcxCustomTreeListControl.RestoreFromStream

TcxCustomTreeListControl

Restores TreeList-specific information from a stream.

procedure RestoreFromStream(AStream: TStream; AChildrenCreating: Boolean = False; AChildrenDeleting: Boolean = False);

Description

Use the RestoreFromStream method to restore TreeList-specific information from a stream.  Restoring the TreeList structure can be useful after changes have been applied to the TreeList control.  Before restoring the TreeList 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, bands and column settings.  Stored items’ (bands, columns) settings specify the position and visibility of items, captions, sort order, data binding etc.

The AChildrenCreating parameter determines whether non-existent TreeList elements (bands, columns) present within the stream are created within the control.  On the contrary, the AChildrenDeleting parameter determines whether existing TreeList elements not present within the stream file are deleted when restoring.


cxExportTL4Link Unit Overview
cxExportTL4Link Unit

Routines

cxExportTL4ToExcel

 cxExportTL4ToHTML

cxExportTL4ToText

cxExportTL4ToXML


cxExportTL4ToExcel
cxExportTL4ToExcel Procedure

Exports the contents of a TreeList in MS Excel format.

Unit

cxExportTL4Link

Declaration

procedure cxExportTL4ToExcel(const AFileName: string; ATreeList: TcxCustomTreeListControl; AExpand: Boolean = True; ASaveAll: Boolean = True; AUseNativeFormat: Boolean = True; const AFileExt: string = 'xls');

Description

The cxExportTL4ToExcel method exports records from the ATreeList control in MS Excel format.

The AFileName parameter defines the name and the path of the output XLS file.  Any extension specified in this parameter is replaced with the extension defined by the AFileExt parameter (xls by default).

The AExpand parameter indicates whether to export all TreeList nodes that have child nodes displayed in the grid including those that are hidden within collapsed nodes.  If this parameter value is False, only visible nodes are written to the file.

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 format (Currency, Date, Time or Float).  If you specify an editor for an item, the display text of all its cells is converted to the correct MS Excel format according to the following table:

An editor assigned to a grid cell	The corresponding MS 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 to Currency, Date, Time and Float formats using the system’s regional settings.  If conversion attempts to all of these formats fails, the cell’s text is exported as a string.

If AUseNativeFormat is set to False, the displayed text of all cells is exported as is without conversion.

The following screenshot demonstrates the contents of output XLS file:


cxExportTL4ToHTML
cxExportTL4ToHTML Procedure

Exports the contents of a TreeList to HTML format.

Unit

cxExportTL4Link

Declaration

procedure cxExportTL4ToHTML(const AFileName: string; ATreeList: TcxCustomTreeListControl; AExpand: Boolean = True; ASaveAll: Boolean = True; const AFileExt: string = 'html');

Description

The cxExportTL4ToHTML method exports records from the ATreeList control in HTML format.

The AFileName parameter defines the name and the path of the output HTML file.  Any extension specified in this parameter is replaced with the extension defined by the AFileExt parameter (html by default).

The AExpand parameter indicates whether to export all TreeList nodes that have child nodes displayed in the grid including those that are hidden within collapsed nodes.  If this parameter value is False, only visible nodes are written to the file.

The ASaveAll parameter indicates whether to export just the selected or all nodes.

The following screenshot demonstrates the output HTML file:


cxExportTL4ToText
cxExportTL4ToText Procedure

Exports the contents of a TreeList to a text file.

Unit

cxExportTL4Link

Declaration

procedure cxExportTL4ToText(const AFileName: string; ATreeList: TcxCustomTreeListControl; AExpand: Boolean = True; ASaveAll: Boolean = True; const ASeparator: string = ''; const ABeginString: string = ''; const AEndString: string = ''; const AFileExt: string = 'txt');

Description

The cxExportTL4ToText method exports records from the ATreeList control to a text file.

The AFileName parameter defines the name and the path of the output text file.  Any extension specified in this parameter is replaced with the extension defined by the AFileExt parameter (txt by default).

The AExpand parameter indicates whether to export all TreeList nodes that have child nodes displayed in the grid including those that are hidden within collapsed nodes.  If this parameter value is False, only visible nodes are written to the file.

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 and postfix strings to add to each cell’s content via ABeginString and AEndString.

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


cxExportTL4ToXML
cxExportTL4ToXML Procedure

Exports the contents of a TreeList to XML format.

Unit

cxExportTL4Link

Declaration

procedure cxExportTL4ToXML(const AFileName: string; ATreeList: TcxCustomTreeListControl; AExpand: Boolean = True; ASaveAll: Boolean = True; const AFileExt: string = 'xml');

Description

The cxExportTL4ToXML method exports records from the ATreeList control to XML format.

The AFileName parameter defines the name and the path of the output XML file.  Any extension specified in this parameter is replaced with the extension defined by the AFileExt parameter (xml by default).

The AExpand parameter indicates whether to export all TreeList nodes that have child nodes displayed in the grid including those that are hidden within collapsed nodes.  If this parameter value is False, only visible nodes are written to the file.

The ASaveAll parameter indicates whether to export just the selected or all nodes.

Together with exporting the control's content into an XML file, the export procedure creates an XSL file that defines how the XML file's data should be rendered within a browser. Since the XML file created refers to the XSL file, it will look just like the exported HTML file when viewed in a browser.


Export

ExpressQuantumTreeList4 allows you to export data to a number of formats.  Currently HTML, XML, MS Excel and text formats are supported.

HTML and XML formats are more complex since they can reflect most of the grid features, such as styles, grouping and master-detail relationships.  When exporting to text format, only data is exported.

There are four methods that allow you to export data to these formats:

•	ExportTL4ToHTML

The sample output HTML file is demonstrated in the picture below:

•	ExportTL4ToXML

•	ExportTL4ToExcel

The sample output XLS file contents are demonstrated in the picture below:

•	ExportTL4ToText

The sample output TXT file contents are demonstrated in the picture below:

In addition to the cxExportTL4Link unit, where these methods are declared, you should include the cxExport module in the uses statement.


cxDBTL Unit Overview
cxDBTL Unit

Classes

TcxCustomDBTreeList

TcxDBItemDataBinding

TcxDBTreeList

TcxDBTreeListColumn

TcxDBTreeListDataController

TcxDBTreeListOptionsData


TcxCustomDBTreeList
TcxCustomDBTreeList Object

Hierarchy          Properties          Methods          Events          See Also

Represents the base class for the data-aware TreeList control.

Unit

cxDBTL

TcxCustomDBTreeList = class(TcxCustomDataTreeList)

Description

The TcxCustomDBTreeList class is the base class for the data-aware treelist control.  This class inherits all its basic functionality from the custom tree list control.  It also declares 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.

TreeList columns are represented by TcxDBTreeListColumn class instances.  This class inherits its basic column functionality from its ancestor – TcxTreeListColumn.  It provides the DataBinding property that manages the column’s connection to a data source.


TcxCustomDBTreeList Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxEditingControl

     |

TcxExtEditingControl

     |

TcxCustomTreeListControl

     |

TcxCustomDataTreeList

     |


Properties for TcxCustomDBTreeList
TcxCustomDBTreeList Properties

TcxCustomDBTreeList          Legend

In TcxCustomDBTreeList

Columns

DataController

RootValue

VisibleColumns

Derived from TcxCustomDataTreeList

OptionsData

Derived from TcxCustomTreeListControl

BandPanelHeight

Bands

ColumnCount

Columns

Count

Customizing

DefaultLayout

DefaultRowHeight

FocusedColumn

FocusedNode

FooterPanelHeight

HeaderHeight

HeaderPanelHeight

HitTest

Images

InplaceColumnIndex

InplaceEditor

IsActive

IsEditing

Items

LastNode

LevelIndentWidth

Nodes

OptionsBehavior

OptionsCustomizing

OptionsData

OptionsSelection

OptionsView

Preview

Searching

SearchingText

SelectionCount

Selections

Sorted

SortedColumnCount

SortedColumns

StateImages

Styles

TopNode

TopVisibleIndex

TopVisibleNode

VisibleBandCount

VisibleBands

VisibleColumnCount

VisibleColumns

VisibleCount

Derived from TcxExtEditingControl

OptionsBehavior

OptionsData

OptionsView

Derived from TcxEditingControl

BufferedPaint

LockUpdate

Styles

Derived from TcxControl

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel


Methods for TcxCustomDBTreeList
TcxCustomDBTreeList Methods

TcxCustomDBTreeList          Legend

Derived from TcxCustomDataTreeList

 FullRefresh

Derived from TcxCustomTreeListControl

 AdjustColumnsWidth

 ApplyBestFit

 CancelEdit

 CancelSearching

 CellRect

 Clear

 ClearSelection

 ColumnByName

 CopyAllToClipboard

 CopySelectedToClipboard

 Create

 CreateColumn

 DeleteAllColumns

 DeleteSelection

 Deselect

 Destroy

 Find

 FindNext

 FindNodeByText

 FullCollapse

 FullExpand

 FullRefresh

 GotoBOF

 GotoEOF

 GotoNext

 GotoNextPage

 GotoPrev

 GotoPrevPage

 HideEdit

 IsBOF

 IsEOF

 MakeDefaultLayout

 RestoreColumnsDefaults

 RestoreColumnsWidths

 RestoreFromIniFile

 RestoreFromRegistry

 RestoreFromStream

 Select

 SelectAll

 ShowEdit

 ShowEditByKey

 ShowEditByMouse

 StoreToIniFile

 StoreToRegistry

 StoreToStream

 Subselect

Derived from TcxEditingControl

 BeginUpdate

 CancelUpdate

 EndUpdate

 LayoutChanged

Derived from TcxControl

 Create

 Destroy

 InvalidateRect


Events for TcxCustomDBTreeList
TcxCustomDBTreeList Events

TcxCustomDBTreeList          Legend

In TcxCustomDBTreeList

 OnInitInsertingRecord

Derived from TcxCustomTreeListControl

 OnAfterSummary

 OnCollapsed

 OnCollapsing

 OnCompare

 OnCustomDrawBackground

 OnCustomDrawBandHeader

 OnCustomDrawCell

 OnCustomDrawCellsGroup

 OnCustomDrawFooter

 OnCustomDrawFooterCell

 OnCustomDrawHeader

 OnCustomDrawHeaderCell

 OnCustomDrawIndentCell

 OnCustomDrawIndicatorCell

 OnCustomDrawPreview

 OnCustomizationFormVisibleChanged

 OnDeletion

 OnEdited

 OnEditing

 OnExpanded

 OnExpanding

 OnFocusedNodeChanged

 OnGetNodeImageIndex

 OnGetNodePreviewHeight

 OnHotTrackNode

 OnIsGroupNode

 OnMoveTo

 OnSelectionChanged

 OnSummary

 OnTopRecordIndexChanged

 StylesEvents

Derived from TcxEditingControl

 OnCustomDrawCell

 OnEditChanged

 OnEdited

 OnEditing

 OnEditValueChanged

 OnInitEdit


TcxCustomDBTreeList.Columns

TcxCustomDBTreeList          See Also

Provides indexed access to TreeList columns.

property Columns[Index: Integer]: TcxDBTreeListColumn;

Description

Use the Columns property to access the collection of TreeList columns.  Each column is represented by a TcxDBTreeListColumn class instance.  This class inherits its basic column functionality from the TcxTreeListColumn class.  It also defines the DataBinding property that manages the connection to a data source.

TreeList columns also provide several properties to manage their look & feel and editing capabilities.


TcxCustomDBTreeList.DataController

TcxCustomDBTreeList          See Also

Represents an object that manages the connection to a data source.

property DataController: TcxDBTreeListDataController;

Description

Use the DataController property to access a TcxDBTreeListDataController object to manage the cxDBTreeList control’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).


TcxCustomDBTreeList.RootValue

TcxCustomDBTreeList

Specifies the ParentField property value for root level nodes.

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).


TcxCustomDBTreeList.VisibleColumns

TcxCustomDBTreeList          See Also

Provides indexed access to the collection of visible TreeList columns.

property VisibleColumns[Index:Integer]: TcxDBTreeListColumn;

Description

Use the VisibleColumns property to access the collection of visible TreeList columns.

The column’s visibility is determined by the Column.VisibleIndex property.  An item is invisible within the current view (but persists within the Columns collection) if the Column.VisibleIndex property value is –1.  The item’s visibility can also be set via the Column.Visible property value.


TcxCustomDBTreeList.OnInitInsertingRecord

TcxCustomDBTreeList

Occurs before a node is inserted into the TreeList control.

type

  TcxDBTreeListInitInsertingRecordEvent = procedure(Sender: TObject; AFocusedNode: TcxTreeListDataNode; var AHandled: Boolean) of object;

property OnInitInsertingRecord: TcxDBTreeListInitInsertingRecordEvent;

Description

The OnInitInsertingRecord event is fired before the end user inserts a node into the TreeList control.  The AFocusedNode parameter identifies the inserted node.  The AHandled parameter specifies whether the 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).


TcxDBItemDataBinding
TcxDBItemDataBinding Object

Hierarchy          Properties

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

Unit

cxDBTL

TcxDBItemDataBinding = class(TcxCustomItemDataBinding)

Description

The TcxDBItemDataBinding object provides the connection of a data-aware cxTreeList 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.


TcxDBItemDataBinding Hierarchy
Hierarchy

TPersistent

     |

TcxOwnedPersistent

     |

TcxCustomItemDataBinding

     |


Properties for TcxDBItemDataBinding
TcxDBItemDataBinding Properties

TcxDBItemDataBinding          Legend

In TcxDBItemDataBinding

Field

FieldName

Derived from TcxCustomItemDataBinding

Data


TcxDBItemDataBinding.Field

TcxDBItemDataBinding          See Also

Returns the dataset field associated with an item.

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


TcxDBItemDataBinding.FieldName

TcxDBItemDataBinding          See Also

Specifies the item’s field name.

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	Default editor
ftBoolean	TcxCheckBox
ftCurrency, ftBCD, ftFMTBcd	TcxCurrencyEdit
ftDate, ftDateTime	TcxDateEdit
ftTime	TcxTimeEdit
ftBytes, ftVarBytes, ftBlob, ftFmtMemo, ftParadoxOle, ftDBaseOle, ftTypedBinary	TcxBlobEdit
ftMemo	TcxMemo
ftGraphic	TcxImage

For items connected to other fields, TcxMaskEdit is used.

You can change the editing behavior for an item by assigning TreeListColumn.Properties or the TreeListColumn.PropertiesClassName property.


TcxDBTreeList
TcxDBTreeList Object

Hierarchy          Properties          Methods          Events

Represents a data-aware version of the TreeList control.

Unit

cxDBTL

TcxDBTreeList = class(TcxCustomDBTreeList)

Description

The TcxDBTreeList class represents a data-aware TreeList control.  This control displays data from the storage in a tree-like structure.

The TcxDBTreeList control is capable of displaying data from a TDataSet or its descendants.  The connection between the dataset and the TreeList control is managed via the TcxDBTreeListDataController instance, which can be accessed by using the DataController property.

The dataset for the TcxDBTreeList control is specified by the DataController.DataSource property.  This dataset must have the two fields needed 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: sorting data against multiple columns, summaries calculation, node preview, grouping nodes, formatting summary values, specifying editors for cell contents, 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.


TcxDBTreeList Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxEditingControl

     |

TcxExtEditingControl

     |

TcxCustomTreeListControl

     |

TcxCustomDataTreeList

     |

TcxCustomDBTreeList

     |


Properties for TcxDBTreeList
TcxDBTreeList Properties

TcxDBTreeList          Legend

Derived from TcxCustomDBTreeList

Columns

DataController

RootValue

Derived from TcxCustomTreeListControl

BandPanelHeight

Bands

ColumnCount

Columns

Count

Customizing

DefaultLayout

DefaultRowHeight

FocusedColumn

FocusedNode

FooterPanelHeight

HeaderHeight

HeaderPanelHeight

HitTest

Images

InplaceColumnIndex

InplaceEditor

IsActive

IsEditing

Items

LastNode

LevelIndentWidth

Nodes

OptionsBehavior

OptionsCustomizing

OptionsData

OptionsSelection

OptionsView

Preview

Searching

SearchingText

SelectionCount

Selections

Sorted

SortedColumnCount

SortedColumns

StateImages

Styles

TopNode

TopVisibleIndex

TopVisibleNode

VisibleBandCount

VisibleBands

VisibleColumnCount

VisibleColumns

VisibleCount

Derived from TcxExtEditingControl

OptionsBehavior

OptionsData

OptionsView

Derived from TcxEditingControl

BufferedPaint

LockUpdate

Styles

Derived from TcxControl

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel


Methods for TcxDBTreeList
TcxDBTreeList Methods

TcxDBTreeList          Legend

Derived from TcxCustomDataTreeList

 FullRefresh

Derived from TcxCustomTreeListControl

 AdjustColumnsWidth

 ApplyBestFit

 CancelEdit

 CancelSearching

 CellRect

 Clear

 ClearSelection

 ColumnByName

 CopyAllToClipboard

 CopySelectedToClipboard

 Create

 CreateColumn

 DeleteAllColumns

 DeleteSelection

 Deselect

 Destroy

 Find

 FindNext

 FindNodeByText

 FullCollapse

 FullExpand

 FullRefresh

 GotoBOF

 GotoEOF

 GotoNext

 GotoNextPage

 GotoPrev

 GotoPrevPage

 HideEdit

 IsBOF

 IsEOF

 MakeDefaultLayout

 RestoreColumnsDefaults

 RestoreColumnsWidths

 RestoreFromIniFile

 RestoreFromRegistry

 RestoreFromStream

 Select

 SelectAll

 ShowEdit

 ShowEditByKey

 ShowEditByMouse

 StoreToIniFile

 StoreToRegistry

 StoreToStream

 Subselect

Derived from TcxEditingControl

 BeginUpdate

 CancelUpdate

 EndUpdate

 LayoutChanged

Derived from TcxControl

 Create

 Destroy

 InvalidateRect


Events for TcxDBTreeList
TcxDBTreeList Events

TcxDBTreeList          Legend

Derived from TcxCustomDBTreeList

 OnInitInsertingRecord

Derived from TcxCustomTreeListControl

 OnAfterSummary

 OnCollapsed

 OnCollapsing

 OnCompare

 OnCustomDrawBackground

 OnCustomDrawBandHeader

 OnCustomDrawCell

 OnCustomDrawCellsGroup

 OnCustomDrawFooter

 OnCustomDrawFooterCell

 OnCustomDrawHeader

 OnCustomDrawHeaderCell

 OnCustomDrawIndentCell

 OnCustomDrawIndicatorCell

 OnCustomDrawPreview

 OnCustomizationFormVisibleChanged

 OnDeletion

 OnEdited

 OnEditing

 OnExpanded

 OnExpanding

 OnFocusedNodeChanged

 OnGetNodeImageIndex

 OnGetNodePreviewHeight

 OnHotTrackNode

 OnIsGroupNode

 OnMoveTo

 OnNodeChanged

 OnSelectionChanged

 OnSummary

 OnTopRecordIndexChanged

 StylesEvents

Derived from TcxEditingControl

 OnCustomDrawCell

 OnEditChanged

 OnEdited

 OnEditing

 OnEditValueChanged

 OnInitEdit


TcxDBTreeListColumn
TcxDBTreeListColumn Object

Hierarchy          Properties          Methods          Events

Represents a column within a data-aware TreeList control.

Unit

cxDBTL

TcxDBTreeListColumn = class(TcxTreeListColumn)

Description

The TcxDBTreeListColumn class represents a column within a data-aware TreeList control.  This class inherits the basic functionality of the TcxTreeListColumn object.  Data-aware functionality is encapsulated within the DataBinding property.  DataBinding.FieldName specifies the dataset field associated with the column.  The corresponding TField object can be accessed via the DataBinding.Field property.

You can change the column’s behavior and appearance by setting the column’s Options and Styles.  The column’s location within the TreeList control is defined by its Position property.  The SummaryFooter property contains summary settings for the column.

Use the PropertiesClassName or the RepositoryItem property to assign an editor for the column contents.


TcxDBTreeListColumn Hierarchy
Hierarchy

TComponent

     |

TcxCustomInplaceEditContainer

     |

TcxTreeListColumn

     |


Properties for TcxDBTreeListColumn
TcxDBTreeListColumn Properties

TcxDBTreeListColumn          Legend

In TcxDBTreeListColumn

DataBinding

Derived from TcxTreeListColumn

Caption

DataBinding

DisplayTexts

DisplayWidth

Editing

EditValue

Focused

IndentWidth

IsHidden

IsLeft

IsPreview

IsRight

ItemIndex

MinWidth

Options

OwnerBand

OwnerBandRow

Position

RealMinWidth

RepositoryItem

SortOrder

SummaryFooter

TreeList

Visible

VisibleIndex

VisibleIndexAtBand

Width

Derived from TcxCustomInplaceEditContainer

DataBinding

Editing

EditValue

ItemIndex

Options

Properties

PropertiesClass

PropertiesClassName

RepositoryItem

Styles


Methods for TcxDBTreeListColumn
TcxDBTreeListColumn Methods

TcxDBTreeListColumn          Legend

Derived from TcxTreeListColumn

 ApplyBestFit

 Assign

 MakeVisible

 RestoreDefaults

 RestoreWidths


Events for TcxDBTreeListColumn
TcxDBTreeListColumn Events

TcxDBTreeListColumn          Legend

Derived from TcxTreeListColumn

 OnGetDisplayText

 OnGetEditingProperties

 OnGetEditProperties

Derived from TcxCustomInplaceEditContainer

 OnGetEditProperties


TcxDBTreeListColumn.DataBinding

TcxDBTreeListColumn

Represents the TreeList column connection to a data source.

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.


TcxDBTreeListDataController
TcxDBTreeListDataController Object

Hierarchy          Properties          Methods          Events          See Also

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

Unit

cxDBTL

TcxDBTreeListDataController = class(TcxDBDataController)

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.

See the Self-Referenced Dataset topic for detailed information on the TreeList dataset.

Note: If the cxDBTreeList control’s SmartLoad feature is enabled, the dataset must be sorted by ParentField values and then by KeyField values.


TcxDBTreeListDataController Hierarchy
Hierarchy

TPersistent

     |

TcxCustomDataController

     |

TcxDBDataController

     |

TcxDBDataController

     |


Properties for TcxDBTreeListDataController
TcxDBTreeListDataController Properties

TcxDBTreeListDataController          Legend

In TcxDBTreeListDataController

ImageIndexFieldName

KeyField

ParentField

StateIndexFieldName

TreeList

Derived from TcxDBDataController

DataModeController

DataSource

DetailKeyFieldNames

Filter

KeyFieldNames

MasterKeyFieldNames


Methods for TcxDBTreeListDataController
TcxDBTreeListDataController Methods

TcxDBTreeListDataController          Legend

In TcxDBTreeListDataController

 CreateAllItems

Derived from TcxDBDataController

 BeginLocate

 ChangeFieldName

 EndLocate

 GetItemByFieldName

 GetItemField

 GetItemFieldName

 GetRecordId

 GetSelectedBookmark

 LocateByKey

Derived from TcxCustomDataController

 Append

 AppendRecord

 BeginUpdate

 BeginUpdateFields

 Cancel

 ChangeDetailExpanding

 ChangeRowSelection

 CheckFocusedSelected

 ClearBookmark

 ClearDetailLinkObject

 ClearDetails

 ClearSelection

 ClearSorting

 CollapseDetails

 DeleteFocused

 DeleteRecord

 DeleteSelection

 Edit

 EndUpdate

 FindRecordIndexByText

 ForEachRow

 FocusDetails

 GetDetailDataController

 GetMasterDataController

 GetMasterRecordIndex

 GetPatternDataController

 GetRowDisplayText

 GetRowIndexByRecordIndex

 GetRowInfo

 GetRowValue

 GetSelectedCount

 GetSelectedRowIndex

 GotoBookmark

 GotoFirst

 GotoLast

 GotoNext

 GotoPrev

 Insert

 InsertRecord

 IsBOF

 IsBookmarkAvailable

 IsDetailMode

 IsEOF

 IsGridMode

 IsRowSelected

 LoadFromStream

 MakeRecordVisible

 Post

 RefreshExternalData

 RestoreKeys

 SaveBookmark

 SaveKeys

 SaveToStream

 SelectAll

 SelectRows

 SyncSelected


Events for TcxDBTreeListDataController
TcxDBTreeListDataController Events

TcxDBTreeListDataController          Legend

Derived from TcxDBDataController

 OnDetailHasChildren

Derived from TcxCustomDataController

 OnAfterCancel

 OnAfterDelete

 OnAfterInsert

 OnAfterPost

 OnBeforeCancel

 OnBeforeDelete

 OnBeforeInsert

 OnBeforePost

 OnCompare

 OnDataChanged

 OnDetailCollapsed

 OnDetailCollapsing

 OnDetailExpanded

 OnDetailExpanding

 OnGroupingChanged

 OnRecordChanged

 OnSortingChanged


TcxDBTreeListDataController.ImageIndexFieldName

TcxDBTreeListDataController

Specifies the name of a field from which to acquire indexes for images.

property ImageIndexFieldName: string;

Description

Use the ImageIndexFieldName 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.


TcxDBTreeListDataController.KeyField

TcxDBTreeListDataController          See Also

Specifies the name of the dataset field whose values identify dataset records.

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).


TcxDBTreeListDataController.ParentField

TcxDBTreeListDataController          See Also

Specifies the name of the dataset field containing the parent node’s key field values.

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).


TcxDBTreeListDataController.StateIndexFieldName

TcxDBTreeListDataController

Specifies the name of the field from which to acquire indexes for state images.

property StateIndexFieldName: string;

Description

Use the StateIndexFieldName to specify the name of a field that contains indexes for the StateIndex property of the cxTreeListNode to determine images that reflect state information.


TcxDBTreeListDataController.TreeList

TcxDBTreeListDataController

Provides access to the TreeList which is controlled by the current data controller.

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


TcxDBTreeListDataController.CreateAllItems

TcxDBTreeListDataController          See Also

Creates items for all dataset fields.

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.


TcxDBTreeListOptionsData
TcxDBTreeListOptionsData Object

Hierarchy          Properties          See Also

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

Unit

cxDBTL

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 CheckHasChildren option specifies whether the search for child nodes is performed before loading a node (record).  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.


TcxDBTreeListOptionsData Hierarchy
Hierarchy

TcxControlOptionsData

     |

TcxTreeListOptionsData

     |

TcxVirtualTreeListOptionsData

     |


Properties for TcxDBTreeListOptionsData
TcxDBTreeListOptionsData Properties

TcxDBTreeListOptionsData          Legend

In TcxDBTreeListOptionsData

AutoCalcKeyValue

CheckHasChildren

SmartRefresh

SyncMode

Derived from TcxVirtualTreeListOptionsData

SmartLoad

Derived from TcxTreeListOptionsData

Deleting

Inserting

SummaryNullIgnore


TcxDBTreeListOptionsData.AutoCalcKeyValue

TcxDBTreeListOptionsData          See Also

Determines whether the key field values for new records are calculated automatically.

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.


TcxDBTreeListOptionsData.CheckHasChildren

TcxDBTreeListOptionsData          See Also

Determines whether the presence of child nodes is checked before loading a specific TreeList node.

property CheckHasChildren: Boolean;

Description

Use the CheckHasChildren property to determine whether the presence of child nodes is checked before loading a TreeList node.  If this property value is True, the TreeList control checks whether the node being loaded has child nodes.  If so, the expand button is displayed beside the current node.  If this option is deactivated, checking is not performed and expand buttons are always displayed beside each node, regardless of whether nodes have children.  This improves the TreeList performance because child node calculations are not performed for each node.

This property is only in effect if the cxDBTreeList control is in SmartLoad mode.

Setting this option to False improves TreeList performance, since additional calculations are not performed

The default value of the CheckHasChildren property is True.


TcxDBTreeListOptionsData.SmartRefresh

TcxDBTreeListOptionsData          See Also

Determines the manner in which dataset records are updated.

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.


TcxDBTreeListOptionsData.SyncMode

TcxDBTreeListOptionsData

Specifies whether synchronization between the grid control and its corresponding TDataSet is enabled.

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.


Resource Strings

Strings displayed in various message boxes, dialogs and control elements of Express products are stored as resources.  This allows you to substitute them easily for custom strings depending on your needs (for instance, for localization purposes).

To replace the default value of a resource string during program execution, use the cxSetResourceString procedure.  This procedure works together with the cxGetResourceString function used by Express Controls.  When controls need to display a particular string, they call the cxGetResourceString function, which returns either the overridden string or the default (if the string has not been overridden).

Resource strings are declared in separate files for individual Express Products.

Example

The TreeList control provides a customization form for runtime customization purposes.  The customization form’s caption is addressed by the scxTreeListDeletingConfirmationCaption identifier.  The following code replaces its caption by its German equivalent:

//Delphi

cxSetResourceString(@scxTreeListDeletingConfirmationCaption, 'Bestätigen');

//C++ Builder

cxSetResourceString(&_scxTreeListDeletingConfirmationCaption, "Bestätigen");

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

Resource identifier	Value	Description
scxBands	'Bands...'	Specifies the caption of the dropdown menu item invoking the Bands tab of the Component Editor.
scxBandsCaption	'    Bands    '	Specifies the caption of the Bands tab of the TreeList customization form.  Read the TreeList.Customizing topic for more information.
scxColumns	'Columns...'	Specifies the caption of the dropdown menu item invoking the Columns tab of the Component Editor.
scxColumnsCaption	'   Columns   '	Specifies the caption of the Columns tab of the TreeList customization form.  Read the TreeList.Customizing topic for more information.
scxCreateAllItems	'Create all columns'	Specifies the caption of the dropdown menu item for creating columns corresponding to all data source fields.
scxCustomizeCaption	'Customize'	Specifies the caption of the TreeList customization form.  Read the TreeList.Customizing topic for more information.
scxDeleteAllItems	'Delete all columns'	Specifies the caption of the dropdown menu item for removing all columns from the TreeList control.
scxDesignerCaption	'TreeListDesigner editing - '	Specifies the caption of the TreeList Items Editor.
scxExportNotVisibleControl	'Control must be visible for export'	The error that occurs when attempting to export an invisible TreeList control.  Read the Export topic for more information on exporting the TreeList control.
scxIndexOutOfBounds	'Index %d out of bounds'	The error that occurs when accessing a non-existent child node via the Node.Items property.
scxInvalidStreamFormat	'Invalid stream format'	Specifies the error that can occur during the TreeList.LoadFromStream method execution.
scxItems	'Items editor...'	Specifies the caption of the dropdown menu item invoking the TreeList Items Editor.
scxMultiSelectRequired	'Multi select required'	The error that occurs when attempting to select several nodes when the OptionsSelection.MultiSelect option is deactivated.
scxOperationNotSupported	'Operation not supported'	The error that occurs when attempting to add or to insert child nodes into a cxDBTreeList or the cxVirtualTreeList node.
scxTreeListDeletingConfirmationCaption	'Confirm'	Specifies the delete confirmation dialog caption.  Read the OptionsBehavior.ConfirmDelete topic for more information.
scxTreeListDeletingFocusedConfirmationText	'Delete record(s)?'	Specifies the delete confirmation dialog text.  Read the OptionsBehavior.ConfirmDelete topic for more information.


Example: TreeList.ColumnCount, cxTreeList.Columns
Example: TreeList.ColumnCount, TreeList.Columns

The following sample code fills 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]);

}


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 uses the VisibleColumns and VisibleColumnCount properties to get access to the collection and to determine the number of visible columns within 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[I]);

}


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;

}


Example: TreeList.Items[], TreeList.Count, Node.AddChild, 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 collection.

The GetNodeInstance method allows you to obtain a child node at the specified index. If the index is greater or equal to the number of child nodes a new 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 child node at the 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): TcxTreeListNode;

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* TUnboundModeDemoMainForm::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;

}


Example: Node.Selected, TreeList.GetSelections, OptionSelecion.MultiSelect
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){

  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;

  }

}


Example: Searching, Behavior.IncSearch, Behavior.IncSearchItem, Behavior.ExpandOnIncSearching, SearchingText, CancelSearching

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 parameter defaults to True.

//Delphi

procedure IncSearch(ASearchColumn: TcxTreeListColumn; ASearchingText: String; AExpandOnIncSearching: Boolean = True);

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 AExpandOnIncSearching = true){

  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);

}


Example: TreeList.Nodes

The following sample demonstrates how to implement the functionality of a radio group using check box inplace 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 Nodes 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 inplace editors. When the end user checks a check box within the column, all other check boxes get unchecked automatically. This behavior fakes the behavior of a radio group control.

//Delphi

procedure ExtendedRadioButtonCheck(ATreeList: TcxTreeList; ANode: TcxTreeListNode; AItemIndex: Integer);

var

  I: Integer;

begin

  ATreeList.BeginUpdate;

  try

    for I := 0 to ATreeList.Nodes.Count - 1 do

      if ATreeList.Nodes[I] = ANode then

        ATreeList.Nodes[I].Values[AItemIndex] := True

      else

        ATreeList.Nodes[I].Values[AItemIndex] := False;

    end;

  finally

    ATreeList.EndUpdate;

  end;

end;

//C++Builder

void __fastcall ExtendedRadioButtonCheck(TcxTreeList *ATreeList,   TcxTreeListNode *ANode, int AItemIndex) {

ATreeList->BeginUpdate();

  try {

    for (int i = 0; i < ATreeList->Nodes->Count; i++) {

      if (ATreeList->Nodes->Items[i] == ANode) {

        ATreeList->Nodes->Items[i]->Values[AItemIndex]= true;

      } else {

        ATreeList->Nodes->Items[i]->Values[AItemIndex] = false;

      }

    }

  } __finally {

ATreeList->EndUpdate();

  }

}


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 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 sorting 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 sorting order of the current column

      Form1->cxTreeList->SortedColumns[i]->SortOrder = (TcxDataSortOrder)((int)(!ASortDesc) + 1);

    }

  } __finally {

    Form1->cxTreeList->EndUpdate();

  }

}


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 TForm1::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];

 }

}


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 TForm1::AddNode(TcxTreeListNode *AParent, char * AValue) {

  AParent->AddChild();

  cxTreeList->ColumnByName("Notes")->Value = AValue;

}


Example: TreeList.Customizing, Customizing.MakeBandSheetVisible, Customizing.MakeColumnSheetVisible, SimpleCustomizeBox

The following sample shows how to display the customization box. The ShowCustomizationForm method accepts the following parameters:

AIsSimple specifies whether the customization box is in simple mode. If set to True, the box will have only the columns sheet available; otherwise, both the columns and the bands sheets are exposed.

AMakeBandsSheetVisible specifies whether to switch to the bands sheet when the box is displayed. Note that this parameter has no effect unless AIsSimple is set to False.

//Delphi

procedure ShowCustomizationForm(AIsSimple, AMakeBandsSheetVisible: Boolean);

begin

  cxTreeList.OptionsView.SimpleCustomizeBox := AIsSimple;

  if not AIsSimple then

    begin

      if AMakeBandsSheetVisible then

        cxTreeList.Customizing.MakeBandSheetVisible

      else

        cxTreeList.Customizing.MakeColumnSheetVisible;

    end;

    cxTreeList.Customizing.Visible := True;

end;

//C++Builder

void __fastcall TForm1::ShowCustomizationForm(bool AIsSimple, bool AMakeBandsSheetVisible) {

  cxTreeList->OptionsView->SimpleCustomizeBox = AIsSimple;

  cxTreeList->Customizing->Visible = true;

  if (!AIsSimple) {

    if (AMakeBandsSheetVisible)

      cxTreeList->Customizing->MakeBandSheetVisible();

    else

      cxTreeList->Customizing->MakeColumnSheetVisible();

    }

}


Example: Column.Focused, Node.Focused, Node.GetPrevVisible, Node.GetPrev, Node.GetNextVisible, Node.GetNext

The following sample searches a tree list column’s values for a search string. The SearchByColumn method accepts the following parameters:

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 examines the visible cells within the column; otherwise, all the values of the column are searched for the search string (AText parameter). In the latter case, if the 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: Boolean);

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 TForm1::SearchByColumn(TcxTreeListColumn *AColumn, String AText, bool AForward, bool AVisibleOnly){

  TcxTreeListNode *ANode = cxTreeList->FocusedNode;

  do {

    if (UpperCase(ANode->Texts[AColumn->ItemIndex]).Pos(UpperCase(AText)) != 0) {

// ensure that the column and the node that contains the match are visible

    AColumn->Focused = true;

    AColumn->MakeVisible();

    ANode->Focused = true;

    ANode->MakeVisible();

    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);

}


Example: OnGetHotTrackStyle

The following sample shows the use of the OnGetHotTrackStyle event. The event handler changes the style of a node depending on the node level.

The sample requires that an instance of the style repository is available. The repository should contain at least two styles: a style for hot-tracked root nodes (stlHotRoot) and a style for other nodes (stlHotItem).

//Delphi

procedure THotTrackMainForm.tlPopupStylesGetHotTrackStyle(

  Sender, AItem: TObject; ANode: TcxTreeListNode; var AStyle: TcxStyle);

begin

  if ANode.Level = 0 then

    AStyle := stlHotRoot

  else

    AStyle := stlHotItem;

end;

//C++Builder

void __fastcall TForm1::tlPopupStylesGetHotTrackStyle(TObject *Sender, TObject *AItem, TcxTreeListNode *ANode, TcxStyle *&AStyle) {

if (ANode->Level == 0)

  AStyle = stlHotRoot;

else

  AStyle = stlHotItem;

}


Example: OnHotTrackNode

The following sample utilizes the OnHotTrackNode event to change the cursor over the first level nodes to crHandPoint.

//Delphi

procedure THotTrackMainForm.tlPopupHotTrackNode(

  Sender: TObject; ANode: TcxTreeListNode; AShift: TShiftState;

  var ACursor: TCursor);

begin

  if ANode.Level = 1 then

    ACursor := crHandPoint

  else

    ACursor := crDefault;

end;

//C++Builder

void __fastcall TForm1::tlPopupHotTrackNode(TObject *Sender, TcxTreeListNode *ANode, TShiftState AShift, TCursor &ACursor) {

if (ANode->Level == 1)

  ACursor = crHandPoint;

else

  ACursor = crDefault;

}


Example: OnGetNodeImageIndex

The following sample uses the OnGetNodeImageIndex event. The event handler assigns an image to a node depending on the node level and on whether the node is hot-tracked.

//Delphi

procedure THotTrackMainForm.tlPopupGetNodeImageIndex(

  Sender: TObject; ANode: TcxTreeListNode;

  AIndexType: TcxTreeListImageIndexType; var AIndex: TImageIndex);

begin

// checking if called for a state image and if so, exit

  if AIndexType = tlitStateIndex 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 TForm1::tlPopupGetNodeImageIndex(TObject *Sender, TcxTreeListNode *ANode, TcxTreeListImageIndexType AIndexType, TImageIndex &AIndex){

// checking if called for a state image and if so, exit

  if (AIndexType == tlitStateIndex) 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;

  }

}


Example: OnIsGroupNode

The following sample uses the OnIsGroupNode event. The event handler checks whether the current node is at root level and, if so, the handler makes it a group node.

Note that it is necessary to set the PaintStyle to tlpsCategorized.

//Delphi

procedure TForm1.cxTreeList1IsGroupNode(Sender: TObject;

  ANode: TcxTreeListNode; var IsGroup: Boolean);

begin

  IsGroup := ANode.Level = 0;

end;

//C++Builder

void __fastcall TForm1::cxTreeList1IsGroupNode(TObject *Sender, TcxTreeListNode *ANode, bool &IsGroup) {

  IsGroup = (ANode->Level == 0);

}


Example: OnGetContentStyle

The following sample uses the OnGetContentStyle event. The event handler assigns a style to the current node depending on whether it is a group node.

Note that the sample requires an instance of the style repository. The repository should contain at least two styles: styCategory (which is used for group nodes) and styTask (used for the other nodes).

//Delphi

procedure TForm1.cxTreeList1StylesGetContentStyle(Sender, AItem: TObject; ANode: TcxTreeListNode; var AStyle: TcxStyle);

begin

  if ANode.IsGroupNode then

    AStyle := styCategory

  else

    AStyle := styTask;

end;

//C++Builder

void __fastcall TForm1::cxTreeList1StylesGetContentStyle(TObject *Sender, TObject *AItem, TcxTreeListNode *ANode, TcxStyle *&AStyle) {

  if (ANode->IsGroupNode) {

    AStyle = styCategory;

  } else {

    AStyle = styTask;

  }

}


Example: Column OnGetDisplayText
Example: Column.OnGetDisplayText

The following sample uses the OnGetDisplayText event. The event handler changes the value of each group node.

//Delphi

procedure TForm1.clTextGetDisplayText(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 TForm1::clTextGetDisplayText(TcxTreeListColumn *Sender, TcxTreeListNode *ANode, AnsiString &Value) {

  if (ANode->IsGroupNode) {

// adding the number of the first level child nodes

    Value = Value + " (" + IntToStr(ANode->Count) + ")";

  }

}


Example: OnGetEditingProperties

The following sample demonstrates how to change the inplace editor just before it activates (i.e. before the end user starts editing a cell).

Note that the sample requires an instance of the cxEditRepository component. The repository should have at least one item (named eriBlobMemo). When the end user clicks a cell within the tree list control, the OnGetEditingProperties event is fired substituting the default inplace editor with eriBlobMemo.

//Delphi

procedure TForm1.clTextGetEditingProperties(Sender: TcxTreeListColumn; ANode: TcxTreeListNode; var EditProperties: TcxCustomEditProperties);

begin

  EditProperties := eriBlobMemo.Properties;

end;

//C++Builder

void __fastcall TForm1::clTextGetEditingProperties(TcxTreeListColumn *Sender, TcxTreeListNode *ANode, TcxCustomEditProperties *&EditProperties) {

  EditProperties = eriBlobMemo->Properties;

}


Example: OnGetEditProperties

The following sample shows how to change a column’s default in-place editor.

Note that the sample requires an instance of the cxEditRepository component. The repository should have at least one item (named eriTextMemo).

//Delphi

procedure TForm1.clTextGetEditProperties(Sender: TcxTreeListColumn; ANode: TcxTreeListNode; var EditProperties: TcxCustomEditProperties);

begin

  EditProperties := eriTextMemo.Properties;

end;

//C++Builder

void __fastcall TForm1::clTextGetEditProperties(TcxTreeListColumn *Sender, TcxTreeListNode *ANode, TcxCustomEditProperties *&EditProperties) {

  EditProperties = eriTextMemo->Properties;

}


Example: Bands.Add, Band.Count, Bands
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 TBandedDemoMainForm.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 TBandedDemoMainForm.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 TBandedDemoMainForm::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* TBandedDemoMainForm::GetBandByCaption(String ABandCaption) {

  TcxTreeListBand *Result = NULL;

  for (int I = 0; I < cxDBTreeList->Bands->Count; I++)

    if (cxDBTreeList->Bands->Items[I]->Caption->Text == ABandCaption){

      Result = cxDBTreeList->Bands->Items[I];

      break;

    }

  return Result;

}


Example: Band.ApplyBestFit, TreeList.FullExpand

The following simple code shows how to apply best fit to a band

//Delphi

procedure TBandedDemoMainForm.FormShow(Sender: TObject);

begin

  cxTreeList1.Bands[0].Caption.Text := 'Primary information about product'

 cxTreeList1.Bands[0].ApplyBestFit;

end;

//C++Builder

void __fastcall TBandedDemoMainForm::FormShow(TObject *Sender) {

  cxTreeList1->Bands->Items[0]->Caption->Text = "Primary information about product"

  cxTreeList1->Bands->Items[0]->ApplyBestFit();

}


TreeList Provider Mode Example

The following code sample shows how to populate treelist in provider mode.

// Delphi

unit TLProviderModeUnit;

interface

uses

  Windows, Messages, SysUtils, StrUtils, Variants, Classes, Controls, Forms, Dialogs, cxCustomData, cxTL, cxControls, cxTLData, cxClasses, cxCalendar, cxTextEdit, cxGraphics, cxInplaceContainer, cxStyles, StdCtrls, Math;

type

  TTLProviderModeForm = class(TForm)

    TreeList: TcxVirtualTreeList;

    procedure FormCloseQuery(Sender: TObject; var CanClose: Boolean);

    procedure FormCreate(Sender: TObject);

    procedure FormDestroy(Sender: TObject);

  end;

  { TcxProviderRecordHandle }

  TcxProviderRecordHandle = class

  private

    FKey: Integer;

    FParent: TcxProviderRecordHandle;

    FValues: TStringList;

    function GetParentKey: Integer;

  protected

    property Parent: TcxProviderRecordHandle read FParent;

  public

    constructor Create(AKey: Integer; AParent: TcxProviderRecordHandle);

    function AddChild(AKey: string): TcxProviderRecordHandle;

    property Key: Integer read FKey;

    property ParentKey: Integer read GetParentKey;

    property Values: TStringList read FValues write FValues;

  end;

 { TcxCustomDemoDataSource}

  TcxCustomDemoDataSource = class(TcxTreeListCustomDataSource)

  private

    FModified: boolean;

    FRecordsList: TList;

    FRootHandle: TcxProviderRecordHandle;

  protected

    function GetKeyValue(ARecordHandle: TcxDataRecordHandle): Variant; override;

    function GetParentKeyValue(ARecordHandle: TcxDataRecordHandle): Variant; override;

    function GetRecordCount: Integer; override;

    function GetRecordHandle(ARecordIndex: Integer): TcxDataRecordHandle; override;

    function GetValue(ARecordHandle: TcxDataRecordHandle; AItemHandle: TcxDataItemHandle): Variant; override;

    procedure SetValue(ARecordHandle: TcxDataRecordHandle; AItemHandle: TcxDataItemHandle; const AValue: Variant); override;

    property RootHandle: TcxProviderRecordHandle read FRootHandle;

  public

    constructor Create; virtual;

    destructor Destroy; override;

    procedure LoadData;

    procedure SaveData;

    // define a flag to check if an end-user has changed data when the application is about to be closed

    property Modified: boolean read FModified;

    property RecordsList: TList read FRecordsList;

  end;

const

  AFileName = 'DEPARTMENTS.txt';

  ATabChar = #9;

var

  TLProviderModeForm: TTLProviderModeForm;

implementation

{$R *.dfm}

{ TcxProviderRecordHandle }

constructor TcxProviderRecordHandle.Create(

  AKey: Integer; AParent: TcxProviderRecordHandle);

begin

  FParent := AParent;

  FKey := AKey;

  Values := TStringList.Create;

end;

function TcxProviderRecordHandle.AddChild(AKey: string): TcxProviderRecordHandle;

begin

  Result := TcxProviderRecordHandle.Create(StrToInt(AKey), Self);

end;

function TcxProviderRecordHandle.GetParentKey: Integer;

begin

  if Parent = nil then

    Result := -1

  else

    Result := Parent.Key;

end;

{ TcxCustomDemoDataSource }

constructor TcxCustomDemoDataSource.Create;

begin

  FRecordsList := TList.Create;

  FRootHandle := TcxProviderRecordHandle.Create(-1, nil);

  LoadData;

end;

destructor TcxCustomDemoDataSource.Destroy;

begin

  FRootHandle.Free;

  FRecordsList.Free;

  inherited Destroy;

end;

function TcxCustomDemoDataSource.GetKeyValue(

  ARecordHandle: TcxDataRecordHandle): Variant;

begin

  Result := TcxProviderRecordHandle(ARecordHandle).Key;

end;

function TcxCustomDemoDataSource.GetParentKeyValue(

  ARecordHandle: TcxDataRecordHandle): Variant;

begin

  Result := TcxProviderRecordHandle(ARecordHandle).ParentKey;

end;

function TcxCustomDemoDataSource.GetRecordCount: Integer;

begin

  Result := FRecordsList.Count;

end;

function TcxCustomDemoDataSource.GetRecordHandle(

  ARecordIndex: Integer): TcxDataRecordHandle;

begin

  Result := FRecordsList[ARecordIndex];

end;

function TcxCustomDemoDataSource.GetValue(ARecordHandle: TcxDataRecordHandle;

  AItemHandle: TcxDataItemHandle): Variant;

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.TreeList.CreateColumn() do

        begin

          Caption.Text := AValues[I];

          Caption.AlignHorz := taCenter;

        end;

    ARecords.Delete(AFieldNamesRecordNumber);

  end;

  function AddRecordHandle(AParentHandle: TcxProviderRecordHandle;

    const ARecord: string): TcxProviderRecordHandle;

  var

    ADelimiterPos, AOffset, AStrLength: Integer;

    AValue: string;

  begin

    AValues.DelimitedText := ARecord;

    Result := AParentHandle.AddChild(AValues[AKeyField]);

    AStrLength := Length(ARecord);

    AOffset := 1;

    // decompose the record string (recall that record values are delimited by a tabulator)

    repeat

      ADelimiterPos := PosEx(ATabChar, ARecord, AOffset);

      if ADelimiterPos = 0 then

        AValue := Copy(ARecord, AOffset, AStrLength - (AOffset - 1))

      else

      begin

        AValue := Copy(ARecord, AOffset, ADelimiterPos - AOffset);

        AOffset := ADelimiterPos + 1;

      end;

      Result.Values.Add(AValue);

    until ADelimiterPos = 0;

  end;

  procedure AddRecordHandles(AParentHandle: TcxProviderRecordHandle;

     const AParentKeyValue: string);

    function GetFieldValue(ARecord: string; AFieldIndex: Integer): string;

    begin

      AValues.DelimitedText := ARecord;

      Result := AValues[AFieldIndex];

    end;

  var

    I: Integer;

    ARecordHandle: TcxProviderRecordHandle;

  begin

    // build up the tree structure

    for I := 0 to ARecords.Count - 1 do

      if GetFieldValue(ARecords[I], AParentKeyField) = AParentKeyValue then

      begin

        ARecordHandle := AddRecordHandle(AParentHandle, ARecords[I]);

        FRecordsList.Add(ARecordHandle);

        AddRecordHandles(ARecordHandle, GetFieldValue(ARecords[I], AKeyField));

      end;

  end;

begin

  if not FileExists(AFileName) then

    raise Exception.Create('No data file was found');

  ARecords := TStringList.Create;

  AValues := TStringList.Create;

  TLProviderModeForm.TreeList.BeginUpdate;

    try

      ARecords.LoadFromFile(AFileName);

      CreateColumns;

      AddRecordHandles(RootHandle, '0');

    finally

      TLProviderModeForm.TreeList.EndUpdate;

      ARecords.Free;

      AValues.Free;

    end;

end;

procedure TcxCustomDemoDataSource.SaveData;

var

  ARecords: TStringList;

  AValue, AValues: string;

  procedure AddColumnCaptions();

  var

    I: Integer;

  begin

    with TLProviderModeForm.TreeList do

    begin

      for I := 0 to ColumnCount - 1 do

      begin

        AValue := Columns[I].Caption.Text;

        if I <> (ColumnCount - 1) then

          AValues := AValues + AValue + ATabChar

        else

          AValues := AValues + AValue;

      end;

      ARecords.Add(AValues);

    end;

  end;

  procedure AddRecords();

  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 buffer

    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

  TreeList.CustomDataSource := TcxCustomDemoDataSource.Create;

  TreeList.Nodes.Root[0].Expand(True);

end;

procedure TTLProviderModeForm.FormDestroy(Sender: TObject);

begin

  TreeList.DataController.CustomDataSource.Free;

  TreeList.DataController.CustomDataSource := nil;

end;

procedure TTLProviderModeForm.FormCloseQuery(Sender: TObject;

  var CanClose: Boolean);

var

  I: Integer;

begin

  with TreeList.DataController.CustomDataSource as TcxCustomDemoDataSource do

  begin

    if Modified then

      I := MessageDlg('Save changes to the ' + AFileName + ' file?', mtConfirmation, [mbYes, mbNo, mbCancel], 0);

    case I of

      mrYes: SaveData;

      mrCancel: CanClose := False;

    end;

  end;

end;

end.


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:

•	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.

•	Fill the root level with nodes when the application starts.

•	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;

  FColumn.Caption.Text := 'Size';

  FColumn.PropertiesClass := TcxTextEditProperties;

//...

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.Nodes.Root is passed as the parent node.  The TreeListNode.HasChildren property for each node displaying a folder is set to True.  This forces the ExpressQuantumTreeList 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;

  FColumn.Caption.Text := 'Name';

  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 the 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.

The following image demonstrates the created application at runtime: