10.6 Ajout de gestionnaire d'évènements

Écrit par Neil Deakin. Traduit par Nadine Henry (24/08/2004).
Page originale : http://www.xulplanet.com/tutorials/xultu/xblevents.html

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

Les gestionnaires d'évènements

Comme vous pourriez 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 pourriez vouloir 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 le démontrait. Dans cet exemple, les gestionnaires oncommand avaient été ajoutés à quelques boutons.

Cependant, vous pouvez vouloir ajouter un gestionnaire d'évènement général au 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 des éléments va décrire l'action prise par un gestionnaire d'évènement simple. 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éral du gestionnaire est la suivante :


<binding id="binding-name">
  <handlers>
    <handler event="event-name" 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 pour la déclaration des 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 changée lorsque l'utilisateur clique dans 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 façon similaire, vous pouvez souhaiter changer une propriété lorsque l'élément est sélectionné. Vous aurez besoin d'ajouter des gestionnaires pour ajuster les propriétés chaque fois qu'une entrée de souris ou de clavier l'exigerait.

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 gérerait tous les évènements concernant la souris sans se soucier du bouton qui a été pressé. L'attribut button doit être définit à 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>

Pour les évènements provenant des touches du clavier, vous pouvez utiliser un nombre d'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 changé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 vérifier 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éfinis avec l'une des valeurs ci-dessous :

alt L'utilisateur doit presser la touche Alt.
control L'utilisateur doit presser la touche Control.
meta L'utilisateur doit presser la touche Meta.
shift L'utilisateur doit presser la touche Shift.
accel L'utilisateur doit presser la touche alernative spéciale qui est habituellement utilisée pour les raccourcis clavier sur sa plate-forme.

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="binding-name">
  <handlers>
    <handler event="event-name">
      -- 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-papier local très primitif :

Exemple 10.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 texte simple. Un champ clipboard lui a été ajouté pour stocker le contenu du presse-papier. Cela signifie que les opérations de presse-papier sont limitées à ce champ de texte simple. Le tampon sera propre à ce champ texte.

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 qui l'appelle. Le premier gestionnaire est l'opération Couper et est appelé lorsque la touche Control est pressée suivie de la touche x. Le script à l'intérieur de l'attribut action est utilisé pour couper le texte de la boîte de texte et pour le mettre dans le champ du presse-papier. Pour faire simple, le texte entier est coupé et pas seulement le texte sélectionné. Le code fonctionne comme suit :

```
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-papier. Le résultat est que le texte qui se trouve dans la champ de texte est copié dans ce presse-papier spécial.
```
document.getAnonymousNodes(this)[0].value=''
```
On assigne ainsi au texte de l'élément textbox une valeur de type chaîne, vide. Cela remplace le texte dans la champ de saisie par un espace libre.

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-papier. Si nous étions en train de créer une réelle implémentation de ces raccourcis clavier de presse-papier, nous utiliserions probablement l'interface réelle du presse-papier et gérerions également la sélection courante.

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