nsIPromptService

IID:1630C61A-325E-49ca-8759-A31B16C47AA5
Inherits From:nsISupports
Status:FROZEN

This is the interface to the embeddable prompt service; the service that implements nsIPrompt. Its interface is designed to be just nsIPrompt, each method modified to take a parent window parameter.

Accesskeys can be attached to buttons and checkboxes by inserting an & before the accesskey character in the checkbox message or button title. For a real &, use && instead. (A "button title" generally refers to the text label of a button.)

One note: in all cases, the parent window parameter can be null. However, these windows are all intended to have parents. So when no parent is specified, the implementation should try hard to find a suitable foster parent.

Implementations are free to choose how they present the various button types. For example, while prompts that give the user a choice between OK and Cancel are required to return a boolean value indicating whether or not the user accepted the prompt (pressed OK) or rejected the prompt (pressed Cancel), the implementation of this interface could very well speak the prompt to the user instead of rendering any visual user-interface. The standard button types are merely idioms used to convey the nature of the choice the user is to make.

Because implementations of this interface may loosely interpret the various button types, it is advised that text messages passed to these prompts do not refer to the button types by name. For example, it is inadvisable to tell the user to "Press OK to proceed." Instead, such a prompt might be rewritten to ask the user: "Would you like to proceed?"

This interface is intended to be used as a service.

This interface is implemented by the following components:


Constants

PRUint32 BUTTON_POS_0 = 1
PRUint32 BUTTON_POS_1 = 256
PRUint32 BUTTON_POS_2 = 65536
PRUint32 BUTTON_TITLE_OK = 1
PRUint32 BUTTON_TITLE_CANCEL = 2
PRUint32 BUTTON_TITLE_YES = 3
PRUint32 BUTTON_TITLE_NO = 4
PRUint32 BUTTON_TITLE_SAVE = 5
PRUint32 BUTTON_TITLE_DONT_SAVE = 6
PRUint32 BUTTON_TITLE_REVERT = 7
PRUint32 BUTTON_TITLE_IS_STRING = 127
PRUint32 BUTTON_POS_0_DEFAULT = 0
PRUint32 BUTTON_POS_1_DEFAULT = 16777216
PRUint32 BUTTON_POS_2_DEFAULT = 33554432
PRUint32 BUTTON_DELAY_ENABLE = 67108864
PRUint32 STD_OK_CANCEL_BUTTONS = 513
PRUint32 STD_YES_NO_BUTTONS = 1027

Methods

void alert ( nsIDOMWindow parent , PRUnichar* dialogTitle , PRUnichar* text ) void alertCheck ( nsIDOMWindow parent , PRUnichar* dialogTitle , PRUnichar* text , PRUnichar* checkMsg , inout PRBool checkState ) PRBool confirm ( nsIDOMWindow parent , PRUnichar* dialogTitle , PRUnichar* text ) PRBool confirmCheck ( nsIDOMWindow parent , PRUnichar* dialogTitle , PRUnichar* text , PRUnichar* checkMsg , inout PRBool checkState ) PRInt32 confirmEx ( nsIDOMWindow parent , PRUnichar* dialogTitle , PRUnichar* text , PRUint32 buttonFlags , PRUnichar* button0Title , PRUnichar* button1Title , PRUnichar* button2Title , PRUnichar* checkMsg , inout PRBool checkState ) PRBool prompt ( nsIDOMWindow parent , PRUnichar* dialogTitle , PRUnichar* text , inout PRUnichar* value , PRUnichar* checkMsg , inout PRBool checkState ) PRBool promptPassword ( nsIDOMWindow parent , PRUnichar* dialogTitle , PRUnichar* text , inout PRUnichar* password , PRUnichar* checkMsg , inout PRBool checkState ) PRBool promptUsernameAndPassword ( nsIDOMWindow parent , PRUnichar* dialogTitle , PRUnichar* text , inout PRUnichar* username , inout PRUnichar* password , PRUnichar* checkMsg , inout PRBool checkState ) PRBool select ( nsIDOMWindow parent , PRUnichar* dialogTitle , PRUnichar* text , PRUint32 count , arrayof PRUnichar* selectList , out PRInt32 outSelection )

void alert ( nsIDOMWindow parent , PRUnichar* dialogTitle , PRUnichar* text )

Puts up an alert dialog with an OK button.

Arguments:
parent: The parent window or null.
dialogTitle: Text to appear in the title of the dialog.
text: Text to appear in the body of the dialog.

void alertCheck ( nsIDOMWindow parent , PRUnichar* dialogTitle , PRUnichar* text , PRUnichar* checkMsg , inout PRBool checkState )

Puts up an alert dialog with an OK button and a labeled checkbox.

Arguments:
parent: The parent window or null.
dialogTitle: Text to appear in the title of the dialog.
text: Text to appear in the body of the dialog.
checkMsg: Text to appear with the checkbox.
checkState: Contains the initial checked state of the checkbox when this method is called and the final checked state after this method returns.

PRBool confirm ( nsIDOMWindow parent , PRUnichar* dialogTitle , PRUnichar* text )

Puts up a dialog with OK and Cancel buttons.

Arguments:
parent: The parent window or null.
dialogTitle: Text to appear in the title of the dialog.
text: Text to appear in the body of the dialog.
Returns:
true for OK, false for Cancel

PRBool confirmCheck ( nsIDOMWindow parent , PRUnichar* dialogTitle , PRUnichar* text , PRUnichar* checkMsg , inout PRBool checkState )

