6.6 Mise à jour de commandes

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.

Dans cette section, nous verrons comment mettre à jour des commandes.

Appel des commandes

Si une commande a un attribut oncommand, vous pouvez simplement l'appeler en utilisant la méthode doCommand de la commande ou un élément qui lui est attaché. Pour d'autres commandes, vous aurez besoin de quelques lignes de codes supplémentaires. Vous devrez passer par ces étapes spéciales dans le cas où les commandes appelées sont implémentées par un contrôleur. Vous aurez aussi besoin de le faire dans le cas où vous créez votre propre menu de commandes, par exemple pour implémenter les commandes du menu d'édition de votre propre application.

Heureusement, le code spécial est assez simple. Tout ce que nous avons besoin de faire est d'obtenir le contrôleur demandé et d'appeler la commande. Une manière simple de le faire est la suivante :

var controller = document.commandDispatcher.getControllerForCommand("cmd_paste");
if (controller && controller.isCommandEnabled("cmd_paste"))
  controller.doCommand(command);
}

Le code ci-dessus recherche d'abord le contrôleur pour la commande 'cmd_paste' grâce au répartiteur de commandes. Puis, il teste si la commande est activée, et enfin exécute la commande utilisant la méthode doCommand du contrôleur. Notez que nous n'avons pas besoin de préciser l'élément ou le contrôleur à utiliser. Le répartiteur de commandes s'en charge. En outre, nous pourrions juste appeler doCommand sans vérifier si la commande est activée ou non, mais il vaut mieux le faire.

Le code ci-dessus est tellement générique qu'il pourrait être une fonction prenant une commande en argument et exécutant cette commande. Cette fonction pourrait être ainsi réutilisée pour toutes les commandes. En fait, c'est tellement commun que Mozilla inclut une bibliothèque qui ne fait que ça. Si vous incluez le script 'chrome://global/content/globalOverlay.js' dans un fichier XUL, vous pouvez appeler la méthode goDoCommand qui exécute la commande passée en argument. Le code pour cette fonction ne fait que quelques lignes, ainsi vous pourriez l'inclure directement dans votre code si pour certaines raisons vous ne souhaitez pas inclure la bibliothèque.

<script src="chrome://global/content/globalOverlay.js"/>

<command id="cmd_paste" oncommand="goDoCommand('cmd_paste');/>
<button label="Coller" command="cmd_paste"/>

L'exemple ci-dessus va implémenter un bouton pour « Coller ». Il est relié à la commande qui va appeler la commande du contrôleur concerné lorsqu'il est appelé. Le code ci-dessus est tout ce dont vous avez besoin pour implémenter la fonctionnalité de la commande Coller dans votre application. La seule autre chose dont vous avez besoin est de vous assurer que le statut de la commande Coller qui est activé, et donc du bouton, est mis à jour au bon moment, comme décrit ci-dessous.

Dispositifs de mise à jour de commande

Un dispositif de mise à jour de commande est un dispositif spécial de l'élément commandset qui lui permet de mettre à jour les statuts activés d'une ou plusieurs commandes lorsque certains événements se produisent. Vous devrez y pensez lorsqu'une commande est valide et lorsqu'elle ne l'est pas. De plus, vous devrez considérer quand l'état pourrait changer et quand les commandes devraient être mises à jour.

Par exemple, la commande « Coller » est valide lorsque le champ de saisie de texte a le focus et qu'il y a quelque chose dans le presse-papiers à coller. La commande deviendra active chaque fois que le champ de saisie aura le focus et lorsque le contenu du presse-papiers changera. Un dispositif de mise à jour de contenu surveillera ces situations et le code qui active et désactive les commandes pourra être exécuté selon les besoins.

Un simple dispositif de mise à jour de commandes ressemble à ceci :

<commandset id="updatePasteItem"
            commandupdater="true"
            events="focus"
            oncommandupdate="goUpdateCommand('cmd_paste');"/>

Un dispositif de mise à jour de commandes est indiqué en utilisant l'attribut commandupdater, qui devrait être déclaré à true. L'attribut events est utilisé pour lister les événements que le dispositif de mise à jour de commandes surveille. Vous pouvez spécifier de multiples événements en les séparant par des virgules. Dans l'exemple ci-dessus, le dispositif de mise à jour de commandes surveille les événements de focus. Il a pour effet de mettre à jour les commandes lorsqu'un élément reçoit le focus.

Lorsqu'un événement de focus se produit, le code dans l'attribut oncommandupdate est appelé. Dans l'exemple, la méthode goUpdateCommand, qui est une fonction provenant du script globalOverlay.js décrit plus tôt, est appelée. Elle va mettre à jour la commande et activer ou désactiver les items de boutons et de menus nécessaires. Le code qui est derrière est assez simple. Il appelle seulement le contrôleur nécessaire, appelle sa méthode isCommandEnabled, et enfin active ou désactive la commande. Si vous avez plusieurs commandes à mettre à jour, appelez la méthode goUpdateCommand une fois pour chaque commande.

Notez que le dispositif de mise à jour de commandes recevra les notifications de tous les événements de focus sur tous les éléments, même si d'autres gestionnaires d'événements répondent à l'événement. Un dispositif de mise à jour de commandes est par essence un gestionnaire global d'événements.

Les dispositifs de mise à jour de commandes disposent de plusieurs événements pouvant répondre à ceux qui sont listés ci-dessous. Il est également possible de créer le votre.

• focus : se produit lorsque l'élément qui a le focus change.
• select : se produit lorsque le texte sélectionné change.
• undo : se produit lorsque le tampon d'annulation change.
• clipboard : se produit lorsque le contenu du presse-papiers change.

L'exemple suivant montre le dispositif de mise à jour de commandes utilisé dans le navigateur Mozilla pour mettre à jour le menu d'édition de commandes. Les fonctions utilisées sont disponibles dans le script 'chrome://communicator/content/utilityOverlay.js'.

<commandset id="globalEditMenuItems"
            commandupdater="true"
            events="focus"
            oncommandupdate="goUpdateGlobalEditMenuItems()"/>
<commandset id="selectEditMenuItems"
            commandupdater="true"
            events="select"
            oncommandupdate="goUpdateSelectEditMenuItems()"/>
<commandset id="undoEditMenuItems"
            commandupdater="true"
            events="undo"
            oncommandupdate="goUpdateUndoEditMenuItems()"/>
<commandset id="clipboardEditMenuItems"
            commandupdater="true"
            events="clipboard"
            oncommandupdate="goUpdatePasteMenuItems()"/>

---

Ensuite, nous vous montrerons comment utiliser les observateurs.