Selecting Objects in Tree Controls
A XUI tree control has two different selection types or modes: single selection and multiple selection. The tree control selection mode is set with the seltype attribute on the treecontrol element. Legal values are single (the default) and multiple. The selection mode cannot be changed at run time.
In single selection mode, the tree control allows only one tree node to be selected at a time.
Multiple selection allows more than one tree node in the tree control to be selected at a time. Multiple selection mode is accessible using ACL only. XUI has no default rules as to how parent and child nodes are handled when selected in multiple selection mode. Such handling is the responsibility of the custom ACL application working with the XUI controls.
Detect selection changes by using the dlgitem_add_callback function to add a callback to the tree control and the check for ITEM_CHANGED events in the callback function. Use the following functions to work with tree control selections:
• dlgitem_get_select_array(window, dlgitem, array)
If the tree control is in single selection mode, the array will be populated with one entry — the list tag of the only selected tree node. If the tree control is in multiple selection mode, the array will be populated with the list tags of all selected nodes in the tree control.
• dlgitem_get_selected_appdata(window, dlgitem)
This function returns the application-specific data for the selected node when in single selection mode. When the tree control is in multiple selection mode, the function returns the application-specific data for the first node in the selection. To get the application-specific data of all selected items when in multiple selection mode, first find all of the selected nodes using dlgitem_get_selected_listtag_array(), then iterate over the returned list tags calling dlgitem_get_appdata_at() for each.
• dlgitem_get_selected_listtag(window, dlgitem)
This function returns the list tag of the selected node when the tree control is in single selection mode. When the tree control is in multiple selection mode, it returns the list tag of the first selected tree node.
• dlgitem_select_list_at(window, listtag, row)
This function selects the tree node at the position specified. When the tree control is in single selection mode, the specified tree node will be set as the only selected node. When the tree control is in multiple selection mode, the specified tree node is added to the current selection; no nodes are unselected as a result of this call when a valid row is specified. To select a single node when the tree control is in multiple selection mode, first clear any selection, then use this function to select the desired node.
• dlgitem_get_selected_listtag_array(window, dlgitem, array)
This function returns an array containing the list tags of all selected nodes in the tree control. When the tree control is in single selection mode the array contains a single value — the list tag of the only selected node in the tree control. When the tree control is in multiple selection mode, the array contains the list tags of each selected node.