References > " . "Element Reference"; $pagetitle="Listbox"; $customsidebar = "elemref-sidebar.php"; include "header.php"; ?>

Listbox

This element is used to create a list of items. This is a simpler version of a tree. Nested rows are not supported, but a listbox may contain multiple columns. There are numerous methods which allow the items in the listbox to be retrieved and modified.

You may specify the number of rows to display in the list using the rows attribute. Additional rows can be viewed by using a scroll bar. All of the rows in the listbox are the same height, which is the height of the largest item in the list.

More information about listbox

Example:

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

The listbox element implements the following interfaces:

nsIAccessibleProvider   nsIDOMXULMultiSelectControlElement  

Attributes:

disableKeyNavigation disabled rows seltype suppressonselect
tabindex value

Properties and Methods:

accessible addItemToSelection appendItem clearSelection currentItem
disableKeyNavigation disabled ensureElementIsVisible ensureIndexIsVisible getIndexOfFirstVisibleRow
getIndexOfItem getItemAtIndex getNextItem getNumberOfVisibleRows getPreviousItem
getRowCount getSelectedItem insertItemAt invertSelection listBoxObject
removeItemAt removeItemFromSelection scrollToIndex selType selectAll
selectItem selectItemRange selectedCount selectedIndex selectedItem
selectedItems timedSelect toggleItemSelection value

Attributes:

Inherited from XUL Element:

align
allowevents
allownegativeassertions
class
coalesceduplicatearcs
collapsed
container
containment
context
contextmenu
datasources
debug
dir
empty
equalsize
flags
flex
height
hidden
id
insertafter
insertbefore
left
maxheight
maxwidth
menu
minheight
minwidth
observes
ordinal
orient
pack
persist
popup
position
ref
removeelement
sortDirection
sortResource
sortResource2
statustext
style
template
tooltip
tooltiptext
top
uri
wait-cursor
width

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.

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.

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.


Properties and Methods:

Inherited from XUL Element:

align
allowEvents
blur
boxObject
boxObject.element
boxObject.getLookAndFeelMetric
boxObject.height
boxObject.screenX
boxObject.screenY
boxObject.width
boxObject.x
boxObject.y
builder
className
click
collapsed
contextMenu
controllers
database
datasources
dir
doCommand
flex
focus
getElementsByAttribute
height
hidden
id
left
maxHeight
maxWidth
menu
minHeight
minWidth
observes
ordinal
orient
pack
persist
ref
resource
statusText
style
tooltip
tooltipText
top
width

Inherited from Element:

addEventListener
appendChild
attributes
childNodes
cloneNode
dispatchEvent
firstChild
getAttribute
getAttributeNS
getAttributeNode
getAttributeNodeNS
getElementsByTagName
getElementsByTagNameNS
hasAttribute
hasAttributeNS
hasAttributes
hasChildNodes
insertBefore
isSupported
lastChild
localName
namespaceURI
nextSibling
nodeName
nodeType
nodeValue
normalize
ownerDocument
parentNode
prefix
previousSibling
removeAttribute
removeAttributeNS
removeAttributeNode
removeChild
removeEventListener
replaceChild
setAttribute
setAttributeNS
setAttributeNode
setAttributeNodeNS
tagName

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.

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.