Dialogues et invites

Cette page vient d'être traduite, mais elle a besoin d'un relecteur différent du traducteur. Pensez également à toujours vérifier le contenu avec sa toute dernière version en anglais.
(en cours de relecture)

Cette page décrit quelques extraits de codes pour afficher et piloter des boîtes de dialogues. Consultez Travailler avec des fenêtres dans le chrome pour une information préalable et des exemples.

Description des fenêtres de dialogues

Les boîtes de dialogues sous Mozilla

Pour créer une boîte de dialogue dans votre application, utilisez <dialog> (plutôt que l'habituel <window>) comme élément racine de votre fichier XUL. Cet élément va :

  • gérer quelques événements clavier (ENTRÉE/ESC et d'autres), ce qui est bon en terme d'accessibilité.
  • ajouter des boutons OK et ANNULER avec l'apparence de ceux de votre OS (tout en restant extrêmement personnalisable, vois ci-dessous).

Code d'une simple boîte de dialogue

Le code XUL suivant définit une simple boîte de dialogue avec deux boutons, OK et ANNULER (l'attribut buttons="accept,cancel" sur l'élément dialog).

<?xml version="1.0"?>
<?xml-stylesheet href="chrome://global/skin/global.css" type="text/css"?>

<dialog xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
	id="..." title="..."
	buttons="accept,cancel"
	ondialogaccept="return onAccept();"
	ondialogcancel="return onCancel();">

<script src="chrome://..."/>

<!-- Contenu -->

</dialog>

Vous devez implémenter les fonctions onAccept et onCancel dans votre script. Si elles retournent autre chose que false, la boîte de dialogue se fermera.

Les boutons dans <dialog>

Prédéfinis

Il existe six types de boutons que vous pouvez utiliser dans l'attribut buttons de <dialog> :

  • accept — bouton OK.
  • cancel — bouton Annuler.
  • disclosure — bouton Plus d'infos.
  • help — bouton Aide (ne fonctionne pas dans Thunderbird 1.0 )
  • extra1, extra2 — deux boutons sans libellés prédéfinis ni significations. extra2 est positionné à gauche de la boîte de dialogue (par défaut).

Vous pouvez définir pour chacun de ces boutons leur libellé, leur touche de raccourci et leur gestionnaire oncommand en ajoutant des attributs buttonlabel<nomdubouton>, buttonaccesskey<nomdubouton> et ondialog<nomdubouton> sur l'élément dialog. Par exemple, pour ajouter un bouton Appliquer sur votre boîte de dialogue, utilisez le code suivant :

<dialog xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul" 
  id="..."
  buttons="accept,cancel,extra1"
  ondialogaccept="onAccept();"
  ondialogextra1="onApply();"
  buttonlabelextra1="Appliquer"
  buttonaccesskeyextra1="A">

<!-- Contenu -->
</dialog>

Vous pouvez également obtenir l'objet élément de n'importe quels boutons avec gDialog.getButton(dlgtype);, où gDialog représente l'élément <dialog> et dlgtype est l'un des six types de boutons listés ci-dessus.

Explicites

Si vous n'êtes pas satisfait de la mise en page des boutons prédéfinis dans dialog, vous pouvez placer explicitement des éléments button dans votre fichier XUL et y mettre des attributs dlgtype. Les valeurs autorisées pour dlgtype sont les six types de boutons listés ci-dessus.

Assurez vous d'utiliser des attributs ondialog* sur l'élément dialog plutôt que de mettre des oncommand sur les boutons avec l'attribut dlgtype, car oncommand n'est exécuté que lorsque le bouton est pressé, tandis que les gestionnaires ondialog* sont exécutés aussi avec le clavier et d'autres événements.

Exemple :

<?xml version="1.0"?>
<?xml-stylesheet href="chrome://global/skin/" type="text/css"?>

<dialog xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
        ondialogaccept="alert("ok !");">
<hbox>
  <label value="Hey !"/>

  <spacer flex="1"/>
  <vbox>
    <button dlgtype="accept"/>
    <button dlgtype="cancel"/>
  </vbox>
</hbox>
</dialog>
Bouton par défaut

Firefox 1.5 a introduit un attribut et une propriété defaultButton sur l'élément <dialog> . Les valeurs possibles pour l'attribut sont les noms des boutons listés ci-dessus, et la valeur par défaut est "accept" pour une compatibilité avec les versions antérieures.

Utilisation de <dialogheader>

Vous pouvez mettre un élément dialogheader pour ajouter un entête à la fenêtre. Pour avoir une idée de ce à quoi il ressemble, ouvrez la boîte de dialogue des Options (ou Préférences) dans Firefox ou Thunderbird (seulement les versions 1). L'entête à droite de la section des boutons est créé avec <dialogheader> : NdT : avec FF1.5, les options ont été modifiées par prefpane, donc la vo me semble obsolète

<dialogheader title="Général" description="blabla"/>

Notez d'utiliser cet élément uniquement dans un <dialog>, sinon il n'aura pas un style correct (bien qu'il semble fonctionner aussi dans <window>).

Liens

Passage d'arguments et affichage d'une boîte de dialogue

Le code suivant montre comment transmettre des arguments personnalisés à une boîte de dialogue, leur traitement, et le retour des arguments modifiés par l'utilisateur au script appelant. Voici le code ouvrant la boîte de dialogue nommée mydialog.xul et lui transmettant des arguments :

var params = {inn:{name:"foo", description:"bar", enabled:true}, out:null};       
  window.openDialog("chrome://myext/content/mydialog.xul", "",
    "chrome, dialog, modal, resizable=yes", params).focus();
  if (params.out) {
    // L'utilisateur a cliqué sur OK. Les arguments ont été modifiés
    // et peuvent servir à un traitement
  }
  else {
    // L'utilisateur a cliqué sur Annuler. Habituellement, rien à faire.
  }

mydialog.xul:

<dialog
  xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
  id="myDialogId"
  title="Ma boîte de dialogue"
  ondialogaccept="return onOK();"
  onload="onLoad();"
  persist="screenX screenY width height"
  windowtype="myDialogWindowType">

  <script type="application/x-javascript" src="chrome://myext/content/mydialog.js"/>
  <grid>
    <columns><column/><column/></columns>
    <rows>
      <row align="center"><label value="Nom :"/><textbox id="name"/></row>
      <row align="center"><label value="Description :"/><textbox id="description"/></row>
      <row align="center"><spacer/><checkbox id="enabled" label="Cochez pour activer"/></row>
    </rows>
  </grid>
</dialog>

mydialog.js:

// Appel uniquement lorsque la boîte de dialogue s'affiche
function onLoad() {
  // Utiliser les arguments transmis par le script appelant
  document.getElementById("name").value = window.arguments[0].inn.name;
  document.getElementById("description").value = window.arguments[0].inn.description;
  document.getElementById("enabled").checked = window.arguments[0].inn.enabled;
}

// Appel uniquement si et seulement si l'utilisateur clique sur OK
function onOK() {
   // Retourne les arguments modifiés.
   // Noter que si l'utilisateur clique sur Annuler,
   // window.arguments[0].out contient null car cette fonction n'est jamais appelée.
   window.arguments[0].out = {name:document.getElementById("name").value,
        description:document.getElementById("description").value,    
        enabled:document.getElementById("enabled").checked};
   return true;
}

Consultez également Passing parameter to a dialog and getting return values from it (en).

Affichage de la boîte de dialogue standard de sélection de fichiers et répertoires

nsIFilePicker

Invites et service prompt

Maintenant que vous maîtrisez les boîtes de dialogue, examinons les invites. Les invites diffèrent des boîtes de dialogue dans le sens qu'elle ne nécessite pas de XUL personnalisé. À cause de cela, elles sont moins personnalisables. La plupart des développeurs Web sont familiers avec la fonction alert() :

Image:AlertHelloWorld.png

C'est l'exemple de base pour une invite.

L'interface XPCOM nsIPromptService est disponible en C++ et en code JavaScript chrome (pas au JS des pages Web) pour fournir des méthodes d'affichage de quelques boîtes de dialogue simples.

Pour les boîtes de sélection de fichiers et répertoires, consultez nsIFilePicker.

nsIPromptService dispose de 9 fonctions et de quelques constantes qu'il est important de comprendre. Cet article contient des explications pour quelque unes, et des exemples pour chacune d'elles.

Récupération de nsIPromptService

Avant toutes choses, vous devez récupérer le service d'invite qui vous permettra d'afficher les messages. Pour cela, utilisez le code suivant :

var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);

Méthodes nsIPromptService

alert()

alert() est la fonction la plus simple qui affiche une boîte contenant un titre et un message spécifiés. Par exemple :

var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);
prompts.alert(window, "Titre de la fenêtre", "Bonjour !");

Comme pour les autres méthodes de nsIPromptService, le premier paramètre est la fenêtre parente au sens de nsIWindowWatcher.openWindow. Vous pouvez mettre null, et dans ce cas la fenêtre parente sera nsIWindowWatcher.activeWindow (la fenêtre active).

alertCheck()

alertCheck() va afficher une boîte contenant un titre, un texte et une case à cocher spécifiés. La case à cocher peut être une option « Ne plus afficher se message » ou quelque chose de similaire.

var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);
check = {value: false}; // valeur par défaut
prompts.alertCheck(window, "Titre de la fenêtre", "Vous avez été prévenu", 
                   "Ne plus me demander", check);
