confirm

confirm

Displays a modal confirmation dialog.

Method of

Install object

Syntax

int confirm( String aText );
int confirm( String aText,
             String aDialogTitle,
             Number aButtonFlags,
             String aButton0Title,
             String aButton1Title,
             String aButton2Title,
             String aCheckMsg,
             Object aCheckState );

Parameters

The second, extended confirm() method is supported starting with Gecko 1.8. It accepts any number of parameters up to 8. Previous Gecko versions only support the first, one-parameter method and will throw an error on occuring the extended form. See the notes at the end of this document for a safe way to implement a fallback.

aText

The string to be displayed in the confirmation dialog. This string is typically in the form of a prompt for the user (e.g., "Are you sure you want to delete the selected file(s)?").

aDialogTitle

The string to be used as the dialog title. Defaults to "Confirm" (or the localized equivalent).

aButtonFlags

A set of flags defining the buttons that should appear in the dialog. The value is calculated by multiplying the corresponding button position constant with a button title constant for each button, then adding the results and any additional options (see Other constants).

Button position constants

• BUTTON_POS_0: The first logical button
• BUTTON_POS_1: The second logical button
• BUTTON_POS_2: The third logical button

Button title constants

• BUTTON_TITLE_OK: An 'OK' button
• BUTTON_TITLE_CANCEL: A 'Cancel' button
• BUTTON_TITLE_YES: A 'Yes' button
• BUTTON_TITLE_NO: A 'No' button
• BUTTON_TITLE_SAVE: A 'Save' button
• BUTTON_TITLE_DONT_SAVE: A 'Don't save' button
• BUTTON_TITLE_REVERT: A 'Revert' button
• BUTTON_TITLE_IS_STRING: Custom title specified by the corresponding aButtonXTitle parameter

Other constants

• BUTTON_POS_0_DEFAULT: Specifies button 0 as the default button. Unless specified otherwise, this is the default.
• BUTTON_POS_1_DEFAULT: Specifies button 1 as the default button.
• BUTTON_POS_2_DEFAULT: Specifies button 2 as the default button.
• BUTTON_DELAY_ENABLE: Specifies that the buttons should only become clickable after a certain delay. Note that this only applies to buttons 0 and 2, not button 1 (the "cancel" button).
• STD_OK_CANCEL_BUTTONS: Use this instead of the constants above to have standard 'OK' and 'Cancel' buttons. If you leave out aButtonFlags, this is the default.
• STD_YES_NO_BUTTONS: Use this instead of the constants above to have standard 'Yes' and 'No' buttons.

Warning: do not make any assumptions on the button placement - the underlying implementation can freely decide where each of the three buttons is placed. The following examples show the result of calling confirm() with three buttons 0='A', 1='B' and 2='C'.

Firefox on Linux

Mozilla Application Suite on Win32

It is therefore recommended to only use two buttons wherever possible, and to keep in mind that button 1 has the same return value as "window closed" (see below).

aButton0Title

Custom title for button 0.

aButton1Title

Custom title for button 1.

aButton2Title

Custom title for button 2.

aCheckMsg

A string to display as a checkbox label.

aCheckState

An object with a boolean value property representing the state of the checkbox: When the dialog box is shown, its checkbox will be checked when this object's value is true. After the user presses a button (or closes the window), the value property is updated according to the checkbox.

var check = { value: false };
var button = confirm("Are you sure you want to install FooBar 0.1?",
                     "Confirm",
                     STD_YES_NO_BUTTONS,
                     null,
                     null,
                     null,
                     "Install FluxCompensator 0.4 as well",
                     check);

Returns

The return value is an integer indicating which button the user selected:

Previous versions of the XPInstall API stated the return value of confirm() to be a Boolean. That is incorrect, confirm() always returned a plain integer (in pre-Gecko-1.8 versions either 0 or 1).

Notes

The preferred method for detecting support for custom dialog boxes is querying the existence of the button constants. Other approaches (e.g. buildID comparisons) are not recommended.

if ("BUTTON_POS_0" in Install) {
  // Use extended confirm() method
} else {
  // Use classic confirm() method
}