3 Widgets and Controls

This page is still under construction.

This section outlines the various widgets and controls that are defined in XUL. It does not attempt to cover the basic layout containers (box, stack, grid and popup), nor does it attempt to cover the specialized document root containers (window, wizard, dialog, page and overlay). Layout is covered in section 2, and the root elements are covered in section 4 (not yet completed).

3.1 The XULElement Interface

IDL Definition

interface XULElement : Element
{
  attribute DOMString id;
  attribute DOMString className;

  // Layout properties
  attribute DOMString align;
  attribute DOMString dir;
  attribute DOMString flex;
  attribute DOMString ordinal;
  attribute DOMString orient;
  attribute DOMString pack;
  
  // Properties for hiding elements.
  attribute boolean hidden;
  attribute boolean collapsed;
  
  // Property for hooking up to broadcasters
  attribute DOMString observes;
  
  // Properties for hooking up to popups
  attribute DOMString menu;
  attribute DOMString contextMenu;
  attribute DOMString tooltip;
  
  // Width/height properties
  attribute DOMString width;
  attribute DOMString height;
  attribute DOMString minWidth;
  attribute DOMString minHeight;
  attribute DOMString maxWidth;
  attribute DOMString maxHeight;

  // Position properties
  attribute DOMString left;
  attribute DOMString top;
  
  // Tooltip and status info
  attribute DOMString tooltipText;
  attribute DOMString statusText;
  
  attribute boolean allowEvents;

  // RDF Properties
  attribute DOMString ref;
  attribute DOMString datasources;

  // Persistence
  attribute DOMString persist;
  
  readonly attribute CSSStyleDeclaration style;

  NodeList getElementsByAttribute(DOMString name,
                                  DOMString value);
};

Attributes

id: The identifier for the element. For XUL elements this always corresponds to the id attribute. The DOM function getElementById can be used to locate an element with a specific identifier.
className: The set of classes supported by this element. For XUL elements this always corresponds to the class attribute. CSS allows you to write rules that match only objects of a certain class. This attribute is identical to the HTML4.0 class attribute.
align: Used on a box to control the alignment of objects along the axis of a box. This property corresponds to the align attribute.
dir: Used on a box to control the direction in which its child elements are flowed. See section 2 for more information. This property corresponds to the dir attribute.
flex: Used on the child element of a box to specify the degree of flexibility of the element. This property corresponds to the flex attribute.
ordinal: Used on the child element of a box to specify its ordinal group. This property corresponds to the ordinal attribute.
orient: Used on a box to specify its orientation. This property corresponds to the orient attribute.
pack: Used on a box to specify how it packs child elements. This property corresponds to the pack attribute.
hidden: The hidden property is analogous to 'display: none' in CSS. When this property is set to true, the element will not be displayed. This property corresponds to the hidden attribute.
collapsed: The collapsed property is analogous to 'visibility: collapse' in CSS. When this property is set, the element will not be displayed. This property corresponds to the collapsed attribute.
observes: This property takes as its value the ID of a broadcaster that this element should observe. This property corresponds to the observes attribute.
menu, contextMenu, tooltip: These properties are used to attach different types of popups to an element. For more information about using these properties, see section 2.4.
width, minWidth, maxWidth
height, minHeight, maxHeight: These properties can be used to specify the preferred, minimum and maximum sizes of XUL elements. They correspond to their equivalent CSS property counterparts.
tooltipText: Can be used on an element to specify tooltip text that should be associated with the element without having to explicitly define a tooltip popup for the element. This is essentially a shorthand syntax for the attachment of simple tooltips. This property corresponds to the tooltiptext attribute.
statusText: Can be used on an element to specify text to display in the status bar when the element is moused over. This is essentially a shorthand syntax for the attachment of status bar text. This property corresponds to the statustext attribute.
allowEvents: XULLabeledControlElements and XULSelectControlItemElements (see definitions below) do not allow events into their child nodes by default. For example, a click on a button will originate with the button itself and not with a label inside the button. The allowevents property can be used to override this behavior for the rare cases where events should be allowed on child nodes within the object. This property corresponds to the allowevents attribute.
style: The value of this property is an object that can then be used to modify stylistic properties on the element. This is analogous to the style property supported on HTML elements.

Methods

getElementsByAttribute

Similar to getElementsByTagName, this function can be used to obtain all descendant elements that have the specified attribute with the specified value.

Parameters

