Create a Set of Tabs for a Pane | Customize a Project

Situational Awareness Projects > Customize a Project > Add a Tree View to a Page

Add a Tree View to a Page

A tree view is a control that provides a hierarchical view of the information on a page. For example, a tree view is used on the default Active Alarms page in a Situational Awareness Starter Project. You can use it to filter the displayed list of alarms.

Each item in a tree view is a Genie that supports the following functionality:

Check boxes allow you to select one or more items in the tree.
Alarms counts indicate the number of associated alarms in the top three alarm priorities, as well as the number of shelved alarms. Alarm and shelve counts will only apply to an equipment data source.

If required, you can use the View Genie parameter to substitute the default Genie with your own. This will allow you to customize the appearance of the tree and the features it supports.

To add a tree view to a page you need to use the Tree View Genie. The Genie's parameters are divided into five main groups:

Basic Setup parameters — primarily used to specify the data source on which the tree is based.
Search parameters — identify the object used to input search text at runtime.
Display parameters — define the size of the space the tree view occupies and the components that will appear at runtime.
Event parameters — define the functions that are executed when an operator interacts with the Genie at runtime.
Customization parameters — enable advanced customization of a tree view.

When the Genie is pasted on a page, the Genie Parameters Dialog Box is displayed. See below for a description of each parameter.

Genie Parameters

Basic Setup Parameters

Parameter	Description
Datasource	Specifies the menu on which the tree is based. You can enter the name of a menu you have created using the Menu Configuration view in the Visualization activity (see Prepare the Navigation Menu). Alternatively, you can use the name of a menu that is created at runtime using the MenuGetPageNode Cicode function. You can also enter "__EquipmentModel" to use the equipment hierarchy defined for the current project.
Use Display Names	Determines if display names are used to label equipment in the tree view. A display name is a meaningful name that can be defined for piece of equipment using the Display Name property (see Manually Define Equipment). If the tree view is displaying the equipment model: TRUE = Equipment display names are used FALSE = Equipment names are used. If this is set to TRUE and no Display Name is configured, the equipment name will be used instead. If the tree view is displaying a generic menu structure: TRUE = Menu item comments are used FALSE = Menu item names are used.

Parameter

Description

Datasource

Specifies the menu on which the tree is based.

You can enter the name of a menu you have created using the Menu Configuration view in the Visualization activity (see Prepare the Navigation Menu).

Alternatively, you can use the name of a menu that is created at runtime using the MenuGetPageNode Cicode function.

You can also enter "__EquipmentModel" to use the equipment hierarchy defined for the current project.

Use Display Names

Determines if display names are used to label equipment in the tree view.

A display name is a meaningful name that can be defined for piece of equipment using the Display Name property (see Manually Define Equipment).

If the tree view is displaying the equipment model:

TRUE = Equipment display names are used

FALSE = Equipment names are used.

If this is set to TRUE and no Display Name is configured, the equipment name will be used instead.

If the tree view is displaying a generic menu structure:

TRUE = Menu item comments are used

FALSE = Menu item names are used.

Search Parameters

Parameter	Description
Search Box Name	This field specifies the name of the ciText.TextBox object that the tree view will use as its input for the search text at runtime. The name to enter is defined in the Text Object Properties dialog on the Access tab. By default, "Search" is used.

Parameter

Description

Search Box Name

This field specifies the name of the ciText.TextBox object that the tree view will use as its input for the search text at runtime. The name to enter is defined in the Text Object Properties dialog on the Access tab.

By default, "Search" is used.

Display Parameters

Parameter	Description
Treeview Height	The height of the area the tree view will occupy (in pixels). If the length of the expanded tree extends beyond the height specified here, a vertical scroll bar will appear.
Treeview Width	The width of the area the tree view will occupy (in pixels). If the width of the expanded tree extends beyond the left edge of the alarm count list, a horizontal scroll bar will appear.
Row Height	The amount of space that will be available to each row within the tree view.
Display Checkboxes	Determines if a check box is displayed for each item in the tree. TRUE = Check boxes are displayed. FALSE = Check boxes are not displayed.
Auto-check Children	Determines if the check boxes within the lower levels of a branch are automatically checked when a parent item is checked. TRUE = Children are automatically checked. FALSE = Children are not automatically checked.
Display Alarms	Determines if alarm counts for the top three alarm categories are displayed for each item in the tree. If the branch is collapsed, the values will represent the number of active alarms for each category within the current branch and its lower levels. If a node is expanded, the count will only shows alarms for that node, as the counts for its children will now be visible on the child nodes. TRUE = Alarm counts for the top three alarm categories are displayed. FALSE = Alarm counts for the top three alarm categories are not displayed.
Display Shelved	Determines if an alarm count for shelved alarms is displayed for each item in the tree. If the branch is collapsed, the values will represent the number of shelved alarms for each category within the current branch and its lower levels. If a node is expanded, the count will only shows shelved alarms for that node, as the counts for its children will now be visible on the child nodes. TRUE = Alarm count for shelved alarms is displayed. FALSE = Alarm count for shelved alarms is not displayed.

