PageRenderTime 134ms CodeModel.GetById 101ms app.highlight 4ms RepoModel.GetById 26ms app.codeStats 0ms

/gecko_sdk/idl/nsIPromptService.idl

http://firefox-mac-pdf.googlecode.com/
IDL | 380 lines | 75 code | 19 blank | 286 comment | 0 complexity | 6b93a57e40f7e44c487cc65036a446e9 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 * @status FROZEN
 73 */
 74[scriptable, uuid(1630C61A-325E-49ca-8759-A31B16C47AA5)]
 75interface nsIPromptService : nsISupports
 76{
 77  /**
 78   * Puts up an alert dialog with an OK button.
 79   *
 80   * @param aParent
 81   *        The parent window or null.
 82   * @param aDialogTitle
 83   *        Text to appear in the title of the dialog.
 84   * @param aText
 85   *        Text to appear in the body of the dialog.
 86   */
 87  void alert(in nsIDOMWindow aParent,
 88             in wstring aDialogTitle,
 89             in wstring aText);
 90
 91  /**
 92   * Puts up an alert dialog with an OK button and a labeled checkbox.
 93   *
 94   * @param aParent
 95   *        The parent window or null.
 96   * @param aDialogTitle
 97   *        Text to appear in the title of the dialog.
 98   * @param aText
 99   *        Text to appear in the body of the dialog.
100   * @param aCheckMsg
101   *        Text to appear with the checkbox.
102   * @param aCheckState
103   *        Contains the initial checked state of the checkbox when this method
104   *        is called and the final checked state after this method returns.
105   */
106  void alertCheck(in nsIDOMWindow aParent,
107                  in wstring aDialogTitle,
108                  in wstring aText,
109                  in wstring aCheckMsg,
110                  inout boolean aCheckState);
111
112  /**
113   * Puts up a dialog with OK and Cancel buttons.
114   *
115   * @param aParent
116   *        The parent window or null.
117   * @param aDialogTitle
118   *        Text to appear in the title of the dialog.
119   * @param aText
120   *        Text to appear in the body of the dialog.
121   *
122   * @return true for OK, false for Cancel
123   */
124  boolean confirm(in nsIDOMWindow aParent,
125                  in wstring aDialogTitle,
126                  in wstring aText);
127
128  /**
129   * Puts up a dialog with OK and Cancel buttons and a labeled checkbox.
130   *
131   * @param aParent
132   *        The parent window or null.
133   * @param aDialogTitle
134   *        Text to appear in the title of the dialog.
135   * @param aText
136   *        Text to appear in the body of the dialog.
137   * @param aCheckMsg
138   *        Text to appear with the checkbox.
139   * @param aCheckState
140   *        Contains the initial checked state of the checkbox when this method
141   *        is called and the final checked state after this method returns.
142   *
143   * @return true for OK, false for Cancel
144   */
145  boolean confirmCheck(in nsIDOMWindow aParent,
146                       in wstring aDialogTitle,
147                       in wstring aText,
148                       in wstring aCheckMsg,
149                       inout boolean aCheckState);
150
151  /**
152   * Button Flags
153   *
154   * The following flags are combined to form the aButtonFlags parameter passed
155   * to confirmEx.  See confirmEx for more information on how the flags may be
156   * combined.
157   */
158   
159  /**
160   * Button Position Flags
161   */
162  const unsigned long BUTTON_POS_0              = 1;
163  const unsigned long BUTTON_POS_1              = 1 << 8;
164  const unsigned long BUTTON_POS_2              = 1 << 16;
165     
166  /**
167   * Button Title Flags (used to set the labels of buttons in the prompt)
168   */
169  const unsigned long BUTTON_TITLE_OK            = 1;
170  const unsigned long BUTTON_TITLE_CANCEL        = 2;
171  const unsigned long BUTTON_TITLE_YES           = 3;
172  const unsigned long BUTTON_TITLE_NO            = 4;
173  const unsigned long BUTTON_TITLE_SAVE          = 5;
174  const unsigned long BUTTON_TITLE_DONT_SAVE     = 6;
175  const unsigned long BUTTON_TITLE_REVERT        = 7;
176  const unsigned long BUTTON_TITLE_IS_STRING     = 127;
177  
178  /**
179   * Button Default Flags (used to select which button is the default one)
180   */
181  const unsigned long BUTTON_POS_0_DEFAULT       = 0;
182  const unsigned long BUTTON_POS_1_DEFAULT       = 1 << 24;
183  const unsigned long BUTTON_POS_2_DEFAULT       = 1 << 25;
184
185  /**
186   * Causes the buttons to be initially disabled.  They are enabled after a
187   * timeout expires.  The implementation may interpret this loosely as the
188   * intent is to ensure that the user does not click through a security dialog
189   * too quickly.  Strictly speaking, the implementation could choose to ignore
190   * this flag.
191   */
192  const unsigned long BUTTON_DELAY_ENABLE        = 1 << 26;
193
194  /**
195   * Selects the standard set of OK/Cancel buttons.
196   */
197  const unsigned long STD_OK_CANCEL_BUTTONS      = (BUTTON_TITLE_OK     * BUTTON_POS_0) +
198                                                   (BUTTON_TITLE_CANCEL * BUTTON_POS_1);
199
200  /**
201   * Selects the standard set of Yes/No buttons.
202   */
203  const unsigned long STD_YES_NO_BUTTONS         = (BUTTON_TITLE_YES * BUTTON_POS_0) +
204                                                   (BUTTON_TITLE_NO  * BUTTON_POS_1);
205
206
207  /**
208   * Puts up a dialog with up to 3 buttons and an optional, labeled checkbox.
209   *
210   * @param aParent
211   *        The parent window or null.
212   * @param aDialogTitle
213   *        Text to appear in the title of the dialog.
214   * @param aText
215   *        Text to appear in the body of the dialog.
216   * @param aButtonFlags
217   *        A combination of Button Flags.
218   * @param aButton0Title
219   *        Used when button 0 uses TITLE_IS_STRING
220   * @param aButton1Title
221   *        Used when button 1 uses TITLE_IS_STRING
222   * @param aButton2Title
223   *        Used when button 2 uses TITLE_IS_STRING
224   * @param aCheckMsg
225   *        Text to appear with the checkbox.  Null if no checkbox.
226   * @param aCheckState    
227   *        Contains the initial checked state of the checkbox when this method
228   *        is called and the final checked state after this method returns.
229   *
230   * @return index of the button pressed.
231   *
232   * Buttons are numbered 0 - 2. The implementation can decide whether the
233   * sequence goes from right to left or left to right.  Button 0 is the
234   * default button unless one of the Button Default Flags is specified.
235   *
236   * A button may use a predefined title, specified by one of the Button Title
237   * Flags values.  Each title value can be multiplied by a position value to
238   * assign the title to a particular button.  If BUTTON_TITLE_IS_STRING is
239   * used for a button, the string parameter for that button will be used.  If
240   * the value for a button position is zero, the button will not be shown.
241   *
242   * In general, aButtonFlags is constructed per the following example:
243   *
244   *   aButtonFlags = (BUTTON_POS_0) * (BUTTON_TITLE_AAA) +
245   *                  (BUTTON_POS_1) * (BUTTON_TITLE_BBB) +
246   *                   BUTTON_POS_1_DEFAULT;
247   *
248   * where "AAA" and "BBB" correspond to one of the button titles.
249   */
250  PRInt32 confirmEx(in nsIDOMWindow aParent,
251                    in wstring aDialogTitle,
252                    in wstring aText,
253                    in unsigned long aButtonFlags,
254                    in wstring aButton0Title,
255                    in wstring aButton1Title,
256                    in wstring aButton2Title,
257                    in wstring aCheckMsg,
258                    inout boolean aCheckState);
259
260  /**
261   * Puts up a dialog with an edit field and an optional, labeled checkbox.
262   *
263   * @param aParent
264   *        The parent window or null.
265   * @param aDialogTitle
266   *        Text to appear in the title of the dialog.
267   * @param aText
268   *        Text to appear in the body of the dialog.
269   * @param aValue
270   *        Contains the default value for the dialog field when this method
271   *        is called (null value is ok).  Upon return, if the user pressed
272   *        OK, then this parameter contains a newly allocated string value.
273   *        Otherwise, the parameter's value is unmodified.
274   * @param aCheckMsg
275   *        Text to appear with the checkbox.  If null, check box will not be shown.
276   * @param aCheckState
277   *        Contains the initial checked state of the checkbox when this method
278   *        is called and the final checked state after this method returns.
279   *
280   * @return true for OK, false for Cancel.
281   */                        
282  boolean prompt(in nsIDOMWindow aParent,
283                 in wstring aDialogTitle,
284                 in wstring aText,
285                 inout wstring aValue, 
286                 in wstring aCheckMsg,
287                 inout boolean aCheckState);
288
289  /**
290   * Puts up a dialog with an edit field, a password field, and an optional,
291   * labeled checkbox.
292   *
293   * @param aParent
294   *        The parent window or null.
295   * @param aDialogTitle
296   *        Text to appear in the title of the dialog.
297   * @param aText
298   *        Text to appear in the body of the dialog.
299   * @param aUsername
300   *        Contains the default value for the username field when this method
301   *        is called (null value is ok).  Upon return, if the user pressed OK,
302   *        then this parameter contains a newly allocated string value.
303   *        Otherwise, the parameter's value is unmodified.
304   * @param aPassword
305   *        Contains the default value for the password field when this method
306   *        is called (null value is ok).  Upon return, if the user pressed OK,
307   *        then this parameter contains a newly allocated string value.
308   *        Otherwise, the parameter's value is unmodified.
309   * @param aCheckMsg
310   *        Text to appear with the checkbox.  If null, check box will not be shown.
311   * @param aCheckState
312   *        Contains the initial checked state of the checkbox when this method
313   *        is called and the final checked state after this method returns.
314   *
315   * @return true for OK, false for Cancel.
316   */                        
317  boolean promptUsernameAndPassword(in nsIDOMWindow aParent,
318                                    in wstring aDialogTitle,
319                                    in wstring aText,
320                                    inout wstring aUsername,
321                                    inout wstring aPassword,
322                                    in wstring aCheckMsg,
323                                    inout boolean aCheckState);
324
325  /**
326   * Puts up a dialog with a password field and an optional, labeled checkbox.
327   *
328   * @param aParent
329   *        The parent window or null.
330   * @param aDialogTitle
331   *        Text to appear in the title of the dialog.
332   * @param aText
333   *        Text to appear in the body of the dialog.
334   * @param aPassword
335   *        Contains the default value for the password field when this method
336   *        is called (null value is ok).  Upon return, if the user pressed OK,
337   *        then this parameter contains a newly allocated string value.
338   *        Otherwise, the parameter's value is unmodified.
339   * @param aCheckMsg
340   *        Text to appear with the checkbox.  If null, check box will not be shown.
341   * @param aCheckState
342   *        Contains the initial checked state of the checkbox when this method
343   *        is called and the final checked state after this method returns.
344   *
345   * @return true for OK, false for Cancel.
346   */                        
347  boolean promptPassword(in nsIDOMWindow aParent,
348                         in wstring aDialogTitle,
349                         in wstring aText,
350                         inout wstring aPassword,
351                         in wstring aCheckMsg,
352                         inout boolean aCheckState);
353
354  /**
355   * Puts up a dialog box which has a list box of strings from which the user
356   * may make a single selection.
357   *
358   * @param aParent
359   *        The parent window or null.
360   * @param aDialogTitle
361   *        Text to appear in the title of the dialog.
362   * @param aText
363   *        Text to appear in the body of the dialog.
364   * @param aCount
365   *        The length of the aSelectList array parameter.
366   * @param aSelectList
367   *        The list of strings to display.
368   * @param aOutSelection
369   *        Contains the index of the selected item in the list when this
370   *        method returns true.
371   *
372   * @return true for OK, false for Cancel.
373   */                                                 
374  boolean select(in nsIDOMWindow aParent,
375                 in wstring aDialogTitle,
376                 in wstring aText,
377                 in  PRUint32 aCount,
378                 [array, size_is(aCount)] in wstring aSelectList,
379                 out long aOutSelection);
380};