Manipulowanie listami

Pudełko listy XUL posiada kilka specjalnych metod.

Manipulowanie listami

Element listbox dostarcza licznych metod do wyszukiwania i manipulowania swoimi pozycjami. Chociaż pudełka listy mogą być manipulowane przy zastosowaniu standardowych funkcji DOM, zalecane jest, żeby stosować specjalne funkcje pudełka list, gdy to jest możliwe. Funkcje te są trochę prostsze i będą poprawnie wykonywały swoje zadanie.

Funkcja appendItem() jest stosowana do dołączania nowej pozycji na końcu listy. Podobna jest do funkcji DOM appendChild() z wyjątkiem tego, że pobiera etykietę w postaci łańcucha znaków, a Ty nie musisz się martwić o to, gdzie ją dodać w strukturze listy. Poniżej mamy przykład:

var el = env.locale; Przykład 1 : Źródła Podgląd

<script>
function addItem(){
  document.getElementById('thelist').appendItem("Czwartek", "czw");
}
</script>

<listbox id="thelist"/>

<button label="Dodaj" oncommand="addItem();"/>

Metoda appendItem() pobiera dwa argumenty; argument label, w tym przypadku 'Czwartek' oraz argument value 'czw'. Te dwa argumenty są przesyłane do atrybutu label i atrybutu value dla elementu w listitem. Ta wartość jest używana tylko jako dodatkowa opcjonalna wartość powiązana z pozycją, którą można by było zastosować w skrypcie.

Podobnie jest również z funkcją insertItemAt() i removeItemAt(), które odpowiednio wstawiają nową pozycję i usuwają poszczególne istniejące pozycje. Składnia jest następująca:

list.insertItemAt(3, "Czwartek", "czw");
list.removeItemAt(3);

Funkcja insertItemAt() pobiera dodatkowy argument, pozycję do wstawienia nowej pozycji. Nowa pozycja jest włożona do tego indeksu, więc w przykładzie nowa pozycja będzie dodana na pozycji 3, podczas gdy wcześniejsza pozycja z tego miejsca będzie teraz pod numerem 4. Pamiętaj, że pierwszą pozycją jest 0. Funkcja removeItemAt() będzie usuwała pozycję o określonym indeksie.

Te trzy metody są również dostępne dla kilku innych elementów XUL i działają w ten sam sposób. Faktycznie, te metody są częścią interfejsu nsIDOMXULSelectControlElement, więc dowolny element XUL, który implementuje ten interfejs, posiada te metody. Obejmuje to elementy menulist, radiogroup i tabs. Na przykład, dodając nową pozycję do menulist, możemy zastosować ta samą składnię jak dla listbox. Poprawny rodzaj elementu będzie mógł zostać dołączony w każdej sytuacji.

Zaznaczenie listy

Interfejs nsIDOMXULSelectControlElement posiada dwie dodatkowe własności: selectedIndex i selectedItem. Pierwsza zwraca index zaznaczonej pozycji, podczas gdy druga zwraca zaznaczony element. Dla przykładu selectedItem listy menu będzie to pozycja menuitem, która jest zaznaczona. Jeśli nie zostanie zaznaczona żadna pozycja, własność selectedIndex zwróci -1, podczas gdy własność selectedItem zwróci null.

Pobieranie zaznaczonej pozycji

Te dwie własności są powszechnie sprawdzane podczas zdarzenia wyboru, jak pokazano w poniższym przykładzie:

var el = env.locale; Przykład 2 : Źródła Podgląd

<listbox id="thelist" onselect="alert(this.selectedItem.label);">
  <listitem label="Niski"/>
  <listitem label="Średni"/>
  <listitem label="Wysoki"/>
</listbox>

Zdarzenie zaznaczenia jest odpalane dla elementu listbox, kiedy pozycja w liście jest zaznaczona. Obsługa wyboru wyświetla alarm zawierający etykietkę wybranej pozycji z listy. Jeśli wyzwolono zdarzenie wyboru, możemy założyć, że pozycja została wybrana. W innych przypadkach możesz życzyć sobie sprawdzenia, aby upewnić się przed kontynuowaniem, że selectedItem nie jest null.

Zdarzenie zaznaczenia jest także odpalane, kiedy jest zaznaczony przycisk opcji w radiogroup i kiedy jest zaznaczona karta w elemencie tabs. Jednak menulists nie odpala zdarzenia zaznaczenia, zamiast tego można nasłuchiwać zdarzenia polecenia do obsługi, kiedy pozycja jest zaznaczona.

Dla elementu tabs często bardziej dogodnymi do użycia funkcjami elementu są funkcje elementu tabbox. Posiada on również funkcję selectedIndex, która będzie zwracała index zaznaczonej karty. Jednakże do pobrania zaznaczonej pozycji użyj zamiast tego własności elementu tabbox selectedTab lub użyj własności selectedPanel do pobrania zaznaczonego panelu, to znaczy, że zwraca zawartość powiązanego z nim elementu tab.

Zmienianie zaznaczenia

Wszystkim podobnym własnościom zaznaczenia, które zostały opisane powyżej, mogą również być przydzielone nowe wartości do zmiany zaznaczenia. W następnym przykładzie właściwość selectedIndex elementu radiogroup jest zmieniana w oparciu o wartość wprowadzoną w polu tekstowym. Kod ten nie jest niestety niezawodny; na przykład nie sprawdza się, jeśli wprowadzona wartość jest poza zakresem. Będziemy chcieli mieć pewność, że dodany zostanie właściwy sposób sprawdzenia tego błędu.

