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.
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:
The Tree item is defined in a resource file with the following structures:
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. |
The following messages are sent to item hook functions that are attached to tree items:
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. |
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.