java.awt
Class Dialog

java.lang.Object
  extended byjava.awt.Component
      extended byjava.awt.Container
          extended byjava.awt.Window
              extended byjava.awt.Dialog
All Implemented Interfaces:
javax.accessibility.Accessible, ImageObserver, MenuContainer, Serializable
Direct Known Subclasses:
FileDialog, JDialog

public class Dialog
extends Window

A Dialog is a top-level window with a title and a border that is typically used to take some form of input from the user. The size of the dialog includes any area designated for the border. The dimensions of the border area can be obtained using the getInsets method, however, since these dimensions are platform-dependent, a valid insets value cannot be obtained until the dialog is made displayable by either calling pack or show. Since the border area is included in the overall size of the dialog, the border effectively obscures a portion of the dialog, constraining the area available for rendering and/or displaying subcomponents to the rectangle which has an upper-left corner location of (insets.left, insets.top), and has a size of width - (insets.left + insets.right) by height - (insets.top + insets.bottom).

The default layout for a dialog is BorderLayout.

A dialog may have its native decorations (i.e. Frame & Titlebar) turned off with setUndecorated. This can only be done while the dialog is not displayable.

A dialog must have either a frame or another dialog defined as its owner when it's constructed. When the owner window of a visible dialog is minimized, the dialog will automatically be hidden from the user. When the owner window is subsequently restored, the dialog is made visible to the user again.

In a multi-screen environment, you can create a Dialog on a different screen device than its owner. See Frame for more information.

A dialog can be either modeless (the default) or modal. A modal dialog is one which blocks input to all other toplevel windows in the application, except for any windows created with the dialog as their owner.

Dialogs are capable of generating the following WindowEvents: WindowOpened, WindowClosing, WindowClosed, WindowActivated, WindowDeactivated, WindowGainedFocus, WindowLostFocus.

Since:
JDK1.0
Author:
Sami Shaio, Arthur van Hoff
See Also:
WindowEvent, Window.addWindowListener(java.awt.event.WindowListener), Serialized Form

Nested Class Summary
protected  class Dialog.AccessibleAWTDialog
          This class implements accessibility support for the Dialog class.
(package private) static class Dialog.WakingRunnable
           
 
Nested classes inherited from class java.awt.Window
Window.AccessibleAWTWindow
 
Nested classes inherited from class java.awt.Container
Container.AccessibleAWTContainer, Container.DropTargetEventTargetFilter, Container.EventTargetFilter, Container.MouseEventTargetFilter
 
Nested classes inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.AWTTreeLock, Component.BltBufferStrategy, Component.FlipBufferStrategy
 
Field Summary
private static String base
           
private  boolean keepBlocking
           
(package private)  boolean modal
          Will be true if the Dialog is modal, otherwise the dialog will be modeless.
private static int nameCounter
           
(package private)  boolean resizable
          A dialog's resizable property.
private static long serialVersionUID
           
private  sun.awt.AppContext showAppContext
          Stores the app context on which event dispatch thread the dialog is being shown.
(package private)  String title
          Specifies the title of the Dialog.
(package private)  boolean undecorated
          This field indicates whether the dialog is undecorated.
 
Fields inherited from class java.awt.Window
beforeFirstShow, inputContext, OPENED, ownedWindowList, state, syncLWRequests, systemSyncLWRequests, warningString, windowFocusListener, windowListener, windowStateListener
 
Fields inherited from class java.awt.Container
component, containerListener, descendantsCount, INCLUDE_SELF, layoutMgr, listeningBoundsChildren, listeningChildren, ncomponents, SEARCH_HEAVYWEIGHTS
 
Fields inherited from class java.awt.Component
accessibleContext, actionListenerK, adjustmentListenerK, appContext, background, BOTTOM_ALIGNMENT, bufferStrategy, CENTER_ALIGNMENT, componentListener, componentListenerK, componentOrientation, containerListenerK, cursor, dropTarget, enabled, eventMask, focusListener, focusListenerK, focusTraversalKeys, font, foreground, graphicsConfig, height, hierarchyBoundsListener, hierarchyBoundsListenerK, hierarchyListener, hierarchyListenerK, ignoreRepaint, incRate, inputMethodListener, inputMethodListenerK, isInc, isPacked, itemListenerK, keyListener, keyListenerK, LEFT_ALIGNMENT, locale, LOCK, metrics, minSize, mouseListener, mouseListenerK, mouseMotionListener, mouseMotionListenerK, mouseWheelListener, mouseWheelListenerK, newEventsOnly, ownedWindowK, parent, peer, peerFont, popups, prefSize, RIGHT_ALIGNMENT, textListenerK, TOP_ALIGNMENT, valid, visible, width, windowClosingException, windowFocusListenerK, windowListenerK, windowStateListenerK, x, y
 
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
Constructor Summary
Dialog(Dialog owner)
          Constructs an initially invisible, non-modal Dialog with an empty title and the specified owner dialog.
