As the number and complexity of your dashboards grow, you need the ability to modularize dashboard components into manageable and reusable sets. This allows you to efficiently develop and maintain your dashboards.
This chapter describes the features of Dashboard Builder that allow you to create reusable dashboard components and expand beyond the Table object for the rich display of tabular data.
The Object Grid allows you to display tabular data using one or more other object types to show the values of DataView fields. An Object Grid is, as the name implies, a grid of objects. Following is an example of an object grid from the Object Grid tutorial sample:
Here the grid is using one of the label object types in order to display the Instrument and Price variables of the tutorial DataView instances. The label object used provides a graphical indication of the price as well. There is one instance of the label object for DataView field. If a new instance is created, an entry for it would automatically be added to the object grid.
Most objects that appear in the object palette can be displayed in the object grid. Exceptions include tables, some graphs and some general objects. More than one object can be used to visualize each row in the tabular data.
The grid above uses three objects to display the Instrument, Price, and Shares variables of the DataView items.
Object grids provide one alternative to table objects for visualizing tabular data. They are simple to use but provide limited control over the layout of the objects:
The following illustrates the layout behavior of the object grid:
This is the same object grid as in the previous illustration. The only change is that it was resized to be slightly narrower which caused the flow layout of objects to change.
If precise control over the layout of objects is required use the Composite or Composite Grid objects.
The Object Grid is in the Composite tab of the object palette.
The Object Grid is initialized to display the same sample data as the Table object. The sample data contains seven rows so there are seven instances of the object in the grid.
After adding an Object Grid to your dashboard, you need to attach its valueTable property to the tabular data that you want to display. It can be attached to any tabular data source, including the following:
The iconProperties property is used to select and configure the objects that are displayed in the grid. With the grid object selected, in the Object Properties panel, double-click the iconProperties property to display the Icon Properties dialog.
By default the Object Grid is configured to display a single object for each row in its tabular data. The Icon Class Name field is where you select the type of object that you want to display in the grid:
The properties listed correspond to the properties of the object type selected. Properties in the Icon Properties dialog can have their value set in one of three ways. How a property is being set is indicated in the Map column of the property list:
If you click in the Map column for a property, the Builder displays a list that you can use to select how the property value is set.
If you select Value, the value for the property is entered in the Property Value column. If you select Column, clicking in the Property Value column will display a list of all the columns in the tabular data.
When you bind a property to a column in the tabular data, each instance of the object displayed in the grid has that property bound to the value of that column in the corresponding row in the tabular data.
To display multiple objects for each data row, enable the Allow multiple icon types check box at the bottom of the Icon Properties dialog.
When enabled, the dialog will change to allow you to add multiple objects for display in the grid.
Use Add Icon and Delete Icon buttons to add and remove objects from the grid.
The Dashboard Builder tutorial includes an example of the Object Grid, which you can view by double-clicking Object Grid on the tutorial main page. This displays the file tutorial-object-grid.rtv.
To recreate this sample, create a new dashboard and perform the following steps
Add an Object Grid to the dashboard and attach its valueTable property to the tutorial DataView as follows.
The grid object will update and display as follows:
Unless you have separately created or deleted instances of the tutorial DataView, the grid will display three instances of the object. The objects do not show any values from the tutorial DataView because none of their properties have been bound to it in the Icon Properties dialog.
Select the grid object and double-click the iconProperties property to display the Icon Properties dialog. In the dialog select obj_label14 as the Icon Class Name.
In the Icon Properties dialog click in the Map column of the value property and select the type Column. Click in the Property Value column and select Price.
This sets the value property of each instance of the object to the value of the Price variable in the corresponding instance of the tutorial DataView.
Similarly for the label property, set the Map column to Column and select Instrument as the value.
The dashboard should now appear similar to the Object Grid tutorial.
The Composite object allows you to display an rtv file as an object within another rtv file. This is a powerful capability which allows a complex dashboard to be subdivided into multiple components that can be independently developed and reused in multiple dashboards. The following illustration shows an example of a bid and ask depth display:
This can be created and saved in an rtv file and with the Composite object be used in one or more other dashboards.
Here the bid and ask display is shown in a Composite object combined with other objects to form a complete dashboard.
While the Composite object can display any rtv file, reusable rtv files are typically parameterized. When you select the rtv for display in a Composite object, the Composite object will expose as properties all the variables defined in the rtv file. These variables are the parameters to the file, and can be set as needed for each use of the file.
As a simple illustration consider an rtv file with a single label object, where you want the text of the label, its color, and its font to be configurable whenever the file is used in a Composite object.
To do this, define variables in the rtv file for each of these properties, such as the following:
In the properties panel, attach the label, labelTextColor, and labelTextFont properties of the label object to these variables.
When you use these variables in a Composite object, you’ll be able to set values for each in order to configure the appearance of the label.
When you edit properties of a Composite object, the property panel attempts to display the appropriate editor based on the name of the variable. Therefore, when you name variables for fonts and colors, end them with Font or Color, for example labelColor.
Variables that will be used for tabular data must have the data type Table.
When you define a variable, if you do not want to expose it as a property in a Composite object, uncheck the Public attribute of the variable in the Variables panel.
rtv file are not exposed as properties when the file is used in a Composite object. Variables that you want exposed as properties cannot be defined as substitutions, hence they can’t start with a $.Variable names cannot conflict with the names of properties of the Composite object; variables whose names conflict with Composite-object property names will not be exposed as properties. For example, you cannot have a variable label in a file displayed in a composite. The name conflicts with the label property of the Composite object.
The Composite object is in the Composite tab of the object palette.
The Composite object is initialized to display one row of the same sample data as the Table object. The rtv file displayed contains three objects to show the city and unit statistics.
After adding a Composite object to a dashboard you need to specify the rtv file to display. The rtvName property is used to select the file.
rtv file must not itself contain any composite objects. You cannot nest composite objects.When you select a file, the Composite object is redrawn in order to display the contents of the file.
Note that the Composite object is resized to the size specified in the file being displayed. When you create the file, set its Background Properties to the desired size and color.
The property panel for the Composite object will update to show as properties all the variables defined in the selected file.
Here the labelColor, labelFont, and labelText variables are exposed as properties. Setting these you can change the appearance of the Composite object:
Here the labelColor is set to red, the labelFont to SanSerif Bold and the labelText to the string Test.
Composite object properties that expose variables do not need to be set to static values. You can attach them to any data source, including a DataView. When so attached, a property’s corresponding variable changes whenever the attached data changes. Properties in the rtv file that are attached to the exposed variables will update in turn. The following dashboard illustrates this:
This dashboard consists of a table object showing all instances of the tutorial DataView and a Composite object containing a single label. This Composite object shows the current price of whatever instrument is selected in the table. Whenever the price changes the composite object updates to show the current price.
As in previous examples, the rtv file that is displayed in the composite has the variable labelText, which is exposed as a property on the Composite object. The label in the file is attached to labelText such that it will show its value. Rather than supplying a static value for the corresponding property labelText in the Composite object, this dashboard has labelText attached to the selected instance of the tutorial DataView.
By attaching the property to the DataView and filtering by $instanceId, the labelText property will update whenever the value of the attachment changes. When the labelText property changes, it will change the value of the corresponding variable in the rtv file displayed in the composite which will in turn be reflected in the label.
The Composite object supports the setting of substitutions on the file displayed in the composite. It has a single substitutions property where the name and value of one or more substitutions can be specified.
Substitutions are specified as a string with the following syntax:
$subname:subvalue $subname2:subvalue2 …
If a substitution value contains a single quote character, it must be escaped using a backslash.
$subname:/'Quoted Value/'
If a substitution value contains a space, the entire value must be enclosed in single quotes. Do not escape these single quotes.
$subname:'Value with Spaces'
The substitution names should not contain any of the following characters:
Colon (:), pipe (|), period (.), comma (,), semi-colon (;), equals (=), brackets (< >, ( ), { }, [ ]), quotation marks (’ “), ampersand (&), slashes (/ \)
When you use a Composite object to display detailed information on a selected DataView item, it is often easiest to set the substitution $instanceId on the composite. Setting $instanceId allows you to define in the rtv file displayed in the composite attachments and commands which filter on $instanceId as you normally would in other dashboards.
For this use case, the simplest way to set $instanceId as a substitution on a composite is to attach the substitutions property of the composite object to the apama.substitutions variable of the selected instance.
The value of apama.substitutions is a string formatted for use as the value of the substitutions property. An example of the value for an instance of the tutorial DataView is the following:
$instanceId:default.tutorial.21
This results in the substitution $instanceId being set to default.tutorial.21 in the rtv file displayed in the composite. Attachments and commands filtering on $instanceId would be tied to this instance.
If the file displayed in a Composite object has buttons or other objects which run Apama commands to edit or delete an instance, you need a substitution set to the ID of the instance. This substitution can be used as the filter on the command to identify the instance that the command operates on. The standard substitution to use is $instanceId.
Variables cannot be used in filters on attachments or commands. You cannot define a variable instanceId, use it in the filter, and set the value as a property on a composite object.
The Composite object has the command and drillDownTarget properties. These operate as with other objects, allowing you to define commands and drilldowns that are run when the object is clicked on.
If the file displayed in the composite contains objects with their command or drillDownTarget properties set, these will take precedence over those defined on the Composite object.
The following illustration is of a Composite object displaying an rtv file with one label object:
The label object Command A is defined to run some command,command A, and the command property of the composite is set to run a different command, command B. Clicking on the label object will run command A, since the command property in the rtv file overrides that of the composite. Clicking on the dark blue background of the composite will run command B.
The Dashboard Builder tutorial includes an example of the Composite object.
Open the file tutorial-composite-simple.rtv by selecting Composite Simple on the tutorial main page.
This dashboard displays a composite object with its rtvName property set to the file tutorial-composite-detail-simple.
Open the file tutorial-composite-detail-simple.rtv in the Dashboard Builder.
Examine the label, labelTextColor, and labelTextFont properties to see that they are attached to variables.
From the Tools menu, select Variables to see that the variables labelText, labelColor, and labelFont are defined as public variables. These variables are set as properties on the Composite object.
To recreate this sample, create a new dashboard and perform the following steps
Add a Composite object to the dashboard and set its rtvName property to tutorial-composite-detail-simple. The list of properties in the property panel for the Composite object will update.
Set the labelColor to red, the labelFont to Sans Serif Bold, and the labelText to Test.
The dashboard should now appear similar to the Composite Simple tutorial. Experiment with adding new variables to tutorial-composite-detail-simple.rtv and attach object properties to these. In the Composite object, experiment with attaching properties and substitutions to the tutorial DataView.
The Composite Grid object combines the capabilities of the Composite and Object Grid objects to provide a powerful and flexible means to display multiple DataView items.
Above, a Composite Grid is used to display the instances of the tutorial DataView. The rtv file displayed in the grid contains a set of objects to display the details of a single instance of the tutorial DataView.
The objects are attached to the tutorial DataView filtering on $instanceId to select a single instance. The Composite Grid object is configured to pass each instance a unique value of $instanceId such that there is one row in the grid for each instance.
iconProperties set to obj_composite. The Composite Grid has all the behaviors of the Object Grid and Composite objects.The Composite Grid is in the Composite tab of the object palette.
The Composite Grid is initialized to display the same sample data as the Table object. The sample data contains seven rows so there are seven instances of the object in the grid. For each row of data the Composite Grid displays an rtv file containing several objects to show the city and unit statistics.
After adding an Object Grid to your dashboard you need to attach its valueTable property to the tabular data to display. See the Object Grid section for details.
The iconProperties property is used to configure the Composite object displayed in the grid. With the grid object selected, in the Object Properties panel, double-click the iconProperties property to display the Icon Properties dialog.
Notice that Icon Class Name is set to obj_composite.
Within the Icon Properties dialog, set the rtvName property to the name of the rtv file to display in the Composite. The list of properties will update to show as properties all the public variables in the selected rtv file.
The properties of the Composite object can now be configured in the Icon Properties dialog as needed.
The substitutions property is preset to the value of apama.substitutions.
The effect of this is to set the substitution $instanceId uniquely for each instance of the Composite object displayed in the grid. Each instance will have $instanceId set to a unique item of DataView that the Composite Grid is attached to.
The Dashboard Builder tutorial includes an example of the Composite Grid object.
Open the file tutorial-composite-grid.rtv by selecting Composite Grid on the tutorial main page.
This dashboard displays in a grid a composite object with its rtvName property set to the file tutorial-composite-grid-detail.rtv.
Open the file tutorial-composite-grid-detail.rtv in the Dashboard Builder.
Examine the label and value properties of the objects to see that they are attached to the tutorial DataView filtering on $instanceId. Range Dynamic objects are used to show Shares, Position, and Velocity. These objects are configured to change color to show if the value is positive, negative, or zero.
To recreate this sample, create a new dashboard and perform the following steps
Add a Composite Grid object to the dashboard.
With the Composite Grid selected, in the Object Properties panel select the valueTable property and attach it to the tutorial DataView as follows:
The Composite Grid will be similar to the following:
Unless you have created or deleted instances of the tutorial DataView, there will be three instances of the Composite object in the grid. They do not show any data because the sample rtv file is not attached to the data of the tutorial DataView.
With the Composite Grid selected, double-click the iconProperties property in the Object Properties panel. This will display the Icon Properties dialog.
In the Icon Properties dialog set the rtvName property to tutorial-composite-grid-detail. Close the Icon Properties dialog.
The dashboard should now appear similar to the Composite Grid tutorial.
The Dashboard Builder include file feature provides a way to partition dashboard development and to reuse content in multiple dashboards. It allows you to include in a dashboard the objects, functions, and variables of another rtv file. Unlike the Composite object, the included file is not in an object; rather, the contents of the included file are added to the dashboard.
A common use of include files is for navigation controls and status bars that are part of multiple dashboards. These objects could be defined in the rtv file statusbar.rtv. The file statusbar.rtv could then be included in another dashboard.
To include an rtv file in a dashboard, select Include Files in the Tools menu. This will display the Include Files dialog.
The Add and Remove buttons are used to add and remove included rtv files. More than one rtv file can be included, and the included files can themselves include other files. However, a file will only be included once.
All the objects, functions, and variables that are defined in an included file become part of the dashboard. Within the Dashboard Builder these are, with one exception, read-only. They appear, can be copied, and can be used in attachments, but they cannot be modified. To modify included elements, open the file containing them in the Dashboard Builder.
The exception is for the initial value of an included variable. Within a dashboard, you can override the initial value of included variables. Consider, for example, an included file that contains a label that is attached to the variable headerTitle. When you include this file in a dashboard, the value of the variable headerTitle can be set to the title of the dashboard.
objName property as objects in the current display, or other included displays, this may cause links to attach to the wrong object. To avoid this overlap, assign a unique value to the objName property of objects in files that you intend to include in other displays.The background properties such as Model Width, Model Height, and bgColor of included files are ignored.
Substitutions such as $instanceId may be used in attachments in included files. Substitutions and variables in included files are scoped to the including dashboard. Runtime changes to their values will be reflected in included objects and functions. An attachment in an included file filtering on $instanceId will update whenever $instanceId changes in the dashboard.
The Dashboard Builder tutorial includes an example of Include Files.
Open the file tutorial-include-sub.rtvby selecting Include File Subs on the tutorial main page.
This dashboard uses a status bar defined in an included file. The status bar contains an indicator of correlator connectivity and objects to show the instrument, price, and other variables of the selected instance of the tutorial DataView.
Open the file tutorial-include-sub-background.rtv in the Dashboard Builder.
Examine the attachments of the value and label properties of the objects. Notice that they are attached to the tutorial DataView and filtering on $instanceId. No values are displayed because $instanceId does not have a value. It is set in the dashboard that includes this file.
To recreate the Include File sample, create a new dashboard and perform the following steps
Add a Table object to the dashboard and attach its valueTable property to the tutorial DataView as follows:
Select Include Files from the Tools menu and add tutorial-include-sub.background.rtv.
The dashboard should now appear similar to the Include File tutorial. Double-click a row in the table to see values displayed in the included status bar.
It is possible to deploy several displays arranged in separate panels in a single window. Multiple panels are useful when you want to view multiple displays from a top level entry point or if you need to include a navigation panel. To define a window with multiple display panels, create an XML file, a panels-configuration file, that specifies a panel layout for a deployed dashboard.
You can supply the location of the panels-configuration file to the Dashboard Viewer executable by using the -C or --panelConfig option (see Startup options for the Dashboard Viewer).
The name of a panels-configuration file must have the .ini extension. By default, the Display Viewer looks for the PANELS.ini file in the current directory. If a panels-configuration file is not found in the current directory, the display server and Display Viewer look for it in the lib directory of your Apama installation directory.
The panels-configuration file is in XML, and must start with the following:
<?xml version="1.0" ?>
<panels xmlns="www.sl.com" version="1.0">
The panels-configuration file must end with the following:
</panels>
In this release, a new set of tags are allowed in the panels-configuration file. These tags are different from the tags that were allowed in previous releases. Previously allowed tags are still allowed. However, new tags and old tags cannot be in the same panels-configuration file.
For information about the new tags, see Using new tags to configure the panels in a window.
For information about the old tags, see Using old tags to configure the panels in a window.
When using the new tags each panels-configuration file must contain exactly one rtvLayout tag. The rtvLayout tag encloses the tags that define the multiple displays. Each child tag of the rtvLayout tag must specify the region attribute with a value of north, south, east, west, or center. This determines the location of each panel in the display.
Typically, an rtvLayout tag contains one of the following combinations:
A main rtvDisplayPanel tag whose region attribute is set to center.
An rtvAccordionPanel tag or an rtvTreePanel tag whose region attribute is set to west or east.
Possibly other secondary rtvDisplayPanel tags with other region attribute values.
A main rtvTabbedDisplayPanel tag whose region attribute is set to center.
Possibly other secondary rtvDisplayPanel tags with other region attribute values.
An rtvLayout tag can contain the following attribute:
dividers - Set to true if you want a divider to be drawn between child panels. The default is false.As a child of the rtvLayout element, you can specify one or more rtvDisplayPanel elements. An rtvDisplayPanel element creates a panel. The display inside the panel is specified by the following rtvDisplayPanel attributes:
display - Specify the location of this CardPanel if it is in a BorderPanel. Valid values are west, east, center, north, and south
name - Specify the Window Name previously specified in the Drill Down Properties dialog. If you are using tabbed panels and you do not specify a name, it is constructed by using the display name and substitutions to make it easy to drill down between tabs. In this case, when you drill down from a tab by using the Current Window option and the specified display with the specified substitutions is already loaded in another tab, the Display Viewer switches to that tab.
region - Specify the position of the panel as west, east, center, north, or south.
subs - Specify initial substitutions for this panel. Substitutions are optional and must use the following syntax:
$subname:subvalue $subname2:subvalue2
If a substitution value contains a single quote you must escape it by using a forward slash, for example:
$filter:Plant=/'Dallas/'
If a substitution value contains a space it must be enclosed in single quotes. Do not escape these single quotes. Following is a correct example:
$subname:subvalue $subname2:'sub value 2'
A substitution string cannot contain the following characters:
: |. tab space,; = < > ' " & / \ { } [ ] ( )
Substitutions that you set in Application Options apply to all displays.
Following is an example of; an rtvDisplayPanel element:
<rtvDisplayPanel region="north" name="title_panel" display="title.rtv"
</rtvDisplayPanel>
As a child of the rtvLayout element, you can specify one or more rtvAccordionPanel elements. An rtvAccordionPanel element creates a panel that contains an accordion control for display navigation. The accordion control assumes there is a panel in the center region that was created with the rtvDisplayPanel element. The accordion control sends its navigation commands to this center panel.
The contents of a panel created with the rtvAccordionPanel element cannot be more than two levels deep, not including the root node. If you require deeper nesting create a panel with the rtvTreePanel element.
Use the following attributes to specify the location of an accordion control panel:
region - Specify the position of the panel as west, east, center, north, or south. The default is center.width - Specify the width of the panel in pixels. The default is 125.As a child of the rtvLayout element, you can specify one or more rtvTreePanel elements. An rtvTreePanel element creates a panel that contains a static navigation tree. The navigation tree assumes there is a panel in the center region that was created with the rtvDisplayPanel element. The static navigation tree sends its navigation commands to this center panel.
There are two ways to create a tree-driven, multi-panel application: the static tree navigation panel and the tree control. Use a static tree navigation panel when you know the specific sources that are to populate the tree and they remain constant for the life of the application. For example, if you know all the displays that compose your application and the static representation of a tree will be used only for navigating those displays the static tree navigation panel is suitable, as well as easier to configure.
Use the tree control when the number of tree nodes, leaves, labels, or icons changes during the lifetime of the application. Data can be provided that will change the nodes and leaves of the tree and also change the label and icon representation on the tree with dynamic data. See Using tree controls in panel displays.
Use the following attributes to specify the location of a static tree navigation panel:
region - Specify the position of the panel as west, east, center, north, or south. The default is center.width - Specify the width of the panel in pixels. The default is 125.As a child of the rtvLayout element, you can specify one or more rtvTabbedDisplayPanel elements. An rtvTabbedDisplayPanel element creates a panel with tabs for navigation. The display inside the panel is specified by the following rtvTabbedDisplayPanel attributes:
tabs - Specify the name of a tab definition file. This XML file should describe the tabs you want in the panel. See Using tab definition files.
display - Specify the name of the display (.rtv) file to load into the panel.
subs - Specify initial substitutions for this panel. Substitutions are optional and must use the following syntax:
$subname:subvalue $subname2:subvalue2
If a substitution value contains a single quote you must escape it by using a forward slash, for example:
$filter:Plant=/'Dallas/'
If a substitution value contains a space it must be enclosed in single quotes. Do not escape these single quotes. Following is a correct example:
$subname:subvalue $subname2:'sub value 2'
A substitution string cannot contain the following characters:
: |. tab space,; = < > ' " & / \ { } [ ] ( )
Substitutions that you set in Application Options apply to all displays.
region - Specify the position of the panel as west, east, center, north, or south.
placement - Specify top or bottom to indicate where you want the tabs to appear in the panel.
Following is an example of; an rtvDisplayPanel element:
<rtvDisplayPanel region="north" name="title_panel" display="title.rtv"
</rtvDisplayPanel>
When you specify an rtvTabbedDisplayPanel element in a panels configuration file, you must set the element’s tabs attribute to the name of the tab definition file that defines the tabs you want in the panel.
The tab definition file must start with the following:
<?xml version="1.0" ?>
<navtree>
The tab definition file must end with the following:
</navtree>
For example:
<?xml version="1.0" ?>
<navtree>
<node label="Bar Chart" display="disp1.rtv"/>
<node label="History Graph" display="disp2.rtv" subs="$v1:xyz"/>
</navtree>
Inside the navtree element, you can define one or more node elements. Each node element adds a tab to the panel. You can specify the following attributes for each node element:
display - Specify the name of the display (.rtv) file.
label - Specify the label for this tab in the panel.
subs - Specify substitutions to apply to this tab. Substitutions are optional and must use the following syntax:
$subname:subvalue $subname2:subvalue2
If a substitution value contains a single quote you must escape it by using a forward slash, for example:
$filter:Plant=/'Dallas/'
If a substitution value contains a space it must be enclosed in single quotes. Do not escape these single quotes. Following is a correct example:
$subname:subvalue $subname2:'sub value 2'
A substitution string cannot contain the following characters:
: |. tab space,; = < > ' " & / \ { } [ ] ( )
The following PANELS.ini file uses the new tags and creates a title panel at the top, an accordion panel on the left, and a main display in the center. There are draggable dividers between all panels.
<?xml version="1.0" ?>
<panels xmlns="www.sl.com" version="1.0">
<rtvLayout title="Accordion Example" dividers="true">
<rtvDisplayPanel region="north" name="title_panel"
display="title.rtv"/>
<rtvAccordionPanel region="west" width="200" navdata="navtree.xml"/>
<rtvDisplayPanel region="center" name="main_panel"
display="chart_main.rtv"/>
</rtvLayout>
</panels>
The next PANELS.INI file creates a tabbed display panel at the top and a title panel at the bottom.
<?xml version="1.0" ?>
<panels xmlns="www.sl.com" version="1.0">
<rtvLayout title="Tab Example">
<rtvTabbedDisplayPanel region="center" tabs="navtabs.xml"
display="stock_chart"/>
<rtvDisplayPanel region="south" name="title_panel" display="title.rtv"/>
</rtvLayout>
</panels>
The tree control (class name: obj_c1tree) lets you create a rich and compact visual presentation of hierarchical data. This control is most often used in a multi-panel application for display navigation. The control tree can also be used in any application where hierarchical data is most effectively displayed using expandable/collapsible tree nodes.
There are two methods for creating a tree-driven multi-panel application:
rtvTreePanel tag to the PANELS.ini file. For details about configuring the tree, see Configuring static tree navigation panels.When using the tree control to construct an application with multiple panels one panel displays a .rtv file that has instanced the tree control and the other contains the displays which are drilled down to by selecting items on the tree.
The following illustrates a two-panel application in which the tree control in the left panel updates the display in the right panel:
You can optionally configure tree control icons, using images of your choice, to visually indicate the type of elements in the tree, for example, Production or Sales, whether the element is in a critical state, and to also propagate the status of priority elements to the top of the tree. See Configuring tree control icons.
The input of tabular data determines the content of the tree control, as well as the appearance of each object in the tree. As with other controls, to configure a drill-down, set substitutions, or run a command when a user clicks a tree node, use the actionCommand property. As with other table-driven objects, the drillDownColumnSubs property can be configured to set substitutions to column values from the row in the table (attached to the valueTable property) that corresponds to the selected tree node.
After you attach your tabular data to the tree control valueTable property, specify the table format for the tree in the valueTableFormat property. The table format is determined by the format of the table you attach to the valueTable property. There are two table format options, each with their own requirements:
valueTable property is attached to a table and all leaves in the tree are at the same depth. For example, where the tree control is attached to an instance table. The nodeIndexColumnNames property specifies the columns from the instance table that will appear in the hierarchy in the tree control.The default table format is row-leaf. The following are examples of the row-leaf and row-node table formats, which both produce the tree in the image that follows. Here is a row-leaf table:
| App Name | PID |
|---|---|
App0 |
1000 |
App0 |
1004 |
App0 |
1008 |
App1 |
1001 |
App1 |
1005 |
Here is a row-node table:
| Node | Parent |
|---|---|
app0 |
|
1000 |
app0 |
1004 |
app0 |
1008 |
app0 |
app1 |
|
1001 |
app1 |
1005 |
app1 |
Here is the tree control that both these tables produce:
After you configure the tree table format, you can optionally configure the tree control icons. See Configuring tree control icons.
In the row-leaf table format, there is one row in the table for each leaf node in the tree. A leaf node is added to the tree for each row in the table attached to the valueTable property. The path to a leaf node (that is, the ancestor nodes of the leaf) is determined by the values in each of the table columns specified by the nodeIndexColumnNames property. When the valueTable property is attached to the instance table, the tree’s nodeIndexColumnNames property is typically set to the same columns that are specified in the Display variables field of the Attach to Apama dialog.
To illustrate how to create a tree using the row-leaf format, consider a table that has two columns, App Name and PID, and the following rows:
| App Name | PID |
|---|---|
app0 |
1000 |
app0 |
1004 |
app0 |
1008 |
app1 |
1001 |
app1 |
1005 |
Set tree control properties as follows:
valueTable property to Apama as you would attach any table object. In the Attach to Apama dialog, in the DisplayVariables field, select the variables App Name and PID.valueTableFormat property to the Row-Leaf format.nodeIndexColumnNames property to App Name;PID.The following image illustrates the structure of the tree. There are two nodes labeled app0 and app1. Node app0 has three child nodes labeled 1000, 1004, 1008. Node app1 has two child nodes, labeled 1001 and 1005.
Suppose we add another column, AgentName, by selecting that variable from the Display Variables field of the Attach to Apama dialog. The table has the following rows:
| AgentName | App Name | PID |
|---|---|---|
Agent1 |
App0 |
1000 |
Agent1 |
App0 |
1004 |
Agent1 |
App0 |
1008 |
Agent1 |
App1 |
1001 |
Agent1 |
App1 |
1005 |
Agent2 |
App0 |
1000 |
Agent2 |
App0 |
1004 |
Agent2 |
App1 |
1001 |
We also update the tree control nodeIndexColumnNames property to AgentName;App Name;PID.
The following figure illustrates the new structure of the tree. The tree now has two top-level nodes labeled Agent1 and Agent2, each with two child nodes, app0 and app1.
As illustrated above, the label string for a node at depth N is taken from the Nth column in the nodeIndexColumnNames property. Therefore, the labels for the top-level nodes come from the first column in the nodeIndexColumnNames property (AgentName), the labels for the second-level nodes come from the second column in nodeIndexColumnNames property (App Name), and so forth.
To specify node labels from a different set of valueTable columns, use the nodeLabelColumnNames property. Enter a semicolon-separated list of column names in the nodeLabelColumnNames property, one for each level in the tree, where the Nth column name in the list contains the labels for tree nodes at depth N.
To modify tree control icons or configure tree control icon behavior, see Configuring tree control icons.
In the row-node format tree control, there is one row in the table for each node in the tree, including the top-level node rather than just one row for each of the leaf nodes as with the row-leaf format.
There are two columns in the table that help define the tree structure:
nodeIdColumnName property. By default, the node ID string is used as the node label in the tree. 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.parentIdColumnName property.To create the same tree as the row-leaf format example in the previous topic, a table representation of the tree control using the row-node format would be as follows:
| Node | Parent |
|---|---|
app0 |
<blank> |
1000 |
app0 |
1004 |
app0 |
1008 |
app0 |
app1 |
<blank> |
1001 |
app1 |
1005 |
app1 |
The <blank> entries represent an empty string, which indicates that nodes app0 and app1 have no parent, making them top-level nodes in the tree.
Set the tree control properties as follows:
valueTable property to attach to the table that contains the data to be displayedvalueTableFormat property to the Row-Node formatnodeIdColumnName property to NodeparentIdColumnName property to ParentThe result is a tree structure with two top-level nodes labeled app0 and app1. Node app0 has three child nodes labeled 1000, 1004, 1008. Node app1 has two child nodes, labeled 1001 and 1005.
To add another tree level for the AgentName, as in the Row-Leaf format example in the previous topic, modify the table as follows:
| Node | Parent |
|---|---|
Agent1 |
<blank> |
app0 |
Agent1 |
1000 |
app0 |
1004 |
app0 |
1008 |
app0 |
Agent2 |
<blank> |
app0 |
Agent2 |
1000 |
app0 |
1004 |
app0 |
app1 |
Agent2 |
1001 |
app1 |
1005 |
app1 |
Also, uncheck the uniqueNodeIdFlag property to allow for node IDs that are not unique, such as the app0 and 1000 nodes in the example, which are used in multiple tree levels. Because some of the rows are also identical, the order of the table rows is important. For example, this row appears twice in the table: 1000 app0. In each case the 1000 app0 row comes after a unique parent row: first under app0 Agent1 and then under app0 Agent2. The tree uses this information to determine where to place the node for 1000 in each case.
The tree now has two top-level nodes labeled Agent1 and Agent2, each with two child nodes, app0 and app1.
By default, the node ID string is used as the node label in the tree. If a different column in the table must provide the label, specify the name of that column in the nodeLabelColumnName property.
In the row-node format, each branch of the tree can have a different depth, while in the row-leaf format all branches typically have the same depth, which is the number of columns specified in the nodeIndexColumnNames property.
To modify tree control icons or configure tree control icon behavior, see Configuring tree control icons.
You can optionally configure tree control icons, using images of your choice, to visually indicate the type of elements in the tree, for example, Production or Sales, whether the element is in a critical state, and to also propagate the status of priority elements to the top of the tree.
The use of one or both of the following icons is optional. Each node in the tree control can display these two configurable icons:
Type icon — Use the type icon to assign static images to nodes that indicate either the type of element it contains, or its level in the tree. By default, a folder image is used for all non-leaf nodes, and a document image is used for all leaf nodes.
For example, if you have groups of elements based on geographic location, you could assign an icon for the country, state and city (for example, US, California, San Francisco). Or, if you have groups of elements based on their function, you could assign an icon for each function (Purchases, Operations, Sales, and so forth). You can also assign images for each depth in the tree for a visual indication of where you are while navigating within the tree.
Status icon — Use the status icon to assign images that are used when an element in the tree has a specified value. You can also configure the status in order of priority so that the most critical status is propagated up the tree first. By default, there is no status icon.
If a node has a type icon and a status icon, the type icon always appears to the left of the status icon.
For convenience, both the type icon and the status icon can be attached to data. The type icon and status icon have different data table requirements. Typically, an attachment to a static XML file containing the appropriate tables is used. The following describes the data table format requirements:
nodeTypeProperties property. 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 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.nodeStatusProperties property. 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 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. For details, see Creating XML Sources.
Type icons indicate the type of node in the tree. The type icon for each node is determined either by the value of a column in the valueTable property, or by the node position in the tree. By default, the type icon appears to the left of the node label.
This section describes how to configure type icons using the Node Properties dialog. You can also configure type icons by attaching the nodeTypeProperties property to data.
To configure the type icon, use the nodeTypeProperties property to define a two-column table of data. Select the nodeTypeProperties property in the property sheet, then click the 
button to open the Node Properties dialog.
In the Node Properties dialog, the Node Depth or Type column lists the available nodes. The first two rows, non-leaf node and leaf node, indicate the default settings: non-leaf nodes in the tree use a folder image and leaf nodes use a document image. To change the default setting, click the button in the Image column for the node and choose an icon from the Select Image dialog.
The next five rows, numbered0 - 4, represent the node depth or level, zero (0) being the root node. The Image column lists the icons being used for each node. By default, the Image column for all of those rows is <blank>, indicating that the non-leaf node and leaf node icon assignments are used. Icon assignments override non-leaf node and leaf node assignments.
You can also assign an image icon based on node level. Such an icon provides a visual indication of where you are while navigating in the tree. To assign an image to a specific node level in the tree, click the button for one of the rows numbered 0 - 4 in the Image column and choose an icon from the Select Image dialog. Repeat for each node level.
You can assign an image icon based on node labels you create that describe the nodes as a group. For example, suppose the Node Depth or Type column contains the string Davies with the 
image selected.
This means that all nodes whose label matches the Davies string display the image in the tree.
To assign an image to a specific node type in the tree, assign a column name in the nodeTypeColumnName property. Select the nodeTypeProperties property in the property sheet, then click on the button to open the Node Properties dialog. Click New to add a custom row to the table. A drop-down list of values for the column assigned to the nodeTypeColumnName property appears in the Node Depth or Type column. Select a column name from the drop-down list. Click the button in the Image column and choose an icon (to use for all nodes that have that column name in the valueTable row that corresponds to the node) from the Select Image dialog.
You can also type a string in the Node Depth or Type column and the Image column.
To not use an icon, in the Node Properties dialog, select the icon in the Image column, then click Clear.
Note that the root node is invisible if the rootNodeLabel property is blank.
Status icons indicate the current state of a node. You can configure the status icon to propagate the status of a child node up the tree to its ancestors. The status icon shown for an ancestor node corresponds to the current highest status priority among all of its descendants.
The status icon for a node is determined by the discrete value of a specified column in the valueTable property. The values can be strings or numbers. The comparison is done for an exact match. If the current status value for a tree node does not match any of the values you specify in the nodeStatusProperties property, no status icon is displayed for that node.
By default, the status icon appears on the left of the node label. The value, Left or Right, is specified in the nodeStatusIconPos property. 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 section describes how to configure status icons using the Node Properties dialog. You can also configure status icons by attaching the nodeStatusProperties property to data. For details about that, see Attaching a tree control icon to data.
To configure status icons, specify the status table column name in the nodeStatusColumnName property, then use the nodeStatusProperties property to define a three-column table of data and configure icon behavior. The nodeStatusProperties property is visible only if the nodeStatusColumnName property is non-blank.
Select the nodeStatusProperties property in the property sheet, then click the button to open the Node Properties dialog.
In the Node Properties dialog, to map an image to a node status, click New, then click in the Status Value column. A drop-down list appears containing all values in the node status column of the valueTable property (which you previously specified in the nodeStatusColumnName property). Select a value from the drop-down list.
Click the button in the Image column for the node and choose an icon from the Select Image dialog. This icon is used as the status icon for all nodes that match the value selected in the Status column.
Click the button in the Priority column for the node and assign an integer value: 0, 1, 2, 3, 4, 5, or a higher number. There is no upper limit on the number. The largest number is the highest priority and is propagated up the tree first. A value of zero (0) is not propagated. You might want to assign a value of zero to multiple nodes so that they do not propagate up the tree. A non-zero value can be assigned only once.
For example, suppose the nodeStatusColumnName property is set to the Application Status table column of the valueTable property. You could define the mapping for the nodeStatusProperties property as follows:
| Status Value | Image | Priority |
|---|---|---|
| Blocked |  |
2 |
| Running |  |
1 |
The values in the Application Status column of each row in the valueTable property is compared to the two values listed in the Status Value column (Blocked and Running). If the Application Status value in one of the rows is Blocked, the status icon is displayed as the status icon for that row. If there is no match, for example, the Application Status value in one of the rows is unknown, no status icon is displayed in the tree node for that row. Because the status icon is assigned the highest priority, the status icon is always propagated up the tree first. If none of the rows has a Blocked status, the status icon is propagated up the tree.
For example, in the following illustration, the priority status of a single node, app3/1003, is propagated up to its parent, app3, and also to the top-level ancestor, Agent1.
There are a number of properties that you can specify for a tree control.
The bgColor property determines the color of the tree control background. Select the bgColor property and click the button. Choose a color from the palette to set the background color of the tree control.
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.
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 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 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.
The following properties specify the appearance of tree control labels.
labelTextColor
This property sets the color of label text. Click the 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.
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 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 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:
rootNodeLabel
Specify whether the tree root node is visible. By default, this property is blank and the root node is not visible.
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:
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:
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.
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.
The following describes properties that behave uniquely with the tree control.
In the Display Viewer, mouseover text is displayed only if the tree has focus.
In the Thin Client:
The tags described in this topic are deprecated. They will be removed in a future release. You should change to the new tags. See Using new tags to configure the panels in a window.
When using the old tags in the panels-configuration file the following tags are supported. Remember that you cannot mix old tags and new tags in the same panels-configuration file.
| Tag | Description |
|---|---|
BorderPanel |
A border panel allows you to specify a central display and place up to four other displays to the north, south, east or west. Border panels are implemented as javax.swing.JPanels with a BorderLayout Add a JPanel with a border layout to the main window. See Using border panels. |
CardPanel |
A card panel allows you to stack displays so that they are all active, but only one is showing. This is useful when you have a trend graph that needs to maintain data when it is not being displayed. Card panels are implemented as javax.swing.JPanel with a CardLayout. Display server deployments do not support card panels. Add a JPanel with a card layout to the main window. See Using card panels. |
GridPanel |
A grid panel allows you to arrange your panels in tabs. Add a JPanel with a grid layout to the main window. See Using grid panels. |
TabbedPanel |
A tabbed panel allows you to arrange your panels in tabs. Add a JTabbedPane to the main window. See Using tabs panels. |
RTViewNavTreePanel |
A tree panel can be used inside a border panel to display a tree that is used to navigate displays in one of the border panel regions. Add a JPanel containing a JTree into a BorderPanel. This requires use of the CardPanel. See Using the RTViewNavTreePanel tag. |
RTViewPanel |
Add a panel containing the specified display into a BorderPanel, CardPanel, TabbedPanel, or GridPanel. See Using the RTViewPanel tag. |
The tags described in this topic are deprecated. They will be removed in a future release. You should change to the new tags. See Using new tags to configure the panels in a window.
Use the BorderPanel tag to add a border panel to the main window. This tag supports the following attribute:
| Attribute | Description |
|---|---|
minWidth |
Set the minimum width for a BorderPanel, in pixels. The default value is 300. The minimum height is determined by the minWidth and the overall aspect ratio of the panels contained in the BorderPanel. The minWidth attribute can be used to prevent the Dashboard Viewer from being resized so small that the displays in the BorderPanel are unreadable. |
Use RTViewPanel or RTViewNavTreePanel subelement to specify .rtv files for the center, north, south, east, and west panels.
Here is an example:
<?xml version="1.0" ?>
<panels xmlns="www.sl.com" version="1.0">
<BorderPanel title="Test of Border Panels">
<RTViewPanel region="north" name="north_panel" display="long_panel"
subs="$title:'North Panel'"/>
<RTViewPanel region="center" name="center_panel" display="small_panel"
subs="$title:'Center Panel'"/>
<RTViewPanel region="west" name="west_panel" display="small_panel"
subs="$title:'West Panel'"/>
<RTViewPanel region="east" name="east_panel" display="small_panel"
subs="$title:'East Panel'"/>
<RTViewPanel region="south" name="south_panel" display="long_panel"
subs="$title:'South Panel'"/>
</BorderPanel>
</panels>
When you create displays for use in border panels, the height and width of each display must be set in relation to the other displays. Displays in the west, east and center must all be equal in height. The width of the display in the north and south, must equal the combined width of the displays in the west, east and center. You will need to increase the width of the display in the north and south by the border width for each border that divides the west, center and east panels. To set the height and width of a display in the Dashboard Builder, select File | Background Properties and set the Model Width and Model Height. If you are using a background image for your display, create the image so that the height and width of the image are one pixel larger than the size you want the display to be.
The following shows dimensions of display (.rtv) files set to fit accurately in multiple display panels:
| Display Name | Display Location | Model Width | Model Height |
|---|---|---|---|
small_panel.rtv |
center | 320 | 240 |
small_panel.rtv |
east | 320 | 240 |
small_panel.rtv |
west | 320 | 240 |
long_panel.rtv |
north | 962 | 120 |
long_panel.rtv |
south | 962 | 120 |
The tags described in this topic are deprecated. They will be removed in a future release. You should change to the new tags. See Using new tags to configure the panels in a window.
With card layout, you use the CardPanel element to specify a main panel and subordinate panels. Display server deployments do not support card layout.
The CardPanel tag supports the following attribute:
| Attribute | Description |
|---|---|
region |
Set the location of this CardPanel if it is in a BorderPanel. Valid values are west, east, center, north, and south. |
Here is an example:
<?xml version="1.0" ?>
<panels xmlns="www.sl.com" version="1.0">
<CardPanel>
<RtViewPanel title=" Main Panels " name="main" display="main_panel"/>
<!-- The following three panels will always be kept in memory -->
<RtViewPanel title="Panel 101" display="med_panel" subs="$title:101">
<RtViewPanel title="Panel 102" display="med_panel" subs="$title:102">
<RtViewPanel title="Panel 103" display="med_panel" subs="$title:103">
<!-- All other displays will be loaded on demand -->
</CardPanel>
</panels>
When you create displays for use in card panels, the height and width of each display must be the same. To set the height and width of a display in the Dashboard Builder, select File | Background Properties and set the Model Width and Model Height. If you are using a background image for your display, create the image so that the height and width of the image are one pixel larger than the size you want the display to be.
The tags described in this topic are deprecated. They will be removed in a future release. You should change to the new tags. See Using new tags to configure the panels in a window.
Use the GridPanel tag to arrange panels into a specified number of rows and columns. Display server deployments do not support grid layout.
This tag supports the following attributes:
| Attribute | Description |
|---|---|
columns |
Sets the number of columns in the grid. If the number of columns is not specified, it will be calculated based on the number of RTViewPanels and the specified number of rows. |
rows |
Sets the number of rows in the grid. If the number of rows is not specified, it will be calculated based on the number of RTViewPanels and the specified number of columns. |
Here is an example:
<?xml version="1.0" ?>
<panels xmlns="www.sl.com" version="1.0">
<GridPanel title="Test of Grid Panels" rows="0" columns="3">
<RTViewPanel name="detail1" display="small_panel" subs="$title:'101'"/>
<RTViewPanel name="detail2" display="small_panel" subs="$title:'102'"/>
<RTViewPanel name="detail3" display="small_panel" subs="$title:'103'"/>
<RTViewPanel name="detail4" display="small_panel" subs="$title:'201'"/>
<RTViewPanel name="detail5" display="small_panel" subs="$title:'202'"/>
<RTViewPanel name="detail6" display="small_panel" subs="$title:'203'"/>
</GridPanel>
</panels>
When you create displays for use in grid panels, the height and width of each display must be the same. To set the height and width of a display in the Dashboard Builder, select File > Background Properties and set the Model Width and Model Height. If you are using a background image for your display, create the image so that the height and width of the image are one pixel larger than the size you want the display to be.
The tags described in this topic are deprecated. They will be removed in a future release. You should change to the new tags. See Using new tags to configure the panels in a window.
Use the TabbedPanel tag to arrange .rtvfiles into a tabbed panel. This tag supports the following attributes:
|
Attribute |
Description |
|---|---|
|
|
Set the position of the tab. Valid arguments are Info
This argument is ignored by the data server. Tabs are always in the top position.
|
|
|
Set to |
<?xml version="1.0" ?>
<panels xmlns="www.sl.com" version="1.0">
<TabbedPanel title="Test of Tabbed Panels" placement="top">
<RTViewPanel title="Main Panel" display="main_panel"/>
<RTViewPanel title="Panel 101" display="med_panel" subs="$title:101"/>
<RTViewPanel title="Panel 102" display="med_panel" subs="$title:102"/>
<RTViewPanel title="Panel 103" display="med_panel" subs="$title:103"/>
<RTViewPanel title="Panel 201" display="med_panel" subs="$title:201"/>
<RTViewPanel title="Panel 202" display="med_panel" subs="$title:202"/>
<RTViewPanel title="Panel 203" display="med_panel" subs="$title:203"/>
</TabbedPanel>
</panels>
When you create displays for use in tabbed panels, the height and width of each display must be the same. To set the height and width of a display in the Dashboard Builder, select File | Background Properties and set the Model Width and Model Height. If you are using a background image for your display, create the image so that the height and width of the image are one pixel larger than the size you want the display to be.
By default, the displays for all tabs are loaded at startup and are never unloaded. You can set to false the preload attribute on the TabbedPanel tag in order to change this behavior so that only the display for the first tab is loaded at startup and the display for a tab is unloaded when the user selects another tab. In other words, if preload is false, only one display at a time is loaded in a tabbed panel.
Following is an example:
<?xml version="1.0" ?>
<panels xmlns="www.sl.com" version="1.0">
<TabbedPanel title="Test of Tabbed Panel" placement="top" preload="false">
<RtViewPanel title="Table Overview" display="overview"/>
<RtViewPanel title="Production Table" display="production_table"/>
<RtViewPanel title="System Table" display="system_table"/> </TabbedPanel>
</panels>
The tags described in this topic are deprecated. They will be removed in a future release. You should change to the new tags. See Using new tags to configure the panels in a window.
With tree panels, you define the contents of a tree-structured navigation pane by specifying an xml file (navtree.xml in this example) as the value of the navtreedata attribute in an RTViewNavTreePanel element:
<?xml version="1.0" ?>
<panels xmlns="www.sl.com" version="1.0">
<BorderPanel>
<RTViewPanel region="north" name="title_panel" display="title_panel"/>
<CardPanel region="center">
<RtViewPanel title=" Overview " name="main" display="main_panel"/>
</CardPanel>
<RtViewNavTreePanel region="west" width="192" height="480"
lineStyle="Angled" navtreedata="navtree.xml">
</RtViewNavTreePanel>
</BorderPanel>
</panels>
The file that you specify for the navtreedata attribute must be in XML, and must start with the following:
<?xml version="1.0" ?>
<navtree xmlns="www.sl.com" version="1.0">
The navtreedata file must end with the following:
</navtree>
The following tags are supported:
| Tag | Description |
|---|---|
node |
Add a node to the navigation tree. |
treefont |
Set the font used in the navigation tree. |
treecolor |
Set font and background color in the navigation tree. Specify in hexadecimal RGB format: # rrggbb (for example, #00FFFF for cyan) or the following: black, white, red, blue, green, yellow, cyan, magenta, gray, lightGray, darkGray, orange, pink. |
The node tag supports the following attributes:
|
Attribute |
Description |
|---|---|
|
|
Name of the display ( |
|
|
Label for this node in the navigation tree. Defaults to display name if no label is set. Specify the font and color of the label using HTML. For example, to draw a green label using a 50-point italic monospaced font: HTML font settings specified here override |
|
|
If the attribute value is |
|
|
Substitutions to apply to the display. Substitutions are optional and must use the following syntax: If a substitution value contains a single quote, it must be escaped using a A substitution string cannot contain any of the following characters: |
| Attribute | Description |
|---|---|
name |
Specifies the font family name. |
style |
Can be set to plain, bold, italic, or bold italic. |
size |
Font point size. |
The treecolor tag supports the following attributes:
| Attribute | Description |
|---|---|
text |
Specifies the font color for tree labels. |
background |
Specifies the background color for the tree and non-selected tree labels. |
selection |
Specifies the background color for a selected tree label. |
Here is an example:
<?xml version="1.0" ?>
<navtree xmlns="www.sl.com" version="1.0">
<node label="Nav Tree Example">
<node label="Main Displays" display="main_panel">
<node label="100 Displays">
<node label="Panel 101" mode="keepalive" display="med_panel"
subs="$title:101">
</node>
<node label="Panel 102" mode="keepalive" display="med_panel"
subs="$title:102">
</node>
<node label="Panel 103" mode="keepalive" display="med_panel"
subs="$title:103">
</node>
</node>
<node label="200 Displays">
<node label="Panel 201" display="med_panel" subs="$title:201">
</node>
<node label="Panel 202" display="med_panel" subs="$title:202">
</node>
<node label="Panel 203" display="med_panel" subs="$title:203">
</node>
</node>
</node>
</node>
</navtree>
Nodes can be nested. You can only specify one top-level node.
The tags described in this topic are deprecated. They will be removed in a future release. You should change to the new tags. See Using new tags to configure the panels in a window.
The RTViewNavTreePanel tag supports the following attributes:
| Attribute | Description |
|---|---|
navtreedata |
Name of the navigation tree definition file. This XML file must describe the elements of the tree. |
lineStyle |
Set the line style used in the navigation tree. Valid values are Angled and Horizontal. |
region |
Set the location of this RTViewNavTreePanel if it is in a BorderPanel. Valid values are west, east, center, north, and south. |
height |
Set the initial height of the RTViewNavTreePanel. |
width |
Set the initial width of the RTViewNavTreePanel. |
The tags described in this topic are deprecated. They will be removed in a future release. You should change to the new tags. See Using new tags to configure the panels in a window.
The RTViewPanel tag supports the following attributes:
|
Attribute |
Description |
|---|---|
|
|
Name of display ( |
|
|
Corresponds to |
|
|
Set the location of this |
|
|
Control the visibility of scroll bars in the panel. The permitted values are as-needed, never, and always. The default value is as-needed. In some cases, setting the scrollbars attribute to never on title or footer panels can improve the resize behavior of the Dashboard Viewer. |
|
|
Specify initial substitutions for this panel. Substitutions are optional and must use the following syntax: If a substitution value contains a single quote, it must be escaped using a If a substitution value contains a space, it must be enclosed in single quotes. Do not escape these single quotes: A substitution string cannot contain any of the following characters: Info
Substitutions set in Application Options will apply to all displays.
|
The name of the object is obj_c1tabs. It appears on the Controls tab of the Builder’s object palette.
The tab control has two fake tabs labeled A and B when it is drawn on the palette, and also when the user places an instance on a display. The fake tabs are replaced with the actual tabs by attaching the tab control’s valueTable property to a data table containing one row for each tab.
The size given to the control in the Builder determines the space available for tabs. The tabs are drawn horizontally with the first tab at the left edge of the control. If the control is not wide enough to show all of the tabs, the tabs will wrap vertically. If the control is not tall enough to show all of the tabs, some of the tabs may be clipped or invisible.
Changing the control’s labelTextSize property will change the size of the tab label text, which will also affect the size of the tabs.
The tab control is populated from a data table attached to its valueTable property, with one tab created for each row in the table. The following tab control properties are used to map the columns of the data table to each tab:
| Property | Description |
|---|---|
labelColumnName |
The value from this column is used as the tab label. If labelColumnName does not specify a column in the valueTable or if it contains an empty string, then the tab for row N in the valueTable will be labeled “Tab N”. The labelColumnName property appears in the Label category. |
valueColumnName |
The value from this column is assigned to the variable (if any) attached to the tab control’s varToSet property when the corresponding tab is selected by the user. If valueColumnName does not specify a column in the valueTable, then the tab’s index (0 through N - 1, for a table with N rows) is used as the tab value. The valueColumnName property appears in the Data category. |
imageColumnName |
The value from this column is used to load an icon image, shown to the left of the tab’s label. If imageColumnName does not specify a column in the valueTable, or if the column is empty, or if the image can’t be found, the tab will not contain an icon. An icon will affect the size of the tab. The imageColumnName property appears in the Image category. |
mouseOverColumnName |
The value from this column is used as the tooltip for each tab. If mouseOverColumnName does not specify a column in the valueTable, or if the column is empty, the tab will not display a tooltip. The mouseOverColumnName property appears in the Interaction category. |
The tab control supports the drillDownColumnSubs property, which can be useful in cases where the tab’s command is a drilldown. As with other objects that support drillDownColumnSubs, it can be used to set the values for substitutions and local variables from columns in the row of the valueTable that corresponds to the selected tab.
The control’s visFlag property can be used to toggle the control’s visibility. Unlike the other control objects, the tab control does not support the enabledFlag property. So it is always enabled. As on other control objects, the predefined substitution named $value can be used in the control’s command. The value of the selected tab will be substituted for $value when the command is run. (See the valueColumnName property for a description of how a tab’s value is determined). If a tab control has a command defined and the commandConfirm property is checked, the user will be asked to confirm the command when a tab is clicked, but the clicked tab will become the selected tab regardless of the user’s response.