Manipulation de listes

La boîte de liste XUL fournit un certain nombre de méthodes spécialisées.

Manipulation d'une liste

L'élément listbox fournit de nombreuses méthodes pour rechercher et manipuler ses items. Bien que les boîtes de liste puissent être manipulées en utilisant les fonctions standard de DOM, il est recommandé d'employer les fonctions spécialisées de listbox autant que possible. Ces fonctions sont plus simples et feront correctement leur travail.

La fonction appendItem() est utilisée pour ajouter un nouvel item à la fin d'une liste. Elle est similaire à la fonction appendChild() du DOM sauf qu'elle prend un libellé texte, et que vous n'avez pas à vous soucier où placer votre item dans la structure de la liste. Voici un exemple :

var el = env.locale; Exemple 1: Source Voir

<script>
function addItem(){
  document.getElementById('laliste').appendItem("Jeudi", "jeu");
}
</script>

<listbox id="laliste"/>

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

La fonction appendItem() prend deux arguments, le libellé, dans l'exemple 'Jeudi', et une valeur 'jeu'. Les deux arguments correspondent aux attributs label et value dans l'élément listitem. L'attribut value est optionnel et sert à affecter à un item une valeur que vous pouvez réutiliser ensuite dans un script.

De même, il existe les fonctions insertItemAt() et removeItemAt(), qui ajoutent respectivement un nouvel item et suppriment un item existant. La syntaxe est la suivante :

list.insertItemAt(3, "Jeudi", "jeu");
list.removeItemAt(3);

La fonction insertItemAt() prend un argument supplémentaire, la position pour insérer le nouvel item. Le nouvel item est inséré à cet index. Ainsi, dans l'exemple, le nouvel item sera ajouté à la position 3 et l'item qui avait cette position aura maintenant l'index 4. Rappelez-vous que le premier item est 0. La fonction removeItemAt() supprimera l'item à un index spécifique.

Ces trois méthodes sont également disponibles pour plusieurs autres éléments XUL et fonctionnent de la même manière. En fait, ces méthodes font parties de l'interface nsIDOMXULSelectControlElement donc tous les éléments XUL qui implémentent cette interface héritent de ces méthodes. Les éléments menulist, radiogroup et tabs en font partie. Par exemple, pour ajouter un nouvel item à un menulist, vous pouvez employer la même syntaxe qu'une listbox. Le bon type d'élément sera ajouté dans chaque cas.

Sélection de liste

L'interface nsIDOMXULSelectControlElement fournit deux propriétés supplémentaires, selectedIndex et selectedItem. La première renvoie l'index de l'item sélectionné tandis que la seconde renvoie l'élément sélectionné. Par exemple, la valeur de retour de selectedItem sera le menuitem sélectionné. Si aucun item n'est sélectionné, selectedIndex retournera '-1', et selectedItem renverra 'null'.

Récupérer l'item sélectionné

Ces deux propriétés sont généralement inspectées durant un événement de sélection, comme dans l'exemple suivant :

var el = env.locale; Exemple 2: Source Voir

<listbox id="thelist" onselect="alert(this.selectedItem.label);">
  <listitem label="Petit"/>
  <listitem label="Moyen"/>
  <listitem label="Grand"/>
</listbox>

L'événement de sélection est exécuté par une listbox quand un item de la liste est sélectionné. Le gestionnaire affiche ici une alerte contenant le libellé de l'item sélectionné dans la liste. Puisque l'événement de sélection s'est exécuté, nous pouvons supposer qu'un item est sélectionné. Dans d'autres cas, vous devrez vous assurer que selectedItem n'est pas 'null' avant de poursuivre.

L'événement de sélection est également exécuté quand un bouton radio dans un radiogroup est sélectionné et quand un onglet est sélectionné dans l'élément tabs. Cependant, les menulists ne génèrent pas d'événement de sélection ; vous pouvez écouter l'événement "command" à la place pour traiter la sélection d'un item.

