10.3 Using JOptionPane

There are basically two ways to use JOptionPane. The simplest, demonstrated by the example at the beginning of this section, is to invoke one of the many static methods of the class. These methods all result in a JDialog or JInternalFrame being displayed immediately for the user. The methods return when the user clicks one of the buttons in the dialog.

The other way to use JOptionPane is to instantiate it using one of the many constructors and then call createDialog( ) or createInternalFrame( ). These methods give you access to the JDialog or JInternalFrame and allow you to control when and where they are displayed. In most cases, the static methods will do everything you need. As with JDialog constructors, the static methods can (since 1.4) potentially throw a HeadlessException if the graphics environment is operating in a "headless" mode, meaning that there is no display, keyboard, or mouse.

It's worth noting that JOptionPane extends JComponent. When you instantiate JOptionPane, you actually have a perfectly usable component, laid out with the structure we described earlier. If you wanted to, you could display the component directly, but it typically makes sense to use it only in a dialog or internal frame.

All of the methods in JOptionPane that result in the creation of a JDialog create modal dialogs, but the methods that display JInternalFrames do not enforce modality. When the internal frame dialog is displayed, the other windows in your application can still receive focus. Typically, you will create modal dialogs. The situations in which you might use internal frames are discussed in the preceding chapter. See Section 10.7 later in this chapter for more information about working with dialogs as internal frames.

10.3.1 Events

JOptionPane fires a PropertyChangeEvent any time one of the bound properties listed in Table 10-6 changes value. This is the mechanism used to communicate changes from the JOptionPane to the JOptionPaneUI, as well to the anonymous inner class listeners JOptionPane creates to close the dialog when the value or inputValue property is set by the L&F.

10.3.2 Constants

Tables Table 10-3 through Table 10-6 list the many constants defined in this class. They fall into four general categories:

Message types

Used to specify what type of message is being displayed

Option types

Used to specify what options the user should be given

Options

Used to specify which option the user selected

Properties

Contains the string names of the pane's bound properties

Table 10-3. JOptionPane constants for specifying the desired message type

Constant	Type	Description
ERROR_MESSAGE	int	Used for error messages
INFORMATION_MESSAGE	int	Used for informational messages
PLAIN_MESSAGE	int	Used for arbitrary messages
QUESTION_MESSAGE	int	Used for question dialogs
WARNING_MESSAGE	int	Used for warning messages

Table 10-4. JOptionPane constants for specifying the user's options

Constant	Type	Description[4]
DEFAULT_OPTION	int	OK button
OK_CANCEL_OPTION	int	OK and Cancel buttons
YES_NO_CANCEL_OPTION	int	Yes, No, and Cancel buttons
YES_NO_OPTION	int	Yes and No buttons

^[4] The actual button labels are determined by the L&F. Currently, Swing L&Fs use the strings shown here. In future releases, these strings will be internationalized.

Table 10-5. JOptionPane selected option (and other "value") constants

Constant	Type	Description
CANCEL_OPTION	int	Cancel button pressed
CLOSED_OPTION	int	No button pressed, e.g., when the window is closed
NO_OPTION	int	No button pressed
OK_OPTION	int	OK button pressed
YES_OPTION	int	Yes button pressed
UNINITIALIZED_VALUE	Object	Value indicating that no value has been set for the pane

Table 10-6. JOptionPane bound property name constants

Constant	Type	Description
ICON_PROPERTY	String	Displayed icon
INITIAL_SELECTION_VALUE_PROPERTY	String	Initially selected value
INITIAL_VALUE_PROPERTY	String	Initially focused button
INPUT_VALUE_PROPERTY	String	Value entered by the user
MESSAGE_PROPERTY	String	Message displayed to the user
MESSAGE_TYPE_PROPERTY	String	Type of message displayed
OPTION_TYPE_PROPERTY	String	Type of options provided
OPTIONS_PROPERTY	String	List of nondefault options provided
SELECTION_VALUES_PROPERTY	String	Selection values available to user
VALUE_PROPERTY	String	Option selected by user
WANTS_INPUT_PROPERTY	String	Whether pane requires input

10.3.3 Four Dialog Types

JOptionPane provides static methods for creating four types of dialogs (see Table 10-7 and the examples that follow).^[5] Each of these types can be automatically enclosed in either a JDialog or a JInternalFrame. The four types are:

^[5] Note that these dialog types are not different Java classes. They simply represent common types of dialog boxes used in applications.

