XUL Tutorial - Tree Selection

The section will describe how to get and set the selected items in a tree.

Getting the Selected Tree Items

Each treeitem element in a tree may be selected individually. If you add the multiple attribute to the tree, the user can select multiple items at a time. The selection is not necessarily contiguous. The tree provides a number of functions which can be used to determine whether an item is selected.

The following examples will use the same tree example, which, because of its size, can be viewed separately. It contains three top-level items, each with a varying number of child items. It also allows multiple selection.

First, let's see how we can determine when an item is selected. The onselect event handler may be added to the tree element. When the user selects an item from the tree, the event handler is called. The handler is called if the user clicks on an item. The user may also change the selection using by using the cursor keys. If the user holds down the cursor key to rapidly scroll through the items, the event handler is not called until the user stops. This results in a performance improvement. This also means that highlight will appear on several items even though the select event is never fired for those items.

The syntax of the onselect event handler is shown below. You could modify the tree example linked to above to that below to experiment with tree selection.

<tree id="treeset" onselect="alert('You selected something!');">

The tree element has a property selectedItems which holds an array of all the selected items in the tree. This will include all selected items, no matter how deeply nested they are. If no items are selected, the array will have zero length.

Modify the tree example to that below. It will add a button which, when clicked, will display a list of the currently selected items.

<script src="treetest.js"/>

<button value="Show Selected" onclick="showSelected()"/>


<tree id="treeset" multiple="true" flex="1">

treetest.js:

function showSelected()
{
  var tree=document.getElementById('treeset');
  var items=tree.selectedItems;
  if (items.length==0) alert("No items are selected.");
  else {
    txt="You have selected:\n\n";
    for (t=0;t<items.length;t++){
      txt+=items[t].firstChild.firstChild.getAttribute('value')+'\n';
    }
    alert(txt);
  }
}

The function showSelected first gets a reference to the tree which can be found using its id. The variable items is assigned to the selectedItems property. If nothing is selected, an alert is displayed saying so. Otherwise, a string txt is created that contains the text of each item. The line that does this gets the first child of the first child of each item in the array. This is necessary to get a reference to the treecell from the treeitem. Then, we get the value of the value attribute, which holds the displayed text. Finally, outside the loop, we display an alert containing the created text.

Remember that the selection array does not distinguish between top-level items and items further down in the tree. For this, you can examine the items themselves, or you can look at the container attribute on the items.

Selecting Items

In addition to retreiving the selected items, we can also modify the selection. There are a variety of functions of the tree object that can be used for this.

Some of the functions described below require or return an index. This will be the position of the item with-in the tree. The items in the tree are numbered starting from 0. Only items that are displayed are included in the count. Thus, if an item with child items is collapsed so that the child items are hidden, the child nodes are not included in the count. If the item is expanded, the child nodes are included in the count.

Child items are included in the count just after their parents. This means that if there are 3 top-level items and each has two child items, there will be a total of 9 items. The first item (at index 0) will be the first top-level item. The next item at index 1 will be its first child. The second child will be at index 2 and the second parent item will be at position 3 and so on.

In the image to the right, there are eight rows displayed, of which two are selected. The first selected row has an index of 4 and the second has an index of 7. The rows that are not displayed are not included in the index count.

The function getItemAtIndex can be used to get a reference to the treeitem at a particular index. The function takes one parameter, the index of the item you want to retreive. You can also retrieve treeitem references by looking them up by their ids. Once you have a treeitem, you can modify whether it is selected or not.

The selection functions allow you to have multiple items selected whether the multiple is used or not. This attribute controls only whether the user can select multiple items at once or not.

The following table lists the selection functions that can be used. These are all methods of the tree object, not of the treeitems.

The following example demonstrates how to select items from a tree. It adds a textfield and two buttons. Enter an index into the field and press the Select button. The item at that index will be selected. Press the Unselect button to unselect it. You can experiment with this by expanding and collapsing the items.

<box>
  <text value="Select item at index:"/>
  <textfield id="tfield"/>
  <button value="Select" onclick="doSelect()"/>
  <button value="Unselect" onclick="doUnselect()"/>
</box>

<tree id="treeset" multiple="true" flex="1">

treetest.js:

function doSelect()
{
  var tree=document.getElementById('treeset');
  var tfield=document.getElementById('tfield');
  var idx=parseInt(tfield.value);
  tree.addItemToSelection(tree.getItemAtIndex(idx));
}
  
function doUnselect()
{
  var tree=document.getElementById('treeset');
  var tfield=document.getElementById('tfield');
  var idx=parseInt(tfield.value);
  tree.removeItemFromSelection(tree.getItemAtIndex(idx));
}

Other Tree Functions

There are a number of other functions which can be used with trees. They are listed below as a short reference. For invalid items or indices, nothing happens.

(Next) Next, we'll find out how to use observers.