MozillaZine

Prompt service

From MozillaZine Knowledge Base

(Difference between revisions)
Revision as of 00:07, 25 August 2005
Msmolens (Talk | contribs)
(Note STD_OK_CANCEL_BUTTONS, STD_YES_NO_BUTTONS)
<-- Previous diff
Revision as of 08:47, 26 August 2005
Asqueella (Talk | contribs)
(put dots in line in the code, as in mozilla code)
Next diff -->
Line 1: Line 1:
-<code>nsIPromptService</code> 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 [[Dev : nsIFilePicker | nsIFilePicker article]].+<code>nsIPromptService</code> 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 | nsIFilePicker article]].
<code>nsIPromptService</code> 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. <code>nsIPromptService</code> 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.
Line 5: Line 5:
==Getting nsIPromptService== ==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: 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"].+ var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
- getService(Components.interfaces.nsIPromptService);+ .getService(Components.interfaces.nsIPromptService);
==nsIPromptService methods== ==nsIPromptService methods==
===alert()=== ===alert()===
<code>alert()</code> is the simplest function, which simply displays a message box with specified title and message. For example: <code>alert()</code> 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"].+ var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
- getService(Components.interfaces.nsIPromptService);+ .getService(Components.interfaces.nsIPromptService);
prompts.alert(window, "Window title", "Hello world!"); prompts.alert(window, "Window title", "Hello world!");
Line 19: Line 19:
===alertCheck()=== ===alertCheck()===
<code>alertCheck()</code> 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. <code>alertCheck()</code> 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"].+ var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
- getService(Components.interfaces.nsIPromptService);+ .getService(Components.interfaces.nsIPromptService);
check = {value: false}; // default value check = {value: false}; // default value
prompts.alertCheck(window, "Window title", "You have been warned", prompts.alertCheck(window, "Window title", "You have been warned",
Line 30: Line 30:
===confirm() and confirmCheck()=== ===confirm() and confirmCheck()===
<code>confirm()</code> is also simple. It displays a dialog with specified title, text and two buttons - OK and Cancel. <code>confirm()</code> 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"].+ var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
- getService(Components.interfaces.nsIPromptService);+ .getService(Components.interfaces.nsIPromptService);
var result = prompts.confirm(window, "Title", "Do you want to quit?"); 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 <code>confirm()</code> and <code>alertCheck()</code>, so it should be easy to understand without additional comments. Below is an example for displaying a confirmation message with a checkbox. It is a hybrid of <code>confirm()</code> and <code>alertCheck()</code>, so it should be easy to understand without additional comments.
- var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"].+ var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
- getService(Components.interfaces.nsIPromptService);+ .getService(Components.interfaces.nsIPromptService);
var check = {value: false}; var check = {value: false};
var result = prompts.confirmCheck(window, "Title", "Do you want to quit?", var result = prompts.confirmCheck(window, "Title", "Do you want to quit?",
Line 45: Line 45:
<code>prompt()</code> 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. <code>prompt()</code> 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"].+ var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
- getService(Components.interfaces.nsIPromptService);+ .getService(Components.interfaces.nsIPromptService);
var input = {value: "default value"}; var input = {value: "default value"};
var check = {value: false}; var check = {value: false};
Line 58: Line 58:
//promptPassword //promptPassword
- var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"].+ var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
- getService(Components.interfaces.nsIPromptService);+ .getService(Components.interfaces.nsIPromptService);
input = {value:"password"}; input = {value:"password"};
check = {value:false}; check = {value:false};
Line 68: Line 68:
//promptUsernameAndPassword //promptUsernameAndPassword
- var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"].+ var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
- getService(Components.interfaces.nsIPromptService);+ .getService(Components.interfaces.nsIPromptService);
username = {value:"ihoss"}; username = {value:"ihoss"};
password = {value:"password"}; password = {value:"password"};
Line 80: Line 80:
===confirmEx()=== ===confirmEx()===
- var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"].+ var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
- getService(Components.interfaces.nsIPromptService);+ .getService(Components.interfaces.nsIPromptService);
var check = {value: false}; var check = {value: false};
var flags = 0; var flags = 0;
Line 88: Line 88:
// |check.value| indicates whether or not the checkbox is checked // |check.value| indicates whether or not the checkbox is checked
// |button| indicates which button was clicked // |button| indicates which button was clicked
 +
<code>confirmEx()</code> 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 <code>null</code> in the eighth (checkbox label) parameter. <code>confirmEx()</code> 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 <code>null</code> in the eighth (checkbox label) parameter.
<code>flags</code> 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: <code>flags</code> 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:
-<table border=1>+<table border="1">
<tr><th>Button Position Flags</th><th>Button Title Flags</th></tr> <tr><th>Button Position Flags</th><th>Button Title Flags</th></tr>
<tr><td valign="top"><code>BUTTON_POS_0<br/>BUTTON_POS_1<br/>BUTTON_POS_2</code></td><td valign="top"><code>BUTTON_TITLE_OK<br/>BUTTON_TITLE_CANCEL<br/>BUTTON_TITLE_YES<br/>BUTTON_TITLE_NO<br/>BUTTON_TITLE_SAVE<br/>BUTTON_TITLE_DONT_SAVE<br/>BUTTON_TITLE_REVERT<br/>BUTTON_TITLE_IS_STRING</code></td></tr> <tr><td valign="top"><code>BUTTON_POS_0<br/>BUTTON_POS_1<br/>BUTTON_POS_2</code></td><td valign="top"><code>BUTTON_TITLE_OK<br/>BUTTON_TITLE_CANCEL<br/>BUTTON_TITLE_YES<br/>BUTTON_TITLE_NO<br/>BUTTON_TITLE_SAVE<br/>BUTTON_TITLE_DONT_SAVE<br/>BUTTON_TITLE_REVERT<br/>BUTTON_TITLE_IS_STRING</code></td></tr>
Line 100: Line 101:
The order in which the buttons appear is platform-dependent. Button 0 is selected by default unless a button default flag is added to <code>flags</code>: The order in which the buttons appear is platform-dependent. Button 0 is selected by default unless a button default flag is added to <code>flags</code>:
-<table border=1>+<table border="1">
<tr><th>Button Default Flags</th></tr> <tr><th>Button Default Flags</th></tr>
<tr><td valign="top"><code>BUTTON_POS_0_DEFAULT<br/>BUTTON_POS_1_DEFAULT<br/>BUTTON_POS_2_DEFAULT</code></td></tr> <tr><td valign="top"><code>BUTTON_POS_0_DEFAULT<br/>BUTTON_POS_1_DEFAULT<br/>BUTTON_POS_2_DEFAULT</code></td></tr>
Line 114: Line 115:
===select()=== ===select()===
<code>select()</code> displays a dialog with a listbox and OK/Cancel buttons. The listbox contains specified options, and user can select exactly one of them. <code>selected.value</code> will get the index of the item user selected and you can get its value with <code>list[selected.value]</code> 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 <code>list</code> array. If it is less then only the items up to that index will be shown in the listbox. <code>select()</code> displays a dialog with a listbox and OK/Cancel buttons. The listbox contains specified options, and user can select exactly one of them. <code>selected.value</code> will get the index of the item user selected and you can get its value with <code>list[selected.value]</code> 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 <code>list</code> 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"].+ var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
- getService(Components.interfaces.nsIPromptService);+ .getService(Components.interfaces.nsIPromptService);
var list = ["ihoss", "internet", "firefox", "xul", "stupid entry", "out of ideas"] var list = ["ihoss", "internet", "firefox", "xul", "stupid entry", "out of ideas"]
var selected = {}; var selected = {};

Revision as of 08:47, 26 August 2005

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 article.

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.

Contents

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.