oracle.javatools.dialogs
Class MessageDialog

java.lang.Object
  oracle.javatools.dialogs.MessageDialog

public final class MessageDialog

extends java.lang.Object

A utility class for displaying alerts. The behavior of alerts is specified in the Oracle User Interface Design Guidelines for Desktop Applications revision 3.3 in section 6.3:

Alert Guidelines (Oracle internal)

To display an alert, call one of the following methods on this class:

• information() to provide the user with harmless status information.
• confirm() to warn the user about the consequences of an action
• error() to notify the user about an unanticipated condition that prevented the user's task from completing successfully ( e.g. validation errors )
• critical() for unanticipated error conditions that may result in data loss. If there is an unhandled exception and the stacktrace might be useful to the user or to the JDev team when problems are reported, you should use the ExceptionDialog instead.

For each of these dialog types, you must supply a parent component (for modality), message and a title. The javadoc for each method contains the relevant guidelines from the UIDS for titling and providing the text for alerts.

You can optionally specify a help topic. The help button will only be displayed if a topic is provided. You only need to provide a help topic if additional information is available to help the user with the alert.

Field Summary

static int	CONFIRM_CANCEL Return value from confirmOrCancel( Component, Object, String, String, boolean ) indicating that the user dismissed the alert using the Cancel button.
static int	CONFIRM_NO Return value from confirmOrCancel( Component, Object, String, String, boolean ) indicating that the user dismissed the alert using the No button.
static int	CONFIRM_YES Return value from confirmOrCancel( Component, Object, String, String, boolean ) indicating that the user dismissed the alert using the Yes button.

Method Summary

static boolean	confirm(java.awt.Component parent, java.lang.Object message, java.lang.String title, java.lang.String helptopic) Display a warning / confirmation alert.
static boolean	confirm(java.awt.Component parent, java.lang.Object message, java.lang.String title, java.lang.String helptopic, boolean isDestructive) Display a warning / confirmation alert.
static boolean	confirm(java.awt.Component parent, java.lang.Object message, java.lang.String title, java.lang.String helptopic, boolean isDestructive, java.lang.String yesText, java.lang.String noText) Display a warning / confirmation alert.
static int	confirmOrCancel(java.awt.Component parent, java.lang.Object message, java.lang.String title) Display a confirmation alert with the option to cancel.
static int	confirmOrCancel(java.awt.Component parent, java.lang.Object message, java.lang.String title, java.lang.String helptopic) Display a confirmation alert with the option to cancel.
static int	confirmOrCancel(java.awt.Component parent, java.lang.Object message, java.lang.String title, java.lang.String helptopic, boolean isDestructive) Display a confirmation alert with the option to cancel.
static void	critical(java.awt.Component parent, java.lang.Object message, java.lang.String title, java.lang.String helptopic) Display a critical alert.
static void	error(java.awt.Component parent, java.lang.Object message, java.lang.String title, java.lang.String helpTopic) Display an error alert.
static void	information(java.awt.Component parent, java.lang.Object message, java.lang.String title, java.lang.String helptopic) Display an information alert.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CONFIRM_CANCEL

public static final int CONFIRM_CANCEL

Return value from confirmOrCancel( Component, Object, String, String, boolean ) indicating that the user dismissed the alert using the Cancel button.

See Also:

Constant Field Values

CONFIRM_NO

public static final int CONFIRM_NO

Return value from confirmOrCancel( Component, Object, String, String, boolean ) indicating that the user dismissed the alert using the No button.

See Also:

Constant Field Values

CONFIRM_YES

public static final int CONFIRM_YES

Return value from confirmOrCancel( Component, Object, String, String, boolean ) indicating that the user dismissed the alert using the Yes button.

See Also:

Constant Field Values

Method Detail

error

public static void error(java.awt.Component parent,
                         java.lang.Object message,
                         java.lang.String title,
                         java.lang.String helpTopic)

Display an error alert. An error alert is used to notify the user about an unanticipated condition which prevented the user's task from completing successfully. The interruption does not result in significant data loss, however the user must resolve the condition before the task can be carried out as planned. Examples of events that can raise error alerts are validation failure, disk full, or network interruption. In general, these are errors that occur within the application and are easily corrected.

Parameters:

parent - a parent component

