--- title: nsIPromptService slug: nsIPromptService tags: - Traduction_à_relire translation_of: Mozilla/Tech/XPCOM/Reference/Interface/nsIPromptService ---
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.

Résumé

nsIPromptService peut être utilisé pour afficher de simples boîtes de dialogue. Ses méthodes devrait être utilisées de préférence à la place de window.alert(), window.confirm(), et des autres fonctions similaires du DOM.

Il est possible de définir les touches de raccourcis pour les boutons en insérant une esperluette ("&") devant le caractère correspondant. Si vous souhaitez insérer cette esperluette directement dans le texte du bouton (c'est-à-dire dans la valeur de l'attribut label, sans utiliser de déclaration d'entité XML), utilisez-en deux ("&&").

Certaines des méthodes de cette interface utilisent des paramètres en entrée/sortie. En C++, les paramètres en sortie sont représentés par des pointeurs de pointeurs (void**). En JavaScript, ce type de paramètre nécessite plus de travail car vous ne pouvez directement récupérer des paramètres en sortie. Vous devez les englober dans un objet. Cet objet peut être vide ou bien comporter un attribut value dont la valeur correspond au type du paramètre en sortie.
Pour de plus amples informations sur les paramètres en sortie en JavaScript, voir Working with out parameters.
embedding/components/windowwatcher/public/nsIPromptService.idlScriptable
Please add a summary to this article.
  Last changed in Gecko 1.7.5

Hérite de : nsISupports

Implémenté par : @mozilla.org/embedcomp/prompt-service;1. Pour créer une instance, faire comme suit :

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

Aperçu des méthodes

void alert(in nsIDOMWindow aParent, in wstring aDialogTitle, in wstring aText);
void alertCheck(in nsIDOMWindow aParent, in wstring aDialogTitle,
                in wstring aText, in wstring aCheckMsg, inout boolean aCheckState);
boolean confirm(in nsIDOMWindow aParent, in wstring aDialogTitle, in wstring aText);
boolean confirmCheck(in nsIDOMWindow aParent, in wstring aDialogTitle, in wstring aText,
                     in wstring aCheckMsg, inout boolean aCheckState);
PRInt32 confirmEx(in nsIDOMWindow aParent,in wstring aDialogTitle,in wstring aText,
                  in unsigned long aButtonFlags,in wstring aButton0Title,
                  in wstring aButton1Title,in wstring aButton2Title,in wstring aCheckMsg,
                  inout boolean aCheckState);
boolean prompt(in nsIDOMWindow aParent, in wstring aDialogTitle, in wstring aText,
               inout wstring aValue, in wstring aCheckMsg, inout boolean aCheckState);
boolean promptUsernameAndPassword(in nsIDOMWindow aParent, in wstring aDialogTitle,
                                  in wstring aText, inout wstring aUsername,
                                  inout wstring aPassword, in wstring aCheckMsg,
                                  inout boolean aCheckState);
boolean promptPassword(in nsIDOMWindow aParent, in wstring aDialogTitle, in wstring aText,
                       inout wstring aPassword, in wstring aCheckMsg, inout boolean aCheckState);
boolean select(in nsIDOMWindow aParent, in wstring aDialogTitle, in wstring aText,
               in  PRUint32 aCount, [array, size_is(aCount)] in wstring aSelectList,
               out long aOutSelection);

Constantes

Les drapeaux décris ci-dessous sont combinés pour former le paramètre aButtonFlags passé à la méthode confirmEx(). Tous les drapeaux sont des constantes de type unsigned long et sont accessibles via Components.interfaces.nsIPromptService.flagname en JavaScript et nsIPromptService::flagname en C++.

Drapeaux de position de bouton

Constante Valeur Description
BUTTON_POS_0 1
BUTTON_POS_1 256
BUTTON_POS_2 65536

Drapeaux de titre de bouton 

Ces drapeaux sont utilisés conjointement avec les drapeaux de position pour modifier les textes des boutons de l'invite de commande.

Constante Valeur Description
BUTTON_TITLE_OK 1
BUTTON_TITLE_CANCEL 2
BUTTON_TITLE_YES 3
BUTTON_TITLE_NO 4
BUTTON_TITLE_SAVE 5
BUTTON_TITLE_DONT_SAVE 6
BUTTON_TITLE_REVERT 7
BUTTON_TITLE_IS_STRING 127

Drapeaux de bouton par défaut

Ces drapeaux sont utilisés pour spécifier le bouton par défaut.

Constante Valeur Description
BUTTON_POS_0_DEFAULT 0
BUTTON_POS_1_DEFAULT 16777216
BUTTON_POS_2_DEFAULT 33554432

BUTTON_DELAY_ENABLE

Le drapeau BUTTON_DELAY_ENABLE désactive les boutons. Ils sont activés après un certaine durée. Son interprétation peut varier, puisque son seul intérêt est de s'assurer que l'utilisateur ne ferme pas trop rapidement une boîte de dialogue renseignant sur des informations sensibles (avertissement concernant la sécurité etc.). À proprement parlé, il peut être ignoré.

Un délai peut être utile non seulement pour donner plus de temps de réflexion à l'utilisateur avant d'agir, mais également comme mesure de sécurité contre les sites internet qui créent intentionnellement une situation de compétition. Par exemple, un invite de commande affichant un message d'avertissement concernant la sécurité est affiché de manière inattendue et le bouton de validation est actionné involontairement.

Constante Valeur
BUTTON_DELAY_ENABLE 67108864

Situation de compétition dans un circuit logique. ∆t1 and ∆t2 représentent les délais de propagation des éléments logiques. Lorsque la valeur en entrée (A) est modifiée, le circuit produit en sortie in pic d'une durée ∆t1.

Drapeaux de boutons standards

Constante Valeur Description
STD_OK_CANCEL_BUTTONS 513

 boutons OK/Annuler.

(BUTTON_TITLE_OK *BUTTON_POS_0) +(BUTTON_TITLE_CANCEL * BUTTON_POS_1)
STD_YES_NO_BUTTONS 1027

 Boutons Oui/Non.

(BUTTON_TITLE_YES *BUTTON_POS_0) +(BUTTON_TITLE_NO * BUTTON_POS_1)

Méthodes

alert()

Affiche une boîte de dialogue avec un bouton de confirmation. Cette méthode est similaire window.alert(), excepté qu'elle permet de spécifier le titre de la boîte de dialogue. Vous devriez utiliser cette méthode à la place de window.alert.

void alert(
  in nsIDOMWindow aParent,
  in wstring      aDialogTitle,
  in wstring      aText
);

Paramètres

aParent
La fenêtre parente de la boîte de dialogue, ou null, dans le cas ou le parent est nsIWindowWatcher.activeWindow.
aDialogTitle
Le titre de la boîte de dialogue.
aText
Le texte de la boîte de dialogue.

Exemple

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

prompts.alert(null, \"Title of this Dialog\", \"Hello! You have now been alerted.\");

AlertExample.png

alertCheck()

Affiche une boîte de dialogue avec un bouton de confirmation et une case à cocher accompagnée de son libellé.

void alertCheck(
  in    nsIDOMWindow aParent,
  in    wstring      aDialogTitle,
  in    wstring      aText,
  in    wstring      aCheckMsg,
  inout boolean      aCheckState
);

Paramètres

aParent
La fenêtre parente de la boîte de dialogue. Si null, la fenêtre parente sera nsIWindowWatcher.activeWindow.
aDialogTitle
Le titre de la boîte de dialogue.
aText
Le texte de la boîte de dialogue.
aCheckMsg
Le libellé de la case à cocher.
aCheckState
Contient l'état initial de la case à cocher, puis son état final une fois la boîte de dialogue fermée. Si vous utilisez cette méthode en Javascript, vous devez englober cet argument dans un objet dont la propriété value est un booléen spécifiant l'état initial (ou utiliser un objet vide).

Exemple

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

var check = {value: false}; // case à cocher décochée par défaut

prompts.alertCheck(null, \"Title of this Dialog\", \"Hello! You have now been alerted.\",
\"And this is a checkbox\", check);

// check.value vaut true si la case est cochée, false sinon

confirm()

Affiche une boîte de dialogue avec un bouton OK et un bouton Annuler.

boolean confirm(
  in nsIDOMWindow aParent,
  in wstring       aDialogTitle,
  in wstring       aText
);

Paramètres

aParent
La fenêtre parente de la boîte de dialogue. Si null, la fenêtre parente sera nsIWindowWatcher.activeWindow.
aDialogTitle
Le titre de la boîte de dialogue.
aText
Le texte de la boîte de dialogue.

Valeur retournée

true si le bouton OK est actionné, false si le bouton Annuler est actionné.

Exemple

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

var result = prompts.confirm(null, \"Title of this Dialog\", \"Are you sure?\");

// result vaut true si le bouton OK est actionné, false si c'est le bouton Annuler

confirmCheck()

Affiche une boîte de dialogue avec un bouton OK et un bouton Annuler ainsi qu'une case à coché accompagnée de son libellé.

boolean confirmCheck(
  in nsIDOMWindow aParent,
  in wstring aDialogTitle,
  in wstring aText,
  in wstring aCheckMsg,
  inout boolean aCheckState
);

Paramètres

aParent
La fenêtre parente de la boîte de dialogue. Si null, la fenêtre parente sera nsIWindowWatcher.activeWindow.
aDialogTitle
Le titre de la boîte de dialogue.
aText
Le texte de la boîte de dialogue.
aCheckMsg
Le libellé de la case à cocher. Si null, la case à cocher ne sera pas affichée.
aCheckState
Contient l'état initial de la case à cocher, puis son état final une fois la boîte de dialogue fermée. Si vous utilisez cette méthode en Javascript, vous devez englober cet argument dans un objet dont la propriété value est un booléen spécifiant l'état initial (ou utiliser un objet vide).

Valeur retournée

true si le bouton OK est actionné, false si le bouton Annuler est actionné.

Exemple

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

var check = {value: true}; // case à cocher cochée par défaut

var result = prompts.confirmCheck(null, \"Title of this Dialog\", \"Are you sure?\",
\"Don't ask again\", check);

// check.value vaut true si la case à cocher est cochée ET que le bouton OK est actionné,
// false si le bouton Annuler est actionné.

confirmEx()

Ouvre une boîte de dialogue comprenant 3 boutons et éventuellement une case à cocher accompagnée de son libellé.

Les boutons sont numérotés de 0 à 2. L'application peut décider d'afficher ces boutons de gauche à droite  ou de droite à gauche. Le bouton 0 est activé par défaut à moins qu'un drapeau de bouton par défaut ne soit spécifié.

Un bouton peut utiliser un libellé prédéfini, spécifié par l'un des drapeaux de libellé de bouton. Chaque libellé peut être multiplié par un drapeau de position de bouton pour assigner le libellé à un bouton particulié. Lorsque le drapeau BUTTON_TITLE_IS_STRING est utilisé pour un bouton, le paramètre de libellé de ce bouton est utilisé. Si la valeur de la position d'un bouton est à 0, le bouton ne sera pas affiché.

L'exemple suivant créé une boîte de dialogue avec un bouton OK et un bouton avec un libellé personnalisé :

aButtonFlags = (BUTTON_POS_0) * (BUTTON_TITLE_OK) +

               (BUTTON_POS_1) * (BUTTON_TITLE_IS_STRING) +

                BUTTON_POS_1_DEFAULT;

confirmEx retourne toujours 1 lorsque l'utilisateur ferme la boîte de dialogue en utilisant le bouton de fermeture de la barre de titre ! bug 345067
PRInt32 confirmEx(
  in nsIDOMWindow  aParent,
  in wstring aDialogTitle,
  in wstring aText,
  in unsigned long aButtonFlags,
  in wstring aButton0Title,
  in wstring aButton1Title,
  in wstring aButton2Title,
  in wstring aCheckMsg,
  inout boolean aCheckState
);

Paramètres

aParent
La fenêtre parente de la boîte de dialogue. Si null, la fenêtre parente sera nsIWindowWatcher.activeWindow.
aDialogTitle
Le titre de la boîte de dialogue.
aText
Le texte de la boîte de dialogue.
aButtonFlags
aButtonFlags est une combinaison de drapeaux de boutons.
aButton0Title
Libellé du bouton 0 si la valeur (BUTTON_TITLE_IS_STRING*BUTTON_TITLE_POS_0) est utilisé pour le paramètre aButtonFlags.
aButton1Title
Libellé du bouton 1 si la valeur (BUTTON_TITLE_IS_STRING*BUTTON_TITLE_POS_1) est utilisé pour le paramètre aButtonFlags.
aButton2Title
Libellé du bouton 2 si la valeur (BUTTON_TITLE_IS_STRING*BUTTON_TITLE_POS_2) est utilisé pour le paramètre aButtonFlags.
aCheckMsg
Le libellé de la case à cocher.
aCheckState
Contient l'état initial de la case à cocher, puis son état final une fois la boîte de dialogue fermée. Si vous utilisez cette méthode en Javascript, vous devez englober cet argument dans un objet dont la propriété value est un booléen spécifiant l'état initial (ou utiliser un objet vide).

Valeur retournée

L'index du bouton actionné.

Exemple

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

var check = {value: false}; // case à cocher décochée par défaut
var flags = prompts.BUTTON_POS_0 * prompts.BUTTON_TITLE_SAVE +
prompts.BUTTON_POS_1 * prompts.BUTTON_TITLE_IS_STRING +
prompts.BUTTON_POS_2 * prompts.BUTTON_TITLE_CANCEL;
// Ces drapeaux créent 3 boutons. Le premier est un bouton \"Save\", le
// second la valeur de aButtonTitle1, et le troisième un bouton \"Cancel\"

var button = prompts.confirmEx(null, \"Title of this Dialog\", \"What do you want to do?\",
flags, \"\", \"Button 1\", \"\", null, check);

// La case à cocher est cachée et button contient l'index du bouton acctionné,
// 0, 1, ou 2.

prompt()

Ouvre une boîte de dialogue contenant un champ texte et éventuellement une case à cocher accompagnée de son libellé.

boolean prompt(
  in nsIDOMWindow aParent,
  in wstring aDialogTitle,
  in wstring aText,
  inout wstring aValue,
  in wstring aCheckMsg,
  inout boolean aCheckState
);

Paramètres

aParent
La fenêtre parente de la boîte de dialogue. Si null, la fenêtre parente sera nsIWindowWatcher.activeWindow.
aDialogTitle
Le titre de la boîte de dialogue.
aText
Le texte de la boîte de dialogue.
aValue
Contient la valeur par défaut du champ texte lors de l'appel de la méthode (la valeur null peut être utilisée pour un champ vide). Lorsque la méthode retourne le résultat, si l'utilisateur a actionné le bouton OK, ce paramètre contient la nouvelle valeur. Sinon, la valeur n'est pas modifiée. Si vous appelez cette méthode en JavaScript, vous devez englober cet argument dans un objet dont l'attribut value est une chaîne de caractère (ou utiliser un objet vide).
aCheckMsg
Le libellé de la case à cocher. Si null, la case à cocher ne sera pas affichée.
aCheckState
Contient l'état initial de la case à cocher, puis son état final une fois la boîte de dialogue fermée. Si vous utilisez cette méthode en Javascript, vous devez englober cet argument dans un objet dont la propriété value est un booléen spécifiant l'état initial (ou utiliser un objet vide).

Valeur retournée

true si le bouton OK est actionné, false si le bouton Annuler est actionné.

Exemple

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

var check = {value: false}; // case à cocher décochée par défaut
var input = {value: \"Bob\"}; // valeur par défaut du champ texte à \"Bob\"
var result = prompts.prompt(null, \"Title\", \"What is your name?\", input, null, check);

// result vaut true si le bouton OK est actionné, false si c'est le bouton Cancel.
// input.value content la valeur du champ texte si le bouton OKest actionné.

promptUsernameAndPassword()

Ouvre une boîte dialogue contenant un champ texte, un champ de mot de passe et éventuellement une case à cocher accompagnée de son libellé.

boolean promptUsernameAndPassword(
  in nsIDOMWindow aParent,
  in wstring aDialogTitle,
  in wstring aText,
  inout wstring aUsername,
  inout wstring aPassword,
  in wstring aCheckMsg,
  inout boolean aCheckState
);

Paramètres

aParent
La fenêtre parente de la boîte de dialogue. Si null, la fenêtre parente sera nsIWindowWatcher.activeWindow.
aDialogTitle
Le titre de la boîte de dialogue.
aText
Le texte de la boîte de dialogue.
aUsername
Nom d'utilisateur par défaut (valeur nulle acceptée). Si l'utilisateur a fermé la fenêtre en actionnant le bouton OK, ce paramètre contient la nouvelle valeur saisie. Sinon, la valeur n'est pas modifiée. Si vous utilisez cette méthode en Javascript, vous devez englober cet argument dans un objet dont la propriété value est un booléen spécifiant l'état initial (ou utiliser un objet vide).
aPassword
Mot de passe par défaut (valeur nulle acceptée). Si l'utilisateur a fermé la fenêtre en actionnant le bouton OK, ce paramètre contient la nouvelle valeur saisie. Sinon, la valeur n'est pas modifiée. Si vous utilisez cette méthode en Javascript, vous devez englober cet argument dans un objet dont la propriété value est un booléen spécifiant l'état initial (ou utiliser un objet vide).
aCheckMsg
Le libellé de la case à cocher. Si null, la case à cocher ne sera pas affichée.
aCheckState
Contient l'état initial de la case à cocher, puis son état final une fois la boîte de dialogue fermée. Si vous utilisez cette méthode en Javascript, vous devez englober cet argument dans un objet dont la propriété value est un booléen spécifiant l'état initial (ou utiliser un objet vide).

Valeur retournée

true si le bouton OK est actionné, false si le bouton Annuler est actionné.

Exemple

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

var username = {value: \"user\"}; // nom d'utilisateur par défaut
var password = {value: \"pass\"}; // mot de passe par défaut
var check = {value: true}; // case à cocher cochée par défaut
var result = prompts.promptUsernameAndPassword(null, \"Title\", \"Enter username and password:\",\nusername, password, \"Save\", check);

// result vaut true si le bouton OK est actionné, false si c'est le bouton Cancel.
// username.value, password.value, et check.value contiennent les nouvelles valeurs saisies si le bouton OK est actionné.

promptPassword()

Ouvre une boîte de dialogue contenant un champ mot de passe et éventuellement une case à cocher accompagnée de son libellé.

boolean promptPassword(
  in nsIDOMWindow aParent,
  in wstring aDialogTitle,
  in wstring aText,
  inout wstring aPassword,
  in wstring aCheckMsg,
  inout boolean aCheckState
);

Paramètres

aParent
La fenêtre parente de la boîte de dialogue. Si null, la fenêtre parente sera nsIWindowWatcher.activeWindow.
aDialogTitle
Le titre de la boîte de dialogue.
aText
Le texte de la boîte de dialogue.
aPassword
Mot de passe par défaut (valeur nulle acceptée). Si l'utilisateur a fermé la fenêtre en actionnant le bouton OK, ce paramètre contient la nouvelle valeur saisie. Sinon, la valeur n'est pas modifiée. Si vous utilisez cette méthode en Javascript, vous devez englober cet argument dans un objet dont la propriété value est un booléen spécifiant l'état initial (ou utiliser un objet vide).
aCheckMsg
Le libellé de la case à cocher. Si null, la case à cocher ne sera pas affichée.
aCheckState
Contient l'état initial de la case à cocher, puis son état final une fois la boîte de dialogue fermée. Si vous utilisez cette méthode en Javascript, vous devez englober cet argument dans un objet dont la propriété value est un booléen spécifiant l'état initial (ou utiliser un objet vide).

Valeur retournée

true si le bouton OK est actionné, false si le bouton Annuler est actionné.

Exemple
var prompts = Components.classes[\"@mozilla.org/embedcomp/prompt-service;1\"]
.getService(Components.interfaces.nsIPromptService);
var password = {value: \"pass\"}; // mot de passe par défaut
var check = {value: true}; // case à cocher cochée par défaut
var result = prompts.promptPassword(null, \"Title\", \"Enter password:\", password, null, check);

// result vaut true si le bouton OK est actionné, false si c'est le bouton Cancel.
// password.value contient la nouvelle valeur saisie si le bouton OK est actionné. }} La case à cocher n'est pas affichée.

select()

Ouvre une boîte de dialogue contenant une liste de chaîne de caractères. L'utilisateur ne peut en sélectionner qu'une seule.

boolean select(
  in  nsIDOMWindow aParent,
  in  wstring       aDialogTitle,
  in  wstring       aText,
  in  PRUint32     aCount,
  [array, size_is(aCount)] in wstring aSelectList,
  out long         aOutSelection
);

Paramètres

aParent
La fenêtre parente de la boîte de dialogue. Si null, la fenêtre parente sera nsIWindowWatcher.activeWindow.
aDialogTitle
Le titre de la boîte de dialogue.
aText
Le texte de la boîte de dialogue.
aCount
Taille du tableau aSelectList.
aSelectList
Liste de chaînes de caractères.
aOutSelection
Contient l'index de l'élément sélectionné dans la liste lorsque le bouton OK est actionné. Si vous utilisez cette méthode en Javascript, vous devez englober cet argument dans un objet dont la propriété value est un booléen spécifiant l'état initial (ou utiliser un objet vide).

Valeur retournée

true si le bouton OK est actionné, false si le bouton Annuler est actionné.

Exemple

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

var items = [\"Hello\", \"Welcome\", \"Howdy\", \"Hi\", \":)\"]; // liste d'éléments

var selected = {};

var result = prompts.select(null, \"Title\", \"What greeting do you want?\", items.length, items, selected);

// result vaut true si le bouton OK est actionné, false si c'est le bouton Cancel.
// selected contient l'index de l'élément sélectionné. Accédez à cet élément avec selected items[selected.value].

selectExample.png

Voir également