7.1 Ajout de gestionnaires d'évènements

Écrit par Neil Deakin. Traduit par Durandal (18/07/2004).
Page originale : http://www.xulplanet.com/tutorials/xultu/events.html

La boîte de dialogue de recherche de fichiers est tout à fait correcte à ce stade. Nous ne l'avons pas beaucoup nettoyé mais nous avons créé une interface utilisateur facilement. Dans ce qui suit, nous allons montrer comment lui ajouter des scripts.

Réagir aux évènements

Pour rendre le dialogue de recherche de fichiers fonctionnel, nous avons besoin d'ajouter des scripts qui vont s'exécuter quand l'utilisateur interagira avec le dialogue. Nous voudrions ajouter un script pour gérer le bouton Rechercher, le bouton Annuler et pour gérer chaque commande du menu. Nous écrivons cela en utilisant des fonctions Javascript de la même manière qu'en HTML.

Si vous connaissez le HTML, vous pourriez deviner comment nous faisons réagir les boutons et les autres éléments XUL aux évènements. Nous devons juste ajouter des gestionnaires comme onmousedown aux éléments. Ensuite nous fournissons un script qui exécute la fonction désirée.

Vous pouvez utiliser l'élément script pour inclure des scripts dans des fichiers XUL. Vous pouvez aussi inclure le script directement dans le fichier XUL entre les balises script ouvrante et fermante, mais il est bien mieux d'inclure le code dans un fichier à part. Votre fenêtre XUL se chargera plus rapidement. Nous utiliserons alors l'attribut src pour lier un fichier de script externe.

Ajoutons un script au dialogue de recherche de fichiers. Bien que le nom du fichier de script n'ait pas d'importance, on lui donne habituellement le même nom que celui du fichier XUL, avec l'extension js. Dans ce cas, on utilisera findfile.js. Ajoutez la ligne ci-dessous juste après la balise window ouvrante et avant tout élément.

<script src="findfile.js"/>

Nous créerons le fichier de script plus tard, quand nous saurons quoi y mettre. Nous allons définir des fonctions dans le fichier, que nous pourrons appeler dans les gestionnaires d'évènements (event handlers).

Les gestionnaires d'évènements en XUL sont faits de la même manière qu'en HTML. Les mêmes gestionnaires d'évènements sont disponibles, plus d'autres additionnels. Pour gérer un évènement, ajoutez simplement un des attributs du tableau ci-dessous à un élément. Il y en a un certain nombre d'autres que vous pouvez aussi ajouter, que nous verrons dans des sections ultérieures.

onclick: Appelé quand la souris est pressée et relâchée sur un élément. Vous ne devez utiliser l'évènement onclick que si vous avez une raison de ne réagir qu'aux clics de la souris. Pour les boutons, les items de menu, et autres, vous devriez utiliser oncommand, parce qu'il prend aussi en compte les utilisateurs qui utilisent le clavier ou d'autres périphériques.
onmousedown: Appelé quand un bouton de la souris est pressé sur un élément. Le gestionnaire de l'évènement sera appelé dès l'appui du bouton de la souris, même s'il n'a pas encore été relâché.
onmouseup: Appelé quand un bouton de la souris est relâché sur un élément.
onmouseover: Appelé quand le pointeur de la souris est déplacé vers un élément. Vous pourriez utiliser ceci pour mettre l'élément en surbrillance, cependant CSS permet de faire cela automatiquement, vous ne devriez donc pas le faire avec un évènement. Vous pourriez, par contre, avoir envie d'afficher du texte d'aide dans une barre d'état.
onmousemove: Appelé quand le pointeur de la souris est déplacé au-dessus d'un élément. L'évènement sera appelé un grand nombre de fois si l'utilisateur déplace la souris donc vous devriez essayer d'éviter d'utiliser ce gestionnaire si vous le pouvez.
onmouseout: Appelé quand le pointeur de la souris est déplacé vers l'extérieur d'un élément. Vous pourriez alors remettre l'élément à l'état normal ou enlever du texte de la barre d'état.
oncommand: Cet évènement est appelé quand un bouton ou un item de menu est sélectionné. Pour les menus, ajoutez ce gestionnaire à l'élément menuitem. Vous devriez utiliser ce gestionnaire plutôt que gérer la souris vous-même, comme l'utilisateur peut sélectionner le bouton ou l'item de menu avec la souris ou en utilisant une touche d'accès ou un raccourci clavier.
onkeypress: Appelé quand une touche est appuyée puis relâchée quand un élément a le focus. Vous pourriez l'utiliser pour ajouter une gestion de touches de raccourcis supplémentaires ou pour vérifier les caractères autorisés d'un champ. Nous verrons comment créer des raccourcis clavier dans la prochaine section.
onkeydown: Appelé quand une touche est appuyée lorsqu'un élément a le focus. Notez que l'évènement sera appelé dès l'appui de la touche, même si elle n'a pas été relâchée. Vous n'utiliserez probablement pas souvent cet évènement comme les autres évènements de touches sont plus appropriés.
onkeyup: Appelé quand une touche est relâchée lorsqu'un élément a le focus.
onfocus: Appelé quand un élément reçoit le focus soit en cliquant dessus soit en utilisant la touche TAB. Vous pouvez utiliser cet évènement pour mettre l'élément en surbrillance ou afficher du texte d'aide.
onblur: Appelé quand un élément perd le focus soit quand l'utilisateur clique sur un autre élément soit en utilisant la touche TAB. Vous pouvez utiliser cet évènement pour vérifier des informations ou fermer des popups. Il est cependant meilleur de vérifier les champs à l'appui du bouton OK.
onload: Appelé à la première ouverture d'une fenêtre. Vous ajouterez généralement ce gestionnaire d'évènement à une balise window pour initialiser une fenêtre. Cela peut permettre de mettre des valeurs par défaut à des champs, selon des conditions contenues dans un script.
onunload: Appelé quand une fenêtre se ferme. Vous l'ajouterez généralement à une balise window pour enregistrer des informations avant que la fenêtre ne se ferme.