message - the message text should contain three parts: what the error is, why the error occurred and how the error can be fixed (if known). Each part should be one to three short sentences.

title - a title for the alert. The title bar text of an error alert should be a one to three word summary of the error. Null or "" are NOT valid values.

helpTopic - the help topic ID. If you pass null, the help button will not be displayed.

confirm

public static boolean confirm(java.awt.Component parent,
                              java.lang.Object message,
                              java.lang.String title,
                              java.lang.String helptopic)

Display a warning / confirmation alert. A confirmation alert is used to warn the user about the consequences of an action, giving the user a chance to accept the consequences, avoid them, or resolve them in some other fashion. When a task initiated by the user raises a confirmation alert, the task does not actually begin until the user responds to the alert. A confirmation alert must be used for destructive operations (like delete) which will result in significant data loss and cannot easily be undone. Examples of events that can raise confirmation alerts are dropping a database table, cancelling an installation, or deleting or overwriting a file.

Parameters:

parent - the parent component

message - the message text of the alert should explain the known consequences of the action, and conclude with a question that presents a choice to the user.

title - the title bar text should be in the form "Confirm [Action]", for example "Confirm Drop". Null or "" are NOT valid values.

helptopic - the help topic. If null, the button is not displayed.

Returns:

true if the user clicked Yes, false otherwise.

confirm

public static boolean confirm(java.awt.Component parent,
                              java.lang.Object message,
                              java.lang.String title,
                              java.lang.String helptopic,
                              boolean isDestructive)

Display a warning / confirmation alert. A confirmation alert is used to warn the user about the consequences of an action, giving the user a chance to accept the consequences, avoid them, or resolve them in some other fashion. When a task initiated by the user raises a confirmation alert, the task does not actually begin until the user responds to the alert. A confirmation alert must be used for destructive operations (like delete) which will result in significant data loss and cannot easily be undone. Examples of events that can raise confirmation alerts are dropping a database table, cancelling an installation, or deleting or overwriting a file.

Parameters:

parent - the parent component

message - the message text of the alert should explain the known consequences of the action, and conclude with a question that presents a choice to the user.

title - the title bar text should be in the form "Confirm [Action]", for example "Confirm Drop". Null or "" are NOT valid values.

helptopic - the help topic. If null, the button is not displayed.

isDestructive - if the operation the confirmation is for is destructive (e.g. file deletion), the No button will be the default

Returns:

true if the user clicked Yes, false otherwise.

confirm

public static boolean confirm(java.awt.Component parent,
                              java.lang.Object message,
                              java.lang.String title,
                              java.lang.String helptopic,
                              boolean isDestructive,
                              java.lang.String yesText,
                              java.lang.String noText)

Display a warning / confirmation alert. A confirmation alert is used to warn the user about the consequences of an action, giving the user a chance to accept the consequences, avoid them, or resolve them in some other fashion. When a task initiated by the user raises a confirmation alert, the task does not actually begin until the user responds to the alert. A confirmation alert must be used for destructive operations (like delete) which will result in significant data loss and cannot easily be undone. Examples of events that can raise confirmation alerts are dropping a database table, cancelling an installation, or deleting or overwriting a file.

Parameters:

parent - the parent component

message - the message text of the alert should explain the known consequences of the action, and conclude with a question that presents a choice to the user.

title - the title bar text should be in the form "Confirm [Action]", for example "Confirm Drop". Null or "" are NOT valid values.

helptopic - the help topic. If null, the button is not displayed.

isDestructive - if the operation the confirmation is for is destructive (e.g. file deletion), the No button will be the default

yesText - the label for the Yes button in the dialog. You can use the ampersand (&) to indicate the mnemonic.

Returns:

true if the user clicked Yes, false otherwise.

confirmOrCancel

public static int confirmOrCancel(java.awt.Component parent,
                                  java.lang.Object message,
                                  java.lang.String title)

Display a confirmation alert with the option to cancel. A confirmation alert is used to warn the user about the consequences of an action, giving the user a chance to accept the consequences, avoid them, or resolve them in some other fashion. When a task initiated by the user raises a confirmation alert, the task does not actually begin until the user responds to the alert. A confirmation alert must be used for destructive operations (like delete) which will result in significant data loss and cannot easily be undone. Examples of events that can raise confirmation alerts are dropping a database table, cancelling an installation, or deleting or overwriting a file.

