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. |