XUL:listbox

z Mozilla Developer Center, polskiego centrum programistów Mozilli.

« Dokumentacja XUL    [ Przykłady | Atrybuty | Własności | Metody | Podobne ]

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

[edytuj] Przykład

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

[edytuj] Atrybuty

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

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.

disableKeyNavigation

Typ: boolean

Jeśli ten atrybut nie jest zastosowany, użytkownik może poruszać się (nawigować) do określonej pozycji wewnątrz elementu przez naciśnięcie klawisza przesyłającego do pozycji etykiety. Zostało to wykonane z zyskiem, więc pisanie czcionek z zaznaczeniem bardziej określonej pozycji. Ta cecha może być wyłączona przez ustawienie tego atrybutu na 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.

seltype

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

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.

[edytuj] Własności

Dziedziczy z elementu XUL align, allowEvents, boxObject, builder, className, collapsed, contextMenu, controllers, currentItem, database, datasources, dir, flex, height, hidden, id, left, listBoxObject, maxHeight, maxWidth, menu, minHeight, minWidth, observes, ordinal, orient, pack, persist, ref, resource, statusText, style, tooltip, tooltipText, top, value, width Dziedziczy z elementu DOM attributes, childNodes, cloneNode, firstChild, lastChild, localName, namespaceURI, nextSibling, nodeName, nodeType, nodeValue, ownerDocument, parentNode, prefix, previousSibling, tagName

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.

selType

Typ: string

Pobiera i ustawia wartość atrybutu seltype.

tabIndex

Typ: integer

Pobiera i ustawia wartość atrybutu tabindex.

[edytuj] Metody

Dziedziczy z elementu XUL blur, click, doCommand, focus, getElementsByAttribute 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.

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.

[edytuj] Podobne

Elementy

listcell, listcol, listcols, listhead, listheader, listitem

Interfejsy

nsIAccessibleProvider, nsIDOMXULMultiSelectControlElement