// faire quelque chose avec check.value;

Notez comment est récupéré l'état de la case à cocher. La fonction modifie le membre value de l'objet check, donc le résultat s'obtient en lisant check.value. Il s'agit de la manière standard de récupérer des paramètres passés en référence à un composant XPCOM.

confirm() et confirmCheck()

confirm() est également simple. Il affiche une boîte de dialogue avec un titre, un texte spécifiés et deux boutons - OK et Annuler.

var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);
var result = prompts.confirm(window, "Titre", "Voulez-vous quitter ?");

Voici après un exemple pour afficher un message de confirmation avec une case à cocher. C'est une méthode hybride entre confirm() et alertCheck() donc il ne devrait pas être difficile de la comprendre sans plus de commentaires.

var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);
var check = {value: false};
var result = prompts.confirmCheck(window, "Title", "Do you want to quit?", 
                                  "Do not ask me again", check);
// faire quelque chose avec check.value / result
prompt()

prompt() est très important et utile dans de nombreux cas, car il permet à l'utilisateur saisir du texte. Plutôt que de créer une boîte de dialogue XUL ou d'ajouter d'autres champs de saisie, il vous suffit d'appeler une fonction prompt. Comme vous pouvez le voir, les quelques premiers arguments sont similaires aux autres fonctions à l'exception d'un objet supplémentaire. Cet objet contient la valeur par défaut avec l'appel de la fonction et sa nouveau valeur après.

