6.1 Ajout de gestionnaires 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.

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

Utilisation de scripts

Pour rendre la boîte de dialogue de recherche de fichiers fonctionnelle, 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 écrirons ces scripts en utilisant des fonctions Javascript de la même manière qu'en HTML.

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 préférable de placer le code dans un fichier séparé. Votre fenêtre XUL se chargera un peu plus rapidement. Nous utiliserons alors l'attribut src pour lier un fichier de script externe.

<script src="findfile.js"/>

Nous pouvons inclure de multiples scripts dans un fichier XUL en utilisant de multiples balises script, chacune pointant vers un script différent. Nous pouvons utiliser des URLs relatives ou absolues. Par exemple, nous pouvons utiliser des URLs sous les formes suivantes :

<script src="findfile.js"/>
<script src="chrome://findfiles/content/help.js"/>
<script src="http://www.example.com/js/items.js"/>

Ce tutoriel n'a pas pour but de décrire comment écrire du JavaScript. C'est un sujet vaste et il existe déjà beaucoup de documentation le traitant.

Par défaut, la console JavaScript n'affiche que les erreurs provenant des contenus Web. Pour voir les erreurs JavaScript du chrome, il est nécessaire de modifier la préférence javascript.options.showInConsole à true. Vous pouvez également faire du débogage en modifiant la préférence javascript.options.strict. En la définissant à true, les erreurs causés par des codes non standard, mal écrits, ou syntaxiquement erronés seront affichés dans la console d'erreurs.

Réponse aux événements

Le script contiendra le code qui répondra aux différents événements déclenchés par l'utilisateur ou par d'autres situations. Il existe environ une trentaine d'événements pouvant être gérés de différentes manières. Un événement classique est le bouton de souris ou la touche pressée par l'utilisateur. Chaque élément XUL a la capacité de déclencher certains événements dans des situations différentes. Quelques déclenchements d'événements sont spécifiques à certains éléments.

Chaque événement a un nom, par exemple, mousemove est le nom de l'événement qui est déclenché quand l'utilisateur passe la souris au-dessus d'un élément d'interface utilisateur. XUL utilise le mécanisme d'événement défini par le DOM Events. Quand survient une action devant déclencher un événement, telle que le déplacement de la souris par l'utilisateur, un objet 'event' correspondant à ce type d'événement est créé. Des propriétés sont assignées à cet objet event telles que la position de la souris, la touche pressée, etc.

L'événement est ensuite envoyé au XUL par phases.

1. Dans la phase de capture, l'événement est d'abord envoyé à la fenêtre, puis au document, suivi par chaque ancêtre de l'élément XUL visé, jusqu'à ce qu'il l'atteigne.
2. Dans la phase de ciblage, l'événement est envoyé à l'élément XUL cible.
3. Pendant la phase de diffusion, l'événement est envoyé à chaque élément dans l'autre sens jusqu'à ce qu'il atteigne à nouveau la fenêtre.

Vous pouvez réagir à un événement pendant la phase de capture ou de diffusion. Une fois que l'événement a terminé de se propager, l'action correspondant au comportement natif de l'élément est déclenchée.

Par exemple, quand la souris passe sur un bouton inclus dans une boîte, un événement mousemove est généré et envoyé d'abord à la fenêtre, puis au document et ensuite à la boîte. Cela complète la phase de capture. Ensuite, l'événement mousemove est envoyé au bouton. Enfin la phase de diffusion se traduit par le renvoi de l'événement vers la boîte, puis le document et enfin la fenêtre. La phase de diffusion est par essence l'inverse de la phase de capture. Notez que certains événements ne passent pas par la phase de diffusion.

Vous pouvez attacher des scrutateurs à chaque élément pour être à l'écoute des événements pendant chaque étape de leur propagation. Étant donné qu'un simple événement est passé à tous les ancêtres, vous pouvez attacher un scrutateur à un élément spécifique ou à un élément supérieur dans la hiérarchie. Naturellement, un événement attaché à un élément parent recevra une notification de tous les éléments qu'il contient, alors qu'un événement attaché à un bouton recevra seulement des événements concernant ce bouton. C'est utile si vous désirez gérer plusieurs éléments avec un code identique ou similaire.

L'événement le plus utilisé est l'événement command. L'événement command est déclenché quand l'utilisateur active un élément, par exemple en pressant un bouton, en cochant une case ou en sélectionnant une entrée d'un menu. L'événement command est pratique car il gère automatiquement les différentes méthodes d'activation d'un élément. Par exemple, l'événement command se produira indifféremment si l'utilisateur utilise sa souris pour cliquer le bouton ou s'il presse la touche Entrée.