Input Dialog

Provides some way (typically a JTextField, JComboBox, or JList) for the user to enter data. Always includes two buttons: OK and Cancel.

Confirm Dialog

Asks a user to confirm some information. Includes buttons such as Yes, No, OK, and Cancel.

Message Dialog

Displays information to the user. Includes a single OK button.

Option Dialog

Displays arbitrary data to the user. May contain any set of buttons for the user to choose from.

The first three types are somewhat restrictive, making it easy to create the most common types of dialogs. Option Dialog is more flexible, giving you complete control. Also, keep in mind that you can use the constructors to instantiate JOptionPane objects directly. These objects will then be Option Dialogs, again allowing you complete control.

10.3.4 Constructors

public JOptionPane( )

public JOptionPane(Object message)

public JOptionPane(Object message, int messageType)

public JOptionPane(Object message, int messageType, int optionType)

public JOptionPane(Object message, int messageType, int optionType, Icon icon)

public JOptionPane(Object message, int messageType, int optionType, Icon icon, Object[] options)

public JOptionPane(Object message, int messageType, int optionType, Icon icon, Object[] options, Object initialValue)

These constructors allow JOptionPanes to be created and held over time (unlike the static methods listed below, which create panes that are used only once).

10.3.5 Static Dialog Display Methods

There are more static "show" methods (used to create and display JDialog and JInternalFrame objects that contain JOptionPanes) than can be listed here; chances are good that there is a variant that does what you want with the parameters you have available. The authoritative list is in the JOptionPane Javadoc, and a summary is presented in Table 10-7.

10.3.6 Dialog Creation Method Parameters

Table 10-7 summarizes the parameter types, names, and default values for JOptionPane's constructors and static dialog creation methods. The parameters are listed (top to bottom) in the order they occur in the methods. Parameters that do not apply to a given column are left blank. In the rest of this section, we'll explain how each of these parameters affects the dialog's display. After that, we'll show some examples of dialogs and internal frames created using specific JOptionPane methods and constructors.

Component parentComponent

For JDialogs, this is the dialog's parent. The dialog is centered on this component when it is displayed. For JInternalFrames, this parameter is used to find a container for the frame. If parentComponent is a JDesktopPane, the internal frame is added to its MODAL_LAYER. Otherwise, an attempt is made to see if parentComponent is contained (possibly recursively) by a JDesktopPane.^[6] If so, the frame is added to the containing desktop's MODAL_LAYER.

^[6] getDesktopPaneForComponent searches a parent component chain for a JDesktopPane. It is static and public, so you are free to use it yourself. It takes a single Component as its parameter.

If neither of these apply, the parentComponent's parent (if it has no parent, a RuntimeException is thrown) is used as the container, and the frame is added with BorderLayout.CENTER constraints.

This last option, while supported, rarely gives you what you're looking for. Since the dialog is added with BorderLayout constraints, your parentComponent's parent should be using a BorderLayout, or you may have various problems (e.g., GridBagLayout throws an exception if you add a component with constraints, other than a GridBagConstraints object). Even if you have a container with a BorderLayout, remember that the dialog fills the entire center of the container causing it to be resized as necessary, possibly to an unusable size. All of this leads to a simple rule: to make your life easier, create only internal dialogs within JDesktopPanes. See the example at the end of the chapter to see how to do this when you're not already using a JDesktopPane in your interface.

Table 10-7. JOptionPane constructor/dialog creation method parameters, defaults, and return types

Parameter type	Parametername	JOptionPane constructors	InputDialog	ConfirmDialog	MessageDialog	Option-Dialog
Component	parentComponent		null[7]	Required[7]	Required[7]	Required[7]
Object	message	"JOptionPane Message"	Required	Required	Required	Required
String	title		"Input"	"Select an Option"	"Message"	Required
int	optionType	PLAIN_MESSAGE[8]		YES_NO_CANCEL_OPTION		Required
int	messageType	DEFAULT_OPTION[8]	QUESTION_MESSAGE	QUESTION_MESSAGE	INFORMATION_MESSAGE	Required
Icon	icon	null	null	null	null	Required
Object[]	selectionValues		null
Object	initialSelectionValue		null
Object[]	options	null				Required
Object	initialValue	null				Required
Return type			String/Object	int	void	int

^[7] If null, a default Frame is used. This Frame is returned by the static getRootFrame method and can be set using the static setRootFrame method.

^[8] The order of the optionType and messageType parameters for the constructors is reversed; messageType must come first.

