PageRenderTime 19ms CodeModel.GetById 13ms app.highlight 2ms RepoModel.GetById 1ms app.codeStats 0ms

/embedding/components/windowwatcher/public/nsIPromptService.idl

http://github.com/zpao/v8monkey
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};