7.8 Mise à jour de commandes

Écrit par Neil Deakin. Traduit par Nadine Henry (20/07/04).
Page originale : http://www.xulplanet.com/tutorials/xultu/commandupdate.html

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 additionnelles. Vous devrez passer par ces étapes spéciales dans le cas où les commandes appelées sont implémentées par un contrôleur. De plus, vous aurez 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 dans 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 vérifie pour voir 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 se charge de cette partie. En outre, nous pourrions juste appeler doCommand sans vérifier si la commande est activée ou non, bien que nous ne le devrions probablement pas.

Le code ci-dessus est tellement générique qu'il peut être une fonction qui prenne en paramètre un argument et exécute cette commande. Cette fonction pourrait être ainsi réutilisée pour toutes les commandes. En fait, c'est tellement commun que Mozilla inclue 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 n'est long que de quelques lignes, ainsi vous pourriez l'inclure directement dans votre code si pour certaines raisons vous ne voudriez 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 passent. 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 la zone de texte a le focus et qu'il y a quelque chose dans le presse-papier à coller. La commande deviendra active chaque fois que la zone de texte aura le focus et lorsque le contenu du presse-papier 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. Cela 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. Essentiellement, un dispositif de mise à jour de commandes est comme un gestionnaire global d'évènement.

Les dispositifs de mise à jour de commandes ont un nombre d'évènements qui peuvent répondre à ceux qui sont listés ci-dessous. Aussi est-il possible de créer le vôtre.

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-papier 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()"/>

Prochainement, nous vous montrerons comment utiliser les observateurs.