java.awt.Dialog

public class java.awt

Dialog

Java SE 6

Extends: Component > Container > Window

Inner classes: Dialog.ModalityType, Dialog.ModalExclusionType, Dialog.AccessibleAWTDialog

Extended by: FileDialog, JDialog

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 may have another window 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 java.awt.Frame for more information.

A dialog can be either modeless (the default) or modal. A modal dialog is one which blocks input to some other top-level windows in the application, except for any windows created with the dialog as their owner. See AWT Modality specification for details.

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

version 1.125, 06/21/06

since JDK1.0

See also java.awt.event.WindowEvent, addWindowListener

Fields

final public static Dialog.ModalityType

DEFAULT_MODALITY_TYPE Details

Default modality type for modal dialogs. The default modality type is APPLICATION_MODAL. Calling the oldstyle setModal(true) is equal to setModalityType(DEFAULT_MODALITY_TYPE).

since	1.6
See also	java.awt.Dialog.ModalityType, setModal

Constructors

public

Dialog(Frame owner) Details

Constructs an initially invisible, modeless Dialog with the specified owner Frame and an empty title.

owner	the owner of the dialog or `null` if this dialog has no owner
Throws	IllegalArgumentException: if the `owner`'s `GraphicsConfiguration` is not from a screen device
Throws	HeadlessException: when `GraphicsEnvironment.isHeadless()` returns `true`
See also	isHeadless, setSize, setVisible

public

Dialog(Frame owner, boolean modal) Details

Constructs an initially invisible Dialog with the specified owner Frame and modality and an empty title.

owner	the owner of the dialog or `null` if this dialog has no owner
modal	specifes whether dialog blocks user input to other top-level windows when shown. If `false`, the dialog is `MODELESS`; if `true`, the modality type property is set to `DEFAULT_MODALITY_TYPE`
Throws	IllegalArgumentException: if the `owner`'s `GraphicsConfiguration` is not from a screen device
Throws	HeadlessException: when `GraphicsEnvironment.isHeadless()` returns `true`
See also	java.awt.Dialog.ModalityType, MODELESS, DEFAULT_MODALITY_TYPE, setModal, setModalityType, isHeadless

public

Dialog(Frame owner, String title) Details

Constructs an initially invisible, modeless Dialog with the specified owner Frame and title.

owner	the owner of the dialog or `null` if this dialog has no owner
title	the title of the dialog or `null` if this dialog has no title
Throws	IllegalArgumentException: if the `owner`'s `GraphicsConfiguration` is not from a screen device
Throws	HeadlessException: when `GraphicsEnvironment.isHeadless()` returns `true`
See also	isHeadless, setSize, setVisible

public

Dialog(Frame owner, String title, boolean modal) Details

Constructs an initially invisible Dialog with the specified owner Frame, title and modality.

owner	the owner of the dialog or `null` if this dialog has no owner
title	the title of the dialog or `null` if this dialog has no title
modal	specifes whether dialog blocks user input to other top-level windows when shown. If `false`, the dialog is `MODELESS`; if `true`, the modality type property is set to `DEFAULT_MODALITY_TYPE`
Throws	IllegalArgumentException: if the `owner`'s `GraphicsConfiguration` is not from a screen device
Throws	HeadlessException: when `GraphicsEnvironment.isHeadless()` returns `true`
See also	java.awt.Dialog.ModalityType, MODELESS, DEFAULT_MODALITY_TYPE, setModal, setModalityType, isHeadless, setSize, setVisible

public

Dialog(Frame owner, String title, boolean modal, GraphicsConfiguration gc) Details

Constructs an initially invisible Dialog with the specified owner Frame, title, modality, and GraphicsConfiguration.

owner	the owner of the dialog or `null` if this dialog has no owner
title	the title of the dialog or `null` if this dialog has no title
modal	specifes whether dialog blocks user input to other top-level windows when shown. If `false`, the dialog is `MODELESS`; if `true`, the modality type property is set to `DEFAULT_MODALITY_TYPE`
gc	the `GraphicsConfiguration` of the target screen device; if `null`, the default system `GraphicsConfiguration` is assumed
Throws	IllegalArgumentException: if `gc` is not from a screen device
Throws	HeadlessException: when `GraphicsEnvironment.isHeadless()` returns `true`
since	1.4
See also	java.awt.Dialog.ModalityType, MODELESS, DEFAULT_MODALITY_TYPE, setModal, setModalityType, isHeadless, setSize, setVisible

