<listbox id="theList">
      <listitem label="Ruby"/>
      <listitem label="Emerald"/>
      <listitem label="Sapphire"/>
      <listitem label="Diamond"/>
    </listbox>

disableKeyNavigation

Type: boolean

If this attribute is not used, the user can navigate to specific items in the list by pressing the first the first letter of the item's label. This is done incrementally, so pressing additional keys will select more specific items. This feature may be disabled for a listbox by setting this attribute to true.

disabled

Type: boolean

Indicates whether the listbox is disabled or not. If this attribute is set to true, the listbox is disabled. This is usually drawn with the text in grey. If the listbox is disabled, it does not respond to user actions. The element cannot be focused and the command event will not fire. The element will still respond to mouse events. To enable the listbox, leave the attribute out entirely as opposed to setting the value to false.

preference    Mozilla 1.8

Type: element id

Connects the listbox to a corresponding preference. This attribute only has any effect when used inside a prefwindow. The value of the preference will be updated to match the value property of the listbox.

rows

Type: integer

The number of rows to display in the list box. If the listbox contains more than this many rows, a scrollbar will appear which the user can use to scroll to the other rows. To get the actual number of rows in the listbox, use the getRowCount method.

seltype

Type: one of the values below

Used to indicate whether multiple selection is allowed.

• single: Only one row may be selected at a time.
• multiple: Multiple rows may be selected at once.

suppressonselect

Type: boolean

If this attribue is not specified, a select event is fired whenever an item is selected, either by the user or by calling one of the select methods. If set to true, the select event is never fired.

tabindex

Type: integer

The tab order of the element. The tab order is the order in which the focus is moved when the user presses the Tab key. Elements with a higher tabindex are later in the tab order sequence.

value

Type: string

You can associate a data value with each listitem. It is not used for any specific purpose but you can access it with a script for your own use.

accessible

Type: nsIAccessible

Returns the accessibility object for the listbox.

addItemToSelection ( item )

Return Type: no return value

Selects the given item, without deselecting any other items that are already selected.

appendItem ( label , value )

Return Type: listitem element

Creates a new listitem element and adds it to the end of the list box. You may optionally set a value. The function returns the new item.

clearSelection ( )

Return Type: no return value

Deselects all of the items.

currentItem

Type: listitem element

Returns the last selected item in the list box, which is only useful in a multiple selection list box.

disableKeyNavigation

Type: boolean

If this attribute is not used, the user can navigate to specific items in the list by pressing the first the first letter of the item's label. This is done incrementally, so pressing additional keys will select more specific items. This feature may be disabled for a listbox by setting this attribute to true.

disabled

Type: boolean

Gets and sets the value of the disabled attribute.

ensureElementIsVisible ( element )

Return Type: no return value

If the element in the list box is not currently visible to the user, the list box view is scrolled so that it is. If the item is already visible, no scrolling occurs.

ensureIndexIsVisible ( index )

Return Type: no return value

If the item at the specified index is not currently visible to the user, the list box view is scrolled so that it is. If the item is already visible, no scrolling occurs.

getIndexOfFirstVisibleRow ( )

Return Type: integer

Returns the index of the first displayed row in the list box. This is not the same as the first row. If the view of the list box has been scrolled down, the function can be used to retrieve the index of the first row that the user can see.

getIndexOfItem ( item )

Return Type: integer

Returns the zero-based position of the given item. Items are numbered starting from the first item displayed in the list.

getItemAtIndex ( index )

Return Type: listitem element

Returns the item that is at the position specified by the parameter index in the list box.

getNextItem ( startItem, delta )

Return Type: listitem element

This method returns a item after another one. The parameter startItem is the item and delta is the number of items to count to.

getNextItem ( someItem, 2 );

This example, given a item someItem, will return the item 2 rows after it, or null if no such item exists.

getNumberOfVisibleRows ( )

Return Type: integer

Returns the number of rows of the list box that are currently visible to the user.

getPreviousItem ( startItem, delta )

Return Type: listitem element

This method returns a item before another one. The parameter startItem is the item and delta is the number of items to count to.

getPreviousItem ( someItem, 5 );

This example, given a item someItem, will return the item 5 rows before it, or null if no such item exists.

getRowCount ( )

Return Type: integer

Returns the total number of rows in the list box, regardless of how many rows are displayed.

getSelectedItem ( index )

Return Type: listitem element

When multiple items are selected, you can retrieve each selected item using this function. The argument index specifies the index in the list of selected items, not the row number of the item. Thus, getSelectedItem(7) will return the seventh selected item.

insertItemAt ( index, label , value )

Return Type: listitem element

Creates a new listitem element and inserts it at a specific position in the list box. You may optionally set a value. The function returns the new item.

invertSelection ( )

Return Type: no return value

Reverses the selected state of all the items. Selected items become deselected and deselected items become selected.

listBoxObject

Type: nsIListBoxObject

The nsIListBoxObject behind the list box. This property is read-only. Most of the features of the list box object are already available directly in the listbox, so you will rarely have need to use this box object directly.

removeItemAt ( index )

Return Type: listitem element

Removes the child item in the list box at the given index. The function returns the removed item.

removeItemFromSelection ( item )

Return Type: no return value

Deselects the given item without deselecting other items.

scrollToIndex ( index )

Return Type: no return value

Scrolls the list box view to the specified index. This is different than ensureIndexIsVisible because the view is always scrolled.

selType

Gets and sets the value of the seltype attribute.

selectAll ( )

Return Type: no return value

Selects all of the items. A select event is sent after the selection is made.

selectItem ( item )

Return Type: no return value

Deselects all of the currently selected items and selects the given item. A select event is sent after the selection is made.

selectItemRange ( startItem , endItem )

Return Type: no return value

Selects the items in-between two items given as arguments, including the start and end items. All other items are deselected. This method does nothing for single-selection list boxes. A select event is sent after the selection is made.

selectedCount

Type: integer

Returns the number of items that are currently selected.

selectedIndex

Type: integer

Returns the index of the currently selected item. You may select an item by assigning its index to this property. By assigning -1 to this property, all items will be deselected.

selectedItem

Type: listitem element

Returns the currently selected item. If there are multiple items selected, the property will hold only the first selected item. To get all of the selected items, use the selectedItems property. You may select an item by assigning a listitem element to this property. All other items will be deselected.

selectedItems

Type: array of listitems

Returns an array of the selected items in the list.

tabIndex    Mozilla 1.8

Type: integer

Get and sets the value of the tabindex attribute.

timedSelect ( item , timeout )

Return Type: no return value

Selects the item specified by the argument item after the number of milliseconds given by the timeout argument. All other items are deselected.

toggleItemSelection ( item )

Return Type: no return value

If the specified item is selected, it is deselected. If it is not selected, it is selected. Other items in the list box that are selected are not affected, and retain their selected state.

value

Type: string

Gets and sets the value of the value attribute.