XUL:Item Selection

An element that supports having one of its children selected implements the nsIDOMXULSelectControlElement interface. The nsIDOMXULMultiSelectControlElement interface is an additional interface which is supported by elements that support multiple selection. The selectable children implement the nsIDOMXULSelectControlItemElement interface.

Elements that implement the nsIDOMXULSelectControlElement interface are:

 listbox, menulist, richlistbox, radiogroup, tabs

There are two ways of specifying the initial selection:

1. Set the selected attribute to true on one of the element's items. For elements that support multiple selection, multiple items may have a selected attribute.
2. Set the value attribute on the element. The value must match one of the values specified on one of the items. If it doesn't, then no item will be selected. This allows only one item to be selected by default, but it does allow the value to be persisted.

The tabbox supports a selectedIndex attribute which may be used to specify the initial selection on its child tabs element. It overrides the selected and value attributes.

To retrieve the selection, use the element's selectedIndex property which retrieves the index of the currently selected item. In multiple selection widgets, it returns the index of the item that was first selected. The selectedItem property may be used to retrieve the currently selected item, which is the item at the selected index. The value property may also be used to retrieve the value of the selected item. It will be set to the same as the value property on the selected item. The value attribute always has the same value as the value property. This is useful for persistence.

An item's selected property is set to true if it is currently selected, and false if it is not. This property is read only.

To change the selection, set the selectedIndex to the index of the item to select, or set the selectedItem property to the item to select. In either case, any existing selected items are deselected. The value property may also be set to the value of an item; in this case, the item with that value, if any, will be selected, and all other items will be deselected. If no item with that value is found, then the selection is not changed. Setting the value will update the value attribute on the element, regardless of whether the value matches an item.

Setting the selectedIndex property to -1, or setting the selectedItem property to null will clear the selection.

For elements that support multiple selection, the methods of the nsIDOMXULMultiSelectControlElement interface may also be used to update the selection.

When the selection is changed, a select event is fired on the element implementing the nsIDOMXULSelectControlElement interface.

The selected attribute is used only for specifying the initial selection when the element implementing the nsIDOMXULSelectControlElement interface is created. Assigning a value to it at any other time has no effect on the selection. However, elements may update the selected attribute internally for whatever purpose. For this reason, the selected attribute should not be used or modified dynamically.

Elements that support multiple selection also have a concept of the current item separate from the selection. This is the item that is currently focused in the list. This item may or may not be selected. The currentIndex property holds the index of the current item and the currentItem property holds the current item.