XUL Programmer's Reference Manual

<tree>
Attributes Common Children
id treehead
multiple treechildren
selectedItems  
selectedIndex  
collapsed Methods
valign selectItems
onclick getNextItem
ondblclick getPreviousItem
onselect getItemAtIndex
observes  

 

<tree> is the root element in a XUL tree. It provides the ability to display multiple items in a tabular format. Each item is represented as a row in the table. Each row may consist of multiple cells.The XUL tree structure is similar to an HTML table structure. The following tags are roughly analogous to their HTML table counterparts.
 
Table Tree
table tree
caption treecaption
colgroup treecolgroup
col treecol
thead treehead
tbody treechildren, treeitem
tfoot treefoot
tr treerow
td treecell
To insert a tree widget into a document, use the tree tag. This tag is analogous to the table tag in HTML.
The tree widget can contain a caption, which can be specified using the treecaption tag.

The tree's column information can be specified using the treecolgroup and treecol tags; these tags respond to all the same properties that the HTML col tags do. These column tags can be used to specify column widths and to apply styles to individual columns in the tree view. Tree column tags can respond to an additional CSS property, column-layout, which indicates whether or not this column's size is alterable using the tree's column resizing capabilities. It has values of fixed and flexible, with the default being flexible.

A tree can contain headers, bodies, and footers, just as a table does. A tree widget's body, unlike a table's body will constrain itself when the height of the table is constrained.

