Tutorials > " . "XUL Tutorial"; $pagetitle="2.5 - List Controls"; $customsidebar = "xultu-sidebar.php"; include "header.php"; ?>

List Controls

XUL has a number of types of elements for creating list boxes.

List Boxes

A list box is used to display a number of items in a list. The user may select an item from the list.

XUL provides two types of elements to create lists, a listbox element to create multi-row list boxes, and a menulist element to create drop-down list boxes. They work similar to the HTML select element, which performs both functions, but the XUL elements have additional features.

The simplest list box uses the listbox element for the box itself, and the listitem element for each item. For example, this list box will have four rows, one for each item.

Example 2.5.1: Source View
<listbox>
  <listitem label="Butter Pecan"/>
  <listitem label="Chocolate Chip"/>
  <listitem label="Raspberry Ripple"/>
  <listitem label="Squash Swirl"/>
</listbox>

Like with the HTML option element, you can assign a value for each item using the value attribute. You can then use the value in a script. The list box will default to a suitable size, but you can control the size with the rows attribute. Set it to the number of rows to display in the list box. A scroll bar will appear that the user can use to display the additional rows.

The following example demonstrates these additional features:

Example 2.5.2: Source View
<listbox rows="3">
  <listitem label="Butter Pecan" value="bpecan"/>
  <listitem label="Chocolate Chip" value="chocchip"/>
  <listitem label="Raspberry Ripple" value="raspripple"/>
  <listitem label="Squash Swirl" value="squash"/>
</listbox>

The example has been changed to display only 3 rows at a time. Values have also been added to each item in the list. List boxes have some additional features, which will be described later.

Drop-down Lists

Drop-down lists can be created in HTML using the select element. The user can see a single choice in a textbox and may click the arrow or some similar such button next to the textbox to make a different selection. The other choices will appear in a pop-up window. XUL has a menulist element which can be used for this purpose. It is made from a textbox and a button beside it. It's name was chosen because it pops up a menu with the choices in it.

Three elements are needed to describe a drop-down box. The first is the menulist element, which creates the textbox with the button beside it. The second, menupopup, creates the popup window which appears when the button is clicked. The third, menuitem, creates the individual choices.

It's syntax is best described with the example below:

Example 2.5.3: Source View
<menulist label="Bus">
  <menupopup>
    <menuitem label="Car"/>
    <menuitem label="Taxi"/>
    <menuitem label="Bus" selected="true"/>
    <menuitem label="Train"/>
  </menupopup>
</menulist>

This menulist will contain four choices, one for each menuitem element. To show the choices, click the arrow button on the menulist. When one is selected, it appears as the choice in the menulist. The selected attribute is used to indicate the value that is selected by default.

By default, you can only select choices from the list. You cannot enter your own text by typing it in. A variant of the menulist allows editing the text in the field. For example, the URL field in the browser has a drop-down for selecting previously typed URLs, but you can also type them in yourself.

To create an editable menulist, add the editable attribute as follows:

Example 2.5.4: Source View
<menulist editable="true">
  <menupopup>
    <menuitem label="www.mozilla.org"/>
    <menuitem label="www.xulplanet.com"/>
    <menuitem label="www.dmoz.org"/>
  </menupopup>
</menulist>

The URL field created here has three pre-populated choices that the user can select or they can enter one of their own by typing it into the field. The text the user enters is not added as a new choice. Because the value attribute was not used in this example, the default value will be blank.


(Next) In the next section, we will learn how to add additional elements to the window using HTML.

Examples: 2.5.1 2.5.2 2.5.3 2.5.4