==============
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>`_.