var el = env.locale; Przykład 3 : Źródła Podgląd

<script>
function doSelect(){
  var val = document.getElementById('number').value;
  val = Number(val);
  if (val != null)
    document.getElementById('level').selectedIndex = val - 1;
}
</script>

<hbox align="center">
  <label value="Wprowadź liczbę od 1 do 3:"/>
  <textbox id="number"/>
  <button label="Zaznacz" oncommand="doSelect();"/>
</hbox>

<radiogroup id="level">
  <radio label="Wyśmienite"/>
  <radio label="Dobre"/>
  <radio label="Słabe"/>
</radiogroup>

Pudełko listy również obsługuje wielokrotne zaznaczenie oraz funkcje interfejsu nsIDOMXULMultiSelectControlElement. Interfejs ten posiada kilka sprecyzowanych funkcji obsługujących wielokrotne zaznaczenie. Na przykład własność selectedItems przechowuje listę pozycji, które są zaznaczone, podczas gdy własność selectedCount przechowuje liczbę zaznaczonych pozycji. Zazwyczaj te własności będą używane do iteracji przez tą listę i wykonywania jakiś operacji dla każdej pozycji. Bądźmy ostrożni, kiedy iterujemy przez zaznaczone pozycje; jeśli modyfikujemy pozycje w liście podczas trwania iteracji, lista będzie zmieniana i własność zaznaczenia może zwrócić różne wartości. Jest to jeden z powodów dla których jest to użyteczny sposób manipulowania listą poprzez pozycje raczej niż poprzez index.

Usuwanie zaznaczonych pozycji

Poniższy przykład pokazuje metodę właściwego usuwania zaznaczonej pozycji:

var el = env.locale; Przykład 4 : Źródła Podgląd

<script>
function deleteSelection(){
  var list = document.getElementById('thelist');
  var count = list.selectedCount;
  while (count--){
    var item = list.selectedItems[0];
    list.removeItemAt(list.getIndexOfItem(item));
  }
}
</script>

<button label="Delete" oncommand="deleteSelection();"/>

<listbox id="thelist" seltype="multiple">
  <listitem label="Cheddar"/>
  <listitem label="Cheshire"/>
  <listitem label="Edam"/>
  <listitem label="Gouda"/>
  <listitem label="Havartie"/>
</listbox>

Wewnątrz pętli while możemy:

• pobierać selecteItem o indeksie 0. Pierwsza zaznaczona pozycja jest zawsze otrzymywana jako rozmiar tablicy będącej zmniejszonej o usunięte pozycje,
• usuwać pozycję używając funkcji removeItemAt(). Od momentu, gdy ta funkcja żąda indeksu.
• konwertować pomiędzy pozycją a indeksem stosując funkcję getIndexOfItem(). Jest to także przesyłanie funkcji getItemAtIndex() do swojej odwrotności.

Interfejs nsIDOMXULMultiSelectControlElement posiada również metody do modyfikacji zaznaczonych pozycji. Dla przykładu funkcja addItemToSelection() dodaje nową pozycję do zbioru zaznaczonych pozycji, bez czyszczenia istniejącego zaznaczenia. Funkcja removeItemFromSelection() usuwa pojedynczą pozycję z zaznaczonych pozycji.

Przewijanie listy

Jeśli jest więcej wierszy w elemencie listbox, niż może być wyświetlonych, pojawi się pasek przewijania pozwalający użytkownikowi przewinąć listę. Pozycja przewijania może być modyfikowana przy użyciu paru metod pola listy.

Metoda scrollToIndex() przewija do danego wiersza. To pole listy będzie przewijane tak, że wiersz, do którego chcemy przewinąć listę, będzie widocznym górnym wierszem, chyba że wiersz jest wierszem tuż przed końcem listy pozycji. Metoda ensureIndexIsVisible() jest podobna w tym, że również przewija pokazując wiersz, ale metoda ta nie przewija, jeśli ta pozycja jest aktualnie widoczna. Zatem pierwsza funkcja jest używana do przewijania do określonego wiersza podczas, gdy druga jest używana tylko do upewnienia się, że wiersz jest widoczny. Jest również metoda ensureIndexIsVisible(), która pobiera pozycje jako argument zamiast jako index. Rezultat porównania obu funkcji przy różnych pozycjach przewinięcia jest w tym przykładzie:

var el = env.locale; Przykład 5 : Źródła Podgląd

<button label="scrollToIndex"
           oncommand="document.getElementById('thelist').scrollToIndex(4);"/>
<button label="ensureIndexIsVisible"
           oncommand="document.getElementById('thelist').ensureIndexIsVisible(4);"/>

<listbox id="thelist" rows="5">
  <listitem label="1"/>
  <listitem label="2"/>
  <listitem label="3"/>
  <listitem label="4"/>
  <listitem label="5"/>
  <listitem label="6"/>
  <listitem label="7"/>
  <listitem label="8"/>
  <listitem label="9"/>
  <listitem label="10"/>
  <listitem label="11"/>
  <listitem label="12"/>
</listbox>

W następnym artykule przeczytamy o obiektach pudełka XUL.