The Tree item is new with MicroStation V8. Trees provide the display and selection of heirarchical data. This data is stored in a GuiTreeModel. The use of different Tree item attributes affect the appearance of the Tree item, e.g. the root node may or may not be displayed; lines connecting the tree nodes may or may not be displayed; and expansion handles may or may not be displayed. The Tree item and GuiTreeModel support different icons depending on the status of a node: parent or leaf, expanded or collapsed, selected or deselected. The Tree item supports multiple columns and an associated detail panel that can be populated from a specified DialogItemList.

v8treeitem.jpg

Item List Specification

The type field should contain Tree.

The ID determines the DItem_TreeRsc instance to load.

The attributes field can be ON or OFF, and optionally combined with hidden. It will usually be ON.

The itemArg field is

The label field

The auxInfo field

The following is an example of an item list specification for the Tree item:

{{X_POS, Y_POS, TREE_X, 0}, Tree, TREEID_EXAMPLE, ON, 0,"",""},

Item Resource Specification

The Tree item is defined in a resource file with the following structures:

typedef struct ditem_treecolumnrsc
{
long id; // ID of this column //
long width; // Width, in dialog coordinates //
long maxSize; // max # of chars in column //
long attributes; // Attributes for this column //
#if defined (resource)
char heading[]; // Heading to be displayed above column //
#else
long headingLength;
char heading[1];
#endif
typedef struct ditem_treersc
{
ULong helpInfo;
ULong helpSource;
long itemHookId;
long itemHookArg;
ULong attributes; // Attributes for this Tree //
ULong nRows; // Num of rows if extent height not set //
long detailPanelId; // Item id of associated container panel //
#if defined (resource)
char label[]; // Label for the Tree item //
DItem_TreeColumnRsc treeColumns[]; // List of column definitions //
#else
long labelLength;
char label[1];
#endif
#if defined (resource)
resourceclass DItem_TreeRsc RTYPE_Tree;
#define Tree RTYPE_Tree
#endif

The DItem_TreeRsc structure has the following unique fields. (See CommonItemResourceFields for a description of any field not in this table.)

Field Description
attributes Specifies the Tree's attributes. It is constructed by combining the constants from the attributes table below with the logical OR operator, or |.
nRows Specifies the number of rows that will display. This value is usurped when the height field is explicitly set in the item's extent when including the Tree in a Dialog Item List.
detailPanelId The item id of an associated DItem_ContainerPanel. When a Tree node is selected, the application may specify a DialogItemListRsc id to be displayed in the ContainerPanel.
treeColumns An array of DItem_TreeColumnRsc. This array will have one entry for each column in the Tree.

Valid constants for use with the attributes field:

Constant Description
TREEATTR_NOSHOWROOT Indicates the TreeModel root is not to be shown.
TREEATTR_NOROOTHANDLE Indicates the expansion handle of the root is not to be shown.
TREEATTR_NOHANDLES Indicates all expansion handles are not to be shown.
TREEATTR_NOLINES Indicates no lines are to be drawn connecting the nodes of the tree.
TREEATTR_NOICONS Indicates no icons are to be shown for the nodes.
TREEATTR_NOAUTOSCROLL Indicates the Tree is not to automatically scroll as many expanded children into view when parent node expansion occurs.
TREEATTR_NOKEYSEARCH Indicates that a pressed key does not cause a search through the displayed rows for a match on the first character typed.
TREEATTR_MULTISELECTION Multiple rows may be selected and added or removed from the selection list by clicking on them.
TREEATTR_DRAGSELECTION Selection of rows changes when dragging the cursor through the rows of the tree.
TREEATTR_EXTENDEDSELECTION Allows the selection of multiple rows with dragging and allows the use of the Shift and/or Ctrl modified keys.
TREEATTR_LINESDOTTED Lines connecting the nodes are dotted instead of solid.
TREEATTR_LINESDIM Lines connecting the nodes are dimmed using the bottom shadow color.
TREEATTR_LABELONSIDE Label is placed on the side as opposed to above the tree.
TREEATTR_INDEPENDENTCOLS Indicates individual cells may be selected as opposed to selecting an entire row.
TREEATTR_DYNAMICSCROLL Contents should be scrolled as the user drags the scroll bar.
TREEATTR_COLHEADINGBORDERS Border lines will be drawn around column headings.
TREEATTR_RESIZABLECOLUMNS Borders between columns become handles, allowing for resizing of column widths. When using resizable columns, the ListBox width should be explicitly set in the DialogItemList instead of specifying 0, which results in the ListBox width being determined by the widths of the columns.
TREEATTR_SEPARATORS Indicates a cell value of `-' will result in a separator line being drawn in the row, and the row will be unselectable.
TREEATTR_DLOGBGCOLOR Indicates the dialog background color will be used as the row background color instead of the normal item background color.
TREEATTR_HORIZSCROLLBAR A horizontal scroll bar will be activated when text for any row is beyond the width of the ListBox.
TREEATTR_SAVECOLUMNINFO Column widths and sorting information are automatically saved to the preferences file.
TREEATTR_TRAVERSAL Indicates a traversal rectangle is to be drawn around each cell.
TREEATTR_GRID Indicates a bounding box is to be drawn around each cell.
TREEATTR_EDITABLE Indicates each cell within the ListBox is editable.
TREEATTR_HIGHLIGHTROW Highlight row instead of only the node's display text.
TREEATTR_DOUBLECLICKEXPANDSIndicates a double-click on a node expands/collapses the node.

The DItem_TreeColumnRsc structure has the following unique fields. (See CommonItemResourceFields for a description of any field not in this table.)

Field Description
id Specifies the column's id.
width Specifies the column width in dialog coordinate units.
maxSize Specifies the maximum number of characters that display in the column.
attributes Specifies the column's attributes.
heading Specifies a heading for the column. The heading will be justified according to the justfication bits in attributes.

Valid constants for use with the attributes field:

Constant Description
ALIGN_LEFT The heading and values will be left-justified in the column area.
ALIGN_RIGHT The heading and values will be right-justified in the column area.
ALIGN_CENTER The heading and values will be centered in the column area.

Item hook function messages

The following messages are sent to item hook functions that are attached to tree items:

Tree item functions

Field Description
mdlDialog_treeGetInfo retrieves parameter values associated with a tree item.
mdlDialog_treeSetInfo sets parameter values associated with a tree item.
mdlDialog_treeGetTreeModelP retrieves the ListModel pointer from the tree.
mdlDialog_treeSetTreeModelP sets the ListModel pointer in the tree.
mdlDialog_treeModelUpdate notifies the tree that the TreeModel has been updated.
mdlDialog_treeGetHeights retrieves cetain internal heights from the tree.
mdlDialog_treeGetDisplayRange gets the range of cells that are displayed in the tree.
mdlDialog_treeSetTopRow sets the first displayed row index in a tree.
mdlDialog_treeDrawContents draws the contents of the tree.
mdlDialog_treeGetSelectRange gets the range of the cells that are currently selected in the tree.
mdlDialog_treeGetNextSelection searches for the next selected cell of a tree.
mdlDialog_treeGetSelections returns a pointer to an array indicating which cells of a tree are currently selected.
mdlDialog_treeSetSelections sets which cells in a tree are selected.
mdlDialog_treeGetLocationCursorreturns the location of the selection cursor from a tree.
mdlDialog_treeSetLocationCursorsets the location of the selection cursor in a tree.
mdlDialog_treeIsCellEnabled determines if a cell is enabled within a tree.
mdlDialog_treeIsCellSelected determines if a cell is selected within a tree.
mdlDialog_treeLastCellClicked determines the cell in the tree in which the Data button was last clicked.
mdlDialog_treeEnableCells enables or disables a range of cells within a tree.
mdlDialog_treeSelectCells selects or deselects a range of cells within a tree.
mdlDialog_treeGetCollInfo retrieves parameters associated with a particular column.
mdlDialog_treeSetCollInfo sets parameters associated with a particular column.
mdlDialog_treeInsertColumn inserts a new column into a tree.
mdlDialog_treeDeleteColumn deletes one column from a tree.
mdlDialog_treeDeleteAll deletes all columns from a tree.

GuiTreeModel Overview

The GuiTreeModel and Tree dialog item are new with MicroStation V8. The GuiTreeModel provides a mechanism for storing heirarchical data, and the Tree dialog item displays the data. Each row displayed by the Tree item is represented by a single item of data called a node. Each node is stored in a GuiTreeNode. The GuiTreeModel contains one root node from which all other tree nodes descend. A tree node can either have children or not. Nodes that can have children, whether or not the currently have children, are called parent nodes. When a parent node has children it is said to be "populated". Parent nodes can have any number of children and descendents. Nodes that are not parent nodes (i.e. they cannot have child nodes) are called leaf nodes.

With the Tree dialog item, the user can expand and collapse parent nodes by clicking them making their children visibly or invisible. When collapsing parent nodes, any parent descendents currently expanded may optionally be collapsed or left expanded but invisible. A separate list of displayable nodes is maintained by the GuiTreeModel for quick access by the Tree item and applications.

The GuiTreeModel may contain multiple columns. The number of columns is set when the GuiTreeModel is created via the mdlTreeModel_create function. For each column, the GuiTreeModel contains a GuiTreeColumn. GuiTreeNodes contain a GuiTreeCell for each column in the GuiTreeModel.

A GuiTreeColumn contains information used when processing GuiTreeCells in its column. This information includes:

A GuiTreeNode contains:

A GuiTreeCell contains:

A GuiTreeNodePath contains:

A broad set of functions is provided to create and destroy the different objects and to access and set information within the objects.


Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.