Prompt.jsm

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.

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?",
}).addSingleChoiceItems(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?",
}).addMultiChoiceItems(items).show(function(data) {
  var colors = data.buttons.map(function(button) {
    return items[button].label;
  });
  alert("Your favorite colors are " + colors.join(","));
});

Document Tags and Contributors

Contributors to this page: wbamberg, wesj, leibovic
Last updated by: leibovic,