listbox

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.
{{ languages( { "en": "en/XUL/Attribute/seltype", "fr": "fr/XUL/Attributs/seltype", "ja": "ja/XUL/Attribute/seltype" } ) }}
{{ XULAttr("seltype") }} {{ mediawiki['#switch']('<magic name="\"PAGENAME\"/">', XUL:richlistbox = .. '<template><name>' .. Fx_minversion_inline .. '</name><arg>' .. 3 .. '</arg></template>') }}</magic>
Typ: jedna z wartości poniżej
Używany do sygnalizowania czy wielokrotne zaznaczanie jest uznane.
  • single: Tylko jeden wiersz może być zaznaczona być w czasie (domyślnie w listbox).
  • multiple: Wielokrotne wiersze mogą być zaznaczane jeden raz (domyślnie w tree.)

{{ mediawiki['#switch']('<magic name="\"PAGENAME\"/">', XUL:tree = * .. '' .. cell .. '' .. : Individual cells can be selected. .. '<template><name>' .. Fx_minversion_inline .. '</name><arg>' .. 3 .. '</arg></template>') }}</magic> {{ mediawiki['#switch']('<magic name="\"PAGENAME\"/">', XUL:tree = * .. '' .. text .. '' .. : Rows are selected, however the selection highlight appears only over the text of the primary column.) }}</magic>



suppressonselect
Type: boolean
If this attribute 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
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

accessible
Typ: nsIAccessible
Zwraca obiekt dostępności dla elementu.
disabled
Typ: boolean
Pobiera i ustawia wartość atrybutu disabled.
disableKeyNavigation
Typ: boolean
Pobiera lub ustawia wartość atrybutu disableKeyNavigation.
selectedCount
Typ: integer
Zwraca liczbę pozycji, która jest aktualnie zaznaczona.
selectedIndex
Typ: integer
Zwraca indeks aktualnie zaznaczonej pozycji. Można zaznaczyć pozycję przypisując jej numer indeksu do własności. Przydzielając -1 do tej własności, wszystkie pozycje zostaną odznaczone.
selectedItem
Typ: element
Podtrzymuje aktualnie zaznaczoną pozycję. Jeśli nie ma zaznaczonych aktualnie pozycji, to jej wartość równa będzie null. Możemy zaznaczyć pozycję poprzez ustawienie tej wartości. Zmiana zdarzenia będzie przesyłana do zaznaczonej pozycji, kiedy zmieniona zostanie jedna z tych własności, własność selectedIndex lub zmieniona będzie przez użytkownika.
selectedItems
Typ: tablica z listą pozycji
Zwraca tablicę zaznaczonych pozycji na liście.
{{ languages( { "en": "en/XUL/Property/selType", "fr": "fr/XUL/Propri\u00e9t\u00e9s/selType", "ja": "ja/XUL/Property/selType" } ) }}
{{ XULProp("selType") }} {{ mediawiki['#switch']('<magic name="\"PAGENAME\"/">', XUL:richlistbox = .. '<template><name>' .. Fx_minversion_inline .. '</name><arg>' .. 3 .. '</arg></template>') }}</magic>
Typ: string
Pobiera i ustawia wartość atrybutu {{ XULAttr("seltype") }}.



tabIndex
Typ: integer
Pobiera i ustawia wartość atrybutu tabindex.

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 <var>jakiejśPozycji</var>: 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 <var>someItem</var>: getPreviousItem ( someItem, 5 );


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



getSelectedItem( index )
Zwraca typ: element
When multiple items are selected, you can retrieve each selected item using this method. The argument index specifies the index in the list of the selected items, not the row number of the item. The item index is zero-based, thus this example will return the first selected item: getSelectedItem(0).
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: Ptak82, lmorchard, Marcoos, Mgjbot
Ostatnia aktualizacja: lmorchard,