Création de boutons de barre d'outils

Un article de MDC.

Cet article explique comment ajouter un bouton à la barre d'outils d'une application (comme Firefox, Thunderbird, Nvu, etc.) en utilisant la technique des overlays. Cet article s'adresse aux développeurs d'extensions connaissant les bases de XUL et CSS.

Le lecteur est supposé être familiarisé avec les bases de la création d'extensions pour Firefox et avoir fait fonctionner sa première extension. Un tutoriel vous guidant à travers le processus depuis le début est également disponible.

[modifier] Création d'un overlay

Avant tout, vous devez créer un overlay pour le document qui contient la barre d'outils que vous souhaitez améliorer. Le but de ce tutoriel n'est pas d'expliquer les overlays — vous pouvez trouver de précieuses informations à ce sujet dans le Tutoriel XUL.

Pour créer un overlay sur un document, vous devez connaître son URI. Vous trouverez en bas de cette page la liste des documents où les overlays sont créés le plus fréquemment.

[modifier] Ajout d'un bouton à la barre d'outils

Les applications toolkit ont une barre d'outils personnalisable. La méthode la plus pratique dans une extension est donc d'ajouter les boutons de la barre d'outils dans la palette plutôt que de les ajouter directement dans la barre d'outils. Cette dernière option est possible mais peu recommandée et plus difficile à mettre en œuvre.

L'ajout d'un bouton à la palette de la barre d'outils est très simple. Il suffit d'ajouter ce code à l'overlay :

 
<toolbarpalette id="BrowserToolbarPalette">
  <toolbarbutton id="myextension-button" class="toolbarbutton-1"
    label="&toolbarbutton.label;" tooltiptext="&toolbarbutton.tooltip;"
    oncommand="MyExtension.onToolbarButtonCommand(event);"/>
</toolbarpalette>

Notes :

• L'id de palette (BrowserToolbarPalette dans l'exemple) dépend de la fenêtre dans laquelle vous désirez ajouter un bouton. Voir ci-dessous la liste des ID de palette les plus communément utilisées.
• class="toolbarbutton-1" permet au bouton de la barre d'outils d'apparaitre correctement en mode icône et texte.
• Il faut également indiquer la commande qui doit être exécutée dans l'attribut oncommand. Si vous avez besoin de prendre en charge le clic du milieu (roulette), vous devez ajouter la prise en charge onclick et vérifier event.button.

onclick: function(event) {
  switch(event.button) {
    case 0:
      // Clic gauche
      break;
    case 1:
      // Clic milieu
      break;
    case 2:
      // Clic droit
      break;
  }
}

Pour ajouter plus de boutons, il suffit de mettre d'autres éléments <toolbarbutton> dans l'élément <toolbarpalette>. Placez les éléments autres que des boutons de barre d'outils dans un élément <toolbaritem>.

[modifier] Application d'un style sur le bouton

Le plus souvent, les boutons ont des icônes. Pour attacher une image à un bouton, on utilise une des fonctionnalités standard de Mozilla pour le personnaliser. Si vous n'êtes pas familier avec celle-ci, lisez la section skinning de l'excellent Toolbar Tutorial de Jonah Bishop (en anglais). Bien que l'article décrive la création d'une barre d'outils complètement personnalisée plutôt que d'un simple bouton, il contient une très bonne explication des techniques que nous allons employer.

[modifier] Taille des icônes

Les boutons pour la barre d'outils peuvent avoir deux tailles différentes — grande et petite. Ceci implique que vous allez devoir fournir de icônes différentes pour chaque bouton de votre barre d'outils. Vous trouverez ci-dessous les dimensions des icônes dans diverses applications (n'hésitez pas à en ajouter d'autres) :

[modifier] Feuille de style

Pour paramétrer l'image de votre bouton de barre d'outils, utilisez les règles CSS suivantes :

/*  skin/toolbar-button.css  */

#myextension-button {
  list-style-image: url("chrome://myextension/skin/btn_large.png");
}

toolbar[iconsize="small"] #myextension-button {
  list-style-image: url("chrome://myextension/skin/btn_small.png");
}

[modifier] Appliquer la feuille de style

Souvenez-vous d'associer la feuille de style que vous avez créée à la fois à l'overlay et à la fenêtre de personnalisation de la barre d'outils.

<?xml-stylesheet href="chrome://myextension/skin/toolbar-button.css" type="text/css"?>

Pour l'associer à la fenêtre de personnalisation (chrome://global/content/customizeToolbar.xul), vous pouvez utiliser skin/contents.rdf, comme ceci :

<?xml version="1.0"?>
<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:chrome="http://www.mozilla.org/rdf/chrome#">

  <Seq about="urn:mozilla:skin:root">
    <li resource="urn:mozilla:skin:classic/1.0"/>
  </Seq>

  <Description about="urn:mozilla:skin:classic/1.0">
    <chrome:packages>
      <Seq about="urn:mozilla:skin:classic/1.0:packages">
        <li resource="urn:mozilla:skin:classic/1.0:myextension"/>
      </Seq>
    </chrome:packages>
  </Description>

  <Seq about="urn:mozilla:stylesheets">
    <li resource="chrome://global/content/customizeToolbar.xul"/>
  </Seq>

  <Seq about="chrome://global/content/customizeToolbar.xul">
    <li>chrome://myextension/skin/toolbar-button.css</li>
  </Seq>
</RDF>

Les extensions pour Firefox et Thunderbird 1.5 doivent plutôt utiliser quelque chose de semblable à ceci dans le chrome.manifest :

skin	myextension	classic/1.0	chrome/skin/
style	chrome://global/content/customizeToolbar.xul	chrome://myextension/skin/toolbar-button.css

[modifier] Erreurs fréquentes

Voici une liste des erreurs fréquemment commises par les auteurs d'extensions, avec leurs symptômes et leurs solutions.

Problème : un assemblage de tous les boutons standards est dessiné à la place de votre propre icône.

Cause : feuille de style mal formée ou non appliquée.

Solution : vérifiez votre feuille de style, vérifiez si votre content.rdf (ou chrome.manifest) est correct, assurez-vous que vous n'avez pas oublié d'appliquer la feuille de style à customizeToolbar.xul.

[modifier] Liste des fenêtres où les overlays de la barre d'outils sont fréquents

   <td class="header">Taille de la grande icône</th>
   <td class="header">Taille de la petite icône</th>

[modifier] Plus d'informations

• La référence XulPlanet.com : <toolbarbutton>, <toolbaritem>.
• How to adjust toolbarbutton's label position
• Une discussion sur le forum de MozillaZine (en) à propos de l'ajout d'une entrée dans la barre d'outils (et pas seulement dans la palette de personnalisation) juste après l'installation de l'extension. Notez qu'il n'est pas recommandé de le faire.
• Il existe une autre page sur MDC avec des information sur l'ajout de boutons à diverses fenêtres dans SeaMonkey. On peut également y trouver des informations utiles sur les overlays pour ChatZilla.