Dialog(Dialog owner, String title)
          Constructs an initially invisible, non-modal Dialog with the specified owner dialog and title.
Dialog(Dialog owner, String title, boolean modal)
          Constructs an initially invisible Dialog with the specified owner dialog, title, and modality.
Dialog(Dialog owner, String title, boolean modal, GraphicsConfiguration gc)
          Constructs an initially invisible Dialog with the specified owner dialog, title, modality, and GraphicsConfiguration.
Dialog(Frame owner)
          Constructs an initially invisible, non-modal Dialog with an empty title and the specified owner frame.
Dialog(Frame owner, boolean modal)
          Constructs an initially invisible Dialog with an empty title, the specified owner frame and modality.
Dialog(Frame owner, String title)
          Constructs an initially invisible, non-modal Dialog with the specified owner frame and title.
Dialog(Frame owner, String title, boolean modal)
          Constructs an initially invisible Dialog with the specified owner frame, title, and modality.
Dialog(Frame owner, String title, boolean modal, GraphicsConfiguration gc)
          Constructs an initially invisible Dialog with the specified owner frame, title, modality, and GraphicsConfiguration.
 
Method Summary
 void addNotify()
          Makes this Dialog displayable by connecting it to a native screen resource.
private  boolean conditionalShow()
           
(package private)  String constructComponentName()
          Construct a name for this component.
 void dispose()
          Disposes the Dialog and then causes show() to return if it is currently blocked.
private  void disposeImpl()
           
 javax.accessibility.AccessibleContext getAccessibleContext()
          Gets the AccessibleContext associated with this Dialog.
 String getTitle()
          Gets the title of the dialog.
 void hide()
          Hides the Dialog and then causes show() to return if it is currently blocked.
private  void hideAndDisposeHandler()
           
private static void initIDs()
          Initialize JNI field and method IDs
(package private)  void interruptBlocking()
           
 boolean isModal()
          Indicates whether the dialog is modal.
 boolean isResizable()
          Indicates whether this dialog is resizable by the user.
 boolean isUndecorated()
          Indicates whether this dialog is undecorated.
protected  String paramString()
          Returns a string representing the state of this dialog.
 void setModal(boolean b)
          Specifies whether this dialog should be modal.
 void setResizable(boolean resizable)
          Sets whether this dialog is resizable by the user.
 void setTitle(String title)
          Sets the title of the Dialog.
 void setUndecorated(boolean undecorated)
          Disables or enables decorations for this dialog.
 void show()
          Makes the Dialog visible.
 
