XUL Tutorial - Input Controls

XUL has elements that are similar to the HTML form controls. Note that some of these elements have only recently been implemented.

Text Entry Fields

HTML has an input element which can used for text entry controls (along with other form controls). XUL has a similar element used for straight text entry fields. The element is the textfield element.

Without any attributes, the textfield element creates a box in which the user can enter text. It is similar to the HTML input. In fact, Mozilla maps both to the same widget. Textfields accept the same attributes as HTML input controls. The following are some of them:

• id
  A unique identifier so that you can identify the textfield.
• class
  The style class of the button.
• value
  If you want the textfield to have default text, supply it with the value attribute.
• disabled
  Set to false to have text entry disabled.
• type
  You can set this attribute to the special value password to create a textfield that hides what it types. This is usually used for password entry fields.
• maxlength
  The maximum number of characters that the textfield allows.

The following example shows some textfields:

<text value="Enter some text"/>
<textfield/>
<text value="Enter a password"/>
<textfield type="password" maxlength="8"/>

The textfield examples above will create text inputs that can only be used for entering one line of text. HTML also has a textarea element for creating a larger text entry area. You can use the textfield element for this purpose as well -- two separate elements are not necessary. If you set the multiline attribute to true, the text entry field will display mutliple rows.

For example:

<textfield multiline="true"
           value="This is some text that could wrap onto multiple lines."/>

Like the HTML textarea, you can use the rows and cols attributes to set the size. This should be set to the number of rows and columns of characters to display.

<text value="Search for:" for="find-text"/>
<textfield id="find-text"/>

<button id="find-button" class="dialog" value="Find" default="true"/>

Checkboxes and Radio Buttons

Two additional elements are used for creating check boxes and radio buttons. They are variations of buttons. The checkbox is used for options that can be enabled or disabled. Radio buttons can be used for a similar purpose when there are a set of them where only one can be selected at once.

You can use most of the same attributes on checkboxes and radio buttons as with buttons. The example below shows some simple checkboxes and radio buttons.

<checkbox id="case-sensitive" checked="true" value="Case sensitive"/>
<radio id="orange" checked="false" value="Orange"/>
<radio id="violet" checked="true" value="Violet"/>
<radio id="yellow" checked="false" value="Yellow"/>

The first line creates a simple checkbox. When the user clicks the checkbox, it switches between checked and unchecked. The checked attribute can be used to indicate the default state. You should set this to either true or false. The value attribute can be used to assign a label that will appear beside the check box. The radio button is similar.

In order to group radio buttons together, you can use the radiogroup element. Only one of the radio buttons in a radio group can be selected at once. Clicking one with turn off all of the others in the same group. The following example demonstrates this.

<radiogroup>
  <radio id="orange" checked="false" value="Orange"/>
  <radio id="violet" checked="true" value="Violet"/>
  <radio id="yellow" checked="false" value="Yellow"/>
</radiogroup>

Check boxes and radio buttons are simply specialized buttons. Remember that buttons are made up of a label and an image. A check box is just a label which has an image of a check mark. You can also use many of the same attributes as buttons:

• value
  The label on the check box or radio button.
• disabled
  Set this to either true or false to disable or enable the check box or radio button.
• accesskey
  The shortcut key that can be used to select the element. The letter specified is usually drawn underlined in the label.
• imgalign
  Specify the side of the label that the check box appears on. You could even put it on top if you wish.
• src
  You can set the image explicitly however it will change when the user clicks the check box.

Drop-down Lists

Drop-down lists can be be created in HTML using the select element. The user can see a single choice in a text field and may click the arrow or some similar such button next to the field 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 text field and a button beside it. It's name was chosen because it pops up a menu with the choices in it. We'll learn more about menus in a later section.

Three elements are needed to describe a drop-down box. The first is the menulist element, which creates the field with the button beside it. (For non-editable menulists, the field will be a button). 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:

<menulist value="Bus">
  <menupopup>
    <menuitem value="Car"/>
    <menuitem value="Taxi"/>
    <menuitem value="Bus"/>
    <menuitem value="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 value attribute is used to indicate the default value.

The menuitem element is really made up of buttons, so you can also use the src, crop and accesskey attributes.

By default, you can only select choices from the list. You cannot enter your own selection by typing it, like you can in some drop-down boxes. A variant of the menulist allows this. Instead of a button for displaying the current selection, a text field is used so that you can type the selection in. For example, the URL field in Navigator 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:

<menulist editable="true">
  <menupopup>
    <menuitem value="www.mozilla.org"/>
    <menuitem value="www.xulplanet.com"/>
    <menuitem value="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. Since the value attribute was not used in this example, the default value will be blank.

List boxes can also be created. We'll find how to create them in the section on trees.

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

Examples: 2.4.1 2.4.2 2.4.3 2.4.4 2.4.5