nsIPromptService.rst

Enable keyboard shortcuts

==============

Prompt Service

==============

The `nsIPromptService` provides methods for opening various types of prompts.

See the `interface documentation <nsIPromptService-reference.html>`_ for a list

of prompt types.

Every prompt method has 3 different versions:

- **Prompt by window**:

  This is considered the legacy way of prompting and only works if the window

  you want to prompt for is in the same process.

  Only supports window prompts.

- **Prompt by browsing context (synchronous)**:

  Use a browsing context as parent for the prompt. Works cross process from

  parent and content process.

- **Prompt by browsing context (asynchronous)**:

  Returns a promise which resolves once the prompt closes.

The synchronous prompt methods use call by reference (XPCOM `inout` or `out`) to

return the updated prompt arguments to the caller.

When prompting async the arguments are passed in by value. Prompt results are

returned in an `nsIPropertyBag` when the Promise resolves.

.. note::

    If you don't provide a parent window or browsing context the prompt service

    will fallback to a window prompt.

    The same goes for browsing contexts of chrome windows, because there is no

    clear association to a browser / tab.

Examples

--------

JavaScript Sync

~~~~~~~~~~~~~~~

Here is an example of opening a confirm prompt from JavaScript. We are in the

parent process and we want to show a tab prompt:

.. code-block:: javascript

    // Get the browsing context for the currently selected tab

    let browsingContext = gBrowser.selectedBrowser.browsingContext;

    // Specify prompt type, can be MODAL_TYPE_TAB, MODAL_TYPE_CONTENT,

    // MODAL_TYPE_WINDOW

    let modalType = Services.prompt.MODAL_TYPE_TAB;

    // Object for checkbox state to pass by reference.

    let check = { value: false };

    // Prompt synchronously and store result

    let confirmed = Services.prompt.confirmCheckBC(browsingContext, modalType,

    "My Title", "Hello, World!", "Check this box if you agree", check);

    // check.value now contains final checkbox state

    // confirmed is a boolean which indicates whether the user pressed ok (true)

    // or cancel (false)

    console.debug("User checked checkbox?", check.value);

    console.debug("User confirmed prompt?", confirmed);

JavaScript Async

~~~~~~~~~~~~~~~~

The same prompt as above, but called async:

.. code-block:: javascript

    // Get the browsing context for the currently selected tab

    let browsingContext = gBrowser.selectedBrowser.browsingContext;

    // Specify prompt type, can be MODAL_TYPE_TAB, MODAL_TYPE_CONTENT,

    // MODAL_TYPE_WINDOW

    let modalType = Services.prompt.MODAL_TYPE_TAB;

    // Note that the checkbox state variable is not an object in this case,

    because we get the checkbox result via the result object.

    let check = false;

    // Prompt asynchronously and await result

    let propBag = await Services.prompt.asyncConfirmCheck(browsingContext,

                                                          modalType,

                                                          "My Title",

                                                          "Hello, World!",

                                                          "Check this box if you agree",

                                                          check);

    let ok = propBag.getProperty("ok");

    let checked = propBag.getProperty("checked");

    // ok is the boolean indicating if the user clicked "ok" (true) or

    // "cancel" (false).

    // checked is a boolean indicating the final checkbox state

    console.debug("User checked checkbox?", checked);

    console.debug("User confirmed prompt?", ok);

C++ Sync

~~~~~~~~

.. code-block:: cpp

      nsCOMPtr<nsIPromptService> promptSvc =

        do_GetService("@mozilla.org/prompter;1");

      if(!promptSvc) {

        // Error handling

        return;

      // Assuming you have the browsing context as a member.

      // You might need to get the browsing context from somewhere else.

      BrowsingContext* bc = mBrowsingContext;

      bool ok;

      bool checked = false;

      nsresult rv = promptSvc->confirmCheck(mBrowsingContext,

                                            nsIPromptService::MODAL_TYPE_TAB,

                                            "My Title"_ns

                                            "Hello, World!"_ns,

                                            "Check this box if you agree"_ns,

                                            &checked, &ok);

      // ok is the boolean indicating if the user clicked "ok" (true) or

      // "cancel" (false).

      // checked is a boolean indicating the final checkbox state

C++ Async

~~~~~~~~~

.. code-block:: cpp

      nsCOMPtr<nsIPromptService> promptSvc =

        do_GetService("@mozilla.org/prompter;1");

      if(!promptSvc) {

        // Error handling

        return;

      bool checked = false;

      Promise* promise;

      // Assuming you have the browsing context as a member.

      // You might need to get the browsing context from somewhere else.

      BrowsingContext* bc = mBrowsingContext;

      // As opposed to the sync case, here we pass the checked flag by value

      nsresult rv = promptSvc->confirmCheckAsync(mBrowsingContext,

                                                 nsIPromptService::MODAL_TYPE_TAB, "My Title"_ns,

                                                 "Hello, World!"_ns,

                                                 "Check this box if you agree"_ns,

                                                 checked, promise);

      // Attach a promise handler

      RefPtr<PromptHandler> handler = new PromptHandler(promise);

      promise->AppendNativeHandler(handler);

Then, in your promise handler callback function:

.. code-block:: cpp

      void PromptHandler::ResolvedCallback(JSContext* aCx,

                                       JS::Handle<JS::Value> aValue) {

        JS::Rooted<JSObject*> detailObj(aCx, &aValue.toObject());

        // Convert the JSObject back to a property bag

        nsresult rv;

        nsCOMPtr<nsIPropertyBag2> propBag;

        rv = UnwrapArg<nsIPropertyBag2>(aCx, detailObj, getter_AddRefs(propBag));

        if (NS_FAILED(rv)) return;

        bool ok;

        bool checked;

        propBag->GetPropertyAsBool(u"ok"_ns, &ok);

        propBag->GetPropertyAsBool(u"checked"_ns, &checked);

        // ok is the boolean indicating if the user clicked "ok" (true) or

        // "cancel" (false).

        // checked is a boolean indicating the final checkbox state.

For a full list of prompt methods check

`nsIPromptService reference <nsIPromptService-reference.html>`_.