Home > Element Reference : Listbox

Contents

### Listbox

Moz0.9.9

This element is used to create a list of items. This is a simpler version of a tree. Nested rows are not supported, but it may contain multiple columns.

More information about Listbox

#### Attributes:

Attributes inherited from XUL Element

rows

The number of rows in the list box.

seltype Moz0.9.8

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 Moz0.9.8

If set to a value other than true, or left out entirely, a select event is fired when an item is selected, either by the user or by calling one of the select methods. This is the default value. If set to true, the select event is never fired.

#### Properties and Methods:

Properties and Methods inherited from XUL Element

addItemToSelection ( item )

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

appendItem ( label , value )

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

clearSelection ( )

Deselects all of the items.

currentItem

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

ensureElementIsVisible ( element )

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 )

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 ( )

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 )

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

getItemAtIndex ( index )

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

getNextItem ( startItem, delta )

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 ( )

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

getPreviousItem ( startItem, delta )

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 ( )

Returns the total number of rows in the list box.

getSelectedItem ( index )

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

insertItemAt ( index, label , value )

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

invertSelection ( )

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

listBoxObject

The nsIListBoxObject behind the list box. This property is read-only.

removeItemAt ( index )

Removes the child item in the list box at the given index.

removeItemFromSelection ( item )

Deselects the given item without deselecting other items.

scrollToIndex ( index )

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

selType Moz0.9.8

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.

selectAll ( )

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

selectItem ( item )

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 )

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

Returns the number of items that are currently selected.

selectedIndex

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

Returns the currently selected item. You may select an item by assigning to this property. All other items will be deselected.

timedSelect
toggleItemSelection ( item )

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

Returns the value property of the currently selected item. Assigning to this property selects the first item with the corresponding value.

Copyright (C) 1999 - 2002 XULPlanet.com