oncommand est le gestionnaire d'évènement que vous utiliserez généralement pour réagir aux évènements liés aux boutons et aux menus. Vous pouvez y mettre du code qui sera exécuté quand l'utilisateur clique sur un élément, ou l'active avec le clavier.

Un gestionnaire oncommand peut être placé sur les boutons Rechercher et Annuler dans le dialogue de recherche de fichiers. Cliquer sur le bouton Rechercher devrait démarrer la recherche. Comme nous n'implémenterons pas cette partie, nous l'omettrons. Par contre, cliquer sur le bouton Annuler devrait fermer la fenêtre. Le code ci-dessous montre comment faire cela. Tant que nous y sommes, ajoutons le même code à l'item de menu Fermer.

<menuitem label="Fermer" accesskey="f" oncommand="window.close();"/>
...

<button id="cancel-button" label="Annuler"
    oncommand="window.close();"/>

Deux gestionnaires ont été ajoutés ici. Le gestionnaire oncommand a été ajouté à l'item de menu Fermer. En utilisant ce gestionnaire, l'utilisateur pourra fermer la fenêtre en cliquant sur l'item de menu ou en le sélectionnant avec le clavier. Le gestionnaire oncommand a été ajouté au bouton Annuler.

De manière similaire, nous pouvons réagir aux autres évènements de la souris et aux appuis de touches du clavier en utilisant les gestionnaires d'évènements de la souris et des touches. Si vous ne spécifiez pas de gestionnaire d'évènement pour un évènement particulier, l'élément le gèrera lui-même. C'est généralement ce que vous voulez qu'il se produise. La plupart des élément XUL auront leurs propres réactions aux évènements de la souris et du clavier. Par exemple, les menuitems réagiront à leurs touches d'accès et des popups apparaîtront au bon moment.

Modèle d'évènement

XUL utilise le même modèle d'évènement que décrit dans les Évènements DOM2. Brièvement, un évènement est envoyé en deux phases. Dans la phase de capture, un évènement comme un clic de la souris est d'abord envoyé au document puis descend dans la hiérarchie des éléments jusqu'à atteindre l'élément qui a déclenché l'évènement. La phase inverse (phase de "bubbling") intervient alors. L'évènement est renvoyé vers le haut de la hiérarchie tour à tour à chaque élément.

Sur son chemin, si l'évènement est géré par un élément, le traitement de l'élément s'arrête. Si cet élément ne gère pas l'évènement, cela continue avec le prochain élément, jusqu'à ce qu'un le gère. Si rien ne gère l'évènement, un traitement par défaut est effectué.

Cela signifie que vous n'êtes pas obligé de mettre le gestionnaire d'évènement sur l'élément sur lequel vous voulez réagir à l'évènement. Vous pouvez aussi le mettre sur n'importe quel élément parent au-dessus de l'élément. Par exemple, au lieu de mettre le gestionnaire d'évènement sur le menuitem, vous pourriez le mettre sur l'élément menu.

Un gestionnaire doit renvoyer true si l'élément a été géré ou false s'il n'a pas été géré. En renvoyant false, vous pouvez faire quelque chose mais le traitement par défaut sera effectué. Ce processus est similaire à la gestion des évènements HTML.

Vous pouvez obtenir l'élément à l'origine de l'évènement grâce à la propriété target de l'objet event. Par exemple, si vous ajoutez le gestionnaire d'évènement suivant à un élément window, une boîte d'alerte apparaîtra quand vous cliquerez sur un élément de la fenêtre. L'alerte affichera l'élément sur lequel vous avez cliqué.

<window
    onclick="alert(event.target.tagName); return false;"
    .
    .
    .
>

Vous pouvez aussi ajouter des gestionnaires d'évènements dynamiquement en utilisant la fonction addEventListener. Vous pouvez l'utiliser pour tout type d'élément et d'évènement. Elle prend trois paramètres : le type d'évènement, une fonction à exécuter quand l'évènement arrive et un booléen indiquant s'il faut capturer ou non.

Dans la prochaine section, nous allons voir l'utilisation du Document Object Model avec les éléments XUL.

Le dialogue de recherche de fichiers à ce stade : Source Voir