public

Dialog(Dialog owner) Details

Constructs an initially invisible, modeless Dialog with the specified owner Dialog and an empty title.

owner	the owner of the dialog or `null` if this dialog has no owner
Throws	IllegalArgumentException: if the `owner`'s `GraphicsConfiguration` is not from a screen device
Throws	HeadlessException: when `GraphicsEnvironment.isHeadless()` returns `true`
since	1.2
See also	isHeadless

public

Dialog(Dialog owner, String title) Details

Constructs an initially invisible, modeless Dialog with the specified owner Dialog and title.

owner	the owner of the dialog or `null` if this has no owner
title	the title of the dialog or `null` if this dialog has no title
Throws	IllegalArgumentException: if the `owner`'s `GraphicsConfiguration` is not from a screen device
Throws	HeadlessException: when `GraphicsEnvironment.isHeadless()` returns `true`
since	1.2
See also	isHeadless

public

Dialog(Dialog owner, String title, boolean modal) Details

Constructs an initially invisible Dialog with the specified owner Dialog, title, and modality.

owner	the owner of the dialog or `null` if this dialog has no owner
title	the title of the dialog or `null` if this dialog has no title
modal	specifes whether dialog blocks user input to other top-level windows when shown. If `false`, the dialog is `MODELESS`; if `true`, the modality type property is set to `DEFAULT_MODALITY_TYPE`
Throws	IllegalArgumentException: if the `owner`'s `GraphicsConfiguration` is not from a screen device
Throws	HeadlessException: when `GraphicsEnvironment.isHeadless()` returns `true`
since	1.2
See also	java.awt.Dialog.ModalityType, MODELESS, DEFAULT_MODALITY_TYPE, setModal, setModalityType, isHeadless

public

Dialog(Dialog owner, String title, boolean modal, GraphicsConfiguration gc) Details

Constructs an initially invisible Dialog with the specified owner Dialog, title, modality and GraphicsConfiguration.

owner	the owner of the dialog or `null` if this dialog has no owner
title	the title of the dialog or `null` if this dialog has no title
modal	specifes whether dialog blocks user input to other top-level windows when shown. If `false`, the dialog is `MODELESS`; if `true`, the modality type property is set to `DEFAULT_MODALITY_TYPE`
gc	the `GraphicsConfiguration` of the target screen device; if `null`, the default system `GraphicsConfiguration` is assumed
Throws	IllegalArgumentException: if `gc` is not from a screen device
Throws	HeadlessException: when `GraphicsEnvironment.isHeadless()` returns `true`
since	1.4
See also	java.awt.Dialog.ModalityType, MODELESS, DEFAULT_MODALITY_TYPE, setModal, setModalityType, isHeadless, setSize, setVisible

public

Dialog(Window owner) Details

Constructs an initially invisible, modeless Dialog with the specified owner Window and an empty title.

owner	the owner of the dialog. The owner must be an instance of `Dialog`, `Frame`, any of their descendents or `null`
Throws	IllegalArgumentException: if the `owner` is not an instance of `Dialog` or `Frame`
Throws	IllegalArgumentException: if the `owner`'s `GraphicsConfiguration` is not from a screen device
Throws	HeadlessException: when `GraphicsEnvironment.isHeadless()` returns `true`
since	1.6
See also	isHeadless

public

Dialog(Window owner, String title) Details

Constructs an initially invisible, modeless Dialog with the specified owner Window and title.

owner	the owner of the dialog. The owner must be an instance of `Dialog`, `Frame`, any of their descendents or `null`
title	the title of the dialog or `null` if this dialog has no title
Throws	IllegalArgumentException: if the `owner` is not an instance of `Dialog` or `Frame`
Throws	IllegalArgumentException: if the `owner`'s `GraphicsConfiguration` is not from a screen device
Throws	HeadlessException: when `GraphicsEnvironment.isHeadless()` returns `true`
since	1.6
See also	isHeadless

public

Dialog(Window owner, Dialog.ModalityType modalityType) Details

