This article needs a technical review. How you can help.
Note: Prompt.jsm is still under development. The API may change. Use with care!The Prompt.jsm JavaScript code module offers utility routines dealing with showing dialogs and prompts in Fennec. The API is chainable, so most methods return the prompt object to you. To use it, you first need to import the code module into your JavaScript scope:
Components.utils.import("resource://gre/modules/Prompt.jsm");
Basic usage
Prompt.jsm provides a Prompt constructor for the current scope. The constructor takes a single Object as an argument. That object can have properties for the prompts:
| Parameter | Description |
window |
The window that is opening this prompt. Optional |
title |
The title to show on the prompt. Optional |
message |
A message to show on the prompt. Optional |
buttons |
An array of Strings to show as buttons on the prompt. Prompts on Android support a maximum of three buttons. Any more will be ignored. Optional |
Example:
var p = new Prompt({
window: window,
title: "My title",
message: "This is the text on my prompt",
buttons: ["OK", "Cancel"]
}).show(function(data) {
alert("Clicked on: " + data.button);
});
Method overview
addButton(aOptions) |
addCheckbox(aOptions) |
addTextbox(aOptions) |
addPassword(aOptions) |
addMenulist(aOptions) |
show(aCallback) |
setSingleChoiceItems(aItems) |
setMultiChoiceItems(aItems) |
Methods
addButton()
Adds a button to the prompt. A maximum of three buttons can be shown at the dialog at any time. If there are already three buttons present, this will silently fail.
Prompt addButton(aOptions);
Parameters
Takes an object with parameters describing the button
| Parameter | Description |
label |
The label to show on the button. |
Return value
Returns the Prompt that is being modified.
Example
var p = new Prompt({
window: window,
title: "My Prompt",
message: "A message on the prompt"
});
if (shouldShowButtons) {
p.addButton({ label: "Button 1" });
p.addButton({ label: "Button 2" });
}
p.show(function(data) {
if (data.button == 0)
alert("Clicked button 1!");
else if (data.button == 1)
alert("Clicked button 2!");
});
addCheckbox()
Adds a checkbox to the prompt.
Prompt addCheckbox(aOptions);
Parameters
Takes an object with parameters describing the checkbox.
| Parameter | Description |
label |
The label to show next to the checkbox. |
checked |
A boolean describing whether or not the checkbox is checked. |
id |
An id to be associated with the checkbox. This can be used to identify the value of the checkbox in the return value. If not specified, the checkbox will be associated with an id of "checkbox" plus the index of this checkbox. i.e. "checkbox0", "checkbox1", etc. |
Return value
Returns the Prompt that is being modified.
Example
var p = new Prompt({
window: window,
title: "My Prompt",
message: "A message on the prompt"
}).addCheckbox({
label: "My checkbox",
checked: true,
id: "myCheckBox"
}).show(function(data) {
alert("Checkbox is " + (data.myCheckBox ? "" : "NOT") + " checked.");
});
addTextbox()
Adds a textbox to the prompt.
Prompt addTextbox(aOptions);
Parameters
Takes an object with parameters describing the textbox.
| Parameter | Description |
autofocus |
A boolean indicating if this textbox should focus itself when the dialog is shown. |
value |
The default value of the textbox |
id |
An id to be associated with the textbox. This can be used to identify the value of the textbox in the return value. If not specified, the textbox will be associated with an id of "textbox" plus the index of this textbox. i.e. "textbox0", "textbox1", etc. |
hint |
Some hint text to show inside the textbox if its empty. |
Return value
Returns the Prompt that is being modified.
Example
var p = new Prompt({
window: window,
title: "Enter a username",
}).addTextbox({
value: "Jim Brown",
id: "username",
hint: "User name",
autofocus: true
}).show(function(data) {
alert("Username is " + data.username);
});
addPassword()
Adds a password textbox to the prompt.
Prompt addPassword(aOptions);
Parameters
Takes an object with parameters describing the textbox.
| Parameter | Description |
autofocus |
A boolean indicating if this textbox should focus itself when the dialog is shown. If multiple elements on the dialog try to autofocus, the behavior is undefined. |
value |
The default value of the textbox |
id |
An id to be associated with the textbox. This can be used to identify the value of the textbox in the return value. If not specified, the textbox will be associated with an id of "textbox" plus the index of this textbox. i.e. "textbox0", "textbox1", etc. |
hint |
Some hint text to show inside the textbox if its empty. |
Return value
Returns the Prompt that is being modified.
Example
var p = new Prompt({
window: window,
title: "Enter a username",
}).addTextbox({
value: "Jim Brown",
id: "username",
hint: "User name",
autofocus: true
}).addPassword({
value: "JimsPassword",
id: "password",
hint: "Password",
}).show(function(data) {
alert(data.username + "'s password is " + data.password);
});
addMenulist()
Adds a menulist (a.k.a. an Android spinner) to the prompt.
Prompt addMenulist(aOptions);
Parameters
Takes an object with parameters describing the menulist.
| Parameter | Description |
values |
An array of strings to show in the menulist |
id |
An id to be associated with the menulist. This can be used to identify the value of the textbox in the callback. If not specified, the menulist will be associated with an id of "menulist" plus an idex. i.e. "menulist0", "menulist1", etc. |
Return value
Returns the Prompt that is being modified.
Example
var colors = ["Red", "Green", "Blue"];
var p = new Prompt({
window: window,
title: "Whats your favorite color?",
}).addMenulist({ values: colors }).show(function(data) {
alert("Your favorite color is: " + colors[data.menulist0]);
});
show()
Shows the prompt
show(aCallback);
Parameters
Takes a callback function to be called when the prompt returns. The callback function is passed an object containing the values of returned inputs, as well as a button parameter with the index of whichever button or list item was clicked. For the setMultiChoiceItems method, the object has a list property consisting of the selected items.
Return value
None
Example
var p = new Prompt({
window: window,
title: "Everything ok?",
buttons: ["Ok", "Not ok"]
}).show(function(data) {
if(data.button == 1)
alert(":(");
else
alert(":)");
});
setSingleChoiceItems()
Adds a set of single-choice list items to the prompt. This will show items as a scrollable list inside the dialog, like a context menu, or a HTML select would appear.
Prompt setSingleChoiceItems(aItems);
Parameters
Takes an array of objects with parameters describing the list items. Objects can have the following parameters:
| Parameter | Description |
label |
The label to show on this list item |
selected |
Whether or not this item is selected. Adding selected to any item will cause all of the items in the list to have an indicator on their right to describe if they're selected or not. |
disabled |
Whether or not this item is disabled. |
children |
Used if this is a header row. Children is an array of menuitems to be shown underneith the header and are indented to indicate they belong inside it. |
submenu |
Used if this row contains a submenu. An indicator will be shown on the right to indicate this item has a submenu. Showing the submenu when this item is selected is up to the implementation. |
Return value
Returns the Prompt that is being modified.
Example
var items = [
{ label: "Shades of red" },
{ label: "Pink", disabled: true, child: true },
{ label: "Maroon", child: true },
{ label: "Green", selected: true },
{ label: "Blue" },
];
var p = new Prompt({
window: window,
title: "Whats your favorite color?",
}).setSingleChoiceItems(items).show(function(data) {
alert("Your favorite color is: " + items[data.button]);
});
setMultiChoiceItems()
Adds a set of multi-choice items to the list. This is very similar to setSingleChoiceItems above, but the list will not dismiss when an item is clicked.
Prompt setMultiChoiceItems(aItems);
Parameters
Takes an array of objects with parameters describing the list items. Objects can have the following parameters:
| Parameter | Description |
label |
The label to show on this list item |
selected |
Whether or not this item is selected. Adding selected to any item will cause all of the items in the list to have an indicator on their right to describe if they're selected or not. |
disabled |
Whether or not this item is disabled. |
children |
Used if this is a header row. Children is an array of menuitems to be shown underneith the header and are indented to indicate they belong inside it. |
submenu |
Used if this row contains a submenu. An indicator will be shown on the right to indicate this item has a submenu. Showing the submenu when this item is selected is up to the implementation. |
Return value
Returns the Prompt that is being modified.
Example
var items = [
{ label: "Shades of red", }
{ label: "Pink", disabled: true, child: true },
{ label: "Maroon", child: true },
{ label: "Green", selected: true },
{ label: "Blue", selected: true },
];
var p = new Prompt({
window: window,
title: "What colors do you like?",
// Without one or more buttons, at least Firefox 34 will close
// the menu after selecting one option.
buttons: [ "OK" ],
}).setMultiChoiceItems(items).show(function(data) {
if (!data.list) {
alert("Cancelled!");
return;
}
var colors = data.list.map(function(i) {
return items[i].label;
});
alert("Your favorite colors are " + colors.join(","));
});