_TPL_VirtualTreeDialog - Pattern for virtual tree dialog (internal data type)

Usage

Virtual tree dialogs are used in dialogs or as sub controls in other windows in order to browse or edit data in hierarchical data structures (e.g. Company --> Employees --> Cars). Since object instances on different hierarchy levels usually have got different data types, the edit form on the right side has to change according to the selected instances object data type. Typically, virtual list dialogs are displayed in project main windows or when calling an edit action from a menu item or action button. In order to call a virtual tree dialog from an action, the ListEdit window has to be linked to a window action.

Structure

The form contains a tree control (tree) for displaying the object instance tree. The tree usually contains several regions on one or more hierarchy levels. Each region in a tree needs to have the same number of region columns. The number of columns in the tree is determined by the number of columns in the tree control.

A standard toolbar is added to the list in order to provide fast tree action access (insert, delete etc.). When no toolbar is required, it might be be removed from the tree control.

An edit control (virtual_edit) is displayed in the right part of the window, which is supposed to display object instance data.

The Finish button is defined in the tree_edit_frame and might be removed or other buttons might be added.

Data source

Typically, the data source is a collection passed by the system or has been defined in the window action calling the dialog. You may, however, define the data source explicitly for the virtual tree dialog.

The data source might also be defined in the tree_edit field of the tree_edit_frame control or in the tree field of the tree_edit control. In the data source tab, data reference type and data reference have to be set in this case (usually to DRT_Extent/extentname).

In order to define multiple region trees (more than one region on top level in the tree), more than one data source have to be defined. In this case the data sources are defined in the tree regions rather than in the tree control.

Changing size

In order to change the size of the pattern controls, you have to decrease or increase the size for the all controls defined in the pattern class. The size defined for the ListEdit window is calculated from the size of the tree_edit_frame control (when set to 0) or should be larger..

The control size of the virtual_edit control (and, thus, the size for workspace and property_stack) depend on the virtual_edit control size defined in the classes to be displayed on the right side.

Design

When initializing a design class with the virtual tree dialog pattern, design classes for object types to be displayed in the edit window have to be initialized with the virtual tab pattern (_TPL_VirtualTab) and have to be designed afterward (see _TPL_VirtualTab).

You may change the tree design by adding columns and regions to the tree control.

You may also add additional buttons on top of the window. When adding buttons in the tree_edit_frame control, you should remove spacers from the grid cells. In order to add more buttons, one may increase the horizontal grid size for the list_edit_frame control.