nsIPromptService

From MDC

[edit] Summary

nsIPromptService can be used to display simple dialogs. Its methods should be used in privileged code instead of DOM window.alert, window.confirm, and other similar functions.

nsIPromptService is defined in embedding/components/windowwatcher/public/nsIPromptService.idl. It is scriptable and has been frozen since Mozilla 1.7.5.

[edit] Interface Code

[scriptable, uuid(1630C61A-325E-49ca-8759-A31B16C47AA5)]
interface nsIPromptService : nsISupports { ... }

[edit] Button flags

The following flags are combined to form the aButtonFlags parameter passed to confirmEx. All flags are defined as unsigned long constants and can be accessed as Components.interfaces.nsIPromptService.flagname from JavaScript and as nsIPromptService::flagname from C++.

See Using the button flags below.

[edit] Button position flags

BUTTON_POS_0 = 1;
BUTTON_POS_1 = 256;
BUTTON_POS_2 = 65536;

[edit] Button title flags

These flags are used along with Button position flags to set the labels of buttons in the prompt.

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;

[edit] Button default flags

These flags are used to select which button is the default one.

BUTTON_POS_0_DEFAULT = 0;
BUTTON_POS_1_DEFAULT = 16777216;
BUTTON_POS_2_DEFAULT = 33554432;

[edit] BUTTON_DELAY_ENABLE

BUTTON_DELAY_ENABLE causes the buttons to be initially disabled. They are enabled after a timeout expires. The implementation may interpret this loosely, as the intent is to ensure that the user does not click through a security dialog too quickly. Strictly speaking, the implementation could choose to ignore this flag. A delay can be useful not only to give the user more time to think before acting, but also as a countermeasure against malicious web sites that intentionally create a race condition whereby the user intends to click or type a key responding, for example, to the web site's prompt but the security dialog pops up unexpectedly and its button is unintentionally activated.

BUTTON_DELAY_ENABLE = 67108864;

[edit] STD_OK_CANCEL_BUTTONS

STD_OK_CANCEL_BUTTONS selects the standard set of OK/Cancel buttons.

STD_OK_CANCEL_BUTTONS = 513;

[edit] STD_YES_NO_BUTTONS

STD_YES_NO_BUTTONS selects the standard set of Yes/No buttons.

STD_YES_NO_BUTTONS = 1027;

[edit] Methods

[edit] alert

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

alert shows an alert dialog with an OK button, title aDialogTitle, and text aText.

aParent is the parent window for the dialog, or null, in which case the parent window will be nsIWindowWatcher.activeWindow.

alert works the same way as window.alert, but accepts a title for the dialog. You should use this method instead of window.alert in chrome code.

[edit] alertCheck

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

alertCheck shows an alert dialog with an OK button, a checkbox label aCheckMsg, title aDialogTitle, and text aText.

aParent is the parent window for the dialog, or null.
aCheckState is the initial state of the checkbox when this method is

called, and the final checked state after this method returns.

[edit] confirm

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

confirm shows a dialog with OK and cancel buttons, title aDialogTitle, and text aText.

aParent is the parent window for the dialog, or null.

confirm returns true for OK, false for cancel.

[edit] confirmCheck

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

confirmCheck shows a dialog with OK and cancel buttons, a checkbox labeled aCheckMsg, title aDialogTitle, and text aText.

aParent is the parent window for the dialog, or null.
aCheckState is the initial state of the checkbox when this method is called, and is the final state of the checkbox when this method returns.

confirmCheck returns true for OK, and false for cancel.

[edit] confirmEx

PRInt32 confirmEx( in    nsIDOMWindow  aParent,
                   in    string        aDialogTitle,
                   in    string        aText,
                   in    unsigned long aButtonFlags,
                   in    string        aButton0Title,
                   in    string        aButton1Title,
                   in    string        aButton2Title,
                   in    string        aCheckMsg,
                   inout boolean       aCheckState);

confirmEx shows a dialog with up to 3 buttons, an optional checkbox, title aDialogTitle, and text aText.

aParent is the parent window for the dialog, null.
aButtonFlags is a combination of Button flags as described in Using the button flags below.
aButton0Title is used when button 0 uses TITLE_IS_STRING.
aButton1Title is used when button 1 uses TITLE_IS_STRING.
aButton2Title is used when button 2 uses TITLE_IS_STRING.
aCheckMsg is the text for the checkbox. If null, the checkbox will be left out.
aCheckState is the initial state of the checkbox when this method is called, and the final state of the checkbox after this method returns.

confirmEx returns the index of the button pressed.

Note: confirmEx always returns 1 if the user closes the window using the close button in the titlebar! bug 345067

[edit] Using the button flags

There can be up to three buttons in the dialog displayed using the prompt service. The buttons are numbered 0 - 2. The implementation can decide whether the sequence goes from right to left or left to right. Button 0 is the default button unless one of the Button default flags is specified.

You can specify a title for each button using one of the Button title flags values. Each title value can be multiplied by a position value to assign the title to a particular button. If BUTTON_TITLE_IS_STRING is used for a button, the correspondent string parameter for that button will be used.

If the value for a button position is zero, the button will not be shown.

In general, buttonFlags is constructed per the following example:

aButtonFlags = (BUTTON_POS_0) * (BUTTON_TITLE_''AAA'') +
               (BUTTON_POS_1) * (BUTTON_TITLE_''BBB'') +
                BUTTON_POS_1_DEFAULT;