Event Parameters

Parameter	Description
On Init Complete Function	Represents the name of the function that is invoked when the tree view completes initialization. OnInitCompleteFunction(INT nTreeviewAN) The argument nTreeviewAN is expected, it is the animation number of the tree view that fires the event.
On Check Function	Represents the name of the function that is invoked upon the checked event. OnCheckFunction(INT hMenuItem) The argument hMenuItem is expected. It is the handle to the menu item that is represented by the tree node on which the check box has just been clicked.
On Left Click Function	Represents the name of the function that is invoked upon the left click event. OnLeftClickFunction(INT hMenuItem) The argument hMenuItem is expected. It is the handle to the menu item that is represented by the tree node that has just been left-clicked.
On Right Click Function	Represents the name of the function that is invoked upon the right click event. OnRightClickFunction(INT hMenuItem) The argument hMenuItem is expected. It is the handle to the menu item that is represented by the tree node that has just been right-clicked.

Customization Parameters

Parameter	Description
View Genie	Refers to the Genie that is called to display each item in the tree. By default, the Tree View Item Genie in the "sa_controls" library is used (sa_controls.treeviewitem).
View Init Function	The Cicode function that is called to initialize the View Genie (see above) for each row. By default, a system function called "_Treeview_InitViewGenie_<resolution>" is used (for example, "_Treeview_InitViewGenie_HD1080").
Fill Function	This function is called on each page scan to manage data updates in the tree view when the tree view state changes (for example, when scrolling, expanding, or collapsing occurs). By default, a system function called "_Treeview_Update" is used.
View Model Data Size	Specifies the number of custom fields per tree view item to be allocated for user data. The data in these fields will be updated by the function specified in the parameter Datasource Item Retrieve Function (see below). This parameter is set to zero (0) by default.
View Model Init Function	Custom function to configure the additional columns specified by the parameter 'View Model Data Size'. This function is called once when the tree view is initialized.
Datasource Item Retrieve Function	A custom function that loads additional user data for the tree view. This function is called whenever the tree view data is refreshed (for example, when scrolling, expanding, or collapsing occurs). The number of custom fields to be updated by this function is defined by the parameter View Model Data Size (see above).
Is Source Ready Function	Enter the name a function that is used to determine if the data source is ready. The tree view initialization code will run the function (in addition to the checks for navigation initialized and workspace system initialized) before allowing the tree view to be displayed. If this function does not return TRUE within five seconds of displaying the page, the tree view initialization will time out. This function needs to return an INT (TRUE or FALSE) and takes a single argument, INT nTreeviewAN.
Datasource Watcher Function	Enter a Cicode function that will be used to monitor the tree view's associated data source for any updates. The function will be called when the Tree View Genie is initialized, and needs to be responsible for triggering a reload if required. The function will run continuously, so it should not return any values. It also needs to accept the arguments sDatasource and hTreeviewAN. If you are using the Tree View Genie to display the entire equipment model (for example, if the Datasource parameter is set to "__EquipmentModel"), you can enter the following function name to trigger a reload of the tree whenever the equipment model changes: _Treeview_MonitorEquipmentModel
Can Check Items Function	A custom function that is used to determine if tree view item checking is allowed. By default, toggling the checked state of a tree view item is allowed at runtime. This function provides a way to disable the check boxes on all items if required. For example, you may want to disable checking if the data that the tree view will interact with is not ready, or if the current user does not have sufficient privileges. The function needs to return a value of TRUE or FALSE.

AN Parameter

Parameter	Description
AN	A unique ID for the Genie object.