MDN may have intermittent access issues April 18 13:00 - April 19 01:00 UTC. See whistlepig.mozilla.org for all notifications.

mozilla
Your Search Results

    Prompt.jsm

    This article is in need of a technical review.

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

    Document Tags and Contributors

    Contributors to this page: wbamberg, backy0175, wesj, leibovic, Lekensteyn
    Last updated by: Lekensteyn,
    Hide Sidebar