Specifying tree control properties

The bgColor property determines the color of the tree control background. Select the bgColor property and click

. Choose a color from the palette to set the background color of the tree control.

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.

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 a scenario 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.

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.

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.

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.

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.

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.

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.

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.

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.

Specifies the format of the valueTable: Row-Leaf or Row-Node.

Allows you to update the attached variable with the value from the control.

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 execute 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 executed, 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 executes only when a leaf node is clicked (a click on a non-leaf node expands only the node). If unchecked, the tree actionCommand property executes on all nodes, not just the leaf.

If selected, the window that initiates a system command will automatically close when the system command is executed successfully. This property only applies to system commands.

With data source commands, the window is closed whether or not the command is executed 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 executed.

The commandCloseWindowOnSuccess property is not supported in the Display Server.

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 executed in sequence with no further confirmation. If the you cancel the execution, none of the commands in the sequence will be executed.

Enter command confirmation text directly in the Property Value field or select the

button to open the Edit commandConfirmText dialog. If commandConfirmText is not specified, then text from the command property will be used.

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

button to open the Drill Down Column Substitutions dialog to customize which substitutions are passed into drill-down displays.

If unchecked, the tree nodes are the color gray and do not respond to user input.

If checked, the tree actionCommand is executed 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 executes on all nodes, and the mouseover tooltip appears for all nodes.

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).

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.

This property sets the font of label text. Select the font from the drop-down menu.

This property sets the height of the label in pixels.

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.

This property specifies the status icon for a node. By default, no status icon is displayed.

Click the

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.

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

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,

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.

Specify whether the tree root node is visible. By default, this property is blank and the root node is not visible.

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:

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.

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:

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 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 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.

This property is read-only. It shows the height in pixels of the object, which is set by the height of the tree display.

Name given to facilitate object management by means of the Object List dialog. Select Tools > Object List.

This property is read-only. It shows the width in pixels of the object, which is set by the width of the tree display.

Sets the x position of the object.

Sets the y position of the object.

Sets the visibility of the object.

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 executes only when a leaf node is clicked (a click on a non-leaf node expands only the node). If unchecked, the tree actionCommand property executes 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.