Prompt service

From MozillaZine Knowledge Base
Revision as of 18:47, 17 June 2006 by Asqueella (talk | contribs) (update filepicker link)
Jump to navigationJump to search

nsIPromptService is an XPCOM interface available to C++ and chrome JavaScript code (not to web pages' JS), that provides methods for displaying a few simple types of dialogs. To learn how to create advanced dialogs, see Creating dialogs. For file/folder picker dialogs, see nsIFilePicker.

nsIPromptService has 9 functions and a few constants that are important to understand. This article contains explanations for some of these functions, and example code for all of them.

Getting nsIPromptService

First of all, you need to obtain the prompt service which you can use to show messages. You can do this using the following code:

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

nsIPromptService methods

alert()

alert() is the simplest function, which simply displays a message box with specified title and message. For example:

var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);
prompts.alert(window, "Window title", "Hello world!");

As in many other methods of nsIPromptService, first parameter is the parent window in the sense of nsIWindowWatcher.openWindow. You can pass null, in which case the parent window will be nsIWindowWatcher.activeWindow.

alertCheck()

alertCheck() will popup a message box with specified title, text and a checkbox. The checkbox can be a "Do not show this message again" option or something similar.

var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);
check = {value: false}; // default value
prompts.alertCheck(window, "Window title", "You have been warned", 
                   "Don't ask again", check);
// do something with check.value;

Notice how we get the state of the checkbox. The function changes the value member of the check object, so to get the result we use check.value. It's the standard way of getting so-called "out" parameters from an XPCOM component.

confirm() and confirmCheck()

confirm() is also simple. It displays a dialog with specified title, text and two buttons - OK and Cancel.

var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);
var result = prompts.confirm(window, "Title", "Do you want to quit?");

Below is an example for displaying a confirmation message with a checkbox. It is a hybrid of confirm() and alertCheck(), so it should be easy to understand without additional comments.

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);
// do something check.value / result

prompt()

prompt() can be very important and useful in lots of cases, as it accepts user input. Instead of making an XUL dialog or adding more textboxes you can simply call a prompt function. As you can see the first few arguments are the same as the others but it has an extra object. This object is the default value before the function is called and the new value after the function has been called.

var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);
var input = {value: "default value"};
var check = {value: false};
result = prompts.prompt(window, "Title", "What's your name?", input, "Do not ask again", check);
// input.value is the string user entered
// check.value indicates whether or not the checkbox is checked
// result - whether user clicked OK (true) or Cancel

promptPassword() and promptUsernameAndPassword()

Below are other versions of prompt, promptPassword() with a password textbox and promptUsernameAndPassword which has a username and password field.

//promptPassword
var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);
input = {value:"password"};
check = {value:false};
okorcancel = prompts.promptPassword(window, 'title', 'Text', input, 'Check?', 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:"ihoss"};
password = {value:"password"};
check = {value:false};
okorcancel = prompts.promptUsernameAndPassword(window, 'title', 'Text', username, password, 'Check?', 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, "Window title", "Message text", flags, 
             "Button 0", "Button 1", "Button 2", "Checkbox label", check);
// |check.value| indicates whether or not the checkbox is checked
// |button| indicates which button was clicked

confirmEx() is designed to be customizable so you can make your own messages. It can display a dialog with up to 3 buttons with a variety of predefined (localized if necessary) labels or specified by your code labels, and a checkbox if you want. If you don't want the checkbox to be displayed, just put null in the eighth (checkbox label) parameter.

flags is a set of flags that indicates which buttons the dialog should display. Each button is specified as a button title flag multiplied by a button position flag:

Button Position FlagsButton Title Flags
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

Buttons can use one of the predefined titles. Alternatively, if BUTTON_TITLE_IS_STRING is specified for a button, then the string parameter for that button will be used.

flags is formed by summing the buttons' values.

The order in which the buttons appear is platform-dependent. Button 0 is selected by default unless a button default flag is added to flags:

Button Default Flags
BUTTON_POS_0_DEFAULT
BUTTON_POS_1_DEFAULT
BUTTON_POS_2_DEFAULT

For example, flags as specified below causes the dialog to have a Save button, a Cancel button, and a third button whose title is the seventh argument to confirmEx() ("Button 2" in the snippet above).

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;

Setting flags to STD_OK_CANCEL_BUTTONS or STD_YES_NO_BUTTONS provides a shorthand to select the standard set of OK/Cancel or Yes/No buttons.

select()

select() displays a dialog with a listbox and OK/Cancel buttons. The listbox contains specified options, and user can select exactly one of them. selected.value will get the index of the item user selected and you can get its value with list[selected.value] The 4th parameter is the number of entries you want to be displayed, it must be less than or equal to the length of the list array. If it is less then only the items up to that index will be shown in the listbox.

var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);
var list = ["ihoss", "internet", "firefox", "xul", "stupid entry", "out of ideas"]
var selected = {};
var ok = prompts.select(window, "Window title", "Prompt text", 
                        list.length, list, selected);
// selected.value contains the index
// |ok| indicates whether OK or Cancel button was pressed


Original version

The original version of this tutorial is by Ihoss and can be found here.