11.6 Ajout de gestionnaire d'évènements

Attention : Ce tutoriel est ancien et n'est pas mis à jour. Bien que beaucoup d'informations soient encore valables pour les dernières versions de gecko, beaucoup sont aussi obsolètes. Il est préférable d'aller consulter cette page sur la version française de ce tutoriel sur developer.mozilla.org.

Nous allons voir comment ajouter des gestionnaires d'événements aux éléments XBL.

Les gestionnaires d'événements

Comme vous pouvez le prévoir, des clics de souris, des touches pressées et d'autres événements sont passés à chacun des éléments à l'intérieur du contenu. Cependant, vous voudrez maîtriser les événements et les gérer à votre façon. Vous pouvez ajouter des gestionnaires d'événements aux éléments au sein du contenu si besoin. Le dernier exemple de la section précédente en faisait une démonstration. Dans cet exemple, des gestionnaires oncommand avaient été ajoutés sur quelques boutons.

Gestionnaires d'événements

Toutefois, vous pouvez vouloir ajouter un gestionnaire d'événement à tout le contenu, ce qui représente tous les éléments définis au sein de la balise content. Cela pourrait être utile pour maîtriser les événements de sélection (NdT : Focus) et de désélection. Pour définir un gestionnaire d'événement, utilisez l'élément handler. Chacun de ces éléments décrit l'action d'un seul gestionnaire d'événement. Vous pouvez utiliser plus d'un gestionnaire si nécessaire. Si un événement ne correspond pas à l'un des événements handler, il est passé simplement dans le contenu comme d'habitude.

La syntaxe générale du gestionnaire est la suivante :

<binding id="nom-liaison">
  <handlers>
    <handler event="nom-evenement" action="script"/>
  </handlers>
</binding>

Placez tous vos gestionnaires dans l'élément handlers. Chaque élément handler définit l'action prise pour un événement particulier grâce à son attribut event. Les événements valides sont ceux supportés par XUL et JavaScript, tels que click et focus. Utilisez le nom de l'événement sans son préfixe 'on'.

La principale raison nécessitant la déclaration de gestionnaires est la modification des propriétés personnalisées lorsqu'un événement se produit. Par exemple, une case à cocher personnalisée pourrait avoir une propriété checked qui doit être modifée lorsque l'utilisateur clique sur la case à cocher :

<handlers>
  <handler event="mouseup" action="this.checked=!this.checked"/>
</handlers>

Lorsque l'utilisateur clique et relâche le bouton de la souris au dessus de la case à cocher, l'événement mouseup lui est envoyé, et le gestionnaire défini ici est appelé, entraînant le renversement de l'état de la propriété checked. De même, vous pouvez modifier une propriété lorsque l'élément est sélectionné. Vous devrez ajouter des gestionnaires pour ajuster les propriétés lors de sollicitations de la souris ou du clavier.

Gestionnaire d'événements de souris

Pour des événements concernant la souris, vous pouvez utiliser l'attribut button pour que le gestionnaire n'accepte que les événements qui correspondent à un certain bouton. Sans cet attribut, le gestionnaire intercepterait tous les événements concernant la souris sans se soucier du bouton qui a été pressé. L'attribut button doit être défini à 0 pour le bouton gauche de la souris, 1 pour le bouton du milieu de la souris ou 2 pour le bouton droit de la souris.

<handlers>
  <handler event="click" button="0" action="alert('Le bouton gauche est pressé');"/>
  <handler event="mouseup" button="1" action="alert('Le bouton du milieu est pressé')"/>
  <handler event="click" button="2" action="alert('Le bouton droit est pressé');"/>
</handlers>

Gestionnaire d'événements clavier

Pour les événements provenant des touches du clavier, vous pouvez utiliser plusieurs attributs similaires à ceux de l'élément key pour les faire correspondre à une touche spécifique et seulement lorsque certaines touches alternatives sont pressées. L'exemple précédent pourrait être complété de telle sorte que la propriété checked de la case à cocher soit modifiée lorsque la barre d'espacement est pressée.

