XUL:tree

From MDC

« XUL Reference home    [ Examples | Attributes | Properties | Methods | Related ]

A container which can be used to hold a tabular or hierarchical set of rows of elements. The tree may contain any number of rows and any number of columns. Each row of the tree may contain child rows which are displayed indented from the parent. Unlike other elements, the data to display inside the tree is not specified using tags, but is determined from a view object. The view object implements the nsITreeView interface. The view is queried for the data to appear in the tree. There are several ways in which trees are used, as listed below. The second column lists the interfaces available via the tree's view property. The third column indicates whether treeitem element are used.

If you would like to allow the tree to be horizontally scrolled, simply set the width attributes for each column to make the tree wider than its containing object.

More information is available in the XUL tutorial. Also Tree Widget Changes.

Attributes

disableKeyNavigation, disabled, editable, enableColumnDrag, flags, hidecolumnpicker, onselect, rows, seltype, statedatasource, tabindex

Properties

accessibleType, builderView, columns, contentView, currentIndex, disableKeyNavigation, disabled, editingColumn, editingRow, enableColumnDrag, firstOrdinalColumn, inputField, selType, selstyle, tabIndex, treeBoxObject, view

[edit] Examples

<tree flex="1">

  <treecols>
    <treecol id="sender" label="Sender" flex="1"/>
    <treecol id="subject" label="Subject" flex="2"/>
  </treecols>

  <treechildren>
    <treeitem>
      <treerow>
        <treecell label="joe@somewhere.com"/>
        <treecell label="Top secret plans"/>
      </treerow>
    </treeitem>
    <treeitem>
      <treerow>
        <treecell label="mel@whereever.com"/>
        <treecell label="Let's do lunch"/>
      </treerow>
    </treeitem>
  </treechildren>

</tree>

A tree with nested items:

<tree id="myTree" flex="1" hidecolumnpicker="false" seltype="single" class="tree">
  <treecols id="myTree2-treeCols">
    <treecol id="myTree2-treeCol0" primary="true" flex="2" label="Column A"
             persist="width" ordinal="1"/>
    <splitter class="tree-splitter" ordinal="2"/>
    <treecol id="myTree2-treeCol1" flex="1" label="Column B"
             persist="width" ordinal="3"/>
  </treecols>
  <treechildren>
    <treeitem>
      <treerow>
        <treecell label="1"/>
        <treecell label="a"/>
      </treerow>
    </treeitem>
    <!-- Make sure to set container="true" -->
    <treeitem container="true" open="true">
      <treerow>
        <treecell label="2"/>
        <treecell label="b"/>
      </treerow>
      <treechildren>
        <treeitem>
          <treerow>
            <treecell label="2a"/>
            <treecell label="ba"/>
          </treerow>
        </treeitem>
      </treechildren>
    </treeitem>
  </treechildren>
</tree>

[edit] Attributes

disabled

Type: boolean

Indicates whether the element is disabled or not. If this element is set to true the element is disabled. Disabled elements are usually drawn with grayed-out text. If the element is disabled, it does not respond to user actions, it cannot be focused, and the command event will not fire.

disableKeyNavigation

Type: boolean

If this attribute is not used, the user can navigate to specific items within the element by pressing keys corresponding to letters in the item's label. This is done incrementally, so typing more letters with select more specific items. This feature may be disabled by setting this attribute to true.

editable

Type: boolean

Indicates that the cells of the tree may be edited.

enableColumnDrag

Type: boolean

When set to true, the user may drag the column headers around to change the order in which they are displayed.

flags

Type: space-separated list of the values below

A set of flags used for miscellaneous purposes. Two flags are defined, which may be the value of this attribute.

• dont-test-empty: For template generated content, the builder will not check that a container is empty.
• dont-build-content: This flag may be used on a tree to indicate that content elements should not be generated. This results in a performace enhancement, but you will not be able to use the DOM functions to retreive the tree rows.

hidecolumnpicker

Type: boolean

When set to false, a drop-down will appear in the upper right corner of the tree, which the user may use to show and hide columns. When set to true, the column picker will be hidden. The default value is false.

onselect

Type: script code

This event is sent to a tree when a row is selected, or whenever the selection changes. The user can select multiple rows by holding down Shift or Control and clicking on a row. The onselect event will be sent for each item added to or removed from the selection.

rows

Type: integer

The number of rows to display in the element. If the element contains more than this number of rows, a scrollbar will appear which the user can use to scroll to the other rows. To get the actual number of rows in the element, use the getRowCount method.

seltype

Type: one of the values below

Used to indicate whether multiple selection is allowed.

• single: Only one row may be selected at a time. (Default in listbox.)
• multiple: Multiple rows may be selected at once. (Default in tree.)
• cell: Individual cells can be selected. New in Firefox 3
• text: Rows are selected, however the selection highlight appears only over the text of the primary column.

statedatasource

Type: datasource URI

Chrome XUL may specify an RDF datasource to use to store tree state information. This is used to hold which tree items are open and which items are collapsed. This information will be remembered for the next time the XUL file is opened. If you do not specify this attribute, state information will be stored in the local store (rdf:local-store).

tabindex

Type: integer

The tab order of the element. The tab order is the order in which the focus is moved when the user presses the "tab" key. Elements with a higher tabindex are later in the tab sequence.

