Ten element jest stosowany do tworzenia listy pozycji, na której można zaznaczyć jedną lub wiele pozycji. Lista taka może zawierać wiele kolumn. Istnieje szereg metod pozwalających na modyfikowanie i dostęp do elementów zawartych w listbox.

Można określić liczbę wierszy do wyświetlenia w liście za pomocą atrybutu rows. Jeśli wierszy jest więcej, niż to określono w tym atrybucie, listę będzie można przewinąć przy pomocy paska przewijania. Wszystkie wiersze w liście mają tę samą wysokość – jest to wysokość największego wiersza z listy. Element listbox powinien zawierać elementy listitem, każdy z nich wyświetla etykietę tekstową. Aby utworzyć listę z zawartością inną niż tekst, należy skorzystać z elementu richlistbox.

Dodatkowe informacje są dostępne w kursie XUL, można także przejrzeć źródła w LXR.

Atrybuty
disabled, disableKeyNavigation, preference, rows, seltype, suppressonselect, tabindex, value
Własności
accessible, disabled, disableKeyNavigation, selectedCount, selectedIndex, selectedItem, selectedItems, selType, tabIndex
Metody
addItemToSelection, appendItem, clearSelection, ensureElementIsVisible, ensureIndexIsVisible, getIndexOfFirstVisibleRow, getIndexOfItem, getItemAtIndex, getNextItem, getNumberofVisibleRows, getPreviousItem, getRowCount, getSelectedItem, insertItemAt, invertSelection, removeItemAt, scrollToIndex, selectAll, selectItem, selectItemRange, timedSelect, toggleItemSelection

Przykład

grafika:XUL_ref_listbox.png
 <listbox id="theList">
   <listitem label="Ruby"/>
   <listitem label="Emerald"/>
   <listitem label="Sapphire" selected="true"/>
   <listitem label="Diamond"/>
 </listbox>

Atrybuty

disabled
Typ: boolean
Określa, czy element jest wyłączony. Jeśli atrybut ten ma wartość true, to element będzie wyłączony. Wyłączone elementy zazwyczaj są wyszarzone. Jeśli element jest wyłączony, nie odpowiada na czynności użytkownika, nie może zostać na niego ustawiony focus, a zdarzenie command nie zostanie wywołane.
grafika:XUL_ref_attr_disabled.png
<!-- Pole wyboru włącza/wyłącza przycisk -->
<checkbox label="Enable button" 
    onclick="document.getElementById('buttRemove').disabled = this.checked"/>
<button id="buttRemove" label="Remove All" disabled="true"/>
disablekeynavigation
Typ: boolean
Jeśli atrybut ten nie jest użyty, użytkownik może przechodzić do określonych pozycji listy poprzez naciśnięcie pierwszej litery etykiety danej pozycji. Odbywa się to przyrostowo, dlatego przyciśnięcie dodatkowych klawiszy spowoduje zaznaczenie lepiej określonych pozycji. Opcja ta może zostać wyłączona poprzez ustawienie wartości atrybutu jako true.


preference
Typ: id elementu
Łączy dany element z odpowiadającym mu elementem preference. Atrybut ten ma skutek tylko wewnątrz okna prefwindow. Wartość opcji (z elementu preference) zostanie zaktualizowana zgodnie z wartością własności value tego elementu.



rows
Typ: integer
Liczba wierszy do wyświetlenia w elemencie. Jeśli w elemencie znajduje się więcej niż ta liczba wierszy, pojawi się pasek przewijania, który użytkownik może zastosować do przewijania do innych wierszy. Aby pobrać aktualną liczbę wierszy w elemencie, zastosuj metodę getRowCount.
tabindex
Typ: integer
Porządek dla przełączania elementów klawiszem Tab. Elementy o wyższym tabindex umieszczane są w dalszej części sekwencji przełączania.
value
Typ: string
Atrybut łańcucha znaków pozwalający na współpracę wartości danych z elementem. Nie jest stosowany dla określenia jakiegoś konkretnego celu, lecz można go wykorzystać w skrypcie do własnego użytku.

Własności

Metody

Dziedziczy z elementu XUL
blur, click, doCommand, focus, getElementsByAttribute getElementsByAttributeNS

Dziedziczy z elementu DOM
addEventListener(), appendChild(), dispatchEvent(), getAttribute(), getAttributeNode(), getAttributeNodeNS(), getAttributeNS(), getElementsByTagName(), getElementsByTagNameNS(), hasAttribute(), hasAttributeNS(), hasAttributes(), hasChildNodes(), insertBefore(), isSupported(), normalize(), removeAttribute(), removeAttributeNode(), removeAttributeNS(), removeChild(), removeEventListener(), replaceChild(), setAttribute(), setAttributeNode(), setAttributeNodeNS(), setAttributeNS()

addItemToSelection( item )
Zwraca typ: nie zwraca wartości
Zaznacza daną pozycje, bez odznaczania innych pozycji aktualnie zaznaczonych.


