10.1 The JDialog Class

JDialog is the Swing version of its superclass, java.awt.Dialog. It provides the same key features described in Chapter 8^[2] in the discussion of JWindow, JFrame, and JApplet: it uses a JRootPane as its container, and it provides default window-closing behavior. Since JDialog extends java.awt.Dialog, it has a heavyweight peer and is managed by the native windowing system. Figure 10-1 shows how JDialog fits into the class hierarchy.

^[2] Certain parts of this chapter assume that you have read at least part of Chapter 8.

Figure 10-1. JDialog class diagram

10.1.1 Properties

JDialog defines the properties and default values listed in Table 10-1. The content-Pane, glassPane, JMenuBar, and layeredPane properties are taken from rootPane, which is set to a new JRootPane by the constructor.

Table 10-1. JDialog properties

Property	Data type	get	is	set	Default value
accessibleContexto	AccessibleContext	·			JDialog.AccessibleJDialog( )
contentPaneo	Container	·		·	From rootPane
defaultCloseOperation	int	·		·	HIDE_ON_CLOSE
defaultLookAndFeelDecorateds, 1.4	boolean		·	·	Depends on L&F, often false
glassPaneo	Component	·		·	From rootPane
JMenuBaro	JMenuBar	·		·	null
layeredPaneo	JLayeredPane	·		·	From rootPane
layouto	LayoutManager	·		·	BorderLayout
modal*	boolean		·	·	false
parent*	Container	·			SwingUtilities.get-SharedOwnerFrame( )
rootPane	JRootPane	·			JRootPane
title*	String	·		·	""
1.4since 1.4, ooverridden, sstatic *Inherited from Dialog; can be set in JDialog constructors. See also the java.awt.Dialog class.

The defaultCloseOperation specifies how the dialog should react if its window is closed. The valid values come from the WindowConstants class, and the default operation is to hide the dialog.

The defaultLookAndFeelDecorated property provides a hint about whether newly created JDialogs should have their window decorations (such as title bars, controls to manipulate or close the window, and the like) drawn by the current L&F. This is only a hint; setting it to true has no effect if the L&F is unable to provide decorations or the window manager is unable to create undecorated windows.

The layout property is listed here because JDialog overrides setLayout( ) to throw an Error if an attempt is made to change the layout manager, rather than set the layout manager of the dialog's content pane.

The parent and title properties are inherited from Component and Dialog, respectively. Both are listed here because they can be set in the JDialog constructors.

The modal property is listed in this table because the JDialog constructors allow this property (inherited from Dialog) to be set. If a dialog is modal, no other window can be active while the dialog is displayed. As noted previously, such a restriction on the user's actions should be avoided if it's possible to design a better approach.

10.1.2 Constructors

There are many constructors to choose from, but they are all variations of the two fully specified constructors listed here, omitting one or more parameters from the end. The difference between the two families of constructors is whether the owner of the JDialog is a Frame or a Dialog. Note that it is valid to supply no owner by passing null as the first argument to any of the constructors or by using the zero argument constructor. The primary role of the owner is to dispose of any windows (including dialogs) that it owns when the owner itself is disposed.

public JDialog( )

Create a new dialog without a specified parent frame. An invisible owner frame is obtained from SwingUtilities.getSharedOwnerFrame( ).

public JDialog(Dialog owner, String title, boolean modal, GraphicsConfiguration gc)

Create a dialog with the given owner dialog, title, modal setting, and Graphics-Configuration.

public JDialog(Frame owner, String title, boolean modal, GraphicsConfiguration gc)

Create a dialog with the given owner frame, title, modal setting, and Graphics-Configuration.

All constructors can now (since 1.4) potentially throw HeadlessException if the graphics environment is operating in a "headless" mode, meaning that there is no display, keyboard, or mouse. This would be true, for example, in a servlet environment that used Swing to generate graphics to be sent to a web browser as downloaded image files.

The versions that specify a GraphicsConfiguration (also introduced in 1.4) allow you to select the display device on which the dialog should appear if your application is running in a multi-screen environment.

10.1.3 Public Methods

public void setLocationRelativeTo(Component c)

Set the dialog's location based on the location of the given component. The dialog is centered within (if the component is larger than the dialog) or over (if the dialog is larger) the input component. If the specified component is not currently displayed, this method centers the dialog on the screen. Note that this method has no effect on the dialog's parent, even if the input component is a different Frame.

public void update(Graphics g)

This implementation of update( ) just calls paint( ).