Where "AAA" and "BBB" correspond to one of the Button title flags.

[edit] prompt

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

prompt shows a dialog with an edit field, optional checkbox, title aDialogTitle, and text aText.

aParent is the parent window for the dialog, or null.
aValue holds the default value for the edit field by its "value" property (an empty object is okay but needs an object with a 'value' property in order to get a value returned), and if the user clicks OK, contains the value entered in the field.
aCheckMsg is the text for the checkbox. If null, the checkbox will be left out.
aCheckState is an object to hold the initial state of the checkbox when this method is called, and to hold the final state of the checkbox after this method returns. Even if you set null for the checkbox, you must at least provide an empty object for aCheckState.

prompt returns true for OK, and false for cancel.

[edit] promptUsernameAndPassword

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

promptUsernameAndPassword shows a dialog with an edit field, a password field, an optional checkbox, title aDialogTitle, and text aText.

aParent is the parent window for the dialog, or null.
aUsername is the default value for the username edit field when this method is called, and is the value entered if the user clicks OK.
aPassword is the default value for the password field when this method is called, and is the value entered if the user clicks OK.
aCheckMsg is the text for the checkbox. If null, the checkbox will be left out.
aCheckState is the initial state of the checkbox when this method is called, and the final state of the checkbox after this method returns.

promptUsernameAndPassword returns true for OK, and false for cancel.

[edit] promptPassword

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

promptPassword shows a dialog with a password field, an optional checkbox, title aDialogTitle, and text aText.

aParent is the parent window for the dialog, or null.
aPassword is the default value for the password field when this method is called, and is the value entered if the user clicks OK.
aCheckMsg is the text for the checkbox. If null, the checkbox will be left out.
aCheckState is the initial state of the checkbox when this method is called, and the final state of the checkbox after this method returns.

promptPassword returns true for OK, and false for cancel.

[edit] select

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

select shows a dialog with a list box of strings, title aDialogTitle, and text aText.

aParent is the parent window for the dialog, or null.
aCount is the number of strings in the array aSelectList.
aSelectList is an array of strings to display.
aOutSelection contains the index of the selected item in the list if the user clicks OK.

select returns true for OK, and false for cancel.

[edit] Related Interfaces

nsIPrompt

[edit] Example code

The following examples all assume that prompts is the prompt service:

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

[edit] alert example

alert displays a simple dialog.

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

[edit] alertCheck example

alertCheck dispays a dialog with a checkbox.

check = {value: false};                      // default the checkbox to false

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

// check.value is now true if the box was checked and false if the box was cleared

[edit] confirm example

confirm displays a dialog with OK/Cancel.

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

// result is now true if OK was clicked, and false if cancel was clicked

[edit] confirmCheck example

confirmCheck displays a dialog with OK/Cancel and a checkbox

var check = {value: true};                   // default the checkbox to true

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

// check.value is now true if the box was checked AND OK was pressed, false if
// the box was cleared AND OK was pressed, and is the default of true if Cancel was pressed.

[edit] confirmEx example

confirmEx displays a dialog with up to 3 buttons and an optional checkbox

var check = {value: false};                  // default the checkbox to false

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;
// This value of flags will create 3 buttons. The first will be "Save", the
// second will be the value of aButtonTitle1, and the third will be "Cancel"

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

// The checkbox will be hidden, and button will contain the index of the button pressed,
// 0, 1, or 2.

[edit] prompt example

prompt displays a dialog with an edit field.

var check = {value: false};                  // default the checkbox to false

var input = {value: "Bob"};                  // default the edit field to Bob

var result = prompts.prompt(null, "Title", "What is your name?", input, null, check);

// result is true if OK is pressed, false if Cancel. input.value holds the value of the edit field if "OK" was pressed.

[edit] promptUsernameAndPassword example

promptUsernameAndPassword displays a dialog with an edit field, password field, and optionally a checkbox.

var username = {value: "user"};              // default the username to user

var password = {value: "pass"};              // default the password to pass

var check = {value: true};                   // default the checkbox to true

var result = prompts.promptUsernameAndPassword(null, "Title", "Enter username and password:",
                                               username, password, "Save", check);

// result is true if OK was pressed, false if cancel was pressed. username.value,
// password.value, and check.value are set if OK was pressed.

[edit] promptPassword example

promptPassword displays a dialog with a password field and an optional checkbox.

var password = {value: "pass"};              // default the password to pass

var check = {value: true};                   // default the checkbox to true

var result = prompts.promptPassword(null, "Title", "Enter password:", password, null, check);

// result is true if OK was pressed, false if cancel was pressed. password.value is
// set if OK was pressed. The checkbox is not displayed.

[edit] select example

select displays a dialog with a listbox of choices.

var items = ["Hello", "Welcome", "Howdy", "Hi", ":)"]; // list items

var selected = {};

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

// result is true if OK was pressed, false if cancel. selected is the index of the item array
// that was selected. Get the item using items[selected].

Retrieved from "http://developer.mozilla.org/en/docs/nsIPromptService"

Categories: XPCOM API Reference | NeedsEditorialReview | Interfaces | Interfaces:Scriptable | Interfaces:Frozen

Mozilla Developer Network

Navigation

Views

Toolbox