Methods inherited from class java.awt.Window
addOwnedWindow, addPropertyChangeListener, addPropertyChangeListener, addWindowFocusListener, addWindowListener, addWindowStateListener, adjustDecendantsOnParent, adjustListeningChildrenOnParent, applyResourceBundle, applyResourceBundle, clearMostRecentFocusOwnerOnHide, connectOwnedWindow, createBufferStrategy, createBufferStrategy, deliverMouseWheelToAncestor, dispatchEventImpl, dispatchMouseWheelToAncestor, eventEnabled, finalize, getBufferStrategy, getFocusableWindowState, getFocusCycleRootAncestor, getFocusOwner, getFocusTraversalKeys, getGraphicsConfiguration, getInputContext, getListeners, getLocale, getMostRecentFocusOwner, getOwnedWindows, getOwner, getTemporaryLostComponent, getToolkit, getWarningString, getWindowFocusListeners, getWindowListeners, getWindowStateListeners, isActive, isFocusableWindow, isFocusCycleRoot, isFocused, isShowing, pack, postEvent, postProcessKeyEvent, postWindowEvent, preProcessKeyEvent, processEvent, processWindowEvent, processWindowFocusEvent, processWindowStateEvent, removeOwnedWindow, removeWindowFocusListener, removeWindowListener, removeWindowStateListener, resetGC, setCursor, setFocusableWindowState, setFocusCycleRoot, setLocationRelativeTo, setTemporaryLostComponent, toBack, toFront
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, adjustDescendants, adjustListeningChildren, applyComponentOrientation, areFocusTraversalKeysSet, checkGD, clearCurrentFocusCycleRootOnHide, containsFocus, countComponents, countHierarchyMembers, createChildHierarchyEvents, createHierarchyEvents, deliverEvent, dispatchEventToSelf, doLayout, findComponentAt, findComponentAt, findComponentAt, getAccessibleAt, getAccessibleChild, getAccessibleChildrenCount, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents_NoClientCode, getComponents, getContainerListeners, getDropTargetEventTarget, getFocusTraversalPolicy, getInsets, getLayout, getMaximumSize, getMinimumSize, getMouseEventTarget, getPreferredSize, initializeFocusTraversalKeys, insets, invalidate, invalidateTree, isAncestorOf, isFocusCycleRoot, isFocusTraversalPolicySet, isParentOf, layout, lightweightPaint, lightweightPrint, list, list, locate, minimumSize, nextFocusHelper, numListening, paint, paintComponents, paintHeavyweightComponents, postsOldMouseEvents, preferredSize, print, printComponents, printHeavyweightComponents, processContainerEvent, proxyEnableEvents, remove, remove, removeAll, removeContainerListener, removeNotify, setFocusTraversalKeys, setFocusTraversalPolicy, setFont, setLayout, setZOrder, transferFocusBackward, transferFocusDownCycle, update, validate, validateTree
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, areInputMethodsEnabled, autoProcessMouseWheel, autoTransferFocus, bounds, checkImage, checkImage, checkWindowClosingException, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, eventTypeEnabled, firePropertyChange, firePropertyChange, firePropertyChange, getAccessibleIndexInParent, getAccessibleStateSet, getBackBuffer, getBackground, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusListeners, getFocusTraversalKeys_NoIDCheck, getFocusTraversalKeysEnabled, getFont_NoClientCode, getFont, getFontMetrics, getForeground, getGraphics, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocation, getLocation, getLocationOnScreen_NoTreeLock, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMouseWheelListeners, getName, getNativeContainer, getParent_NoClientCode, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkitImpl, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isEnabledImpl, isFocusable, isFocusOwner, isFocusTraversable, isFocusTraversableOverridden, isFontSet, isForegroundSet, isLightweight, isOpaque, isRecursivelyVisible, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusHelper, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, setBackground, setBounds, setBounds, setComponentOrientation, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeys_NoIDCheck, setFocusTraversalKeysEnabled, setForeground, setGCFromPeer, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, setVisible, show, size, toString, transferFocus, transferFocusUpCycle, updateCursorImmediately
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

resizable

boolean resizable
A dialog's resizable property. Will be true if the Dialog is to be resizable, otherwise it will be false.

See Also:
setResizable(boolean)

undecorated

boolean undecorated
This field indicates whether the dialog is undecorated. This property can only be changed while the dialog is not displayable. undecorated will be true if the dialog is undecorated, otherwise it will be false.

Since:
1.4
See Also:
setUndecorated(boolean), isUndecorated(), Component.isDisplayable()

modal

boolean modal
Will be true if the Dialog is modal, otherwise the dialog will be modeless. A modal Dialog grabs all the input to the owner frame from the user.

See Also:
isModal(), setModal(boolean)

title

String title
Specifies the title of the Dialog. This field can be null.

See Also:
getTitle(), setTitle(String)

keepBlocking

private transient boolean keepBlocking

base

private static final String base
See Also:
Constant Field Values

nameCounter

private static int nameCounter

serialVersionUID

private static final long serialVersionUID
See Also:
Constant Field Values

showAppContext

private transient sun.awt.AppContext showAppContext
Stores the app context on which event dispatch thread the dialog is being shown. Initialized in show(), used in hideAndDisposeHandler()

Constructor Detail

Dialog

public Dialog(Frame owner)
Constructs an initially invisible, non-modal Dialog with an empty title and the specified owner frame.

Parameters:
owner - the owner of the dialog
Throws:
IllegalArgumentException - if the owner's GraphicsConfiguration is not from a screen device
IllegalArgumentException - if owner is null; this exception is always thrown when GraphicsEnvironment.isHeadless returns true
See Also:
GraphicsEnvironment.isHeadless(), Component.setSize(int, int), Component.setVisible(boolean)

Dialog

public Dialog(Frame owner,
              boolean modal)
Constructs an initially invisible Dialog with an empty title, the specified owner frame and modality.