name of type DOMString: The attribute to look for.
value of type DOMString: The value of the attribute that must be matched in order for the element to be included in the returned node list. A value of * can be used to indicate that the value is irrelevant, and that the attribute need merely be present in order for the element to be included in the returned node list.

Return Value

NodeList

No Exceptions

3.2 Descriptions and Labels

View the remaining desc/label compliance issues in Bugzilla.
View the description/label test page (only works in Mozilla)

The description is one of the basic building blocks of XUL and is defined using the description tag. It is typically used in dialogs to provide explanatory text that describes the purpose of a given UI element.

A description is nothing more than a specialized CSS2 block. As such, it obeys all of the rules of blocks and can contain arbitrary markup.

<description style="border:1px solid red; width: 100px">
  This text can be <html:b>bold</html:b> and 
  can wrap to several lines.
</description>

This text can be bold and can wrap to several lines.

For simple single-line descriptions that contain no markup, a shorthand syntax is available. The value attribute can be used to specify the text of the description.

<description style="border:1px solid blue" 
   value="Single line description with no markup allowed."/>

Single line description with no markup allowed.

Most XUL widgets (e.g., buttons, menus, trees, etc.) operate under similar principles. Namely they are capable of containing arbitrary markup, but they also support a shorthand syntax using attributes.