[edit] Properties

accessibleType

Type: integer

A value indicating the type of accessibility object for the element.

builderView

Type: nsIXULTreeBuilder

A reference to the tree builder which constructed the tree data. The builder provides access to the RDF resources for each row in the tree, and allows sorting the data by column. In newer versions of Mozilla, the builderView property is actually a synonym for the view property, since the two interfaces are flattened together into a single interface in JavaScript. This property is read-only.

columns

Type: nsITreeColumns

Returns the columns for the tree as an nsITreeColumns object.

contentView

Type: nsITreeContentView

For trees built with a content builder - that is, those that do not have flags="dont-build-content" set -- the contentView will be a reference to the nsITreeContentView for the tree. This interface lets you retrieve the DOM element corresponding to a given a row index and vice versa. For trees that are not built with a content builder, the functions of nsITreeContentView will not be available, since there are no DOM nodes to retrieve. In newer versions of Mozilla, the contentView property is actually a synonym for the view property, since the two interfaces are flattened together into a single interface in JavaScript. This property is read-only.

currentIndex

Type: integer

Set to the index of the currently focused row in the tree. If no row is focused, the value will be -1. For multiple selection trees, the current index is the last row selected. Do not use this property to change the selection. Instead, use the methods of the nsITreeSelection object available via tree.view.selection.

disabled

Type: boolean

Gets and sets the value of the disabled attribute.

disableKeyNavigation

Type: boolean

Gets or sets the value of the disableKeyNavigation attribute.

editingColumn New in Firefox 3

Type: integer

The row index of the tree cell currently being edited, or -1 if there is no cell currently being edited.

editingRow New in Firefox 3

Type: nsITreeColumn

The column of the tree cell currently being edited, or null if there is no cell being edited.

enableColumnDrag

Type: boolean

When set to true, the user may drag the column headers around to change the order in which they are displayed.

firstOrdinalColumn

Type: treecol element

A reference to the first treecol element, which or may not be the first column displayed in the tree.

inputField

Type: textbox element

Read-only property that holds the textbox that is used for editing.

selType

Type: string

Gets and sets the value of the seltype attribute.

selstyle

Type: string

If set to the value primary, only the label of the primary column will be highlighted when an item in the tree is selected. Otherwise, the entire row will be highlighted. To see the difference, compare the selection style in the folder list and the message list in Mozilla mail.

tabIndex

Type: integer

Gets and sets the value of the tabindex attribute.

treeBoxObject

Type: nsITreeBoxObject

The box object is responsible for rendering the tree on the window. This object implements the nsITreeBoxObject interface and contains functions for retrieving the cells at certain coordinates, redrawing cells and scrolling the tree. This property is equivalent to the boxObject property.

view

Type: nsITreeView

The view for the tree, which is the object which generates the data to be displayed. You can assign an object which implements nsITreeView to this property. Trees built from RDF or those which use treeitems directly will already have a view. Functions available in the view allow one to retrieve the data within the cells, and determine which rows are nested within others. For a complete list of view functions, see the nsITreeView interface.

[edit] Methods

startEditing( row, column ) New in Firefox 3

Return type: no return value

Activates user editing of the given cell, which is specified by row index number and the nsITreeColumn in which it is located.

stopEditing( shouldaccept ) New in Firefox 3

Return type: no return value

Stops editing the cell currently being edited. If the shouldAccept parameter is true, the cell's label is changed to the edited value. Otherwise the cell label is reverted to the value it had prior to editing.

[edit] Related

Elements

treecols, treecol, treechildren, treeitem, treerow, treecell and treeseparator.

Interfaces

nsIAccessibleProvider, nsIDOMXULTreeElement, nsIDOMXULMultiSelectControlElement

[edit] Script Examples

To have alternating colors for each row, use the style rules like the following: pma at daffodil dot uk dot com

treechildren::-moz-tree-row(selected) { background-color: #FFFFAA; }
treechildren::-moz-tree-row(odd) { background-color: #EEEEEE; }
treechildren::-moz-tree-row(odd, selected) { background-color: #FFFFAA; }
treechildren::-moz-tree-cell-text(selected) { color: #000000; }
treechildren::-moz-tree-cell-text(odd, selected) { color: #000000; }

If using a content tree view, use the following to get the value of the id attribute for each of the selected rows of a tree: tcooper_mont at yahoo dot com

var rangeCount = tree.view.selection.getRangeCount();
for (var i = 0; i < rangeCount; i++)
{
   var start = {};
   var end = {};
   tree.view.selection.getRangeAt(i, start, end);
   for(var c = start.value; c <= end.value; c++)
   {
      idList.push(tree.view.getItemAtIndex(c).firstChild.id);
   }
}

The following returns a array of the indicies of the rows where the value is checked in a checkbox type column: jfabre at ismans dot fr

function getCellChecked(tree, columnid)
{
  var arr = [];
  var column = tree.columns.getNamedColumn(columnid);
  for (var i = 0; i < tree.view.rowCount; i++){
    if (tree.view.getCellValue(i, column) == 'true')
      arr.push(i);
  }
  return arr;
}

To get the text value for a specific column (e.g. column 'age') from the currently focused row in the tree:

var t = document.getElementById('mytree');
document.title = t.view.getCellText(t.currentIndex,t.columns.getNamedColumn('age'));