Parameters:
owner - the owner of the dialog
modal - if true, dialog blocks input to other app windows when shown
Throws:
IllegalArgumentException - if the owner's GraphicsConfiguration is not from a screen device
IllegalArgumentException - if owner is null; this exception is always thrown when GraphicsEnvironment.isHeadless returns true
See Also:
GraphicsEnvironment.isHeadless()

Dialog

public Dialog(Frame owner,
              String title)
Constructs an initially invisible, non-modal Dialog with the specified owner frame and title.

Parameters:
owner - the owner of the dialog
title - the title of the dialog; a null value will be accepted without causing a NullPointerException to be thrown
Throws:
IllegalArgumentException - if the owner's GraphicsConfiguration is not from a screen device
IllegalArgumentException - if owner is null; this exception is always thrown when GraphicsEnvironment.isHeadless returns true
See Also:
GraphicsEnvironment.isHeadless(), Component.setSize(int, int), Component.setVisible(boolean)

Dialog

public Dialog(Frame owner,
              String title,
              boolean modal)
Constructs an initially invisible Dialog with the specified owner frame, title, and modality.

Parameters:
owner - the owner of the dialog
title - the title of the dialog; a null value will be accepted without causing a NullPointerException to be thrown
modal - if true, dialog blocks input to other app windows when shown
Throws:
IllegalArgumentException - if the owner's GraphicsConfiguration is not from a screen device
IllegalArgumentException - if owner is null. This exception is always thrown when GraphicsEnvironment.isHeadless returns true
See Also:
GraphicsEnvironment.isHeadless(), Component.setSize(int, int), Component.setVisible(boolean)

Dialog

public Dialog(Frame owner,
              String title,
              boolean modal,
              GraphicsConfiguration gc)
Constructs an initially invisible Dialog with the specified owner frame, title, modality, and GraphicsConfiguration.

Parameters:
owner - the owner of the dialog
title - the title of the dialog. A null value will be accepted without causing a NullPointerException to be thrown.
modal - if true, dialog blocks input to other app windows when shown
gc - the GraphicsConfiguration of the target screen device. If gc is null, the same GraphicsConfiguration as the owning Frame is used.
Throws:
IllegalArgumentException - if owner is null. This exception is always thrown when GraphicsEnvironment.isHeadless() returns true
Since:
1.4
See Also:
GraphicsEnvironment.isHeadless(), Component.setSize(int, int), Component.setVisible(boolean)

Dialog

public Dialog(Dialog owner)
Constructs an initially invisible, non-modal Dialog with an empty title and the specified owner dialog.

Parameters:
owner - the owner of the dialog
Throws:
IllegalArgumentException - if owner is null. This exception is always thrown when GraphicsEnvironment.isHeadless() returns true
Since:
1.2
See Also:
GraphicsEnvironment.isHeadless()

Dialog

public Dialog(Dialog owner,
              String title)
Constructs an initially invisible, non-modal Dialog with the specified owner dialog and title.

Parameters:
owner - the owner of the dialog
title - the title of the dialog. A null value will be accepted without causing a NullPointerException to be thrown.
Throws:
IllegalArgumentException - if owner is null. This exception is always thrown when GraphicsEnvironment.isHeadless() returns true
Since:
1.2
See Also:
GraphicsEnvironment.isHeadless()

Dialog

public Dialog(Dialog owner,
              String title,
              boolean modal)
Constructs an initially invisible Dialog with the specified owner dialog, title, and modality.

Parameters:
owner - the owner of the dialog
title - the title of the dialog; a null value will be accepted without causing a NullPointerException to be thrown
modal - if true, dialog blocks input to other app windows when shown
Throws:
IllegalArgumentException - if the owner's GraphicsConfiguration is not from a screen device
IllegalArgumentException - if owner is null; this exception is always thrown when GraphicsEnvironment.isHeadless returns true
Since:
1.2
See Also:
GraphicsEnvironment.isHeadless()

Dialog

public Dialog(Dialog owner,
              String title,
              boolean modal,
              GraphicsConfiguration gc)
Constructs an initially invisible Dialog with the specified owner dialog, title, modality, and GraphicsConfiguration.

