Tutorials > " . "XUL Tutorial"; $pagetitle="7.5 - Tree Selection"; $customsidebar = "xultu-sidebar.php"; include "header.php"; ?>

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 seltype attribute to the tree, set to the value multiple, 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.

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 user may also change the selection 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 the 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.

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

The tree has a property currentIndex, which can be used to get the currently selected item, where the first row is 0. You can change the selected item by assigning a new value to this property.

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

For trees that allow multiple selection, getting the list of selected rows is a bit more complicated. The tree element has a property view which in turn has a property selection, which contains properties and methods related to the current selection in the tree. You can use these methods to retrieve the set of selected items or modify the selection.

Because the selected items in a multiple selection tree are not necessarily contiguous, you can retrieve each block of contigous selections, using the getRangeCount and getRangeAt functions. The first function returns the number of selection ranges there are. If only one value is selected, this value will be 1. You would then write a loop for the number of ranges, calling getRangeAt to get the actual indices of the start and end of the range.

The getRangeAt function takes three arguments. The first is the range index. The second is an object which will be filled in by the function with the index of the first selected item. The third argument is an object which will be filled in with the index of the last selected item.

For example:

var start = new Object();
var end = new Object();
var numRanges = tree.view.selection.getRangeCount();

for (var t=0; t<numRanges; t++){
  tree.view.selection.getRangeAt(t,start,end);
  for (var v=start.value; v<=end.value; v++){
    alert("Item "+v+" is selected.");
  }
}

We create two objects called 'start' and 'end'. Then, we iterate over the set of ranges, the number of which is returned by the getRangeCount function. The getRangeAt function is called passing the range index and the start and end objects. This function will fill in the start and end indicies by assigning them to the 'value' property. So if the first range is from the third item to the seventh item, 'start.value' will be 2 (remember that indices start with 0, so we subtract one.) and 'end.value' will be 6. An alert is displayed for each index.


(Next) Next, we'll find out how to create a custom view for a tree.