The treeitem tag is used to declare a single item (along with that item's row and children) in the tree. The tree item contains one or more rows, which are specified using the treerow tag. Each row consists of one or more cells, which are specified using the treecell tag.

 
<tree>
  <treehead>
    <treerow>
      <treecell value="Name" flex="1" />
      <treecell value="URL" flex="1" />
    </treerow>
  </treehead>

  <treechildren flex="1" >
    <treeitem container="true" parent="true">
      <treerow>
        <treecell value="Netscape Home Page"/>
        <treecell value="http://www.netscape.com" />
      </treerow>
    </treeitem>
  </treechildren>
</tree>

Tree items are either open or closed, and their state is specified using the open attribute. This attribute, when set to true, indicates that the tree item's children should be displayed in the tree. If it is set to false, or if it isn't set at all, then the tree item's children are not displayed.

A tree item's children are specified using the treechildren tag, which is placed within the parent treeitem tag. The treechildren tag contains tree items that represent the children of the parent node.

 
<box width="200">
  <tree open="true" container="true" >
    <treechildren id="panelChildren" flex="1">
      <treeitem container="true" open="true" id="Folder" position="3">
        <treerow>       
          <treecell class="treecell-indent" value="Folder"/> 
        </treerow>
        <treechildren id="folderItems" flex="1">
          <treeitem>
            <treerow>
              <treecell class="treecell-indent" value="Item 1"/> 
            </treerow>
          </treeitem>

          <treeitem>
            <treerow>
              <treecell class="treecell-indent" value="Item 2"/> 
            </treerow>
          </treeitem>
       </treechildren>
      </treeitem>
    </treechildren>
  </tree>
</box>

The tree automatically handles selection, and it is capable of supporting single and multiple selection (through the use of CTRL/command and SHIFT modifier keys). The tree's selection is reflected into the content model. Tree items that are selected have an attribute called selected set to true. Tree rows that are selected have an attribute called selectedrow set. Tree cells that are selected have an attribute called selectedcell that is set to true. CSS can be applied using attribute selector rules, thus enabling the tree designer to control the look of the tree's selection.

A select handler can be attached to the tree, and this handler will be invoked whenever the tree's selection changes. You can either add it as an attribute (e.g., onselect) on the tree tag or add it using the DOM addEventListener method.

The tree widget also supports hover feedback on items and cells. This hover feedback is also reflected into the content model. Tree items that are currently moused over have an attribute called hover set to true. Tree cells that are being moused over have an attribute called hover set to true. Tree rows also use hover. CSS can be applied using attribute selector rules, which enable control of the hover feedback effects for the tree. [This will probably change to use the :hover mechanism at some point, assuming some sort of bubbling mechanism for hover is determined.]

Because the tree handles selection, events that would normally go to the content inside the cell are intercepted by the cell. This behavior can be turned off on a cell by cell basis by setting the treeallowevents attribute on the cell. This attribute, when set to true, indicates that the cell is unselectable, and that the content inside should receive events (like mouse clicks and keystrokes).

To selectively allow events to go to cell content (e.g., a button inside a cell), the treeallowevents attribute can be placed on a node that is a descendant of the cell.
 

multiple

Description

The multiple attribute specifies whether the tree allows multiple selection or not.

Syntax

<tree multiple="true | false" />

Example

<tree multiple="true">
  <treeheader></treeheader>

  <treechildren id="Main" />
    <treeitem
    ...
  </treechildren>
</tree>

Notes

The default for multiple selection is false, which means that only a single child of the tree can be selected at any one time. When multiple select is enabled, you can select multiple elements using +click and +click key combinations.

In the example above, the treechildren can all be selected. When multiple is set to true, the selection of any particular item is toggled on and off, and is independent of the selection state of other items.


 
 
 
onclick
Description
onclick is an event listener attribute for adding functionality to tree widgets. 
Syntax
<tree container="true" onclick="javascript statements or javascript function call"
Example
<tree container="true" onclick="alert('Collapsing tree...'); Collapse();" />
...
Notes
The onclick event listener is a way to invoke commands from user clicks on a tree widget.

The click event is fired whenever the user clicks the tree. Clicks events are fired on the particular tree item and bubble up to the parent tree if they are not handled somewhere lower down in the tree.

Other event listener attributes available for the <tree> widget include:

 
 
 
ondblclick
Description
ondblclick is an event listener attribute for adding functionality to tree widgets. 
Syntax
<tree container="true" ondblclick="javascript statements or javascript function call"
Example
<tree container="true" ondblclick="Tree_Properties();" />
...
Notes
The ondblclick event listener is a way to invoke commands when the user double clicks on a tree.

The dblclick event is fired whenever the user double clicks the tree. Events are fired on the particular tree item and bubble up to the parent tree if they are not handled somewhere lower down in the tree.

 
 
 
onselect
Description
onselect is an event listener attribute for adding functionality to trees. 
Syntax
<tree container="true" onselect="javascript statements or javascript function call"
Example
<tree container="true" onselect="change_display_class();" />
...
Notes

The select event is fired whenever the user selects the tree as a whole. Select events are also fired on tree items in the tree and bubble up to the parent if they are not handled somewhere lower down.

 
 
 
selectedItems
Description
selectedItems returns a nodeList of the items selected in the tree.
Syntax
nodeList = treeObj.selectedItems
Example
nodelist = treeObj.selectedItems
...
Notes

This property can be used in JavaScript to get a nodeList representing all the selected items in the tree.

 
 
 
selectedIndex
Description
selectedIndex returns returns the index of the selected item the tree.
Syntax
i = treeObj.selectedIndex
Example
i = treeObj.selectedIndex;
treeObj.getItemAtIndex(i + 1);
Notes

None.

 
 
 
getItemAtIndex
Description
getItemAtIndex returns a nodeList of the items selected in the tree.
Syntax
node = treeObj.getItemAtIndex(i)
Example
i = treeObj.selectedIndex;
treeObj.getItemAtIndex(i + 1);
Notes

This property can be used in JavaScript to get a nodeList representing all the selected items in the tree.

 
 
 
collapsed
Description
collapsed is an optional attribute that specifies the tree as collapsed and not visible.
Syntax
<tree collapsed="[ true | false ]" />
Example
<tree collapsed="true" >
...
Notes

None.

 
 
 
getNextItem
Description
getNextItem selects an item in the tree based on a start and an offset.
Syntax
<tree getNextItem(start, offset) ... />
Example
start = document.getElementById("starter_cell");
treeObj.getNextItem(start, 2);;
Notes

None.

 
 
 
getPreviousItem
Description
getPreviousItem selects an item in the tree based on a start and an offset.
Syntax
<tree getPreviousItem(start, offset) ... />
Example
start = document.getElementById("starter_cell");
treeObj.getPreviousItem(start, 2);;
Notes

None.

 
 
 

 
 

Last updated: 02/22/01 Ian Oeschger