nsIPromptService

Résumé

nsIPromptService peut être utilisée 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 ("&&").

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

Constantes

Les drapeaux décris ci-dessous sont combinés pour formé 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

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.

Drapeaux de bouton par défaut

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

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

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.\");

alertCheck()

Affiche une boîte de dialogue avec un bouton de confirmation et une case à coché 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 particulier. 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;

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 à cochée 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].

Voir également

• nsIPrompt
• Working with out parameters
• Quelques exemples (MozillaZine)