Parameters:
owner - the owner of the dialog
title - the title of the dialog; a null value will be accepted without causing a NullPointerException to be thrown
modal - if true, dialog blocks input to other app windows when shown
gc - the GraphicsConfiguration of the target screen device; if gc is null, the same GraphicsConfiguration as the owning Dialog is used
Throws:
IllegalArgumentException - if the owner's GraphicsConfiguration is not from a screen device
IllegalArgumentException - if owner is null; this exception is always thrown when GraphicsEnvironment.isHeadless returns true
Since:
1.4
See Also:
GraphicsEnvironment.isHeadless(), Component.setSize(int, int), Component.setVisible(boolean)
Method Detail

constructComponentName

String constructComponentName()
Construct a name for this component. Called by getName() when the name is null.

Overrides:
constructComponentName in class Window

addNotify

public void addNotify()
Makes this Dialog displayable by connecting it to a native screen resource. Making a dialog displayable will cause any of its children to be made displayable. This method is called internally by the toolkit and should not be called directly by programs.

Overrides:
addNotify in class Window
See Also:
Component.isDisplayable(), Container.removeNotify()

isModal

public boolean isModal()
Indicates whether the dialog is modal. When a modal Dialog is made visible, user input will be blocked to the other windows in the application, except for any windows created with this dialog as their owner.

Returns:
true if this dialog window is modal; false otherwise.
See Also:
setModal(boolean)

setModal

public void setModal(boolean b)
Specifies whether this dialog should be modal.

Since:
JDK1.1
See Also:
isModal()

getTitle

public String getTitle()
Gets the title of the dialog. The title is displayed in the dialog's border.

Returns:
the title of this dialog window. The title may be null.
See Also:
setTitle(java.lang.String)

setTitle

public void setTitle(String title)
Sets the title of the Dialog.

Parameters:
title - the title displayed in the dialog's border; a null value results in an empty title
See Also:
getTitle()

conditionalShow

private boolean conditionalShow()
Returns:
true if we actually showed, false if we just called toFront()

show

public void show()
Makes the Dialog visible. If the dialog and/or its owner are not yet displayable, both are made displayable. The dialog will be validated prior to being made visible. If the dialog is already visible, this will bring the dialog to the front.

If the dialog is modal and is not already visible, this call will not return until the dialog is hidden by calling hide or dispose. It is permissible to show modal dialogs from the event dispatching thread because the toolkit will ensure that another event pump runs while the one which invoked this method is blocked.

Overrides:
show in class Window
See Also:
Component.hide(), Component.isDisplayable(), Component.validate(), isModal()

interruptBlocking

void interruptBlocking()

hideAndDisposeHandler

private void hideAndDisposeHandler()

hide

public void hide()
Hides the Dialog and then causes show() to return if it is currently blocked.

Overrides:
hide in class Window
See Also:
Window.show(), Window.dispose()

dispose

public void dispose()
Disposes the Dialog and then causes show() to return if it is currently blocked.

Overrides:
dispose in class Window
See Also:
Component.isDisplayable(), Window.pack(), Window.show()

disposeImpl

private void disposeImpl()

isResizable

public boolean isResizable()
Indicates whether this dialog is resizable by the user.

Returns:
true if the user can resize the dialog; false otherwise.
See Also:
setResizable(boolean)

setResizable

public void setResizable(boolean resizable)
Sets whether this dialog is resizable by the user.

Parameters:
resizable - true if the user can resize this dialog; false otherwise.
See Also:
isResizable()

setUndecorated

public void setUndecorated(boolean undecorated)
Disables or enables decorations for this dialog. This method can only be called while the dialog is not displayable.

Parameters:
undecorated - true if no dialog decorations are to be enabled; false if dialog decorations are to be enabled.
Throws:
IllegalComponentStateException - if the dialog is displayable.
Since:
1.4
See Also:
isUndecorated(), Component.isDisplayable()

isUndecorated

public boolean isUndecorated()
Indicates whether this dialog is undecorated. By default, all dialogs are initially decorated.

Returns:
true if dialog is undecorated; false otherwise.
Since:
1.4
See Also:
setUndecorated(boolean)

paramString

protected String paramString()
Returns a string representing the state of this dialog. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class Container
Returns:
the parameter string of this dialog window.

initIDs

private static void initIDs()
Initialize JNI field and method IDs


getAccessibleContext

public javax.accessibility.AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this Dialog. For dialogs, the AccessibleContext takes the form of an AccessibleAWTDialog. A new AccessibleAWTDialog instance is created if necessary.

Specified by:
getAccessibleContext in interface javax.accessibility.Accessible
Overrides:
getAccessibleContext in class Window
Returns:
an AccessibleAWTDialog that serves as the AccessibleContext of this Dialog