Tree Item

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.

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 
} DItem_TreeColumnRsc;
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 
} DItem_TreeRsc;
#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_DOUBLECLICKEXPANDS	Indicates 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_treeGetLocationCursor	returns the location of the selection cursor from a tree.
mdlDialog_treeSetLocationCursor	sets 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:

• An ID
• Sort function
• Search function
• Number of information fields (info fields) the GuiTreeCells in this column will have

A GuiTreeNode contains:

• A status flag
• List of GuiTreeCells
• Reference back to its parent
• List of child nodes
• Level number within the heirarchy of nodes; the root node has a level of 0
• Different icons which are displayed by the Tree item based on the current status of the node (parent or leaf, expanded or collapsed, selected or deselected)
• A path of ancestors, represented by a GuiTreeNodePath

A GuiTreeCell contains:

• A status flag
• An ID
• Color Descriptor
• Font Index
• Icon information
• Mono icon color overrides
• Pixel indent info
• Display text
• An internal value. The internal value may be the same or different from the display text, and can have a data type of short, long, double or character string.
• Information fields. The number of info fields is obtained from the GuiTreeColumn.

A GuiTreeNodePath contains:

• The number of nodes in the path
• A list of nodes, starting at either the root node, or a specified ancestor.

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