<handlers>
  <handler event="keypress" key=" " action="this.checked=!checked"/>
</handlers>

Vous pouvez aussi utiliser l'attribut keycode pour tester les touches non imprimables. La section sur les raccourcis clavier fournit plus d'informations. Les touches alternatives peuvent être vérifiées en ajoutant un attribut modifiers. Il peut être défini avec l'une des valeurs suivante :

alt

L'utilisateur doit presser la touche Alt.

control

L'utilisateur doit presser la touche Ctrl.

meta

L'utilisateur doit presser la touche Meta.

shift

L'utilisateur doit presser la touche Maj.

accel

L'utilisateur doit presser la touche alternative spéciale qui est habituellement utilisée pour les raccourcis clavier sur sa plateforme.

S'il est déclaré, le gestionnaire est appelé uniquement lorsque la touche alternative est pressée. Vous pouvez combiner plusieurs touches modificatrices en les séparant par des espaces.

La syntaxe alternative suivante peut être utilisée lorsque le code dans un gestionnaire est plus complexe :

<binding id="nom-liaison">
  <handlers>
    <handler event="nom-evenement">
      -- le code du gestionnaire vient ici --
    </handler>
  </handlers>
</binding>

Exemple de gestionnaires

L'exemple suivant ajoute des gestionnaires de touches pour créer un presse-papiers local très primitif :

Exemple 11.6.1 : Source

<binding id="clipbox">
  <content>
    <xul:textbox/>
  </content>
  <implementation>
    <field name="clipboard"/>
  </implementation>
  <handlers>
    <handler event="keypress" key="x" modifiers="control"
      action="this.clipboard=document.getAnonymousNodes(this)[0].value;
document.getAnonymousNodes(this)[0].value='';"/>
    <handler event="keypress" key="c" modifiers="control"
      action="this.clipboard=document.getAnonymousNodes(this)[0].value;"/>
    <handler event="keypress" key="v" modifiers="control"
      action="document.getAnonymousNodes(this)[0].value=this.clipboard ? this.clipboard : '';"/>
  </handlers>
</binding>

Le contenu est un champ de saisie simple. Un champ clipboard lui a été ajouté pour stocker le contenu du presse-papiers. Il signifie que les opérations de presse-papiers sont limitées à ce seul champ de saisie. Le tampon sera propre à ce champ.

Trois gestionnaires ont été ajoutés, un pour couper, un pour copier et l'autre pour coller. Chacun d'eux a sa propre combinaison de touche appellante. Le premier gestionnaire est l'opération Couper et est appelé lorsque la touche Ctrl est pressée suivie de la touche x. Le script à l'intérieur de l'attribut action est utilisé pour couper le texte du champ de saisie et pour le mettre dans le champ du presse-papiers. Pour faire simple, le texte entier est coupé et pas seulement le texte sélectionné. Le code fonctionne comme suit :

1. this.clipboard=document.getAnonymousNodes(this)[0].value;

   On récupère le premier élément du tableau de contenu anonyme qui donne une référence à l'élément textbox qui s'avère être le premier (et le seul) élément au sein de l'élément content. On récupère la propriété value qui fournira le texte du champ de saisie. Elle est ainsi assignée au champ du presse-papiers. Le résultat est que le texte qui se trouve dans la champ de saisie est copié dans ce presse-papiers spécial.

2. document.getAnonymousNodes(this)[0].value=''

   On assigne ainsi au texte de l'élément textbox une chaîne de caractères vide. Elle efface le texte dans le champ de saisie.

Une opération de copie est similaire mais n'efface pas le texte. Le collage est l'opération inverse si ce n'est que la valeur du champ de saisie est assignée à partir de la valeur du champ du presse-papiers. Si nous étions en train de créer une réelle implémentation de ces raccourcis clavier de presse-papiers, nous utiliserions probablement l'interface réelle du presse-papiers et nous gérerions également la sélection courante.

---

Dans la prochaine section, nous verrons comment étendre les définitions XBL existantes.