12.2 Créer des boîtes de dialogues

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.

Une application XUL requiert souvent l'affichage de boîtes de dialogue. Cette section décrit comment les construire.

Création d'une boîte de dialogue

La fonction open() est utilisée pour ouvrir une fenêtre. Une fonction apparentée est openDialog(). Cette fonction a plusieurs différences importantes. Au lieu d'une fenêtre (window), elle affiche une boîte de dialogue (dialog), ce qui implique qu'elle demande quelque chose à l'utilisateur. Elle peut avoir des différences subtiles dans sa manière de fonctionner et d'apparaître à l'utilisateur suivant les différentes plateformes.

De plus, la fonction openDialog() peut prendre des arguments additionnels en plus des trois premiers habituels. Ces arguments sont passés à la nouvelle boîte de dialogue et placés dans un tableau stocké dans la propriété arguments de la nouvelle fenêtre. Vous pouvez passer autant d'arguments que nécessaire. C'est un moyen pratique de fournir des valeurs par défaut aux champs de la boîte de dialogue.

var somefile=document.getElementById('enterfile').value;

window.openDialog("chrome://findfile/content/showdetails.xul","showmore",
                  "chrome",somefile);

Dans cet exemple, la boîte de dialogue showdetails.xul sera affichée. L'argument somefile provenant d'un élément d'id enterfile lui est transmis. Dans un script utilisé par la boîte de dialogue, nous pouvons alors faire référence à l'argument en utilisant la propriété arguments de la fenêtre. Par exemple :

var fl=window.arguments[0];

document.getElementById('thefile').value=fl;

C'est un moyen efficace de passer des valeurs à la nouvelle fenêtre. Vous pouvez renvoyer des valeurs de la fenêtre ouverte vers la fenêtre originelle de deux manières. Première méthode : vous pouvez utiliser la propriété window.opener qui contient une référence à la fenêtre qui a ouvert la boîte de dialogue. Seconde méthode : vous pouvez passer une fonction ou un objet en argument, puis appeler la fonction ou modifier l'objet dans la boîte de dialogue ouverte.

Note : openDialog() nécessite un privilège UniversalBrowserWrite. Cela signifie que cette méthode ne fonctionnera pas sur des sites distants ; pour ces sites, utilisez la méthode window.open() à la place.

L'élément dialog

L'élément dialog doit être utilisé à la place de l'élément window lors de la création d'une boîte de dialogue. Il offre la possibilité de construire jusqu'à quatre boutons au bas de la boîte de dialogue, pour « OK », « Annuler », etc. Vous n'avez pas besoin d'inclure le code XUL pour chaque bouton mais vous devez fournir le code à exécuter quand l'utilisateur les presse. Ce mécanisme est nécessaire car les différentes plateformes ont un ordre d'affichage spécifique de ces boutons.

Exemple de boîte de dialogue

Exemple 11.2.1 : Source Voir

<?xml version="1.0" encoding="iso-8859-1"?>

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

<dialog id="donothing" title="Ne fait rien"
        xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
        buttons="accept,cancel"
        ondialogaccept="return doOK();"
        ondialogcancel="return doCancel();">

<script>
function doOK()
{
  alert("Vous avez appuyé sur OK !");
  return true;
}

function doCancel()
{
  alert("Vous avez appuyé sur Annuler !");
  return true;
}
</script>

<description value="Veuillez sélectionner un bouton"/>

</dialog>

Vous pouvez placer tous les éléments que vous souhaitez dans une boîte de dialogue. L'élément dialog a des attributs que les fenêtres n'ont pas. L'attribut buttons, par exemple, est utilisé pour spécifier quels boutons doivent apparaître dans la boîte de dialogue. Les valeurs suivantes peuvent être utilisées en les séparant par des virgules :

• accept - un bouton OK
• cancel - un bouton Annuler
• help - un bouton Aide
• disclosure - un bouton d'information, utilisé pour montrer plus d'informations.

Vous pouvez exécuter du code lors de l'appui des boutons en utilisant les attributs ondialogaccept, ondialogcancel, ondialoghelp et ondialogdisclosure. Si vous essayez l'exemple ci-dessus, vous remarquerez que la fonction doOK est appelée quand le bouton OK est pressé et que la fonction doCancel est appelée quand le bouton Annuler est pressé.

Les deux fonctions doOK et doCancel renvoient true, ce qui indique que la boîte de dialogue doit être fermée. Si la valeur false était renvoyée, la boîte de dialogue resterait ouverte. Ce fonctionnement pourrait être utilisé dans le cas où une valeur invalide serait entrée dans un champ de la boîte de dialogue.

Voici d'autres attributs utiles :

• buttonlabelaccept - libellé devant apparaître sur le bouton d'acceptation (par ex. Sauvegarder)
• buttonaccesskeyaccept - touche de raccourci pour le bouton d'acceptation (par ex. S)
• defaultButton - le bouton activé lorsque la touche Entrée est appuyée

Note : Les attributs label sont nécessaires pour les sites distants et ont probablement été omis dans les exemples précédents à cause du bug 224996.

Exemple de dialogue avec plus de fonctionnalités

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

<dialog id="myDialog" title="Mon dialogue"
        xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
        onload="window.sizeToContent();"
        buttons="accept,cancel"
        buttonlabelaccept="Choix favori"
        buttonaccesskeyaccept="S"
        ondialogaccept="return doSave();"
        buttonlabelcancel="Annuler"
        buttonaccesskeycancel="n"
        ondialogcancel="return doCancel();">

<script>
function doSave(){
 //faireTraitement()
 return true;
}
function doCancel(){
  return true;
}
</script>

<dialogheader title="Mon dialogue" description="Exemple de dialogue"/>
<groupbox flex="1">
  <caption label="Sélectionnez votre fruit préféré"/>
  <radio id="orange" label="Des oranges car elles sont juteuses"/>
  <radio id="violet" selected="true" label="Des frises à cause de leur couleur"/>
  <radio id="yellow" label="Des bananes car elles sont déjà emballées"/>
</groupbox>

</dialog>

Les éléments correspondants aux boutons sont accessibles en JavaScript par le script suivants :

// le bouton d'acceptation
var acceptButt = document.documentElement.getButton("accept")

Autres exemples

D'autres exemples sont disponibles dans Dialogues et invites.

---

Dans la prochaine section, nous allons voir comment ouvrir des boîtes de dialogue de sélection de fichiers.