Il y a deux manières d'attacher un scrutateur d'événement à un élément. Premièrement, en utilisant un attribut avec un script comme valeur. Deuxièmement, en appelant la méthode addEventListener d'un élément. La première manière peut seulement gérer les événements en phase de diffusion mais est plus simple à écrire. La seconde peut gérer les événements sur chaque phase et peut aussi être utilisée pour attacher plusieurs scrutateurs pour un événement à un élément. L'utilisation de la « forme par attribut » est une manière plus commune pour la plupart des événements.

Scrutateurs d'événements par attributs

Pour utiliser la forme par attribut, placez un attribut sur un élément à l'endroit que vous voulez, son nom devra être le nom de l'événement précédé par le mot « on ». Par exemple, l'attribut correspondant à l'événement command est oncommand. La valeur de l'attribut devra être le code à exécuter quand l'événement se produira. Typiquement, ce code sera court et appellera une fonction définie dans un script séparé. Voici un exemple de réponse lorsqu'un bouton est pressé :

Exemple 6.1.1 : Source Voir

<button label="OK" oncommand="alert('Le bouton a été pressé !');"/>

Puisque l'événement command va se diffuser, il est également possible de placer le scrutateur d'événement sur un élément conteneur. Dans l'exemple ci-dessous, le scrutateur a été placé sur une boîte et il recevra les événements pour tous ses éléments.

Exemple 6.1.2 : Source Voir

<vbox oncommand="alert(event.target.tagName);">
  <button label="OK"/>
  <checkbox label="Voir les images"/>
</vbox>

Dans cet exemple, l'événement command va se diffuser du bouton ou de la case à cocher jusqu'à la boîte, où il sera traité. Si un second scrutateur (l'attribut oncommand) était placé sur le bouton, son code serait appelé en premier, suivi par le gestionnaire de la boîte. L'objet event est transmis aux gestionnaires d'événements comme un argument implicite nommé event. Il est utilisé pour obtenir des informations spécifiques à propos de l'événement. Une des plus utilisées est la propriété target (cible) de l'événement, qui cible l'élément à partir duquel l'événement s'est produit. Dans l'exemple, nous affichons une alerte contenant le nom de l'élément cible. La cible est très utile lors de l'utilisation d'un événement en diffusion dans le cas où vous auriez une série de boutons gérée par un même script.

Vous noterez que la syntaxe de l'attribut est identique à celle utilisée pour les événements dans les documents HTML. En fait, HTML et XUL partagent le même mécanisme d'événement. Une différence importante est que l'événement click (ou l'attribut onclick) est utilisé en HTML pour répondre aux boutons, alors qu'on devra utiliser l'événement command en XUL. XUL possède un événement click, mais il répond uniquement aux clics de souris, pas à l'utilisation du clavier. Ainsi, l'événement click devra être évité en XUL, sauf si vous avez une raison d'avoir un élément uniquement géré avec la souris. De plus, tandis que l'événement 'command' ne sera pas envoyé si un élément est désactivé, l'événement 'click' sera envoyé sans tenir compte de l'état activé ou non de l'élément.

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

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

Scrutateurs d'événements DOM

La seconde façon d'ajouter un gestionnaire d'événement est d'appeler la méthode addEventListener d'un élément. Celle-ci vous permet d'attacher dynamiquement un scrutateur d'événement et de scruter les événements durant la phase de capture. La syntaxe est la suivante :

Exemple 6.1.3 : Source Voir

<button id="okbutton" label="OK"/>

<script>
function buttonPressed(event) {
  alert('Le bouton a été pressé !');
}

var button = document.getElementById("okbutton");
button.addEventListener('command', buttonPressed, true);
</script>

La fonction getElementById() retourne l'élément ayant un identifiant id, dans notre cas, le bouton. La fonction addEventListener() est appelée pour ajouter un nouveau scrutateur d'événement en phase de capture. Le premier argument est le nom de l'événement à scruter. Le deuxième argument est la fonction du scrutateur d'événement qui sera appelée quand l'événement se produira. Enfin, le dernier argument devra être true pour les scrutateurs en phase de capture. Vous pouvez également scruter durant la phase de diffusion en donnant la valeur false au dernier argument. La fonction scrutateur d'événement passée comme deuxième argument devra avoir un argument, l'objet 'event', comme vous le voyez dans la déclaration de la fonction buttonPressed ci-dessus.

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

Dans la prochaine section, nous aborderons plus en détail l'objet event.