Constructs an initially invisible Dialog with the specified owner Window and modality and an empty title.

owner	the owner of the dialog. The owner must be an instance of `Dialog`, `Frame`, any of their descendents or `null`
modalityType	specifies whether dialog blocks input to other windows when shown. `null` value and unsupported modality types are equivalent to `MODELESS`
Throws	IllegalArgumentException: if the `owner` is not an instance of `Dialog` or `Frame`
Throws	IllegalArgumentException: if the `owner`'s `GraphicsConfiguration` is not from a screen device
Throws	HeadlessException: when `GraphicsEnvironment.isHeadless()` returns `true`
Throws	SecurityException: if the calling thread does not have permission to create modal dialogs with the given `modalityType`
since	1.6
See also	java.awt.Dialog.ModalityType, setModal, setModalityType, isHeadless, isModalityTypeSupported

public

Dialog(Window owner, String title, Dialog.ModalityType modalityType) Details

Constructs an initially invisible Dialog with the specified owner Window, title and modality.

owner	the owner of the dialog. The owner must be an instance of `Dialog`, `Frame`, any of their descendents or `null`
title	the title of the dialog or `null` if this dialog has no title
modalityType	specifies whether dialog blocks input to other windows when shown. `null` value and unsupported modality types are equivalent to `MODELESS`
Throws	IllegalArgumentException: if the `owner` is not an instance of `Dialog` or `Frame`
Throws	IllegalArgumentException: if the `owner`'s `GraphicsConfiguration` is not from a screen device
Throws	HeadlessException: when `GraphicsEnvironment.isHeadless()` returns `true`
Throws	SecurityException: if the calling thread does not have permission to create modal dialogs with the given `modalityType`
since	1.6
See also	java.awt.Dialog.ModalityType, setModal, setModalityType, isHeadless, isModalityTypeSupported

public

Dialog(Window owner, String title, Dialog.ModalityType modalityType, GraphicsConfiguration gc) Details

Constructs an initially invisible Dialog with the specified owner Window, title, modality and GraphicsConfiguration.

owner	the owner of the dialog. The owner must be an instance of `Dialog`, `Frame`, any of their descendents or `null`
title	the title of the dialog or `null` if this dialog has no title
modalityType	specifies whether dialog blocks input to other windows when shown. `null` value and unsupported modality types are equivalent to `MODELESS`
gc	the `GraphicsConfiguration` of the target screen device; if `null`, the default system `GraphicsConfiguration` is assumed
Throws	IllegalArgumentException: if the `owner` is not an instance of `Dialog` or `Frame`
Throws	IllegalArgumentException: if `gc` is not from a screen device
Throws	HeadlessException: when `GraphicsEnvironment.isHeadless()` returns `true`
Throws	SecurityException: if the calling thread does not have permission to create modal dialogs with the given `modalityType`
since	1.6
See also	java.awt.Dialog.ModalityType, setModal, setModalityType, isHeadless, isModalityTypeSupported

Methods

public void

addNotify() Details

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.

See also

isDisplayable, removeNotify

public void

hide()

Hides the Dialog and then causes show to return if it is currently blocked.

deprecated	As of JDK version 1.5, replaced by `setVisible(boolean)`.
See also	show, dispose, setVisible(boolean)

protected String

paramString() Details

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.

return

the parameter string of this dialog window.

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.

deprecated As of JDK version 1.5, replaced by setVisible(boolean).

See also hide, isDisplayable, validate, isModal, setVisible(boolean)

public void

toBack() Details

If this Window is visible, sends this Window to the back and may cause it to lose focus or activation if it is the focused or active Window.

Places this Window at the bottom of the stacking order and shows it behind any other Windows in this VM. No action will take place is this Window is not visible. Some platforms do not allow Windows which are owned by other Windows to appear below their owners. Every attempt will be made to move this Window as low as possible in the stacking order; however, developers should not assume that this method will move this Window below all other windows in every situation.

Because of variations in native windowing systems, no guarantees about changes to the focused and active Windows can be made. Developers must never assume that this Window is no longer the focused or active Window until this Window receives a WINDOW_LOST_FOCUS or WINDOW_DEACTIVATED event. On platforms where the top-most window is the focused window, this method will probably cause this Window to lose focus. In that case, the next highest, focusable Window in this VM will receive focus. On platforms where the stacking order does not typically affect the focused window, this method will probably leave the focused and active Windows unchanged.

