Tutorials > " . "XUL Tutorial"; $pagetitle="6.3 - Trees"; $customsidebar = "xultu-sidebar.php"; include "header.php"; ?>

Trees

XUL provides a way to create tabular or hierarchical lists using a tree.

The Tree Elements

One of the more complex elements in XUL is the tree. Like a listbox. a tree may be used for creating lists of items. The tree element may also used for creating hierarchical lists and tables. For example, the list of messages in a mail application, or the Edit Bookmarks window in Mozilla can be created using a tree.

The tree has many of the same features as the listbox. Both can be used to create tables of data with multiple rows and columns, and both may contain column headers. The tree also supports nested rows, whereas the listbox does not. However, listboxes may contain any type of content, whereas trees may only contain text and images. The listbox is intended to be a lightweight alternative to the tree, for simpler cases, so use it instead when you can.

There are several ways that the contents of a tree can be created. The simplest is by putting tree items directly within the tree element. We'll look at this method in this section. The other method, which is actually more common and useful allows you to create the tree contents from a data source. This means that the tree can be filled with information from the user's bookmark list, from a directory on disk, or from the results of a search, or a number of other places. Trees may also be populated with a script. We'll see these latter two methods in later sections.

Trees can be created with the tree element, which is decribed in the following sections. Related elements are used to specify columns and rows. Much like menus, each element is nested inside each other. The elements that make up a tree are described briefly below:

Let's start by looking at how to create a simple table with multiple columns. This could be used to create a list of mail messages. There might be multiple columns, such as sender, subject and date.

First, the entire table is surrounded with a tree element. This declares an element that is used as a table or tree. In this case, we'll use it like a table.

There are two parts to a tree's syntax. The first part is used to declare the content of the tree. Like HTML tables, the data is organized into rows. The table data is created by placing a single row or rows of data inside a treechildren element. The second part is used to specify what columns you want in a tree, using the treecols tag. This is much like how listboxes and the grids are created. You can specify how many rows you want to appear in a tree by setting the rows attribute on the tree element. This attribute specifies how tall the tree appears in the user interface, not how many rows of data there are. If there are more rows of data in the tree, a scrollbar will appear to allow the user to see the rest of them. If you don't specify the rows attribute, the default value is 0, which means that none of the rows will appear. In this case, you would make the tree flexible. If your tree is flexible, it doesn't need a rows attribute since it will grow to fit the available space.

You may place as many columns as you wish in a tree. Like with listboxes, a header row will appear with column labels. A drop-down menu will appear in the upper-right corner of the tree, which the user may use to show and hide individual columns.

Each column is created with a treecol element. You can set the header label using the label attribute. You may also want to make the columns flexible if your tree is flexible, so that the columns stretch as the tree does. All of the columns should be placed directly inside a treecols element.

The body of the tree is created using four elements. The treechildren element surrounds all of the rows. Inside the body are individual rows, which may in turn contain other rows. Trees with nested rows are described in the next section. For a simpler tree, each row is created with the treeitem and treerow elements. The former is used for a row and its child rows and the latter is used for a single row.

Inside the rows, you will put individual tree cells. These are created using the treecell element. You can set the text for the cell using the label attribute. The first treecell in a row determines the content that will appear in the first column, the second treecell determines the content that will appear in the second column, and so on.

The sample below shows a tree created with the syntax so far.

Example 6.3.1: Source View
<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>

As can be seen in the image, the tree has been created with two rows of data.

This tree has two columns, the second of which will take up more space than the first. You will usually make the columns flexible You can also supply widths with the CSS width property. You should include the same number of treecol elements as there are columns in the tree. Otherwise strange things will happen.

The header row is created automatically. The button in the upper right corner can be used to hide and show the columns. You can place a hidecolumnpicker attribute on the tree and set it to true if you would like to hide this button. Make sure that you set an id attribute on each column or the hiding and showing of columns will not work.

The user can select the treeitems by clicking on them with the mouse, or by highlighting them with the keyboard. The user can select multiple items by holding down the Shift or Control keys and clicking additional rows. To disable multiple selection, place a seltype attribute on the tree, set to the value single. With this, the user may only select a single row at a time.

Tree Example

Let's add a tree to the find files window where the results of the search would be displayed. The following code should be added in place of the iframe.

<tree flex="1">
  <treecols>
    <treecol id="name" label="Filename" flex="1"/>
    <treecol id="location" label="Location" flex="2"/>
    <treecol id="size" label="Size" flex="1"/>
  </treecols>

  <treechildren>
   <treeitem>
     <treerow>
       <treecell label="mozilla"/>
       <treecell label="/usr/local"/>
       <treecell label="2520 bytes"/>
     </treerow>
   </treeitem>
  </treechildren>
</tree>

<splitter collapse="before" resizeafter="grow"/>

We've added a tree with three columns for the filename, the location and the file size. The second column will appear twice as wide due to the larger flexibility. A single row has been added to demonstrate what the table would look like with a row. In a real implementation, the rows would be added by a script as the search was performed.


(Next) Next, we'll learn how to create more advanced trees.

Examples: 6.3.1

Find files example so far: Source View