Puts up a dialog with OK and Cancel buttons and a labeled checkbox.

Arguments:
parent: The parent window or null.
dialogTitle: Text to appear in the title of the dialog.
text: Text to appear in the body of the dialog.
checkMsg: Text to appear with the checkbox.
checkState: Contains the initial checked state of the checkbox when this method is called and the final checked state after this method returns.
Returns:
true for OK, false for Cancel

PRInt32 confirmEx ( nsIDOMWindow parent , PRUnichar* dialogTitle , PRUnichar* text , PRUint32 buttonFlags , PRUnichar* button0Title , PRUnichar* button1Title , PRUnichar* button2Title , PRUnichar* checkMsg , inout PRBool checkState )

Puts up a dialog with up to 3 buttons and an optional, labeled checkbox.

Buttons are numbered 0 - 2. The implementation can decide whether the sequence goes from right to left or left to right. Button 0 is the default button unless one of the Button Default Flags is specified.

A button may use a predefined title, specified by one of the Button Title Flags values. Each title value can be multiplied by a position value to assign the title to a particular button. If BUTTON_TITLE_IS_STRING is used for a button, the string parameter for that button will be used. If the value for a button position is zero, the button will not be shown.

In general, buttonFlags is constructed per the following example:

AButtonFlags = (BUTTON_POS_0) * (BUTTON_TITLE_AAA) + (BUTTON_POS_1) * (BUTTON_TITLE_BBB) + BUTTON_POS_1_DEFAULT;

Where "AAA" and "BBB" correspond to one of the button titles.

Arguments:
parent: The parent window or null.
dialogTitle: Text to appear in the title of the dialog.
text: Text to appear in the body of the dialog.
buttonFlags: A combination of Button Flags.
button0Title: Used when button 0 uses TITLE_IS_STRING
button1Title: Used when button 1 uses TITLE_IS_STRING
button2Title: Used when button 2 uses TITLE_IS_STRING
checkMsg: Text to appear with the checkbox. Null if no checkbox.
checkState: Contains the initial checked state of the checkbox when this method is called and the final checked state after this method returns.
Returns:
index of the button pressed.

PRBool prompt ( nsIDOMWindow parent , PRUnichar* dialogTitle , PRUnichar* text , inout PRUnichar* value , PRUnichar* checkMsg , inout PRBool checkState )

Puts up a dialog with an edit field and an optional, labeled checkbox.

Arguments:
parent: The parent window or null.
dialogTitle: Text to appear in the title of the dialog.
text: Text to appear in the body of the dialog.
value: Contains the default value for the dialog field when this method is called (null value is ok). Upon return, if the user pressed OK, then this parameter contains a newly allocated string value. Otherwise, the parameter's value is unmodified.
checkMsg: Text to appear with the checkbox. If null, check box will not be shown.
checkState: Contains the initial checked state of the checkbox when this method is called and the final checked state after this method returns.
Returns:
true for OK, false for Cancel.

PRBool promptPassword ( nsIDOMWindow parent , PRUnichar* dialogTitle , PRUnichar* text , inout PRUnichar* password , PRUnichar* checkMsg , inout PRBool checkState )

Puts up a dialog with a password field and an optional, labeled checkbox.

Arguments:
parent: The parent window or null.
dialogTitle: Text to appear in the title of the dialog.
text: Text to appear in the body of the dialog.
password: Contains the default value for the password field when this method is called (null value is ok). Upon return, if the user pressed OK, then this parameter contains a newly allocated string value. Otherwise, the parameter's value is unmodified.
checkMsg: Text to appear with the checkbox. If null, check box will not be shown.
checkState: Contains the initial checked state of the checkbox when this method is called and the final checked state after this method returns.
Returns:
true for OK, false for Cancel.

PRBool promptUsernameAndPassword ( nsIDOMWindow parent , PRUnichar* dialogTitle , PRUnichar* text , inout PRUnichar* username , inout PRUnichar* password , PRUnichar* checkMsg , inout PRBool checkState )

Puts up a dialog with an edit field, a password field, and an optional, labeled checkbox.

Arguments:
parent: The parent window or null.
dialogTitle: Text to appear in the title of the dialog.
text: Text to appear in the body of the dialog.
username: Contains the default value for the username field when this method is called (null value is ok). Upon return, if the user pressed OK, then this parameter contains a newly allocated string value. Otherwise, the parameter's value is unmodified.
password: Contains the default value for the password field when this method is called (null value is ok). Upon return, if the user pressed OK, then this parameter contains a newly allocated string value. Otherwise, the parameter's value is unmodified.
checkMsg: Text to appear with the checkbox. If null, check box will not be shown.
checkState: Contains the initial checked state of the checkbox when this method is called and the final checked state after this method returns.
Returns:
true for OK, false for Cancel.

PRBool select ( nsIDOMWindow parent , PRUnichar* dialogTitle , PRUnichar* text , PRUint32 count , arrayof PRUnichar* selectList , out PRInt32 outSelection )

Puts up a dialog box which has a list box of strings from which the user may make a single selection.

Arguments:
parent: The parent window or null.
dialogTitle: Text to appear in the title of the dialog.
text: Text to appear in the body of the dialog.
count: The length of the selectList array parameter.
selectList: The list of strings to display.
outSelection: Contains the index of the selected item in the list when this method returns true.
Returns:
true for OK, false for Cancel.

Reference documentation is generated from Mozilla's source.

Add a note User Contributed Notes
No comments available

Copyright © 1999 - 2005 XULPlanet.com