Prompt service: Difference between revisions

From MozillaZine Knowledge Base
Jump to navigationJump to search
m (update filepicker link)
(Moved to MDC)
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 [http://developer.mozilla.org/en/docs/nsIFilePicker nsIFilePicker].
[http://developer.mozilla.org/en/docs/Code_snippets:Dialogs Moved to MDC]
 
<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.
 
==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()===
<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"]
                        .getService(Components.interfaces.nsIPromptService);
prompts.alert(window, "Window title", "Hello world!");
 
As in many other methods of <code>nsIPromptService</code>, first parameter is the ''parent window'' in the sense of <code>[http://xulplanet.com/references/xpcomref/ifaces/nsIWindowWatcher.html#method_openWindow nsIWindowWatcher.openWindow]</code>. You can pass <code>null</code>, in which case the parent window will be <code>nsIWindowWatcher.activeWindow</code>.
 
===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.
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 <code>value</code> member of the <code>check</code> object, so to get the result we use <code>check.value</code>. It's the standard way of getting so-called "out" parameters from an XPCOM component.
 
===confirm() and confirmCheck()===
<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"]
                        .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 <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"]
                        .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()===
<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"]
                        .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
 
<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:
<table border="1">
<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>
</table>
Buttons can use one of the predefined titles.  Alternatively, if <code>BUTTON_TITLE_IS_STRING</code> is specified for a button, then the string parameter for that button will be used.
 
<code>flags</code> 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 <code>flags</code>:
<table border="1">
<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>
</table>
 
For example, <code>flags</code> 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 <code>confirmEx()</code> (<code>"Button 2"</code> 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 <code>flags</code> to <code>STD_OK_CANCEL_BUTTONS</code> or <code>STD_YES_NO_BUTTONS</code>  provides a shorthand to select the standard set of OK/Cancel or Yes/No buttons.
 
===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.
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 [[User:Ihoss|Ihoss]] and can be found [http://ihoss.not-a-blog.com/prompt.php here].


[[Category:Example code]]
[[Category:Example code]]

Revision as of 21:11, 31 October 2006