10.2 The JOptionPane Class

JOptionPane is a utility class used to create complex JDialogs and JInternalFrames (the latter of which is used for lightweight dialogs). Figure 10-2 shows where JOptionPane fits into the class hierarchy; Figure 10-3 shows JOptionPane in four L&Fs. It provides a range of convenient ways to create common pop-up modal dialog boxes, which significantly reduces the amount of code you are required to write, at the expense of forcing the user to drop whatever she's doing and react to the pop up.

Figure 10-2. JOptionPane class diagram

Figure 10-3. JOptionPanes (showing internal confirm dialogs) in four L&Fs

For example, to create a very simple dialog window with the text "Click OK after you read this" and an OK button without JOptionPane, you'd have to write something like this:

  public void showSimpleDialog(JFrame f) {
  final JDialog d = new JDialog(f, "Click OK", true);
  d.setSize(200, 150);
  JLabel l = new JLabel("Click OK after you read this", JLabel.CENTER);
  d.getContentPane( ).setLayout(new BorderLayout( ));
  d.getContentPane( ).add(l, BorderLayout.CENTER);
  JButton b = new JButton("OK");
  b.addActionListener(new ActionListener( ) {
    public void actionPerformed(ActionEvent ev) {
      d.setVisible(false);
      d.dispose( );
    }
  });
  JPanel p = new JPanel( );     // Flow layout will center button.
  p.add(b);
  d.getContentPane( ).add(p, BorderLayout.SOUTH);
  d.setLocationRelativeTo(f);
  d.setVisible(true);
}

That's quite a lot of work for such a conceptually simple task. Using JOptionPane, this method can be replaced with:

JOptionPane.showMessageDialog(f, "Click OK after you read this",
  "Click OK", JOptionPane.INFORMATION_MESSAGE);

Figure 10-4 shows the dialogs created by these two examples.

Figure 10-4. JDialogs created with (left) and without (right) JOptionPane

10.2.1 Properties

JOptionPane defines the properties listed in Table 10-2. The maxCharactersPerLine property specifies the maximum number of characters the L&F should display on a single line. By default there is no limit. To change this value, you must subclass JOptionPane.^[3]

^[3] If you subclass JOptionPane for this purpose, you'll need to construct instances of your subclasses rather than using the static methods (which will just construct JOptionPane objects, ignoring your subclass).

Table 10-2. JOptionPane properties

Property	Data type	get	is	set	Default value
accessibleContexto	AccessibleContext	·			JOptionPane.AccessibleJOptionPane( )
iconb	Icon	·		·	null
initialSelectionValueb	Object	·		·	null
initialValueb	Object	·		·	null
inputValueb	Object	·		·	null
maxCharactersPerLineCount	int	·			Integer.MAX_VALUE
messageb	Object	·		·	"JOptionPane Message"
messageTypeb	int	·		·	PLAIN_MESSAGE
optionsb	Object[]	·		·	null
optionTypeb	int	·		·	DEFAULT_OPTION
rootFrames	Frame	·		·	From L&F
selectionValuesb	Object[]	·		·	null
UI	JOptionPaneUI	·		·	From L&F
UIClassIDo	String	·			"OptionPaneUI"
valueb	Object	·		·	null
wantsInputb	boolean	·		·	false
bbound, ooverridden, sstatic See also properties from the JComponent class (Table 3-6).

The UI and UIClassID properties are defined as usual. value specifies the value selected by the user and is set by the L&F when the user closes the dialog.

rootFrame is a static "property" that controls the default root Frame to be used when calling static "show" methods that don't take a Frame parameter.

wantsInput indicates whether the pane is expecting input (beyond just clicking a JButton) from the user.

The other properties (as well as more on value and wantsInput) are discussed in detail throughout the chapter.

10.2.2 JOptionPane Structure

The dialogs created by JOptionPane are made up of four basic elements, some of which may be null. These elements are shown in Figure 10-5. (The input appearing in the frame's title bar is not part of the JOptionPane itself but can be set using the static dialog-creation methods.)

Figure 10-5. JOptionPane structure

The elements are:

An icon

The icon usually provides some visual indication of the type of message being displayed. The icons used for four Swing L&Fs are shown in Figure 10-7.

A message area

The message area usually contains a simple textual message. However, it can actually be any arbitrary Object. We'll discuss how different types of objects are displayed later in this chapter.

A data input area

This area allows the user to enter a value or make a selection in response to the message. Typically, this is a JTextField, JComboBox, or JList, but this is entirely up to the L&F.

A set of option buttons

For example, OK and Cancel.