michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: #include "nsISupports.idl" michael@0: michael@0: interface nsIDOMWindow; michael@0: michael@0: /** michael@0: * This is the interface to the embeddable prompt service; the service that michael@0: * implements nsIPrompt. Its interface is designed to be just nsIPrompt, each michael@0: * method modified to take a parent window parameter. michael@0: * michael@0: * Accesskeys can be attached to buttons and checkboxes by inserting an & michael@0: * before the accesskey character in the checkbox message or button title. For michael@0: * a real &, use && instead. (A "button title" generally refers to the text michael@0: * label of a button.) michael@0: * michael@0: * One note: in all cases, the parent window parameter can be null. However, michael@0: * these windows are all intended to have parents. So when no parent is michael@0: * specified, the implementation should try hard to find a suitable foster michael@0: * parent. michael@0: * michael@0: * Implementations are free to choose how they present the various button michael@0: * types. For example, while prompts that give the user a choice between OK michael@0: * and Cancel are required to return a boolean value indicating whether or not michael@0: * the user accepted the prompt (pressed OK) or rejected the prompt (pressed michael@0: * Cancel), the implementation of this interface could very well speak the michael@0: * prompt to the user instead of rendering any visual user-interface. The michael@0: * standard button types are merely idioms used to convey the nature of the michael@0: * choice the user is to make. michael@0: * michael@0: * Because implementations of this interface may loosely interpret the various michael@0: * button types, it is advised that text messages passed to these prompts do michael@0: * not refer to the button types by name. For example, it is inadvisable to michael@0: * tell the user to "Press OK to proceed." Instead, such a prompt might be michael@0: * rewritten to ask the user: "Would you like to proceed?" michael@0: */ michael@0: [scriptable, uuid(1630C61A-325E-49ca-8759-A31B16C47AA5)] michael@0: interface nsIPromptService : nsISupports michael@0: { michael@0: /** michael@0: * Puts up an alert dialog with an OK button. michael@0: * michael@0: * @param aParent michael@0: * The parent window or null. michael@0: * @param aDialogTitle michael@0: * Text to appear in the title of the dialog. michael@0: * @param aText michael@0: * Text to appear in the body of the dialog. michael@0: */ michael@0: void alert(in nsIDOMWindow aParent, michael@0: in wstring aDialogTitle, michael@0: in wstring aText); michael@0: michael@0: /** michael@0: * Puts up an alert dialog with an OK button and a labeled checkbox. michael@0: * michael@0: * @param aParent michael@0: * The parent window or null. michael@0: * @param aDialogTitle michael@0: * Text to appear in the title of the dialog. michael@0: * @param aText michael@0: * Text to appear in the body of the dialog. michael@0: * @param aCheckMsg michael@0: * Text to appear with the checkbox. michael@0: * @param aCheckState michael@0: * Contains the initial checked state of the checkbox when this method michael@0: * is called and the final checked state after this method returns. michael@0: */ michael@0: void alertCheck(in nsIDOMWindow aParent, michael@0: in wstring aDialogTitle, michael@0: in wstring aText, michael@0: in wstring aCheckMsg, michael@0: inout boolean aCheckState); michael@0: michael@0: /** michael@0: * Puts up a dialog with OK and Cancel buttons. michael@0: * michael@0: * @param aParent michael@0: * The parent window or null. michael@0: * @param aDialogTitle michael@0: * Text to appear in the title of the dialog. michael@0: * @param aText michael@0: * Text to appear in the body of the dialog. michael@0: * michael@0: * @return true for OK, false for Cancel michael@0: */ michael@0: boolean confirm(in nsIDOMWindow aParent, michael@0: in wstring aDialogTitle, michael@0: in wstring aText); michael@0: michael@0: /** michael@0: * Puts up a dialog with OK and Cancel buttons and a labeled checkbox. michael@0: * michael@0: * @param aParent michael@0: * The parent window or null. michael@0: * @param aDialogTitle michael@0: * Text to appear in the title of the dialog. michael@0: * @param aText michael@0: * Text to appear in the body of the dialog. michael@0: * @param aCheckMsg michael@0: * Text to appear with the checkbox. michael@0: * @param aCheckState michael@0: * Contains the initial checked state of the checkbox when this method michael@0: * is called and the final checked state after this method returns. michael@0: * michael@0: * @return true for OK, false for Cancel michael@0: */ michael@0: boolean confirmCheck(in nsIDOMWindow aParent, michael@0: in wstring aDialogTitle, michael@0: in wstring aText, michael@0: in wstring aCheckMsg, michael@0: inout boolean aCheckState); michael@0: michael@0: /** michael@0: * Button Flags michael@0: * michael@0: * The following flags are combined to form the aButtonFlags parameter passed michael@0: * to confirmEx. See confirmEx for more information on how the flags may be michael@0: * combined. michael@0: */ michael@0: michael@0: /** michael@0: * Button Position Flags michael@0: */ michael@0: const unsigned long BUTTON_POS_0 = 1; michael@0: const unsigned long BUTTON_POS_1 = 1 << 8; michael@0: const unsigned long BUTTON_POS_2 = 1 << 16; michael@0: michael@0: /** michael@0: * Button Title Flags (used to set the labels of buttons in the prompt) michael@0: */ michael@0: const unsigned long BUTTON_TITLE_OK = 1; michael@0: const unsigned long BUTTON_TITLE_CANCEL = 2; michael@0: const unsigned long BUTTON_TITLE_YES = 3; michael@0: const unsigned long BUTTON_TITLE_NO = 4; michael@0: const unsigned long BUTTON_TITLE_SAVE = 5; michael@0: const unsigned long BUTTON_TITLE_DONT_SAVE = 6; michael@0: const unsigned long BUTTON_TITLE_REVERT = 7; michael@0: const unsigned long BUTTON_TITLE_IS_STRING = 127; michael@0: michael@0: /** michael@0: * Button Default Flags (used to select which button is the default one) michael@0: */ michael@0: const unsigned long BUTTON_POS_0_DEFAULT = 0; michael@0: const unsigned long BUTTON_POS_1_DEFAULT = 1 << 24; michael@0: const unsigned long BUTTON_POS_2_DEFAULT = 1 << 25; michael@0: michael@0: /** michael@0: * Causes the buttons to be initially disabled. They are enabled after a michael@0: * timeout expires. The implementation may interpret this loosely as the michael@0: * intent is to ensure that the user does not click through a security dialog michael@0: * too quickly. Strictly speaking, the implementation could choose to ignore michael@0: * this flag. michael@0: */ michael@0: const unsigned long BUTTON_DELAY_ENABLE = 1 << 26; michael@0: michael@0: /** michael@0: * Selects the standard set of OK/Cancel buttons. michael@0: */ michael@0: const unsigned long STD_OK_CANCEL_BUTTONS = (BUTTON_TITLE_OK * BUTTON_POS_0) + michael@0: (BUTTON_TITLE_CANCEL * BUTTON_POS_1); michael@0: michael@0: /** michael@0: * Selects the standard set of Yes/No buttons. michael@0: */ michael@0: const unsigned long STD_YES_NO_BUTTONS = (BUTTON_TITLE_YES * BUTTON_POS_0) + michael@0: (BUTTON_TITLE_NO * BUTTON_POS_1); michael@0: michael@0: michael@0: /** michael@0: * Puts up a dialog with up to 3 buttons and an optional, labeled checkbox. michael@0: * michael@0: * @param aParent michael@0: * The parent window or null. michael@0: * @param aDialogTitle michael@0: * Text to appear in the title of the dialog. michael@0: * @param aText michael@0: * Text to appear in the body of the dialog. michael@0: * @param aButtonFlags michael@0: * A combination of Button Flags. michael@0: * @param aButton0Title michael@0: * Used when button 0 uses TITLE_IS_STRING michael@0: * @param aButton1Title michael@0: * Used when button 1 uses TITLE_IS_STRING michael@0: * @param aButton2Title michael@0: * Used when button 2 uses TITLE_IS_STRING michael@0: * @param aCheckMsg michael@0: * Text to appear with the checkbox. Null if no checkbox. michael@0: * @param aCheckState michael@0: * Contains the initial checked state of the checkbox when this method michael@0: * is called and the final checked state after this method returns. michael@0: * michael@0: * @return index of the button pressed. michael@0: * michael@0: * Buttons are numbered 0 - 2. The implementation can decide whether the michael@0: * sequence goes from right to left or left to right. Button 0 is the michael@0: * default button unless one of the Button Default Flags is specified. michael@0: * michael@0: * A button may use a predefined title, specified by one of the Button Title michael@0: * Flags values. Each title value can be multiplied by a position value to michael@0: * assign the title to a particular button. If BUTTON_TITLE_IS_STRING is michael@0: * used for a button, the string parameter for that button will be used. If michael@0: * the value for a button position is zero, the button will not be shown. michael@0: * michael@0: * In general, aButtonFlags is constructed per the following example: michael@0: * michael@0: * aButtonFlags = (BUTTON_POS_0) * (BUTTON_TITLE_AAA) + michael@0: * (BUTTON_POS_1) * (BUTTON_TITLE_BBB) + michael@0: * BUTTON_POS_1_DEFAULT; michael@0: * michael@0: * where "AAA" and "BBB" correspond to one of the button titles. michael@0: */ michael@0: int32_t confirmEx(in nsIDOMWindow aParent, michael@0: in wstring aDialogTitle, michael@0: in wstring aText, michael@0: in unsigned long aButtonFlags, michael@0: in wstring aButton0Title, michael@0: in wstring aButton1Title, michael@0: in wstring aButton2Title, michael@0: in wstring aCheckMsg, michael@0: inout boolean aCheckState); michael@0: michael@0: /** michael@0: * Puts up a dialog with an edit field and an optional, labeled checkbox. michael@0: * michael@0: * @param aParent michael@0: * The parent window or null. michael@0: * @param aDialogTitle michael@0: * Text to appear in the title of the dialog. michael@0: * @param aText michael@0: * Text to appear in the body of the dialog. michael@0: * @param aValue michael@0: * Contains the default value for the dialog field when this method michael@0: * is called (null value is ok). Upon return, if the user pressed michael@0: * OK, then this parameter contains a newly allocated string value. michael@0: * Otherwise, the parameter's value is unmodified. michael@0: * @param aCheckMsg michael@0: * Text to appear with the checkbox. If null, check box will not be shown. michael@0: * @param aCheckState michael@0: * Contains the initial checked state of the checkbox when this method michael@0: * is called and the final checked state after this method returns. michael@0: * michael@0: * @return true for OK, false for Cancel. michael@0: */ michael@0: boolean prompt(in nsIDOMWindow aParent, michael@0: in wstring aDialogTitle, michael@0: in wstring aText, michael@0: inout wstring aValue, michael@0: in wstring aCheckMsg, michael@0: inout boolean aCheckState); michael@0: michael@0: /** michael@0: * Puts up a dialog with an edit field, a password field, and an optional, michael@0: * labeled checkbox. michael@0: * michael@0: * @param aParent michael@0: * The parent window or null. michael@0: * @param aDialogTitle michael@0: * Text to appear in the title of the dialog. michael@0: * @param aText michael@0: * Text to appear in the body of the dialog. michael@0: * @param aUsername michael@0: * Contains the default value for the username field when this method michael@0: * is called (null value is ok). Upon return, if the user pressed OK, michael@0: * then this parameter contains a newly allocated string value. michael@0: * Otherwise, the parameter's value is unmodified. michael@0: * @param aPassword michael@0: * Contains the default value for the password field when this method michael@0: * is called (null value is ok). Upon return, if the user pressed OK, michael@0: * then this parameter contains a newly allocated string value. michael@0: * Otherwise, the parameter's value is unmodified. michael@0: * @param aCheckMsg michael@0: * Text to appear with the checkbox. If null, check box will not be shown. michael@0: * @param aCheckState michael@0: * Contains the initial checked state of the checkbox when this method michael@0: * is called and the final checked state after this method returns. michael@0: * michael@0: * @return true for OK, false for Cancel. michael@0: */ michael@0: boolean promptUsernameAndPassword(in nsIDOMWindow aParent, michael@0: in wstring aDialogTitle, michael@0: in wstring aText, michael@0: inout wstring aUsername, michael@0: inout wstring aPassword, michael@0: in wstring aCheckMsg, michael@0: inout boolean aCheckState); michael@0: michael@0: /** michael@0: * Puts up a dialog with a password field and an optional, labeled checkbox. michael@0: * michael@0: * @param aParent michael@0: * The parent window or null. michael@0: * @param aDialogTitle michael@0: * Text to appear in the title of the dialog. michael@0: * @param aText michael@0: * Text to appear in the body of the dialog. michael@0: * @param aPassword michael@0: * Contains the default value for the password field when this method michael@0: * is called (null value is ok). Upon return, if the user pressed OK, michael@0: * then this parameter contains a newly allocated string value. michael@0: * Otherwise, the parameter's value is unmodified. michael@0: * @param aCheckMsg michael@0: * Text to appear with the checkbox. If null, check box will not be shown. michael@0: * @param aCheckState michael@0: * Contains the initial checked state of the checkbox when this method michael@0: * is called and the final checked state after this method returns. michael@0: * michael@0: * @return true for OK, false for Cancel. michael@0: */ michael@0: boolean promptPassword(in nsIDOMWindow aParent, michael@0: in wstring aDialogTitle, michael@0: in wstring aText, michael@0: inout wstring aPassword, michael@0: in wstring aCheckMsg, michael@0: inout boolean aCheckState); michael@0: michael@0: /** michael@0: * Puts up a dialog box which has a list box of strings from which the user michael@0: * may make a single selection. michael@0: * michael@0: * @param aParent michael@0: * The parent window or null. michael@0: * @param aDialogTitle michael@0: * Text to appear in the title of the dialog. michael@0: * @param aText michael@0: * Text to appear in the body of the dialog. michael@0: * @param aCount michael@0: * The length of the aSelectList array parameter. michael@0: * @param aSelectList michael@0: * The list of strings to display. michael@0: * @param aOutSelection michael@0: * Contains the index of the selected item in the list when this michael@0: * method returns true. michael@0: * michael@0: * @return true for OK, false for Cancel. michael@0: */ michael@0: boolean select(in nsIDOMWindow aParent, michael@0: in wstring aDialogTitle, michael@0: in wstring aText, michael@0: in uint32_t aCount, michael@0: [array, size_is(aCount)] in wstring aSelectList, michael@0: out long aOutSelection); michael@0: };