parentComponent is allowed to be null, in which case a default Frame is used. This Frame is returned by the static method getRootFrame, and the default can be changed by calling the static method setRootFrame.

Object message

This is the message that will be displayed in the dialog. Typically, it is a simple String object. However, the methods allow this to be any arbitrary object. It's up to the L&F to determine how to handle other objects. Typically (for the Swing L&Fs), if the message is a Component, it is displayed as is. If it is an Icon, it is wrapped in a JLabel and displayed. If message is an Object[], the elements of the array are recursively expanded (applying these same rules) and added to form a vertical column. Any other types passed in are added as strings by calling the object's toString( ) method.

Note that the flexibility of this parameter allows you to use any arbitrary component (including containers with many other components inside) as the "message" for the dialog. Figure 10-6 shows an internal dialog that was created by passing in a custom calendar component as the message parameter.

Figure 10-6. Custom component in a JOptionPane internal dialog

String title

This parameter contains the string that appears on the dialog's title bar. Note that this parameter does not apply to the JOptionPane constructors since JOptionPane itself does not have a title bar.

int optionType

This parameter determines which options the user is given for dismissing the dialog. This parameter applies only to Confirm Dialogs, Option Dialogs, and JOptionPane constructors. As a rule, Input Dialogs have an OK button and a Cancel button. Message Dialogs have only an OK button. For the other types of dialogs, this parameter may be one of these values: DEFAULT_OPTION, YES_NO_OPTION, YES_NO_CANCEL_OPTION, or OK_CANCEL_OPTION. Again, it's up to the L&F to determine how to interpret these, but you can confidently assume that YES_NO_OPTION provides a Yes and a No button, and so on. The DEFAULT_OPTION value provides a single OK button.

If you want a different set of buttons, you need to use an Option Dialog, which allows you to specify any arbitrary set of buttons via the options parameter.

int messageType

This parameter indicates the type of dialog to create. The possible values are: WARNING_MESSAGE, QUESTION_MESSAGE, INFO_MESSAGE, ERROR_MESSAGE, and PLAIN_MESSAGE. It's up to the L&F to determine how to interpret these options. Usually, the value of the parameter determines the icon displayed in the dialog. Figure 10-7 shows the icons used by several L&Fs (note that in some cases there isn't a distinct icon for each messageType). This default icon can be overridden by passing in a non-null value for the icon parameter. There is no icon associated with PLAIN_MESSAGE.

Figure 10-7. JOptionPane icons (Warning, Question, Info, and Error)

Icon icon

This parameter specifies the Icon to display in the dialog, allowing you to further customize the display. If it is set to null, the icon is determined based on the messageType. To have no icon displayed, pass PLAIN_MESSAGE as the messageType.

Object[] selectionValues

This parameter is used only in Input dialogs. It allows you to specify a set of selections for the user to choose from. As you might expect, it's up to the L&F to determine how to supply these options to the user. It's common for a JComboBox to be used when there are only a few values and to have it replaced by a scrolling JList (with a selection mode of MULTIPLE_INTERVAL_SELECTION) when there are many. In either case, the array of objects is passed directly to the list or combo box for interpretation. (See the documentation of these components for details on how different object types are interpreted.) If the selectionValues parameter is null, a JTextField is used for data entry.

Object initialSelectionValue

This parameter also applies only to Input Dialogs. It allows you to specify which of the options supplied in selectionValues should be initially selected.

Object[] options

This parameter applies only to JOptionPane constructors and Option Dialogs. It allows you to specify the set of option buttons the user will see. Using null here indicates that the optionType should be used to determine the set of buttons displayed. Useful parameter types for this parameter are String and Icon. These are used to construct JButton objects. Components passed in via this parameter are added as is.^[9] Any other input objects are used to create JButtons with a label generated by calling toString( ) on the object.

^[9] This is not as useful as it sounds, as no event listeners are added for the components. It would be nice if a future release at least supported passing JButtons by having the L&F add an action listener for them, like the one it adds to JButtons it creates.

Object initialValue

This parameter (also available only for constructors and Option Dialogs) allows you to specify a default option from the list supplied by the options parameter. Note that this works only if the options parameter is non-null. This value determines which button has initial focus. In addition, if the initial value is a JButton, it becomes the default button on the root pane that contains it (if there is one). For example, specifying {"Register", "Not yet"} as the options and Register as the initialValue causes the Register button to have initial focus and be the default button.