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