Prompt.jsm

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:

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

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

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.

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.

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.

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.

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:

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:

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(","));
});