Parameters:

parent - the parent component

message - the message text of the alert should explain the known consequences of the action, and conclude with a question that presents a choice to the user.

title - the title bar text should be in the form "Confirm [Action]", for example "Confirm Drop". Null or "" are NOT valid values.

Returns:

CONFIRM_YES, CONFIRM_NO or CONFIRM_CANCEL.

confirmOrCancel

public static int confirmOrCancel(java.awt.Component parent,
                                  java.lang.Object message,
                                  java.lang.String title,
                                  java.lang.String helptopic)

Display a confirmation alert with the option to cancel. A confirmation alert is used to warn the user about the consequences of an action, giving the user a chance to accept the consequences, avoid them, or resolve them in some other fashion. When a task initiated by the user raises a confirmation alert, the task does not actually begin until the user responds to the alert. A confirmation alert must be used for destructive operations (like delete) which will result in significant data loss and cannot easily be undone. Examples of events that can raise confirmation alerts are dropping a database table, cancelling an installation, or deleting or overwriting a file.

Parameters:

parent - the parent component

message - the message text of the alert should explain the known consequences of the action, and conclude with a question that presents a choice to the user.

title - the title bar text should be in the form "Confirm [Action]", for example "Confirm Drop". Null or "" are NOT valid values.

helptopic - the help topic. If null, the button is not displayed.

Returns:

CONFIRM_YES, CONFIRM_NO or CONFIRM_CANCEL.

confirmOrCancel

public static int confirmOrCancel(java.awt.Component parent,
                                  java.lang.Object message,
                                  java.lang.String title,
                                  java.lang.String helptopic,
                                  boolean isDestructive)

Display a confirmation alert with the option to cancel. A confirmation alert is used to warn the user about the consequences of an action, giving the user a chance to accept the consequences, avoid them, or resolve them in some other fashion. When a task initiated by the user raises a confirmation alert, the task does not actually begin until the user responds to the alert. A confirmation alert must be used for destructive operations (like delete) which will result in significant data loss and cannot easily be undone. Examples of events that can raise confirmation alerts are dropping a database table, cancelling an installation, or deleting or overwriting a file.

Parameters:

parent - the parent component

message - the message text of the alert should explain the known consequences of the action, and conclude with a question that presents a choice to the user.

title - the title bar text should be in the form "Confirm [Action]", for example "Confirm Drop". Null or "" are NOT valid values.

helptopic - the help topic. If null, the button is not displayed.

isDestructive - if the operation the confirmation is for is destructive (e.g. file deletion), the No button will be the default

Returns:

CONFIRM_YES, CONFIRM_NO or CONFIRM_CANCEL.

information

public static void information(java.awt.Component parent,
                               java.lang.Object message,
                               java.lang.String title,
                               java.lang.String helptopic)

Display an information alert. An information alert is used to provide the user with harmless status information. The event communicated by an information alert is not an interruption of a task initiated by the user. The event also has not resulted in data loss and does not require any resolution; it merely informs the user that something has happened. Examples of events that can raise information alerts are completing a compilation, virus definitions becoming out-of-date or the arrival of new mail.

Parameters:

parent - the parent of the dialog

message - the message to display. This should contain an extended narrative of the event.

title - the title of the dialog. This should be a one to three word summary of the event. Null or "" are NOT valid values.

helptopic - the help topic. If null, no Help button will be displayed.

critical

public static void critical(java.awt.Component parent,
                            java.lang.Object message,
                            java.lang.String title,
                            java.lang.String helptopic)

Display a critical alert. A critical alert is used to notify the user about a severe unanticipated condition which will not allow task completion. The interruption may have reseulted in significant data loss, however the is little the user can do to resolve the condition. Examples of events that can raise critical alerts are vendor OS errors, database integrity errors, or web cache corruption. In general, these are potentially harmful events that occur outside of the application and are largely beyond the user's control.

Parameters:

parent - the parent component for the dialog

message - The message text should explain what the problem is including an error number if available, and any known reasons for why the error might have occurred. It is also useful to suggest some possible solution to help the user understand what might need to be done to fix the condition (if known)

title - The title bar text should be a one to three word summary of the problem condition. Null or "" are NOT valid values.

helptopic - an optional help topic, if null no Help button is shown.