1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/embedding/components/windowwatcher/public/nsIPromptService.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,346 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsIDOMWindow;
1.12 +
1.13 +/**
1.14 + * This is the interface to the embeddable prompt service; the service that
1.15 + * implements nsIPrompt. Its interface is designed to be just nsIPrompt, each
1.16 + * method modified to take a parent window parameter.
1.17 + *
1.18 + * Accesskeys can be attached to buttons and checkboxes by inserting an &
1.19 + * before the accesskey character in the checkbox message or button title. For
1.20 + * a real &, use && instead. (A "button title" generally refers to the text
1.21 + * label of a button.)
1.22 + *
1.23 + * One note: in all cases, the parent window parameter can be null. However,
1.24 + * these windows are all intended to have parents. So when no parent is
1.25 + * specified, the implementation should try hard to find a suitable foster
1.26 + * parent.
1.27 + *
1.28 + * Implementations are free to choose how they present the various button
1.29 + * types. For example, while prompts that give the user a choice between OK
1.30 + * and Cancel are required to return a boolean value indicating whether or not
1.31 + * the user accepted the prompt (pressed OK) or rejected the prompt (pressed
1.32 + * Cancel), the implementation of this interface could very well speak the
1.33 + * prompt to the user instead of rendering any visual user-interface. The
1.34 + * standard button types are merely idioms used to convey the nature of the
1.35 + * choice the user is to make.
1.36 + *
1.37 + * Because implementations of this interface may loosely interpret the various
1.38 + * button types, it is advised that text messages passed to these prompts do
1.39 + * not refer to the button types by name. For example, it is inadvisable to
1.40 + * tell the user to "Press OK to proceed." Instead, such a prompt might be
1.41 + * rewritten to ask the user: "Would you like to proceed?"
1.42 + */
1.43 +[scriptable, uuid(1630C61A-325E-49ca-8759-A31B16C47AA5)]
1.44 +interface nsIPromptService : nsISupports
1.45 +{
1.46 + /**
1.47 + * Puts up an alert dialog with an OK button.
1.48 + *
1.49 + * @param aParent
1.50 + * The parent window or null.
1.51 + * @param aDialogTitle
1.52 + * Text to appear in the title of the dialog.
1.53 + * @param aText
1.54 + * Text to appear in the body of the dialog.
1.55 + */
1.56 + void alert(in nsIDOMWindow aParent,
1.57 + in wstring aDialogTitle,
1.58 + in wstring aText);
1.59 +
1.60 + /**
1.61 + * Puts up an alert dialog with an OK button and a labeled checkbox.
1.62 + *
1.63 + * @param aParent
1.64 + * The parent window or null.
1.65 + * @param aDialogTitle
1.66 + * Text to appear in the title of the dialog.
1.67 + * @param aText
1.68 + * Text to appear in the body of the dialog.
1.69 + * @param aCheckMsg
1.70 + * Text to appear with the checkbox.
1.71 + * @param aCheckState
1.72 + * Contains the initial checked state of the checkbox when this method
1.73 + * is called and the final checked state after this method returns.
1.74 + */
1.75 + void alertCheck(in nsIDOMWindow aParent,
1.76 + in wstring aDialogTitle,
1.77 + in wstring aText,
1.78 + in wstring aCheckMsg,
1.79 + inout boolean aCheckState);
1.80 +
1.81 + /**
1.82 + * Puts up a dialog with OK and Cancel buttons.
1.83 + *
1.84 + * @param aParent
1.85 + * The parent window or null.
1.86 + * @param aDialogTitle
1.87 + * Text to appear in the title of the dialog.
1.88 + * @param aText
1.89 + * Text to appear in the body of the dialog.
1.90 + *
1.91 + * @return true for OK, false for Cancel
1.92 + */
1.93 + boolean confirm(in nsIDOMWindow aParent,
1.94 + in wstring aDialogTitle,
1.95 + in wstring aText);
1.96 +
1.97 + /**
1.98 + * Puts up a dialog with OK and Cancel buttons and a labeled checkbox.
1.99 + *
1.100 + * @param aParent
1.101 + * The parent window or null.
1.102 + * @param aDialogTitle
1.103 + * Text to appear in the title of the dialog.
1.104 + * @param aText
1.105 + * Text to appear in the body of the dialog.
1.106 + * @param aCheckMsg
1.107 + * Text to appear with the checkbox.
1.108 + * @param aCheckState
1.109 + * Contains the initial checked state of the checkbox when this method
1.110 + * is called and the final checked state after this method returns.
1.111 + *
1.112 + * @return true for OK, false for Cancel
1.113 + */
1.114 + boolean confirmCheck(in nsIDOMWindow aParent,
1.115 + in wstring aDialogTitle,
1.116 + in wstring aText,
1.117 + in wstring aCheckMsg,
1.118 + inout boolean aCheckState);
1.119 +
1.120 + /**
1.121 + * Button Flags
1.122 + *
1.123 + * The following flags are combined to form the aButtonFlags parameter passed
1.124 + * to confirmEx. See confirmEx for more information on how the flags may be
1.125 + * combined.
1.126 + */
1.127 +
1.128 + /**
1.129 + * Button Position Flags
1.130 + */
1.131 + const unsigned long BUTTON_POS_0 = 1;
1.132 + const unsigned long BUTTON_POS_1 = 1 << 8;
1.133 + const unsigned long BUTTON_POS_2 = 1 << 16;
1.134 +
1.135 + /**
1.136 + * Button Title Flags (used to set the labels of buttons in the prompt)
1.137 + */
1.138 + const unsigned long BUTTON_TITLE_OK = 1;
1.139 + const unsigned long BUTTON_TITLE_CANCEL = 2;
1.140 + const unsigned long BUTTON_TITLE_YES = 3;
1.141 + const unsigned long BUTTON_TITLE_NO = 4;
1.142 + const unsigned long BUTTON_TITLE_SAVE = 5;
1.143 + const unsigned long BUTTON_TITLE_DONT_SAVE = 6;
1.144 + const unsigned long BUTTON_TITLE_REVERT = 7;
1.145 + const unsigned long BUTTON_TITLE_IS_STRING = 127;
1.146 +
1.147 + /**
1.148 + * Button Default Flags (used to select which button is the default one)
1.149 + */
1.150 + const unsigned long BUTTON_POS_0_DEFAULT = 0;
1.151 + const unsigned long BUTTON_POS_1_DEFAULT = 1 << 24;
1.152 + const unsigned long BUTTON_POS_2_DEFAULT = 1 << 25;
1.153 +
1.154 + /**
1.155 + * Causes the buttons to be initially disabled. They are enabled after a
1.156 + * timeout expires. The implementation may interpret this loosely as the
1.157 + * intent is to ensure that the user does not click through a security dialog
1.158 + * too quickly. Strictly speaking, the implementation could choose to ignore
1.159 + * this flag.
1.160 + */
1.161 + const unsigned long BUTTON_DELAY_ENABLE = 1 << 26;
1.162 +
1.163 + /**
1.164 + * Selects the standard set of OK/Cancel buttons.
1.165 + */
1.166 + const unsigned long STD_OK_CANCEL_BUTTONS = (BUTTON_TITLE_OK * BUTTON_POS_0) +
1.167 + (BUTTON_TITLE_CANCEL * BUTTON_POS_1);
1.168 +
1.169 + /**
1.170 + * Selects the standard set of Yes/No buttons.
1.171 + */
1.172 + const unsigned long STD_YES_NO_BUTTONS = (BUTTON_TITLE_YES * BUTTON_POS_0) +
1.173 + (BUTTON_TITLE_NO * BUTTON_POS_1);
1.174 +
1.175 +
1.176 + /**
1.177 + * Puts up a dialog with up to 3 buttons and an optional, labeled checkbox.
1.178 + *
1.179 + * @param aParent
1.180 + * The parent window or null.
1.181 + * @param aDialogTitle
1.182 + * Text to appear in the title of the dialog.
1.183 + * @param aText
1.184 + * Text to appear in the body of the dialog.
1.185 + * @param aButtonFlags
1.186 + * A combination of Button Flags.
1.187 + * @param aButton0Title
1.188 + * Used when button 0 uses TITLE_IS_STRING
1.189 + * @param aButton1Title
1.190 + * Used when button 1 uses TITLE_IS_STRING
1.191 + * @param aButton2Title
1.192 + * Used when button 2 uses TITLE_IS_STRING
1.193 + * @param aCheckMsg
1.194 + * Text to appear with the checkbox. Null if no checkbox.
1.195 + * @param aCheckState
1.196 + * Contains the initial checked state of the checkbox when this method
1.197 + * is called and the final checked state after this method returns.
1.198 + *
1.199 + * @return index of the button pressed.
1.200 + *
1.201 + * Buttons are numbered 0 - 2. The implementation can decide whether the
1.202 + * sequence goes from right to left or left to right. Button 0 is the
1.203 + * default button unless one of the Button Default Flags is specified.
1.204 + *
1.205 + * A button may use a predefined title, specified by one of the Button Title
1.206 + * Flags values. Each title value can be multiplied by a position value to
1.207 + * assign the title to a particular button. If BUTTON_TITLE_IS_STRING is
1.208 + * used for a button, the string parameter for that button will be used. If
1.209 + * the value for a button position is zero, the button will not be shown.
1.210 + *
1.211 + * In general, aButtonFlags is constructed per the following example:
1.212 + *
1.213 + * aButtonFlags = (BUTTON_POS_0) * (BUTTON_TITLE_AAA) +
1.214 + * (BUTTON_POS_1) * (BUTTON_TITLE_BBB) +
1.215 + * BUTTON_POS_1_DEFAULT;
1.216 + *
1.217 + * where "AAA" and "BBB" correspond to one of the button titles.
1.218 + */
1.219 + int32_t confirmEx(in nsIDOMWindow aParent,
1.220 + in wstring aDialogTitle,
1.221 + in wstring aText,
1.222 + in unsigned long aButtonFlags,
1.223 + in wstring aButton0Title,
1.224 + in wstring aButton1Title,
1.225 + in wstring aButton2Title,
1.226 + in wstring aCheckMsg,
1.227 + inout boolean aCheckState);
1.228 +
1.229 + /**
1.230 + * Puts up a dialog with an edit field and an optional, labeled checkbox.
1.231 + *
1.232 + * @param aParent
1.233 + * The parent window or null.
1.234 + * @param aDialogTitle
1.235 + * Text to appear in the title of the dialog.
1.236 + * @param aText
1.237 + * Text to appear in the body of the dialog.
1.238 + * @param aValue
1.239 + * Contains the default value for the dialog field when this method
1.240 + * is called (null value is ok). Upon return, if the user pressed
1.241 + * OK, then this parameter contains a newly allocated string value.
1.242 + * Otherwise, the parameter's value is unmodified.
1.243 + * @param aCheckMsg
1.244 + * Text to appear with the checkbox. If null, check box will not be shown.
1.245 + * @param aCheckState
1.246 + * Contains the initial checked state of the checkbox when this method
1.247 + * is called and the final checked state after this method returns.
1.248 + *
1.249 + * @return true for OK, false for Cancel.
1.250 + */
1.251 + boolean prompt(in nsIDOMWindow aParent,
1.252 + in wstring aDialogTitle,
1.253 + in wstring aText,
1.254 + inout wstring aValue,
1.255 + in wstring aCheckMsg,
1.256 + inout boolean aCheckState);
1.257 +
1.258 + /**
1.259 + * Puts up a dialog with an edit field, a password field, and an optional,
1.260 + * labeled checkbox.
1.261 + *
1.262 + * @param aParent
1.263 + * The parent window or null.
1.264 + * @param aDialogTitle
1.265 + * Text to appear in the title of the dialog.
1.266 + * @param aText
1.267 + * Text to appear in the body of the dialog.
1.268 + * @param aUsername
1.269 + * Contains the default value for the username field when this method
1.270 + * is called (null value is ok). Upon return, if the user pressed OK,
1.271 + * then this parameter contains a newly allocated string value.
1.272 + * Otherwise, the parameter's value is unmodified.
1.273 + * @param aPassword
1.274 + * Contains the default value for the password field when this method
1.275 + * is called (null value is ok). Upon return, if the user pressed OK,
1.276 + * then this parameter contains a newly allocated string value.
1.277 + * Otherwise, the parameter's value is unmodified.
1.278 + * @param aCheckMsg
1.279 + * Text to appear with the checkbox. If null, check box will not be shown.
1.280 + * @param aCheckState
1.281 + * Contains the initial checked state of the checkbox when this method
1.282 + * is called and the final checked state after this method returns.
1.283 + *
1.284 + * @return true for OK, false for Cancel.
1.285 + */
1.286 + boolean promptUsernameAndPassword(in nsIDOMWindow aParent,
1.287 + in wstring aDialogTitle,
1.288 + in wstring aText,
1.289 + inout wstring aUsername,
1.290 + inout wstring aPassword,
1.291 + in wstring aCheckMsg,
1.292 + inout boolean aCheckState);
1.293 +
1.294 + /**
1.295 + * Puts up a dialog with a password field and an optional, labeled checkbox.
1.296 + *
1.297 + * @param aParent
1.298 + * The parent window or null.
1.299 + * @param aDialogTitle
1.300 + * Text to appear in the title of the dialog.
1.301 + * @param aText
1.302 + * Text to appear in the body of the dialog.
1.303 + * @param aPassword
1.304 + * Contains the default value for the password field when this method
1.305 + * is called (null value is ok). Upon return, if the user pressed OK,
1.306 + * then this parameter contains a newly allocated string value.
1.307 + * Otherwise, the parameter's value is unmodified.
1.308 + * @param aCheckMsg
1.309 + * Text to appear with the checkbox. If null, check box will not be shown.
1.310 + * @param aCheckState
1.311 + * Contains the initial checked state of the checkbox when this method
1.312 + * is called and the final checked state after this method returns.
1.313 + *
1.314 + * @return true for OK, false for Cancel.
1.315 + */
1.316 + boolean promptPassword(in nsIDOMWindow aParent,
1.317 + in wstring aDialogTitle,
1.318 + in wstring aText,
1.319 + inout wstring aPassword,
1.320 + in wstring aCheckMsg,
1.321 + inout boolean aCheckState);
1.322 +
1.323 + /**
1.324 + * Puts up a dialog box which has a list box of strings from which the user
1.325 + * may make a single selection.
1.326 + *
1.327 + * @param aParent
1.328 + * The parent window or null.
1.329 + * @param aDialogTitle
1.330 + * Text to appear in the title of the dialog.
1.331 + * @param aText
1.332 + * Text to appear in the body of the dialog.
1.333 + * @param aCount
1.334 + * The length of the aSelectList array parameter.
1.335 + * @param aSelectList
1.336 + * The list of strings to display.
1.337 + * @param aOutSelection
1.338 + * Contains the index of the selected item in the list when this
1.339 + * method returns true.
1.340 + *
1.341 + * @return true for OK, false for Cancel.
1.342 + */
1.343 + boolean select(in nsIDOMWindow aParent,
1.344 + in wstring aDialogTitle,
1.345 + in wstring aText,
1.346 + in uint32_t aCount,
1.347 + [array, size_is(aCount)] in wstring aSelectList,
1.348 + out long aOutSelection);
1.349 +};