var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);
var input = {value: "valeur par défaut"};
var check = {value: false};
result = prompts.prompt(window, "Titre", "Quel est ton nom ?", input, "Ne plus de la demander", check);
// input.value contient la chaîne de caractères saisie par l'utilisateur
// check.value indique l'état de la case à cocher
// result - contient true si l'utilisateur a cliqué sur OK
promptPassword() et promptUsernameAndPassword()

Voici dessous les autres versions d'invites, promptPassword() avec un champ de saisie de mot de passe, et promptUsernameAndPassword() avec un nom d'utilisateur et mot de passe.

//promptPassword
var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);
input = {value:"motdepasse"};
check = {value:false};
okorcancel = prompts.promptPassword(window, 'titre', 'Texte', input, 'Vérifie ?', check);
return input.value;
return check.value;
return okorcancel;

//promptUsernameAndPassword
var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);
username = {value:"moi"};
password = {value:"motdepasse"};
check = {value:false};
okorcancel = prompts.promptUsernameAndPassword(window, 'titre', 'Texte', username, password, 'Vérifie ?', check);
return username.value;
return password.value;
return check.value;
return okorcancel;
confirmEx()
var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);
var check = {value: false};
var flags = 0;
var button = prompts.confirmEx(window, "Titre de la fenêtre", "Texte", flags, 
             "Bouton 0", "Bouton 1", "Bouton 2", "Libellé de la case à cocher", check);
