Tutorials > " . "XUL Tutorial"; $pagetitle="6.2 - More Listbox Features"; $customsidebar = "xultu-sidebar.php"; include "header.php"; ?>

More Listbox Features

The listbox element was described in an earlier section. It has a number of additional features that are described below.

Multi-Column List Boxes

The listbox element is used to create a list of items from which the user can select one or more items from. It is internally created in Mozilla using a grid. It simply uses a set of custom tags and adds code to handle selection automatically. You might use it when you need a grid with selectable rows.

Because it is a grid, it supports multiple columns. Each cell may have arbitrary content within it, although usually only text is used. In a listbox, the content always goes in the rows, unlike a grid where the content may be placed either in the rows or the columns. The syntax is similar but different tags are used. The following table lists the equivalent tags in a listbox:

DescriptionTag in a GridTag in a Listbox
Outer elementgridlistbox
A group of columnscolumnslistcols
A single columncolumnlistcol
A group of rowsrows( no equivalent )
A single rowrowlistitem
A single cell( no equivalent )listcell

List boxes have no equivalent of the grid's rows element. Actually, there is an equivalent, but it is created automatically and placed in the list box for you. It is also hidden so you don't even need to know it is there.

The listcell element may be used for each cell in the grid. To specify the text content of a cell, place a label attribute on a listcell. For the simple case where there is only one column, you may also place the label attributes directly on the listitem elements and leave the listcell elements out entirely.

When the user selects an item, the entire row is selected. You cannot have a single cell selected.

The following example is of a listbox with two columns and three rows:

Example 6.2.1: Source View
<listbox>
  <listcols>
    <listcol flex="1"/>
    <listcol flex="2"/>
  </listcols>
  <listitem>
    <listcell label="George"/>
    <listcell label="House Painter"/>
  </listitem>
  <listitem>
    <listcell label="Mary Ellen"/>
    <listcell label="Candle Maker"/>
  </listitem>
  <listitem>
    <listcell label="Roger"/>
    <listcell label="Swashbuckler"/>
  </listitem>
</listbox>

This list box has two columns, the second one being twice as flexible as the first one. If you shrink the size horizontally, the labels on the cells will crop themselves automatically. As with other elements, you can use the crop attribute on the cells or items to control the cropping.

Header Rows

List boxes also allow a special header row to be used. This is much like a regular row except that it is displayed differently. You would use this to create column headers. Two new elements are used.

The listhead element is used for the header rows, just as the listitem element is used for regular rows. The header row is not a normal row however, so using a script to get the first row in the list box will skip the header row.

The listheader element is used for each cell in the header row. Use the label to set the label for the header cell.

Here is the earlier example with a header row:

Example 6.2.2: Source View
<listbox>
  <listhead>
    <listheader label="Name"/>
    <listheader label="Occupation"/>
  </listhead>

  <listcols>
    <listcol flex="1"/>
    <listcol flex="2"/>
  </listcols>
  <listitem>
    <listcell label="George"/>
    <listcell label="House Painter"/>
  </listitem>
  <listitem>
    <listcell label="Mary Ellen"/>
    <listcell label="Candle Maker"/>
  </listitem>
  <listitem>
    <listcell label="Roger"/>
    <listcell label="Swashbuckler"/>
  </listitem>
</listbox>

(Next) Next, we'll look at how to create trees.

Examples: 6.2.1 6.2.2