TreeList Elements Review
- 6 minutes to read
This topic describes the main visual elements provided by the TreeList control and its functionality groups. Click the links below to jump to the required section of this topic.
Bands
Columns
Nodes
Footer and Group Footers
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 (Data, Footer, and Group Footer Cells).
Navigation (Indicator and Expand Buttons).
Analysis and summary (Footer and Group Footers).
Description (Preview).
Layout adjustment (Sizing Edges).
The following image represents TreeList elements and their location within the control.
The main control elements are Bands, Columns, Nodes, and Footers.
Let’s discuss them in detail:
Bands
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, resized and nested within other bands. Bands can be moved and nested within the control by clicking and dragging their headers and can be resized by clicking and dragging their edges. Bands can be sized both horizontally and vertically. Band moving and sizing is controlled by the band or TreeList options (a band’s Options and the TreeList control’s OptionsCustomizing properties respectively).
Each TreeList band has a Position property that contains information about the band’s position within the control. The Position.ColIndex and Position.BandIndex properties determine the band’s header position within its parent band.
Bands can be hidden at runtime. To do this, click a band header and then drag it to the TreeList control’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. The customization form can be shown by setting the TreeList control’s 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 a band’s FixedKind property to specify the control’s side to which the band is fixed.
Columns
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, resized and stacked. Columns can be moved and stacked within the TreeList control by clicking and dragging their headers and can be resized by clicking and dragging their edges. Columns can be sized both horizontally and vertically:
Column moving and sizing is controlled by column or TreeList options (a column’s Options and the TreeList control’s OptionsCustomizing properties respectively).
Each TreeList column has a Position property that contains information about the column’s position within the control. A column’s Position.ColIndex and Position.RowIndex properties determine the column’s header position within the band.
Column headers specify cell positions. Node cells in the image below have the same background color as the corresponding column header.
You can also make column values occupy the entire node area by using categorized columns. Categorized data representation is enabled via the TreeList control’s OptionsView.CategorizedColumn and OptionsView.PaintStyle properties.
Columns can be hidden at runtime. To do this, click a column header and then drag it to the TreeList control’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.
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 first band within the TreeList control’s Bands collection becomes the column’s owner.
Nodes
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 users 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 control’s Items collection. Each node in the collection has its own child nodes collection available via the node’s Items property. These child nodes have their own children, etc.
Tree branches are called nesting levels:
The node’s nesting level can be obtained via the node’s Level property.
Each node consists of the following elements:
Node cells (also called data cells) display data that can be modified by users using in-place editors. Programmatic changes to the contents are performed via the node’s Values property.
The node’s image section contains a descriptive image and an image that indicates whether the node is selected. To provide images for the TreeList control, set its Images property for node images and the StateImages property for state images.
The most flexible way of assigning images to nodes at runtime is to handle the TreeList control’s OnGetNodeImageIndex event, but in unbound mode you can simply use a node’s ImageIndex, StateIndex, OverlayIndex, OverlayStateIndex, and SelectedIndex properties.
A node’s expand button allows users 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 a node’s Expand and Collapse methods.
A node’s preview section allows you to display large memo field values across the whole node. The TreeList control has the Preview property 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.
To select a node, click it and the node will become both focused and selected (its Focused and Selected properties are True).
The TreeList control also allows users to multi-select nodes. To enable the multi-select feature, set the control’s OptionsSelection.MultiSelect to True.
The TreeList indicator displays selected and focused records with circles and triangles respectively. (see the above image).
Footer and Group Footers
The TreeList control’s simple and group footers are used for displaying summaries Summaries allow you to calculate totals against a group of nodes or all nodes and display the results in a convenient format. You can create multiple summaries both at design and runtime.
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 control’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, use the Summary.FooterSummaryItems and Summary.GroupFooterSummaryItems collections of a column or TreeList control.