If this dialog is modal and blocks some windows, then all of them are also sent to the back to keep them below the blocking dialog.

See also toBack

Properties

public AccessibleContext

getAccessibleContext() Details

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.

return	an AccessibleAWTDialog that serves as the AccessibleContext of this Dialog
since	1.3

public void

setModal(boolean modal) Details

Specifies whether this dialog should be modal.

This method is obsolete and is kept for backwards compatibility only. Use setModalityType() instead.

Note: changing modality of the visible dialog may have no effect until it is hidden and then shown again.

modal specifies whether dialog blocks input to other windows when shown; calling to setModal(true) is equivalent to setModalityType(Dialog.DEFAULT_MODALITY_TYPE), and calling to setModal(false) is equvivalent to setModalityType(Dialog.ModalityType.MODELESS)

since 1.1

See also DEFAULT_MODALITY_TYPE, MODELESS, isModal, getModalityType, setModalityType

public boolean

isModal() Details

Indicates whether the dialog is modal.

This method is obsolete and is kept for backwards compatiblity only. Use getModalityType() instead.

return true if this dialog window is modal; false otherwise

See also DEFAULT_MODALITY_TYPE, MODELESS, setModal, getModalityType, setModalityType

public void

setModalityType(Dialog.ModalityType type) Details

Sets the modality type for this dialog. See ModalityType for possible modality types.

If the given modality type is not supported, MODELESS is used. You may want to call getModalityType() after calling this method to ensure that the modality type has been set.

Note: changing modality of the visible dialog may have no effect until it is hidden and then shown again.

type specifies whether dialog blocks input to other windows when shown. null value and unsupported modality types are equivalent to MODELESS

Throws SecurityException: if the calling thread does not have permission to create modal dialogs with the given modalityType

since 1.6

See also getModalityType, isModalityTypeSupported

public Dialog.ModalityType

getModalityType() Details

Returns the modality type of this dialog.

return	modality type of this dialog
since	1.6
See also	setModalityType

public void

setResizable(boolean resizable) Details

Sets whether this dialog is resizable by the user.

resizable	`true` if the user can resize this dialog; `false` otherwise.
See also	isResizable

public boolean

isResizable() Details

Indicates whether this dialog is resizable by the user. By default, all dialogs are initially resizable.

return	`true` if the user can resize the dialog; `false` otherwise.
See also	setResizable

public void

setTitle(String title) Details

Sets the title of the Dialog.

title	the title displayed in the dialog's border; a null value results in an empty title
See also	getTitle

public String

getTitle() Details

Gets the title of the dialog. The title is displayed in the dialog's border.

return	the title of this dialog window. The title may be `null`.
See also	setTitle

public void

setUndecorated(boolean undecorated) Details

Disables or enables decorations for this dialog. This method can only be called while the dialog is not displayable.

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, isDisplayable

public boolean

isUndecorated() Details

Indicates whether this dialog is undecorated. By default, all dialogs are initially decorated.

return	`true` if dialog is undecorated; `false` otherwise.
since	1.4
See also	setUndecorated

public void

setVisible(boolean b) Details

Shows or hides this Dialog depending on the value of parameter b.

b

if true, makes the Dialog visible, otherwise hides the Dialog. 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 false, hides the Dialog and then causes setVisible(true) to return if it is currently blocked.

Notes for modal dialogs.

setVisible(true): If the dialog is not already visible, this call will not return until the dialog is hidden by calling setVisible(false) or dispose.
setVisible(false): Hides the dialog and then returns on setVisible(true) if it is currently blocked.
It is OK to call this method from the event dispatching thread because the toolkit ensures that other events are not blocked while this method is blocked.

See also setVisible, dispose, isDisplayable, validate, isModal

About DocWeb · Bundles · Export · Export All

Top 10 · Statistics · Login

About Sun · Contact · Privacy · Terms of Use · Trademarks

Java SE 6

· Copyright © 1994-2013 Sun Microsystems, Inc.
All rights reserved. Use is subject to license terms