How to: Create a Tree-like Row Structure

• Feb 26, 2024
• 4 minutes to read

All row types can maintain a collection of nested rows. This topic explains how to create a tree-like row hierarchy in a Vertical Grid control.

Tree Structure Overview

A tree-like row structure increases data readability and helps users to search and manage data. For example, a tree-like row structure is convenient when:

• Data displayed by rows is hierarchical by nature. For instance, if rows in your control display a person’s details, it is natural to display a row showing the person’s name as the parent row and rows that display the individual’s details (title, hire date, date of birth, etc.) as child rows.

• If data is arranged into a tree, you can display only the rows visible at application startup. Users can expand rows and display hidden data on demand.

• Parent and child rows are kept together. If a parent row is moved either to another position within the grid or to the customization form, its child rows are moved with it.

The image below displays an example of arranging rows of the vertical grid into a tree.

Rows are arranged into a tree-like structure at the object level. A TcxVerticalGridRows accessible through the TcxCustomVerticalGrid.Rows property stores all rows. Every row can have a collection of child rows accessible through the TcxCustomRow.Rows property. In turn, child rows can have their own child rows, etc.

Creating a Tree at Design Time

At design time, rows can be arranged in a tree using the Layout Editor. To do this, you can drag & drop rows to the tree. The following drag & drop operations are available:

• Drag the source row over the row indent to insert the source row before the target row (at the same level).

Note

To invoke the Layout Editor, double-click the grid control. In the invoked Rows Collection Editor, click the Layout editor… button, which displays the Layout Editor. As an alternative, you can right-click the grid control. When the pop-up menu appears, select Layout Editor….

• Drag the source row over the target row header to move the source row into the child collection of the target row.

You can also use the Customization Form to rearrange rows. To invoke this dialog, click the Layout Editor‘s Customize button.

Creating a Tree at Runtime

You can rearrange existing rows or build a tree from scratch.

The first example rearranges existing rows.

// ...
// Move the ID editor row to the first position at the same level within the grid control
fldID.Index := 0;
//...
// Add the HP editor row to the collection of the Performance Attributes category row and move it to the first position in the collection
fldHP.Parent := rowPerformance_Attributes;
fldHP.Index := 0;

Note: If you need to move the desired row from the child collection to the top level, implement an operation similar to the following:

// ...
fldHP.Parent := nil;
// The HP row will be moved to the end of the top level

You can implement the Customization Form to enable a user to rearrange rows at runtime without the code snippet listed above. This form allows the user to rearrange rows within the grid control or within the form by dragging the desired rows onto the form.

To invoke the Customization Form, set the TcxVerticalGridCustomizing.Visible property to True, as shown in the following code example:

// ...
cxDBVerticalGrid.Customizing.Visible := True;

To build a new tree, use TcxCustomVerticalGrid.Add and TcxCustomVerticalGrid.AddChild methods. The first method places the created row at the top level while the second adds a row to the child collection of the specified parent. The constructed tree is sorted according to the method invocation order.

// ...
rowPerformance_Attributes := cxDBVerticalGrid.Add(TcxCategoryRow);
 with rowPerformance_Attributes do
    begin
    Properties.Caption := 'Performance Attributes';
    // ...
 end;
// Add the HP child row to the Performance Attributes row collection
fldHP := TcxEditorRow(cxDBVerticalGrid.AddChild(rowPerformance_Attributes, TcxEditorRow));
  with fldHP do
    begin
    Properties.Caption := 'HP';
    // ...
  end;
// Add the Liter child row to the Performance Attributes row collection
fldLiter := TcxEditorRow(cxDBVerticalGrid.AddChild(rowPerformance_Attributes, TcxEditorRow));
  with fldLiter do
    begin
    Properties.Caption := 'Liter';
    // ...
  end;
// ...