Apama 10.15.0 | Building and Using Apama Dashboards | Building Dashboard Clients | Reusing Dashboard Components | Working with multiple display panels | Using tree controls in panel displays | Specifying tree control properties
 
Specifying tree control properties
There are a number of properties that you can specify for a tree control.
Specifying tree control background properties
The bgColor property determines the color of the tree control background. Select the bgColor property and click the Three dots button. Choose a color from the palette to set the background color of the tree control.
Specifying tree control data display properties
The following properties specify how data is displayed in the tree control.
*nodeIdColumnName
This property is available when the valueTableFormat is Row-Node. With the Row-Node format there are two table columns that define the tree structure: the nodeIdColumnName property and the parentIdColumnName property.
The nodeIdColumnName property specifies the table column containing the node ID string. The node ID string must be unique among all nodes with the same parent. Or, if the uniqueNodeIdFlag property is checked, each node ID string must be unique in the entire tree. By default, the node ID string is used as the node label in the tree.
*nodeIndexColumnNames
This property is available when the valueTableFormat is Row-Leaf. It specifies the path to a leaf node, that is, the ancestor nodes of the leaf.
When the valueTable property is attached to the current table of an instance the nodeIndexColumnNames property is typically set to the same columns that are specified in the Display variables field of the Attach to Apama dialog used to set the valueTable property.
Enter a semicolon-separated list of column names, where the Nth column name in the list contains the labels for tree nodes at depth N. The labels for top-level nodes are defined by the first column in the nodeIndexColumnNames property, the labels for the second-level nodes are defined by the second column, and so forth. For example:
AgentName;App Name;PID
The labels for the top-level nodes are defined by the AgentName column, the labels for the second-level nodes are defined by the App Name column, and labels for the third-level nodes are defined by the PID column.
To specify node labels from a different set of valueTable columns, use the nodeLabelColumnNames property.
*nodeLabelColumnName
This property is available when the valueTableFormat is Row-Node. By default, the node ID string is used as the node label in the tree. Use the nodeLabelColumnName property to specify a different valueTable column to provide the label.
*nodeLabelColumnNames
This property is available when the valueTableFormat is Row-Leaf. Use the nodeLabelColumnNames property to specify a different set of valueTable columns to provide node labels. Enter a semicolon-separated list of column names, one for each level in the tree, where the Nth column name in the list contains the labels for tree nodes at depth N.
*nodeStatusColumnName
This property applies to the status icon. It specifies the name of the valueTable column containing node status values. The column specified populates the Node Properties dialog Status Value column, in which you map node status values to image icons. The icons are displayed for any node whose value matches the value selected.
*nodeTypeColumnName
This property applies to the type icon. It specifies the name of the valueTable column containing values to use for mapping icon images to node types in the tree. The column specified populates the list of available values in the Node Properties dialog Node Depth or Type column, in which you map node types to image icons. The icons are displayed for any node whose value matches the value selected.
*parentIdColumnName
This property is available when the valueTableFormat is Row-Node. With the Row-Node format there are two table columns that define the tree structure: the parentIdColumnName property and the nodeIdColumnName property.
The parentIdColumnName property specifies the table column containing the parent node ID.
*uniqueNodeIdFlag
This property is available when the valueTableFormat is Row-Node.
When enabled, this property specifies that each node ID string must be unique in the entire tree. When disabled, it specifies that each node ID string must be unique among all nodes with the same parent.
*valueColumnName
Specifies the name of the column whose value is assigned to the $value variable when a node in the tree is selected. If not specified, the label string of the selected node is assigned to the $value variable. The $value variable is the only substitution that can be used in the Display Name field of a drill-down command.
*valueTable
Attach your tabular input data to this property. There are two valueTable format options, each with their own requirements: Row-Leaf and Row-Node.
As with other table-driven objects, the drillDownColumnSubs property can be configured to set substitutions to column values from the row in the valueTable that corresponds to the selected tree node.
*valueTableFormat
Specifies the format of the valueTable: Row-Leaf or Row-Node.
*varToSet
Allows you to update the attached variable with the value from the control.
Specifying tree control interaction properties
The following properties specify interactions in the tree control.
*actionCommand
Use the actionCommand property to assign a command to the tree. You can configure the tree to open a drill-down display, set substitutions, or run a command in response to a user click on a tree node.
The actionCommand property can reference the value from the tree by using the keyword $value. When the command is run, the variable attached to the varToSet property is updated with the selected node data.
The drillDownColumnSubs property can be configured to set substitutions to column values from the row in the valueTable that corresponds to the selected tree node.
If the execOnLeafOnlyFlag property is checked, the tree actionCommand property runs only when a leaf node is clicked (a click on a non-leaf node expands only the node). If unchecked, the tree actionCommand property runs on all nodes, not just the leaf.
*commandCloseWindowOnSuccess
If selected, the window that initiates a system command will automatically close when the system command is run successfully. This property only applies to system commands.
With data source commands, the window is closed whether or not the command is run successfully.
For multiple commands, this property is applied to each command individually. Therefore, if the first command in the multiple command sequence succeeds, the window will close before the rest of the commands are run.
The commandCloseWindowOnSuccess property is not supported in the display server.
*commandConfirm
If selected, the command confirmation dialog is enabled. Use the commandConfirmText property to write your own text for the confirmation dialog, otherwise text from the command property will be used.
For multiple commands, if you confirm the execution then all individual commands will be run in sequence with no further confirmation. If the you cancel the execution, none of the commands in the sequence will be run.
*commandConfirmText
Enter command confirmation text directly in the Property Value field or select the Three dots button to open the Edit commandConfirmText dialog. If commandConfirmText is not specified, then text from the command property will be used.
*drillDownColumnSubs
Use the drillDownColumnSubs property to set substitutions to column values from the row in the valueTable that corresponds to the selected tree node.
Select the Three dots button to open the Drill Down Column Substitutions dialog to customize which substitutions are passed into drill-down displays.
*enabledFlag
If unchecked, the tree nodes are the color gray and do not respond to user input.
*execOnLeafOnlyFlag
If checked, the tree actionCommand is run only for leaf nodes, and a click on a non-leaf node only expands the node. Also, the mouseover tooltip only appears for leaf nodes.
If unchecked, the tree actionCommand property runs on all nodes, and the mouseover tooltip appears for all nodes.
*mouseOverFlag
Specifies whether a tooltip appears when the cursor is positioned over a node. The tooltip shows the node path (the node label preceded by the labels of all of its ancestors), the node status (if the nodeStatusColumnName property is specified), and its value (if the valueColumnName property is specified).
*tabIndex
Use the tabIndex property to define the order in which the tree receives focus when navigated from your keyboard. Initial focus is given to the object with the smallest tabIndex value, from there the tabbing order proceeds in ascending order. If multiple objects share the same tabIndex value, initial focus and tabbing order are determined by the alpha-numeric order of the table names. Tables with a tabIndex value of 0 are last in the tabbing order.
The tabIndex property does not apply to tables in the display server, nor to objects that are disabled, invisible, or have a value of less than 0.
Specifying tree control label properties
The following properties specify the appearance of tree control labels.
*labelTextColor
This property sets the color of label text. Click the Three dots button and choose a color from the palette.
*labelTextFont
This property sets the font of label text. Select the font from the drop-down menu.
*labelTextSize
This property sets the height of the label in pixels.
Specifying tree control node structure properties
The following properties specify the node structure in the tree control.
*nodeStatusIconPos
Specify the status icon position in the tree: Left or Right. By default, the status icon appears on the left of the node label. If a node has both a type icon and a status icon, the type icon always appears to the left of the status icon. By default, no status icons appear in the tree.
*nodeStatusProperties
This property specifies the status icon for a node. By default, no status icon is displayed.
Click the Three dots button to open the Node Properties dialog and map images to values, and set the status priority order for propagation up the tree.
The nodeStatusProperties property is visible only if the nodeStatusColumnName property is non-blank.
You can also use the nodeStatusProperties property to attach a status icon to data. The data attachment must be a three-column table. Typically, a static XML file containing the table is used. The first column must contain string values that match values from the column in the valueTable specified by the nodeStatusColumnName property. The second column must be the path to the .png, .gif, or .jpg image. The third column must contain the non-negative integer priority value.
A static XML file is read once each time you run Dashboard Viewer. If you specify (or modify) an XML source using the Application Options dialog, you may specify whether that XML source is static.
*nodeTypeProperties
This property specifies the type icon for a node. By default, non-leaf nodes in the tree use a folder image and leaf nodes use a document image.
Click the Three dots button to open the Node Properties dialog to map images to nodes. Mapping can be based on the node depth in the tree or the type of node.
You can also use the nodeTypeProperties property to attach a type icon to data. The data attachment must be a two-column table. Typically, a static XML file containing the table is used. The first column must contain string values of _node (for non-leaf nodes), _leaf (for leaf nodes), numeric values for depth, or string values that match the node labels, or the values from the column in the valueTable specified by the nodeTypeColumnName property. The second column must be the path to the .png, .gif, or .jpg image. The default assignments are _node, rtvTreeNode16.png and _leaf, rtvTreeLeaf16.png. The column names are not important.
The logic for determining which type icon is used is as follows.
If the nodeTypeColumnName property specifies column C, and the value of C in the valueTable row that corresponds to N is V, and there is a row in nodeTypeProperties that assigns value V to image I1, then I1 is used as the type icon for N. Otherwise:
*If the label of node N is XYZ, and there is a row in the nodeTypeProperties property that assigns value XYZ to image I2, then I2 is used. Otherwise,
*If the depth of node N is D, and there is a row in the nodeTypeProperties property that assigns depth D to image I3, I3 is used. Otherwise,
*If N is a leaf, and the leaf node image is I4, I4 is used. If I4 is blank no type icon appears. Otherwise,
*If the non-leaf node image is I5, I5 is used. If I5 is blank no type icon appears.
A static XML file is read once each time you run Dashboard Viewer. If you specify (or modify) an XML source using the Application Options dialog, you may specify whether that XML source is static.
*rootNodeLabel
Specify whether the tree root node is visible. By default, this property is blank and the root node is not visible.
Specifying tree control object layout properties
The following properties specify the layout in the tree control.
*anchor
Specifies where to anchor an object in the display. If an object has the dock property set, the anchor property will be ignored.
The anchor property is only applied when the dimensions of the display are modified, either by editing Background Properties or resizing the window in Layout mode.
Select None, or one or more the following options:
*None - Object not anchored. This is the default.
*Top - Anchor top of object at top of display.
*Left - Anchor left side of object at left of display.
*Bottom - Anchor bottom of object at bottom of display.
*Right - Anchor right side of object at right of display.
When a display is resized the number of pixels between an anchored object and the specified location remain constant. If an object is anchored on opposite sides (that is, top and bottom or left and right), the object will be stretched to fill the available space. If the Resize Mode is set to Scale and an object is anchored on opposite sides, then the object will be moved rather than stretched to fill the available space.
*dock
Specifies the docking location of an object in the display. An object should not be docked if the Resize Mode is set to Scale.
Select from the following options:
*None - Object is not docked. This is the default.
*Top- Dock object at top of display.
*Left - Dock object at left of display.
*Bottom - Dock object at bottom of display.
*Right - Dock object at right of display.
*Fill - Dock object in available space remaining in the display after all docked objects are positioned.
If the dimensions of the display are modified, either by editing Background Properties or resizing the window in Layout mode, the properties (objX, objY, objWidth and objHeight) of docked objects will automatically adapt to match the new size of the display.
When multiple objects are docked to the same side of the display, the first object is docked against the side of the display, the next object is docked against the edge of the first object, and so on.
When objects are docked to multiple sides of the display, the order in which objects were added to the display controls docking position. For example, suppose the first object added to the display is docked at the top and the second object is docked at the left. Consequently, the first object will fill the entire width of the display and the second object will fill the left side of the display from the bottom of the first object to the bottom of the display.
Objects in a display that have the dock property set to Fill, are laid out across a grid in the available space remaining after all docked objects are positioned. By default, the grid has one row and as many columns as there are objects in the display. You can modify the grid in the Background Properties dialog.
Once an object is docked, there are some limitations on how that object can be modified.
*Docked objects cannot be dragged or repositioned using objX and objY properties.
*Docked objects cannot be resized using the objWidth or objHeight properties. To resize you must drag on the resize handle.
*Docked objects can only be resized toward the center of the display. For example, if an object is docked at the top, only its height can be increased by dragging down toward the center of the display.
*Docked objects set to Fill cannot be resized.
*Docked objects cannot be moved using Align. Non-docked objects can be aligned against a docked object, but a docked object will not move to align against another object.
*Docked objects are ignored by Distribute.
*objHeight
This property is read-only. It shows the height in pixels of the object, which is set by the height of the tree display.
*objName
Name given to facilitate object management by means of the Object List dialog. Select Tools > Object List.
*objWidth
This property is read-only. It shows the width in pixels of the object, which is set by the width of the tree display.
*objX
Sets the x position of the object.
*objY
Sets the y position of the object.
*visFlag
Sets the visibility of the object.
Descriptions of unique tree control property behavior
The following describes properties that behave uniquely with the tree control.
*valueColumnName - This property specifies the name of the column whose value should be assigned to the $value variable when a node in the tree is clicked. If not specified, the label string of the selected node is assigned to $value. Note that $value is the only substitution that can be used in the Display Name field of a drill-down command.
*mouseOverFlag - If this property is checked, a tooltip appears when the cursor is positioned over a leaf node. The tooltip shows the node path (the node label preceded by the labels of all of its ancestors), the node status (if the nodeStatusColumnName property is specified), and its value (if the valueColumnName property is specified).
*execOnLeafOnlyFlag - If this property is checked, the tree actionCommand property runs only when a leaf node is clicked (a click on a non-leaf node expands only the node). If unchecked, the tree actionCommand property runs on all nodes, not just the leaf.
*rootNodeLabel - This property specifies the tree root node (of which there is only one). By default, this property is blank and the root node is not visible.