appendItem( label, value )
Zwraca typ: element
Tworzy nową pozycję i dodaje ją na koniec istniejącej listy pozycji. Opcjonalnie posiada ustawioną wartość. Funkcja zwraca nowo utworzony element.
clearSelection()
Zwraca typ: nie zwraca wartości
Odznacza wszystkie pozycje.


ensureElementIsVisible( element )
Zwraca typ: nie zwraca wartości
Jeśli określony element nie jest aktualnie widziany przez użytkownika, to wyświetlane pozycje są przewijane, do momentu, aż będzie on widoczny. Jeśli pozycja jest już widoczna, przewijanie nie będzie miało miejsca.


ensureIndexIsVisible( index )
Zwraca typ: nie zwraca wartości
Jeśli pozycja w określonym indeksie nie jest aktualnie widoczna, to użytkownik wyświetla tą pozycję poprzez przewinięcie okna. Jeśli natomiast pozycja jest widoczna, nie będzie możliwe żadne przewijanie.


getNumberOfVisibleRows()
Zwraca typ: integer
Zwraca liczbę wierszy, które są aktualnie widoczne dla użytkownika.


getIndexOfItem( item )
Zwraca typ: integer
Zwraca od zera pozycję określonych pozycji. Pozycje są numerowane zaczynając od pierwszej wyświetlanej pozycji na liście.


getItemAtIndex( index )
Zwraca typ: element
Zwraca element, który jest o określonym indeksie.


getNextItem( startItem, delta )
Zwraca typ: element
Metoda ta zwraca pozycję danej odległości (delta) po określonym startItem lub zwraca null, jeśli takiej pozycja nie istnieje. Ten przykład będzie zwracał pozycję dwa wiersze po jakiejśPozycji: getNextItem ( someItem, 2 );


getNumberOfVisibleRows()
Zwraca typ: integer
Zwraca liczbę wierszy, które są aktualnie widoczne dla użytkownika.


getPreviousItem( startItem, delta )
Zwraca typ: element
Metoda zwraca pozycję danej odległości (delta) przed określonym startItem lub zwraca null, jeśli taka pozycja nie istnieje. Ten przykład zwróci pozycje pięć wierszy przed someItem: getPreviousItem ( someItem, 5 );


getRowCount()
Zwraca typ: integer
Zwraca ogólną liczbę wierszy w elemencie, nieważne ile wierszy jest wyświetlanych.



insertItemAt( index, label, value )
Zwraca typ: element
Ta metoda tworzy nowy element listy i umieszcza go w określonej pozycji. Opcjonalnie można ustawić jego wartość. Nowy element jest zwracany.
invertSelection()
Zwraca typ: nie zwraca wartości
Odwraca status wszystkich zaznaczonych pozycji. Pozycja zaznaczona staje się odznaczona oraz odznaczona pozycja staje się zaznaczoną.
removeItemAt( index )
Zwraca typ: element
Usuwa pozycję potomną w elemencie o określonym indeksie. Metoda zwraca usuniętą pozycję.
scrollToIndex( index )
Zwraca typ: nie zwraca wartości
Przewija element do określonego indeksu. Jest inne niż ensureIndexIsVisible, ponieważ widok jest zawsze przewijany.
selectAll()
Zwraca typ: nie zwraca wartości
Zaznacza wszystkie pozycje. Zdarzenie zaznaczenia jest wysyłane po tym, jak zostanie zrobione zaznaczenie.
selectItem( item )
Zwraca typ: nie zwraca wartości
Odznacza wszystkie aktualnie zaznaczone pozycje i zaznacza daną pozycję. Zdarzenie zaznaczenia jest wysyłane po wykonaniu zaznaczenia.
selectItemRange( startItem, endItem)
Zwraca typ: nie zwraca wartości
Zaznaczone pozycje pomiędzy dwoma danymi pozycjami jako argumenty. Wszystkie inne pozycje są odznaczone. Ta metoda does nothing for single-selection list boxes. A select event is sent after the selection is made.
timedSelect( item, timeout )
Zwraca typ: nie zwraca wartości
Zaznacza pozycję określoną przez argument po danej liczbie milisekund argumentu czasu przerwy. Wszystkie inne pozycje są odznaczone.
toggleItemSelection( item )
Zwraca typ: nie zwraca wartości
Jeśli określona pozycja jest zaznaczona, to jest odznaczana. Jeśli nie jest zaznaczona, to jest zaznaczana. Inne pozycje na liście pudełka, które są zaznaczone are not affected, and retain their selected state.

Podobne

Elementy
listcell, listcol, listcols, listhead, listheader, listitem
Interfejsy
nsIAccessibleProvider, nsIDOMXULMultiSelectControlElement


Autorzy i etykiety dokumentu

Autorzy tej strony: teoli, lmorchard, Mgjbot, Marcoos, Ptak82
Ostatnia aktualizacja: teoli,