[Editor's Note: In Mozilla, there are two deprecated tags used to describe descriptions: text and html. These two tags have been consolidated into the single description tag.]

Text Overflow

Single line descriptions support text cropping through the use of the crop attribute. Its possible values are start, center and end. A description will be cropped if the computed width of the description exceeds the description's preferred width (as determined by the XUL layout system).

In all three cases (start, center, and end), the text string is reduced until the contents of the string are as close to the desired width as possible. The values determine how the string is reduced. In start cropping, characters are removed from the front of the string until the reduced string and ellipses fit within the desired width. In center cropping, characters are removed from the center of the string (at each step in the reduction, the middle character of the current string is removed), until the reduced string and the ellipses fit. In end cropping, the characters are removed from the end of the string, and the ellipses are appended to the reduced string.

<hbox>
  <description width="50" crop="end" 
      value="This string will be cropped to fit."/>
  <textbox flex="1"/>
</hbox>

[Editor's Note: The CSS3 Text Module defines rules for the cropping of arbitrary wrapping text, e.g., for blocks. Until this specification is fully defined, only the single-line form of a description will support cropping. Multi-line descriptions will ignore the crop attribute. This applies to all other XUL controls that support cropping as well.]

Labels

A label is a specialized description that is always associated with a specific control. It is specified using the label tag. Labels support all of the same features that descriptions support.

A label can be associated with a control (e.g., with a listbox) using the control attribute. The value of this attribute is the ID of the control element elsewhere in the document. This attribute is analogous to the for attribute supported in HTML 4.0.

<hbox>
  <label control="username" 
         accesskey="e" 
         value="Enter your User ID:"/>
  <textbox id="username" flex="1"/>
</hbox>

Labels also support access keys. These can be specified using the accesskey attribute. This attribute is only meaningful if the label has also specified an associated control using the 'control' attribute. If so, then the user agent will associate the access key specified with the label's associated control.

The XULDescriptionElement Interface

IDL Definition

interface XULDescriptionElement : XULElement {
  attribute boolean disabled;
  attribute boolean crop;
  attribute DOMString value;
};

Attributes

disabled: Whether or not the description is disabled. Setting this property is exactly equivalent to setting the disabled attribute.
crop: Specifies cropping behavior for situations where the description's text overflows its specified bounds. This property corresponds to the crop attribute.
value: Sets the text of the description. This property corresponds to the value attribute. When this property is used, the description will not wrap to multiple lines.

The XULLabelElement Interface

IDL Definition

interface XULLabelElement : XULDescriptionElement {
  attribute boolean accessKey;
  attribute DOMString control;
};

Attributes

accessKey: The defined access key for this label. This property corresponds to the accesskey attribute.
control: Specifies the ID of the control element to which the label should be attached. This property corresponds to the control attribute.

3.3 Images

Another basic building block of XUL is the image. It is declared using the image tag, and its behavior is similar to the HTML4.0 img element.

The resource to use for an image can be specified either using a src attribute referencing the URI of the image to load, or using the CSS2 'list-style-image' property.

<image style="border: 3px solid blue" 
  src="http://www.mozilla.org/images/mozilla-banner.gif"/>

If the image's preferred size is not the same as the actual size of the image, then the image will be scaled to fit in the space provided.

<image style="width: 200px; border: 3px solid blue" 
  src="http://www.mozilla.org/images/mozilla-banner.gif"/>

The XULImageElement Interface

IDL Definition

interface XULImageElement : XULElement {
  attribute DOMString src;
};

Attributes

src: The URI of an image resource to display. This property corresponds to the src attribute.

3.4 Spacers and Separators

XUL supports a lightweight element called a spacer, designed simply to introduce space between two elements. It is specified using the spacer tag.

There are two types of spacers: springs and struts. A strut is an inflexible spacer element that introduces a fixed amount of space between two objects. The spacer specified below can be inserted between two objects to create a 20 pixel gap.

<spacer width="20"/>

A spring is a flexible spacer that can be used to introduce a flexing gap between two objects.

<spacer flex="1"/>

[Editor's Note: In Mozilla, the <spring> element serves the same purpose. Because the name spring implies that the object is flexible by default, this tag has been deprecated in favor of the <spacer> element.]

A separator element can be used to insert a visual separator between two elements. It can be used in toolbars to separate buttons, within menus to separate menu items, and within dialogs to provide clear separation between controls. Like a spacer the separator can be made flexible.

3.5 Controls

Controls in XUL come in two varieties. The first type of control is called a labeled control. It is a single atomic element (e.g., a button) that can be associated with a specific action. The second type of control is a select control (e.g., a list box), which presents a set of options to a user. Every control implements the XULControlElement interface, which includes methods for focusing and blurring the control and support for the connection of controllers (see section 5 for information about commands and controllers). Controls also have a notion of being enabled or disabled. Examples of controls include list boxes, buttons and checkboxes. Each XUL control is covered in its own section below.

The XULControlElement Interface

IDL Definition

interface XULControlElement : XULElement {
  attribute boolean disabled;
  attribute long tabIndex;
  
  readonly attribute XULControllers controllers;
  
  void focus();
  void blur();
};

Attributes

disabled: Whether or not the control is disabled. When disabled the control cannot be focused and will not respond to user events (such as mouse clicks). This property corresponds to the disabled attribute.
tabIndex: The tab index of the control in the tabbing order of the XUL document. Tab index works just as it does in HTML4. This property corresponds to the tabindex attribute.
controllers: An array of controllers that can handle commands that the control supports. For more information on controllers and commands, see section 5.

Methods

focus

When this method is invoked the control becomes focused. This method is analogous to the focus method found on form controls in HTML4.

No Parameters
No Return Value
No Exceptions

blur

When this method is invoked the control loses focus. This method is analogous to the blur method found on form controls in HTML4.

No Parameters
No Return Value
No Exceptions

3.6 Labeled Controls

A labeled control is a single atomic control that performs a specific action when invoked. Labeled controls such as buttons support shorthands that allow you to specify information about the label or image associated with the widget (as well as cropping and access key information for that label). These controls implement the XULLabeledControlElement interface.

IDL Definition

interface XULLabeledControlElement : XULControlElement {
  attribute DOMString crop;
  attribute DOMString image;
  attribute DOMString label;
  attribute DOMString accessKey;
  attribute DOMString command;

  void doCommand();
};

Attributes

crop: Specifies the cropping behavior for the label associated with the control. This property corresponds to the crop attribute.
image: Specifies the URI of an image that can be associated with the control. This property corresponds to the image attribute.
label: Specifies the text for the label associated with the control. This property corresponds to the label attribute.
accessKey: The defined access key for this control's label. This property corresponds to the accesskey attribute.
command: The ID of the command element that should be associated with the control. This property corresponds to the command attribute.

Methods

doCommand

When invoked, this function generates a command event for the control. If the widget has any command listeners, they will be notified, and their handlers will be executed.

No Parameters
No Return Value
No Exceptions

All labeled controls generate a command event when they are invoked. A command handler can be attached to the labeled control to listen to the event. The oncommand shorthand attribute can be used on any XUL element to attach a 'command' listener to that element.

<button label="Hello World" oncommand="alert('I was invoked!');"/>

Buttons

View the remaining dialog button compliance issues in Bugzilla.
View the dialog button test page (only works in Mozilla)

The button tag in XUL describes the traditional button control used in dialogs. It is a labeled control (see the XULLabeledControlElement interface described above).

The label attribute, if specified, describes a single line of text that should appear on the face of the button.

<button label="Apply";/>

A command handler can be placed on a button using either the oncommand attribute or the DOM addEventListener method with an event argument of 'command'. When the button is invoked, a command event is generated and the command handler will then be executed.

<button label="Alert!" oncommand="alert('Button pressed!');/>

The accesskey attribute describes the character within the button text that should contain the access key. If activated, a command event will be generated on the button.

<button accesskey="i" label="Hit ALT+I" oncommand="alert('Button pressed!');/>

The image attribute or the CSS2 'list-style-image' property can be used to specify an image that will be displayed on the face of the button. This is a shorthand syntax for specifying an image that will appear before the text of the button.

Although the 'label' and 'image' properties of the button are convenient as a shorthand syntax, the content of the button can be specified using child elements to provide more flexibility over the alignment and orientation of the button's components. In most themes a button is a box with a horizontal orientation.

<button>
  <label width="100">
    This text should really be wrapped, since it is quite long.
    Arbitrary <b>markup</b> is supported.
  </label>
</button>

<button>
  <image src="dummyicon.gif"/>
  <label>
    The image appears to the left of the text.
  </label>
</button>

<button orient="vertical">
  <image src="dummyicon.gif"/>
  <label>
    The image appears above the text.
  </label>
</button>

Button Types

XUL supports several different kinds of buttons with special built-in behavior. The type attribute can be used to specify these additional behaviors.

Menu Buttons

A menu button is a button with an associated menu (either associated explicitly using the menu attribute or implicitly via a menupopup child element). To explicitly indicate that a button is a menu, the type attribute can be used with a value of 'menu'.

<button type="menu">
  <label>
    Menu Button
  </label>
  <menupopup>
    <menuitem label="Item One"/>
  </menupopup>
</button>

If a button has no type attribute specified but a menu is connected to the button (either implicitly or explicitly) then the button's type will be changed to 'menu'. Therefore the type attribute typically does not need to be specified for menu buttons.

If the popup has no position specified, then the default position for the menu will be 'after_start'. For more details on popup positioning, see section 2.4.

The open attribute is used to programmatically show and hide the popup attached to the menupopup. A value of 'true' indicates that the popup should appear. A value of 'false' indicates that the popup should be hidden. This attribute can also be used to query the current state of the popup.

Dual Menu Buttons

A dual menu button is a button whose menu is attached through a separate visible component, e.g., a dropdown that is adjacent to the button. This type of button is used when the button itself can still support an action when clicked, but there are also additional commands accessible via the dropdown. This button can be specified using a type attribute with a value of 'menu-button'.

A dual menu button automatically cancels any command events that originate within the dropdown. It does this so that the command handler on the button need not check its target. A single handler attached to the menupopup can still field all the menu item command events for the menu items.

<button type="menu-button" oncommand="alert('Button invoked.');">
  <label>
    Dual Menu Button
  </label>
  <menupopup oncommand="alert('Menu item invoked.')">
    <menuitem label="Item One"/>
    <menuitem label="Item Two"/>
  </menupopup>
</button>

Checkbox Buttons

A button that toggles between a depressed and undepressed state is called a checkbox button. A checkbox button can be specified using a type attribute with a value of 'checkbox'. Command handlers can be hooked up to the button. The command event will not fire on the button until after the checked state has changed.

The checked attribute indicates whether or not the button is currently depressed. A value of 'true' indicates that the button is depressed. A value of 'false' indicates the button is not currently depressed.

A checkbox button can be placed into a mixed state using the checkState property. This property has values of 0, 1, and 2, where 0 is unchecked, 1 is checked, and 2 is indeterminate (e.g., mixed). A push button will never enter the mixed state automatically, but once placed into it, the button will cycle back to a checked state when pressed again.

The author can disable the automatic push behavior in order to gain precise control over when the button checks and unchecks. The autocheck attribute indicates whether or not the button should automatically perform the check. If omitted, a default value of 'true' is assumed.

Radio Buttons

Checkbox buttons that are designed to be placed in a group such that only one button can be pressed at a time are called radio buttons. These buttons are specified in XUL using the type attribute with a value of 'radio'.

Radio buttons must be siblings of one another, and they are grouped together using the group attribute. Once grouped together, only one button can be checked at any given point in time. The checked attribute when set to 'true' on a radio button indicates that the button is the current selection in the radio button group.

The autoCheck property can be used to disable the automatic setting/unsetting behavior that occurs when a radio is activated. If set to 'false' on a button, then when the button is activated, it will not be checked, nor will any other buttons be unchecked.

Special Buttons

There are four special types of buttons that are typically found in dialogs. They are as follows:

The Default Button - Buttons such as the Ok button perform the default action for the dialog.
The Cancel Button - The cancel button cancels the dialog without performing the default action. The dialog is closed by default.
The Help Button - The help button invokes the help information for the dialog.
The Disclosure Button - The disclosure button can be used to show/hide a part of the dialog.

These four special buttons are specified using the dlgtype attribute on the button. When the type is specified, the label does not have to be specified. The default text for that type of button will be inserted automatically. The possible values of the dlgtype attribute are: accept, cancel, help and details.

<button dlgtype="cancel"/>

IDL Definition

interface XULButtonElement : XULLabeledControlElement {
  attribute DOMString type;
  attribute DOMString dlgType;

  // For buttons of type="menu" only.
  attribute boolean open;
  
  // For buttons of type="checkbox" and type="radio" only.
  attribute boolean checked;
  attribute long checkState;
  attribute boolean autoCheck;
  
  // For buttons of type="radio" only.
  attribute DOMString group;
};

Attributes

type: Specifies a specialized type for a button. Possible values are menu, menu-button and checkbox. This property corresponds to the 'type' attribute.
dlgType: This property specifies whether or not a dialog button is the default action for a dialog (e.g., the Ok button), the cancel action for the dialog (e.g., a Cancel button), a disclosure button (e.g., a Details button) or the entry into a help system (e.g., a Help button). The possible values are accept, cancel, disclosure and help. This property is only relevant if the button is used within a dialog. The user agent is free to ignore the value of the property otherwise. This property corresponds to the dlgtype attribute.
open: For menu buttons, indicates whether or not the attached popup is currently showing. This property corresponds to the 'open' attribute.
checked: For checkbox buttons, this property indicates whether the button is depressed. This property corresponds to the 'checked' attribute.
checkState: For checkbox buttons, this property indicates whether the button is depressed, undepressed, or indeterminate. This property corresponds to the 'checkstate' attribute.
autoCheck: For checkbox buttons, this property indicates whether or not the button should automatically change states when invoked. This property corresponds to the 'autocheck' attribute.

Toolbar Buttons

A toolbar button is a specialized button designed for use within a toolbar element. A toolbar button is declared using the toolbarbutton tag. It supports all the button types specified above (e.g., menu, menu-button, checkbox).

<toolbarbutton label="Reload" image="reload.gif"/>

Typically themes will define a toolbar button as a box with a vertical orientation. If the image and label shortcuts are used, the image will appear above the text. Like its dialog button cousin, the toolbar button supports both direction and orientation for fine-grained control over the placement of the image relative to the label.

Checkboxes

A checkbox is a box with an associated label that can appear in either a checked state, an unchecked state, or an indeterminate state. It is traditionally used in dialogs to represent a boolean choice. Command handlers can be hooked up to a checkbox. The command event will not fire on the checkbox until after the checked state has changed.

<checkbox label="Click me to check and uncheck."/>

Click me to check and uncheck.

The checked attribute indicates whether or not the checkbox is currently checked. A value of 'true' indicates that the checkbox should be checked. A value of 'false' indicates that the checkbox is unchecked.

A checkbox can be placed into a mixed state using the checkState property. This property has values of 0, 1, and 2, where 0 is unchecked, 1 is checked, and 2 is indeterminate (e.g., mixed). A checkbox will never enter the mixed state automatically, but once placed into it, the checkbox will cycle back to a checked state when pressed again.

The author can disable the automatic toggle behavior in order to gain precise control over when the checkbox checks and unchecks. The autocheck attribute indicates whether or not the checkbox should automatically perform the check. If omitted, a default value of 'true' is assumed.

Checkboxes support all the features of labeled controls, including access keys, cropping, and the ability to specify image and label shorthands for the checkbox. In most themes, a checkbox is a box with a horizontal orientation. To gain control over the position of the checkbox relative to its image and label, orientation and direction can be used.

<checkbox orient="vertical" label="Vertically oriented checkbox"/>

Vertically oriented checkbox

IDL Definition

interface XULCheckboxElement : XULLabeledControlElement {
  attribute boolean checked;
  attribute long checkState;
  attribute boolean autoCheck;
};

Attributes

checked: This property indicates whether the checkbox is currently checked. This property corresponds to the 'checked' attribute.
checkState: This property indicates whether the checkbox is checked, unchecked, or indeterminate. This property corresponds to the 'checkstate' attribute.
autoCheck: This property indicates whether or not the checkbox should automatically change states. This property corresponds to the 'autocheck' attribute.

3.7 Select Controls

In XUL, a select control is a widget that presents a set of choices to a user. Select widgets contain individual items and track the user's selection, which can be either a single item or multiple items, depending on the type of the select widget.

There are five basic select widgets in XUL: the radio group, the tab strip, the list box, the menu list and the outliner. They are each covered in their own sections following the definition of the select element interfaces.

The XULSelectControlElement Interface

All select controls implement the XULSelectControlElement interface. This interface contains methods for tracking which item within the control is selected and for tracking the current value of the entire control (as determined by the value of the selected element).

IDL Definition

interface XULSelectControlElement : XULControlElement {
  attribute XULSelectControlItemElement selectedItem;
  attribute long selectedIndex;

  attribute DOMString value;
  
  XULSelectControlItemElement appendItem(DOMString label, DOMString value);
  XULSelectControlItemElement insertItemAt(long index, DOMString label, DOMString value);
  XULSelectControlItemElement removeItemAt(long index);
};

Attributes

selectedItem: The control item that is currently selected. Setting this property can be used to change the selection within the control. If the specified item is not an item contained within the control, an exception is generated and the selection remains unchanged.
selectedIndex: The index of the item that is currently selected. Setting the index to -1 clears the selection of the control. The index is 0-based, so the first item has an index of 0.
value: The current value of the select control. It corresponds to the value of the currently selected item. This value can also be set independently of any individual items.

Methods

appendItem

This function creates the correct item for the control, e.g., a radio for a radiogroup, a listitem for a listbox, etc., and it appends it to the control's list of items. The first argument is the label for the item, and the second argument is a value that can be associated with the item. The newly-created item is returned.

Parameters

label of type DOMString: The label for the new item.
value of type DOMString: The value that should be associated with the new item.

Return Value

XULSelectConrolitemElement

No Exceptions

insertItemAt

This function creates the correct item for the control, e.g., a radio for a radiogroup, a listitem for a listbox, etc., and it inserts it into the control's list of items at the specified index. The second argument is the label for the item, and the third argument is a value that can be associated with the item. The newly-created item is returned.

Parameters

index of type long: The index for the new item.
label of type DOMString: The label for the new item.
value of type DOMString: The value that should be associated with the new item.

Return Value

XULSelectConrolitemElement

No Exceptions

insertItemAt

This function removes the item at the specified index. The removed item is then returned. If no item exists at that index, then null is returned.

Parameters

index of type long: The index of the item to remove.

Return Value

XULSelectConrolitemElement

No Exceptions

The XULSelectControlItemElement Interface

Select controls are built from individual items. These items implement a common interface: XULSelectControlItemElement. Examples of control items can be found in the section on select controls below.

IDL Definition

interface XULSelectControlItemElement : XULElement {
  attribute boolean disabled;
  attribute DOMString crop;
  attribute DOMString image;
  attribute DOMString label;
  attribute DOMString accessKey;
  attribute DOMString command;
  
  attribute DOMString value;
  
  readonly attribute boolean selected;
  
  readonly attribute XULSelectControlElement control;

  void doCommand();
};

Attributes

disabled: Can be used to disable the individual item within the control. This property corresponds to the disabled attribute.
crop: Specifies the cropping behavior for the label associated with the control item. This property corresponds to the crop attribute.
image: Specifies the URI of an image that can be associated with the control item. This property corresponds to the image attribute.
label: Specifies the text for the label associated with the control item. This property corresponds to the label attribute.
accessKey: The defined access key for this control's label. This property corresponds to the accesskey attribute.
command: The ID of the command element that should be associated with the item. This property corresponds to the command attribute.
selected: Whether or not this element is currently one of the selected items in the enclosing control. This property corresponds to the 'selected' attribute.
value: Associates data with the control item. This property corresponds to the value attribute.
control: The enclosing control for the specified item.

Methods

doCommand

When invoked, this function generates a command event for the control item. If the item has any command listeners, they will be notified, and their handlers will be executed.

No Parameters
No Return Value
No Exceptions

Radio Groups

Radio groups are designed to present a set of mutually exclusive options to a user in a dialog. A radio group is declared using the radiogroup tag. It contains radio elements as children. A radio element always belongs to the nearest enclosing radio group.

A radio group is a box with a default vertical orientation. The radio group extends XULSelectControlElement and therefore it can be focused.

An entire radio group can be disabled using the 'disabled' attribute. If the radio group is disabled, then none of the radio items can be accessed. If the radio group is enabled, individual radio items can still be disabled (effectively excluding them from the list of available choices) by setting the disabled attribute on the items.

<radiogroup>
  <radio label="Item One"/>
  <radio label="Item Two"/>
  <radio label="Item Three"/>
</radiogroup>

	Item One
	Item Two
	Item Three

Note in the above example, no item was initially selected. A radio group will automatically select the first item in the layout model (e.g., accounting for box direction and ordinal groups) if no items are selected.

To indicate that a radio item should be selected initially, the selected attribute can be used on a radio element.

<radiogroup>
  <radio label="Item One"/>
  <radio selected="true" label="Item Two"/>
  <radio label="Item Three"/>
</radiogroup>

	Item One
	Item Two
	Item Three

The selectedItem property can be used to obtain the current selected radio item from the radio group. It can also be used to select a specific radio item. Alternatively the selected property/attribute can be used on a radio item to query for its selected state.

Whenever the selection changes on a radiogroup, a 'select' event fires on the radio group. A handler can be attached to the radiogroup to listen for changes in selection. The handler will fire after the selection has changed.

<radiogroup onselect="alert('The new selected item is: ' + this.selectedItem + '\n');">
  <radio label="Item One"/>
  <radio selected="true" label="Item Two"/>
  <radio label="Item Three"/>
</radiogroup>

Data values can be associated with individual radio items using the value attribute. If the radio item becomes selected, its 'value' attribute becomes the value of the radio group itself.

<radiogroup onselect="alert('The new value of the radio group is: ' + this.value + '\n');">
  <radio label="Item One" value="1"/>
  <radio selected="true" label="Item Two" value="3"/>
  <radio label="Item Three" value="29"/>
</radiogroup>

A radio group is a XULSelectControlElement, and a radio item is a XULSelectControlItemElement.

The Tab Strip

A tab in XUL is a XULSelectControlItemElement that must always be used as part of an enclosing XULSelectControlElement called a tab strip. The tab strip itself is declared using the tabs element. Individual tabs are declared using the tab element.

The tabs element is normally used in conjunction with an enclosing tab box to provide a complete tab control that can be used to switch between a set of visible panels by selecting the individual tabs. For a complete description of the tab box, see section 3.9.

Like other select controls, the tab strip tracks a selected item, the current active tab and can have a value associated with individual tabs and with the control itself. Whenever the active tab changes a 'select' event fires.

<tabs onselect="alert('The new value of the tabs is: ' + this.value + '\n');">
  <tab label="Tab One" value="1">
  <tab label="Tab Two" value="2">
  <tab label="Tab Three" value="3">
</tabs>

The tab strip also supports the selectedItem and selectedIndex properties.

Menu Lists

A menu list is a control designed to present a set of mutually exclusive choices that can be selected from a dropdown list. When closed, the current selected item is shown in the list.

<menulist>
  <menupopup>
    <menuitem label="Item One">
    <menuitem label="Item Two">
    <menuitem selected="true" label="Item Three">
  </menupopup>
</menulist>

A menu list is declared using the menulist tag. Individual menu items are declared using the menuitem tag and are placed within a menupopup tag.

Values can be associated with individual items, and the menulist also fires a 'select' event whenever its selected item changes.

A menu list, unlike other select control elements, supports the specification of a label using the label shorthand attribute. This label is displayed on the face of the menu list. Menu lists also support the longhand form of the label using the label element.

<menulist label="Empty"/>

<menulist>
  <label>Empty</label>
  <menupopup/>
</menulist>

Menu lists, in addition to supporting individual menu items, also support the use of menus to provide nested hierarchies of submenus. The menus themselves are declared using the menu tag. The menus are not considered items in the menu list, and they cannot be selected. Only menu items within a menu list can actually be selected. Menus are simply used to group related items within a list under a common heading.

<menulist>
  <menupopup>
    <menu label="Menu One">
      <menupopup>
        <menuitem label="Item One"/>
        <menuitem label="Item Two"/>
      </menupopup>
    </menu>
    <menuitem label="Item Three"/>
  </menupopup>
</menulist>

For more information on menus and menu items, see section 3.xxx. For more information on the menupopup element, see section 2.4.

The open property can be used to dynamically open and close a menu list. When set to true, the menu list is opened. When set to false, the menu list is closed.

Editable Menu Lists

An editable menu list provides a dropdown list of choices as well as a text field that can be used to enter a value that may not correspond to an item in the list. This widget is also known as a combo box because the user can use either the text field or the list to set the value of the control.

An editable menu list is specified using the editable attribute or property with a value of 'true'. Instead of a static label on the face of the menu list, the widget instead contains a text field that can be used to enter text.

The inputField property can be used to obtain the XULTextBoxElement that represents the input field. For more information on the API supported by text box, see section 3.xxx. When using an editable menu list, the value of the widget always corresponds to the current value of the text field. Selecting an item from within the list sets the value of the text field and the value of the menu list.

The XULMenuListElement Interface

The menu list interface extends the XULSelectControlItemElement interface and contains some additional functionality for supplying a label on the menu list and for opening and closing the menu list.

IDL Definition

interface XULMenuListElement : XULSelectControlElement {
  attribute boolean editable;
  attribute boolean open;
  
  attribute DOMString label;
  attribute DOMString crop;
  attribute DOMString image;
  
  // For editable menu lists only.
  readonly attribute XULTextBoxElement inputField;
};

Attributes

editable: Whether or not the menu list is editable. This property corresponds to the editable attribute.

List Boxes

A list box is used to provide a set of choices to a user in a dialog. It is declared using the listbox tag. The individual elements of the list are list items, and they are declared using the listitem tag.

<listbox>
  <listitem label="Item One"/>
  <listitem label="Item Two"/>
  <listitem label="Item Three"/>
</listbox>

The rows attribute can be used to specify the number of visible rows to display. If this is set, the list will fix itself to the height required. If omitted, the normal rules of the enclosing layout object apply, e.g., the list box can be made flexible, be set to a specified height, etc.

<listbox rows="4">
  <listitem label="Item One"/>
  <listitem label="Item Two"/>
  <listitem label="Item Three"/>
  <listitem label="Item Four"/>
  <listitem label="Item Five"/>
  <listitem label="Item Six"/>
  <listitem label="Item Seven"/>
  <listitem label="Item Eight"/>
</listbox>

By default a list box only allows one item to be selected at a time. This behavior can be customized using the seltype attribute. Its possible values are 'single' and 'multiple'. The default is 'single'.

There are two properties for accessing the first selected item in the list. These properties are selectedIndex and selectedItem. The index is 0-based, which means that the first item in the list has an index of 0. The index can be set to -1 to deselect all items in the list.

For lists that support multiple selection, the selectedItems property can be used to obtain a NodeList of all the currently selected items. The items are sorted in the order that they occur in the list. The list of selected items is "live", and remains up to date as elements are selected and deselected.

Whenever the selection of a list box changes, a select event fires on the listbox. This event can be listened for with an 'onselect' shorthand attribute.

<listbox onselect="alert('The index of the new
           selected item is: ' + this.selectedIndex + '\n')">
  ...
</listbox>

Just as with radio items a value can be stored with each list item using the value attribute. The value of the list box itself becomes the value of the first selected item in the list box. The list box can also be set to its own unique value using the value attribute.

<listbox onselect="alert('The new value of the listbox is:
   + this.value + '\n')">
  <listitem label="One" value="3"/>
  <listitem label="Two" value="9"/>
  <listitem label="Three" value="27"/>
</listbox>

.....

3.??? Group Boxes

A group box is used to group controls together in a dialog. It is traditionally rendered as a grooved box with a caption embedded within the border. A group box is declared using the groupbox tag. The caption for a group box is declared using the caption tag.

A caption for a group box is a XULLabeledControlElement. Therefore it is a horizontal box that supports label and image shorthands. A group box behaves just like a vertical box except for the way it handles captions. If a caption is encountered as a child of a group box, it is embedded within the group box's border and does not participate in the box layout with the other group box children.

  <groupbox>
   <caption label="Group Box Caption"/>
   <description flex="1">
    The interior of the group box.
   </description>
  </groupbox>

A group box is a XULElement.

previous contents