// |check.value| indique si la case à été ou non cochée
// |button| indique quel bouton a été cliqué

confirmEx() est prévu pour être personnalisable selon vos propres messages. Il peut afficher une boîte de dialogue contenant jusqu'à 3 boutons avec une variété de libellés prédéfinis (localisés si nécessaire) ou spécifiés par votre code, et une case à cocher si vous le souhaitez. Si vous ne voulez pas que la case à cocher s'affiche, mettez simplement null dans le huitième paramètre (le libellé de la case à cocher).

flags représente une série d'options qui indique quels sont les boutons que la boîte de dialogue doit afficher. Chaque bouton est défini comme la multiplication du drapeau d'un bouton_titre avec le drapeau d'un bouton_position :

Drapeaux bouton_position Drapeaux bouton_titre
BUTTON_POS_0
BUTTON_POS_1
BUTTON_POS_2
BUTTON_TITLE_OK
BUTTON_TITLE_CANCEL
BUTTON_TITLE_YES
BUTTON_TITLE_NO
BUTTON_TITLE_SAVE
BUTTON_TITLE_DONT_SAVE
BUTTON_TITLE_REVERT
BUTTON_TITLE_IS_STRING

Les boutons ne peuvent utiliser que l'un des titres prédéfinis. Cependant, si le drapeau BUTTON_TITLE_IS_STRING est spécifié pour un bouton, alors la chaîne de caractères passée en paramètre pour ce bouton sera utilisée.

flags est composé de la somme des valeur des boutons.

L'ordre d'apparition des boutons dépend de la plateforme. Bouton 0 est sélectionné par défaut, à moins qu'un drapeau définissant le bouton par défaut ne soit ajouté à flags :

Drapeaux bouton par défaut
BUTTON_POS_0_DEFAULT
BUTTON_POS_1_DEFAULT
BUTTON_POS_2_DEFAULT

Par exemple, tel que flags est défini ci-après, la boîte de dialogue aura un bouton Sauvegarder, un bouton Annuler et un troisième bouton dont le titre aura la valeur du septième argument de confirmEx() ("Bouton 2" dans l'extrait ci-dessus).

var flags = prompts.BUTTON_TITLE_SAVE      * prompts.BUTTON_POS_0 +
            prompts.BUTTON_TITLE_CANCEL    * prompts.BUTTON_POS_1 +
            prompts.BUTTON_TITLE_IS_STRING * prompts.BUTTON_POS_2;

En définissant flags avec les valeurs STD_OK_CANCEL_BUTTONS ou STD_YES_NO_BUTTONS, vous obtenez des modèles rapides de boutons OK/Annuler ou Oui/Non.

select()

select() affiche une boîte de dialogue avec une liste et des boutons OK/Annuler. La liste contient des options spécifiées, et l'utilisateur peut en sélectionner une exactement. selected.value contient l'index de l'item sélectionné de la liste par l'utilisateur et vous obtiendrez sa valeur avec list[selected.value]. Le quatrième paramètre est le nombre d'entrée à afficher dans la liste, et il doit avoir une valeur inférieure ou égale au nombre d'items du tableau list. S'il est inférieur alors seuls les items jusqu'à cet index seront affichés dans la liste.

var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);
var list = ["moi", "internet", "firefox", "xul", "entrée stupide", "plus d'idées"]
var selected = {};
var ok = prompts.select(window, "Titre de la fenêtre", "Message", 
                        list.length, list, selected);
// selected.value contient l'index
// |ok| indique lequel des boutons OK ou Annuler a été pressé
Version originale

La version originale de ce tutoriel est disponible ici.

Détails

nsIPromptService

 

Pièces jointes

Fichier Taille Date Joint par
AlertHelloWorld.png
4432 octets 2006-11-14 12:15:43 Chbok
pluralForm-checker.0.3.png
82572 octets 2008-04-12 22:23:31 BenoitL

Étiquettes et contributeurs liés au document

Contributeurs ayant participé à cette page : VincentN, cyril17, Chbok, fscholz, Mgjbot
Dernière mise à jour par : fscholz,