/embedding/components/windowwatcher/public/nsIPromptService.idl
IDL | 378 lines | 75 code | 19 blank | 284 comment | 0 complexity | e482673eac3d88563b192f2037f015df MD5 | raw file
1/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ 2/* ***** BEGIN LICENSE BLOCK ***** 3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1 4 * 5 * The contents of this file are subject to the Mozilla Public License Version 6 * 1.1 (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * http://www.mozilla.org/MPL/ 9 * 10 * Software distributed under the License is distributed on an "AS IS" basis, 11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License 12 * for the specific language governing rights and limitations under the 13 * License. 14 * 15 * The Original Code is mozilla.org code. 16 * 17 * The Initial Developer of the Original Code is 18 * Netscape Communications Corporation. 19 * Portions created by the Initial Developer are Copyright (C) 2001 20 * the Initial Developer. All Rights Reserved. 21 * 22 * Contributor(s): 23 * 24 * Alternatively, the contents of this file may be used under the terms of 25 * either the GNU General Public License Version 2 or later (the "GPL"), or 26 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), 27 * in which case the provisions of the GPL or the LGPL are applicable instead 28 * of those above. If you wish to allow use of your version of this file only 29 * under the terms of either the GPL or the LGPL, and not to allow others to 30 * use your version of this file under the terms of the MPL, indicate your 31 * decision by deleting the provisions above and replace them with the notice 32 * and other provisions required by the GPL or the LGPL. If you do not delete 33 * the provisions above, a recipient may use your version of this file under 34 * the terms of any one of the MPL, the GPL or the LGPL. 35 * 36 * ***** END LICENSE BLOCK ***** */ 37 38#include "nsISupports.idl" 39 40interface nsIDOMWindow; 41 42/** 43 * This is the interface to the embeddable prompt service; the service that 44 * implements nsIPrompt. Its interface is designed to be just nsIPrompt, each 45 * method modified to take a parent window parameter. 46 * 47 * Accesskeys can be attached to buttons and checkboxes by inserting an & 48 * before the accesskey character in the checkbox message or button title. For 49 * a real &, use && instead. (A "button title" generally refers to the text 50 * label of a button.) 51 * 52 * One note: in all cases, the parent window parameter can be null. However, 53 * these windows are all intended to have parents. So when no parent is 54 * specified, the implementation should try hard to find a suitable foster 55 * parent. 56 * 57 * Implementations are free to choose how they present the various button 58 * types. For example, while prompts that give the user a choice between OK 59 * and Cancel are required to return a boolean value indicating whether or not 60 * the user accepted the prompt (pressed OK) or rejected the prompt (pressed 61 * Cancel), the implementation of this interface could very well speak the 62 * prompt to the user instead of rendering any visual user-interface. The 63 * standard button types are merely idioms used to convey the nature of the 64 * choice the user is to make. 65 * 66 * Because implementations of this interface may loosely interpret the various 67 * button types, it is advised that text messages passed to these prompts do 68 * not refer to the button types by name. For example, it is inadvisable to 69 * tell the user to "Press OK to proceed." Instead, such a prompt might be 70 * rewritten to ask the user: "Would you like to proceed?" 71 */ 72[scriptable, uuid(1630C61A-325E-49ca-8759-A31B16C47AA5)] 73interface nsIPromptService : nsISupports 74{ 75 /** 76 * Puts up an alert dialog with an OK button. 77 * 78 * @param aParent 79 * The parent window or null. 80 * @param aDialogTitle 81 * Text to appear in the title of the dialog. 82 * @param aText 83 * Text to appear in the body of the dialog. 84 */ 85 void alert(in nsIDOMWindow aParent, 86 in wstring aDialogTitle, 87 in wstring aText); 88 89 /** 90 * Puts up an alert dialog with an OK button and a labeled checkbox. 91 * 92 * @param aParent 93 * The parent window or null. 94 * @param aDialogTitle 95 * Text to appear in the title of the dialog. 96 * @param aText 97 * Text to appear in the body of the dialog. 98 * @param aCheckMsg 99 * Text to appear with the checkbox. 100 * @param aCheckState 101 * Contains the initial checked state of the checkbox when this method 102 * is called and the final checked state after this method returns. 103 */ 104 void alertCheck(in nsIDOMWindow aParent, 105 in wstring aDialogTitle, 106 in wstring aText, 107 in wstring aCheckMsg, 108 inout boolean aCheckState); 109 110 /** 111 * Puts up a dialog with OK and Cancel buttons. 112 * 113 * @param aParent 114 * The parent window or null. 115 * @param aDialogTitle 116 * Text to appear in the title of the dialog. 117 * @param aText 118 * Text to appear in the body of the dialog. 119 * 120 * @return true for OK, false for Cancel 121 */ 122 boolean confirm(in nsIDOMWindow aParent, 123 in wstring aDialogTitle, 124 in wstring aText); 125 126 /** 127 * Puts up a dialog with OK and Cancel buttons and a labeled checkbox. 128 * 129 * @param aParent 130 * The parent window or null. 131 * @param aDialogTitle 132 * Text to appear in the title of the dialog. 133 * @param aText 134 * Text to appear in the body of the dialog. 135 * @param aCheckMsg 136 * Text to appear with the checkbox. 137 * @param aCheckState 138 * Contains the initial checked state of the checkbox when this method 139 * is called and the final checked state after this method returns. 140 * 141 * @return true for OK, false for Cancel 142 */ 143 boolean confirmCheck(in nsIDOMWindow aParent, 144 in wstring aDialogTitle, 145 in wstring aText, 146 in wstring aCheckMsg, 147 inout boolean aCheckState); 148 149 /** 150 * Button Flags 151 * 152 * The following flags are combined to form the aButtonFlags parameter passed 153 * to confirmEx. See confirmEx for more information on how the flags may be 154 * combined. 155 */ 156 157 /** 158 * Button Position Flags 159 */ 160 const unsigned long BUTTON_POS_0 = 1; 161 const unsigned long BUTTON_POS_1 = 1 << 8; 162 const unsigned long BUTTON_POS_2 = 1 << 16; 163 164 /** 165 * Button Title Flags (used to set the labels of buttons in the prompt) 166 */ 167 const unsigned long BUTTON_TITLE_OK = 1; 168 const unsigned long BUTTON_TITLE_CANCEL = 2; 169 const unsigned long BUTTON_TITLE_YES = 3; 170 const unsigned long BUTTON_TITLE_NO = 4; 171 const unsigned long BUTTON_TITLE_SAVE = 5; 172 const unsigned long BUTTON_TITLE_DONT_SAVE = 6; 173 const unsigned long BUTTON_TITLE_REVERT = 7; 174 const unsigned long BUTTON_TITLE_IS_STRING = 127; 175 176 /** 177 * Button Default Flags (used to select which button is the default one) 178 */ 179 const unsigned long BUTTON_POS_0_DEFAULT = 0; 180 const unsigned long BUTTON_POS_1_DEFAULT = 1 << 24; 181 const unsigned long BUTTON_POS_2_DEFAULT = 1 << 25; 182 183 /** 184 * Causes the buttons to be initially disabled. They are enabled after a 185 * timeout expires. The implementation may interpret this loosely as the 186 * intent is to ensure that the user does not click through a security dialog 187 * too quickly. Strictly speaking, the implementation could choose to ignore 188 * this flag. 189 */ 190 const unsigned long BUTTON_DELAY_ENABLE = 1 << 26; 191 192 /** 193 * Selects the standard set of OK/Cancel buttons. 194 */ 195 const unsigned long STD_OK_CANCEL_BUTTONS = (BUTTON_TITLE_OK * BUTTON_POS_0) + 196 (BUTTON_TITLE_CANCEL * BUTTON_POS_1); 197 198 /** 199 * Selects the standard set of Yes/No buttons. 200 */ 201 const unsigned long STD_YES_NO_BUTTONS = (BUTTON_TITLE_YES * BUTTON_POS_0) + 202 (BUTTON_TITLE_NO * BUTTON_POS_1); 203 204 205 /** 206 * Puts up a dialog with up to 3 buttons and an optional, labeled checkbox. 207 * 208 * @param aParent 209 * The parent window or null. 210 * @param aDialogTitle 211 * Text to appear in the title of the dialog. 212 * @param aText 213 * Text to appear in the body of the dialog. 214 * @param aButtonFlags 215 * A combination of Button Flags. 216 * @param aButton0Title 217 * Used when button 0 uses TITLE_IS_STRING 218 * @param aButton1Title 219 * Used when button 1 uses TITLE_IS_STRING 220 * @param aButton2Title 221 * Used when button 2 uses TITLE_IS_STRING 222 * @param aCheckMsg 223 * Text to appear with the checkbox. Null if no checkbox. 224 * @param aCheckState 225 * Contains the initial checked state of the checkbox when this method 226 * is called and the final checked state after this method returns. 227 * 228 * @return index of the button pressed. 229 * 230 * Buttons are numbered 0 - 2. The implementation can decide whether the 231 * sequence goes from right to left or left to right. Button 0 is the 232 * default button unless one of the Button Default Flags is specified. 233 * 234 * A button may use a predefined title, specified by one of the Button Title 235 * Flags values. Each title value can be multiplied by a position value to 236 * assign the title to a particular button. If BUTTON_TITLE_IS_STRING is 237 * used for a button, the string parameter for that button will be used. If 238 * the value for a button position is zero, the button will not be shown. 239 * 240 * In general, aButtonFlags is constructed per the following example: 241 * 242 * aButtonFlags = (BUTTON_POS_0) * (BUTTON_TITLE_AAA) + 243 * (BUTTON_POS_1) * (BUTTON_TITLE_BBB) + 244 * BUTTON_POS_1_DEFAULT; 245 * 246 * where "AAA" and "BBB" correspond to one of the button titles. 247 */ 248 PRInt32 confirmEx(in nsIDOMWindow aParent, 249 in wstring aDialogTitle, 250 in wstring aText, 251 in unsigned long aButtonFlags, 252 in wstring aButton0Title, 253 in wstring aButton1Title, 254 in wstring aButton2Title, 255 in wstring aCheckMsg, 256 inout boolean aCheckState); 257 258 /** 259 * Puts up a dialog with an edit field and an optional, labeled checkbox. 260 * 261 * @param aParent 262 * The parent window or null. 263 * @param aDialogTitle 264 * Text to appear in the title of the dialog. 265 * @param aText 266 * Text to appear in the body of the dialog. 267 * @param aValue 268 * Contains the default value for the dialog field when this method 269 * is called (null value is ok). Upon return, if the user pressed 270 * OK, then this parameter contains a newly allocated string value. 271 * Otherwise, the parameter's value is unmodified. 272 * @param aCheckMsg 273 * Text to appear with the checkbox. If null, check box will not be shown. 274 * @param aCheckState 275 * Contains the initial checked state of the checkbox when this method 276 * is called and the final checked state after this method returns. 277 * 278 * @return true for OK, false for Cancel. 279 */ 280 boolean prompt(in nsIDOMWindow aParent, 281 in wstring aDialogTitle, 282 in wstring aText, 283 inout wstring aValue, 284 in wstring aCheckMsg, 285 inout boolean aCheckState); 286 287 /** 288 * Puts up a dialog with an edit field, a password field, and an optional, 289 * labeled checkbox. 290 * 291 * @param aParent 292 * The parent window or null. 293 * @param aDialogTitle 294 * Text to appear in the title of the dialog. 295 * @param aText 296 * Text to appear in the body of the dialog. 297 * @param aUsername 298 * Contains the default value for the username field when this method 299 * is called (null value is ok). Upon return, if the user pressed OK, 300 * then this parameter contains a newly allocated string value. 301 * Otherwise, the parameter's value is unmodified. 302 * @param aPassword 303 * Contains the default value for the password field when this method 304 * is called (null value is ok). Upon return, if the user pressed OK, 305 * then this parameter contains a newly allocated string value. 306 * Otherwise, the parameter's value is unmodified. 307 * @param aCheckMsg 308 * Text to appear with the checkbox. If null, check box will not be shown. 309 * @param aCheckState 310 * Contains the initial checked state of the checkbox when this method 311 * is called and the final checked state after this method returns. 312 * 313 * @return true for OK, false for Cancel. 314 */ 315 boolean promptUsernameAndPassword(in nsIDOMWindow aParent, 316 in wstring aDialogTitle, 317 in wstring aText, 318 inout wstring aUsername, 319 inout wstring aPassword, 320 in wstring aCheckMsg, 321 inout boolean aCheckState); 322 323 /** 324 * Puts up a dialog with a password field and an optional, labeled checkbox. 325 * 326 * @param aParent 327 * The parent window or null. 328 * @param aDialogTitle 329 * Text to appear in the title of the dialog. 330 * @param aText 331 * Text to appear in the body of the dialog. 332 * @param aPassword 333 * Contains the default value for the password field when this method 334 * is called (null value is ok). Upon return, if the user pressed OK, 335 * then this parameter contains a newly allocated string value. 336 * Otherwise, the parameter's value is unmodified. 337 * @param aCheckMsg 338 * Text to appear with the checkbox. If null, check box will not be shown. 339 * @param aCheckState 340 * Contains the initial checked state of the checkbox when this method 341 * is called and the final checked state after this method returns. 342 * 343 * @return true for OK, false for Cancel. 344 */ 345 boolean promptPassword(in nsIDOMWindow aParent, 346 in wstring aDialogTitle, 347 in wstring aText, 348 inout wstring aPassword, 349 in wstring aCheckMsg, 350 inout boolean aCheckState); 351 352 /** 353 * Puts up a dialog box which has a list box of strings from which the user 354 * may make a single selection. 355 * 356 * @param aParent 357 * The parent window or null. 358 * @param aDialogTitle 359 * Text to appear in the title of the dialog. 360 * @param aText 361 * Text to appear in the body of the dialog. 362 * @param aCount 363 * The length of the aSelectList array parameter. 364 * @param aSelectList 365 * The list of strings to display. 366 * @param aOutSelection 367 * Contains the index of the selected item in the list when this 368 * method returns true. 369 * 370 * @return true for OK, false for Cancel. 371 */ 372 boolean select(in nsIDOMWindow aParent, 373 in wstring aDialogTitle, 374 in wstring aText, 375 in PRUint32 aCount, 376 [array, size_is(aCount)] in wstring aSelectList, 377 out long aOutSelection); 378};