Pour l'élément tabs, il est souvent plus commode d'employer les fonctions de l'élément tabbox. Il a aussi une fonction selectedIndex qui renverra l'index de l'onglet sélectionné. Cependant, pour récupérer l'item sélectionné, utilisez plutôt la fonction selectedTab de tabbox. Ou alors, utilisez la fonction selectedPanel pour récupérer la page d'onglet sélectionnée, ce qui renvoie le contenu associé à l'onglet.

Modifier la sélection

Toutes les propriétés de sélection décrites ci-dessus peuvent également se voir assigner une nouvelle valeur pour modifier la sélection. Dans l'exemple suivant, la propriété selectedIndex de l'élément radiogroup est modifiée avec la valeur entrée dans un champ de saisie. Ce code n'est cependant pas performant ; par exemple, il ne vérifie pas si la valeur entrée est hors limite. Il est conseillé d'ajouter ce genre de vérification d'erreur.

var el = env.locale; Exemple 3: Source Voir

<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="Entrez un nombre compris entre 1 et 3 :"/>
  <textbox id="number"/>
  <button label="Sélectionnez" oncommand="doSelect();"/>
</hbox>

<radiogroup id="level">
  <radio label="Excellent"/>
  <radio label="Bon"/>
  <radio label="Mauvais"/>
</radiogroup>

Les boîtes de liste supportent aussi les sélections multiples et les fonctions de l'interface nsIDOMXULMultiSelectControlElement. Cette interface fournit un certain nombre de fonctions dédiées pour contrôler la sélection multiple. Par exemple, la propriété selectedItems contient une liste des items qui sont sélectionnés, alors que la propriété selectedCount contient le nombre d'items sélectionnés. En général, vous utiliserez ces propriétés pour parcourir la liste et y effectuer quelques opérations sur chaque item. Faites attention lorsque vous parcourez les items sélectionnés de la liste ; si vous modifiez les items dans la liste pendant que vous les parcourez, la liste sera modifiée et les propriétés de sélection pourraient retourner des valeurs différentes. C'est une raison pour laquelle il est utile de manipuler la liste par item plutôt que par l'index.

Effacer des items sélectionnés

L'exemple suivant montre une méthode correcte de suppression des items sélectionnés :

var el = env.locale; Exemple 4: Source Voir

<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="Supprimer" oncommand="deleteSelection();"/>

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

À l'intérieur de la boucle while,

• Nous récupérons d'abord l'item sélectionné à l'index 0. Le premier item sélectionné est toujours recherché car la taille du tableau diminuera au fur et à mesure que les items seront supprimés.
• Ensuite, nous supprimons l'item en utilisant la fonction removeItemAt. Comme cette fonction nécessite un index,
• Nous pouvons faire correspondre un item et son index en utilisant la fonction getIndexOfItem(). La fonction inverse correspondante est getItemAtIndex()

L'interface nsIDOMXULMultiSelectControlElement fournit également des méthodes pour modifier les items sélectionnés. Par exemple, la fonction addItemToSelection() ajoute un nouvel item à la liste des items sélectionnés, sans vider la sélection existante. La fonction removeItemFromSelection() supprime un seul item dans la sélection.

Défilement de liste

Si la boîte de liste contient plus de lignes qu'elle ne peut en afficher, une barre de défilement apparaîtra pour permettre à l'utilisateur de faire défiler la liste. La position du défilement peut être ajustée en utilisant quelques méthodes de listbox.

La méthode scrollToIndex() fait défiler jusqu'à une ligne donnée. Cette boîte de liste défilera jusqu'à ce que la ligne soit la première ligne visible, à moins que la ligne ne soit proche de la fin de la liste des items. La méthode ensureIndexIsVisible() est similaire puisqu'elle fait défiler la liste pour afficher une ligne, mais cette méthode ne défilera pas si l'item est déjà visible. Ainsi, la première fonction est utilisée pour faire défiler jusqu'à une ligne précise alors que la deuxième est utilisée pour s'assurer que la ligne soit visible. Il y a également ensureItemIsVisible() qui nécessite un item en argument au lieu d'un index. Comparez l'effet de ces deux fonctions à des positions de défilement différentes dans cet exemple :

var el = env.locale; Exemple 5: Source Voir

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

Nous verrons ensuite les objets boîtes XUL.

Interwiki