Class Dialog
- All Implemented Interfaces:
IShellProvider
- Direct Known Subclasses:
EditorSelectionDialog
,IconAndMessageDialog
,InputDialog
,ResizableDialog
,TrayDialog
,ViewSettingsDialog
Dialogs are usually modal. Consequently, it is generally bad practice to open a dialog without a parent. A modal dialog without a parent is not prevented from disappearing behind the application's other windows, making it very confusing for the user.
If more than one modal dialog is open, the second one should be parented off of the shell of the first one. Otherwise, it is possible that the OS will give focus to the first dialog, potentially blocking the UI.
This class also moves the default button to the right if required, see
initializeBounds()
.
-
Nested Class Summary
Nested classes/interfaces inherited from class org.eclipse.jface.window.Window
Window.IExceptionHandler
-
Field Summary
Modifier and TypeFieldDescriptionstatic IDialogBlockedHandler
Create a default instance of the blocked handler which does not do anything.The button bar;null
until dialog is layed out.static final int
A value that can be used for stored dialog width or height that indicates that the default bounds should be used.static final int
Persist the last location of the dialog.static final int
Persist the last known size of the dialog.protected Control
The dialog area;null
until dialog is layed out.static final String
Deprecated, for removal: This API element is subject to removal in a future version.use org.eclipse.swt.widgets.Display.getSystemImage(SWT.ICON_ERROR)static final String
Image registry key for help image (value"dialog_help_image"
).static final String
Deprecated, for removal: This API element is subject to removal in a future version.use org.eclipse.swt.widgets.Display.getSystemImage(SWT.ICON_INFORMATION)static final String
Image registry key for info message image (value"dialog_message_error_image"
).static final String
Image registry key for info message image (value"dialog_messasge_info_image"
).static final String
Image registry key for info message image (value"dialog_messasge_warning_image"
).static final String
Deprecated, for removal: This API element is subject to removal in a future version.org.eclipse.swt.widgets.Display.getSystemImage(SWT.ICON_QUESTION)static final String
Deprecated.use org.eclipse.swt.widgets.Display.getSystemImage(SWT.ICON_WARNING)static final String
The ellipsis is the string that is used to represent shortened text.Fields inherited from class org.eclipse.jface.window.Window
CANCEL, OK, resizeHasOccurred
-
Constructor Summary
ModifierConstructorDescriptionprotected
Dialog
(IShellProvider parentShell) Creates a dialog with the given parent.protected
Creates a dialog instance. -
Method Summary
Modifier and TypeMethodDescriptionstatic void
applyDialogFont
(Control control) Applies the dialog font to all controls that currently have the default font.protected void
buttonPressed
(int buttonId) Notifies that this dialog's button with the given id has been pressed.protected void
Notifies that the cancel button of this dialog has been pressed.boolean
close()
Closes this window, disposes its shell, and removes this window from its window manager (if it has one).protected int
convertHeightInCharsToPixels
(int chars) Returns the number of pixels corresponding to the height of the given number of characters.static int
convertHeightInCharsToPixels
(FontMetrics fontMetrics, int chars) Returns the number of pixels corresponding to the height of the given number of characters.protected int
convertHorizontalDLUsToPixels
(int dlus) Returns the number of pixels corresponding to the given number of horizontal dialog units.static int
convertHorizontalDLUsToPixels
(FontMetrics fontMetrics, int dlus) Returns the number of pixels corresponding to the given number of horizontal dialog units.protected int
convertVerticalDLUsToPixels
(int dlus) Returns the number of pixels corresponding to the given number of vertical dialog units.static int
convertVerticalDLUsToPixels
(FontMetrics fontMetrics, int dlus) Returns the number of pixels corresponding to the given number of vertical dialog units.protected int
convertWidthInCharsToPixels
(int chars) Returns the number of pixels corresponding to the width of the given number of characters.static int
convertWidthInCharsToPixels
(FontMetrics fontMetrics, int chars) Returns the number of pixels corresponding to the width of the given number of characters.void
create()
Creates this window's widgetry in a new top-level shell.protected Button
createButton
(Composite parent, int id, String label, boolean defaultButton) Creates a new button with the given id.protected Control
createButtonBar
(Composite parent) Creates and returns the contents of this dialog's button bar.protected void
createButtonsForButtonBar
(Composite parent) Adds buttons to this dialog's button bar.protected Control
createContents
(Composite parent) TheDialog
implementation of thisWindow
method creates and lays out the top level composite for the dialog, and determines the appropriate horizontal and vertical dialog units based on the font size.protected Control
createDialogArea
(Composite parent) Creates and returns the contents of the upper part of this dialog (above the button bar).protected static boolean
Return whether or not the dialog font is currently the same as the default font.static IDialogBlockedHandler
Get the IDialogBlockedHandler to be used by WizardDialogs and ModalContexts.protected Button
getButton
(int id) Returns the button created by the methodcreateButton
for the specified ID as defined onIDialogConstants
.protected Control
Returns the button bar control.protected Button
Deprecated.UsegetButton(IDialogConstants.CANCEL_ID)
instead.protected Control
Returns the dialog area control.protected IDialogSettings
Gets the dialog settings that should be used for remembering the bounds of of the dialog, according to the dialog bounds strategy.protected int
Get the integer constant that describes the strategy for persisting the dialog bounds.static Image
Returns the standard dialog image with the given key.protected Point
getInitialLocation
(Point initialSize) Returns the initial location to use for the shell.protected Point
Returns the initial size to use for the shell.protected Button
Deprecated.UsegetButton(IDialogConstants.OK_ID)
instead.protected void
Initializes the location and size of this window's SWT shell after it has been created.protected void
initializeDialogUnits
(Control control) Initializes the computation of horizontal and vertical dialog units based on the size of current font.protected boolean
Returns a boolean indicating whether the dialog should be considered resizable when the shell style is initially set.protected void
Notifies that the ok button of this dialog has been pressed.static void
setBlockedHandler
(IDialogBlockedHandler blockedHandler) Set the IDialogBlockedHandler to be used by WizardDialogs and ModalContexts.protected void
setButtonLayoutData
(Button button) Set the layout data of the button to a GridData with appropriate heights and widths.protected void
setButtonLayoutFormData
(Button button) Set the layout data of the button to a FormData with appropriate heights and widths.static String
shortenText
(String textValue, Control control) Try to shorten the given texttextValue
so that its width in pixels does not exceed the width of the given control.Methods inherited from class org.eclipse.jface.window.Window
canHandleShellCloseEvent, configureShell, constrainShellSize, createShell, getConstrainedShellBounds, getContents, getDefaultImage, getDefaultImages, getDefaultOrientation, getLayout, getParentShell, getReturnCode, getShell, getShellListener, getShellStyle, getWindowManager, handleFontChange, handleShellCloseEvent, open, setBlockOnOpen, setDefaultImage, setDefaultImages, setDefaultModalParent, setDefaultOrientation, setExceptionHandler, setParentShell, setReturnCode, setShellStyle, setWindowManager
-
Field Details
-
DLG_IMG_ERROR
Deprecated, for removal: This API element is subject to removal in a future version.use org.eclipse.swt.widgets.Display.getSystemImage(SWT.ICON_ERROR)Image registry key for error image (value"dialog_error_image"
).- See Also:
-
DLG_IMG_INFO
Deprecated, for removal: This API element is subject to removal in a future version.use org.eclipse.swt.widgets.Display.getSystemImage(SWT.ICON_INFORMATION)Image registry key for info image (value"dialog_info_image"
).- See Also:
-
DLG_IMG_QUESTION
Deprecated, for removal: This API element is subject to removal in a future version.org.eclipse.swt.widgets.Display.getSystemImage(SWT.ICON_QUESTION)Image registry key for question image (value"dialog_question_image"
).- See Also:
-
DLG_IMG_WARNING
Deprecated.use org.eclipse.swt.widgets.Display.getSystemImage(SWT.ICON_WARNING)Image registry key for warning image (value"dialog_warning_image"
).- See Also:
-
DLG_IMG_MESSAGE_INFO
Image registry key for info message image (value"dialog_messasge_info_image"
).- Since:
- 2.0
- See Also:
-
DLG_IMG_MESSAGE_WARNING
Image registry key for info message image (value"dialog_messasge_warning_image"
).- Since:
- 2.0
- See Also:
-
DLG_IMG_MESSAGE_ERROR
Image registry key for info message image (value"dialog_message_error_image"
).- Since:
- 2.0
- See Also:
-
DLG_IMG_HELP
Image registry key for help image (value"dialog_help_image"
).- Since:
- 3.2
- See Also:
-
ELLIPSIS
The ellipsis is the string that is used to represent shortened text.- Since:
- 3.0
- See Also:
-
DIALOG_DEFAULT_BOUNDS
public static final int DIALOG_DEFAULT_BOUNDSA value that can be used for stored dialog width or height that indicates that the default bounds should be used.- Since:
- 3.2
- See Also:
-
DIALOG_PERSISTLOCATION
public static final int DIALOG_PERSISTLOCATIONPersist the last location of the dialog.- Since:
- 3.2
- See Also:
-
DIALOG_PERSISTSIZE
public static final int DIALOG_PERSISTSIZEPersist the last known size of the dialog.- Since:
- 3.2
- See Also:
-
dialogArea
The dialog area;null
until dialog is layed out. -
buttonBar
The button bar;null
until dialog is layed out. -
blockedHandler
Create a default instance of the blocked handler which does not do anything.
-
-
Constructor Details
-
Dialog
Creates a dialog instance. Note that the window will have no visual representation (no widgets) until it is told to open. By default,open
blocks for dialogs.- Parameters:
parentShell
- the parent shell, ornull
to create a top-level shell
-
Dialog
Creates a dialog with the given parent.- Parameters:
parentShell
- object that returns the current parent shell- Since:
- 3.1
-
-
Method Details
-
convertHeightInCharsToPixels
Returns the number of pixels corresponding to the height of the given number of characters.The required
FontMetrics
parameter may be created in the following way:GC gc = new GC(control); gc.setFont(control.getFont()); fontMetrics = gc.getFontMetrics(); gc.dispose();
- Parameters:
fontMetrics
- used in performing the conversionchars
- the number of characters- Returns:
- the number of pixels
- Since:
- 2.0
-
convertHorizontalDLUsToPixels
Returns the number of pixels corresponding to the given number of horizontal dialog units.The required
FontMetrics
parameter may be created in the following way:GC gc = new GC(control); gc.setFont(control.getFont()); fontMetrics = gc.getFontMetrics(); gc.dispose();
- Parameters:
fontMetrics
- used in performing the conversiondlus
- the number of horizontal dialog units- Returns:
- the number of pixels
- Since:
- 2.0
-
convertVerticalDLUsToPixels
Returns the number of pixels corresponding to the given number of vertical dialog units.The required
FontMetrics
parameter may be created in the following way:GC gc = new GC(control); gc.setFont(control.getFont()); fontMetrics = gc.getFontMetrics(); gc.dispose();
- Parameters:
fontMetrics
- used in performing the conversiondlus
- the number of vertical dialog units- Returns:
- the number of pixels
- Since:
- 2.0
-
convertWidthInCharsToPixels
Returns the number of pixels corresponding to the width of the given number of characters.The required
FontMetrics
parameter may be created in the following way:GC gc = new GC(control); gc.setFont(control.getFont()); fontMetrics = gc.getFontMetrics(); gc.dispose();
- Parameters:
fontMetrics
- used in performing the conversionchars
- the number of characters- Returns:
- the number of pixels
- Since:
- 2.0
-
shortenText
Try to shorten the given texttextValue
so that its width in pixels does not exceed the width of the given control. Overrides characters in the center of the original string with an ellipsis ("...") if necessary. If anull
value is given,null
is returned.Note: if the text cannot be shortened because the width of control is too low the full original string is returned.
- Parameters:
textValue
- the original string ornull
control
- the control the string will be displayed on- Returns:
- the string to display, or
null
if null was passed in - Since:
- 3.0
-
buttonPressed
protected void buttonPressed(int buttonId) Notifies that this dialog's button with the given id has been pressed.The
Dialog
implementation of this framework method callsokPressed
if the ok button is the pressed, andcancelPressed
if the cancel button is the pressed. All other button presses are ignored. Subclasses may override to handle other buttons, but should callsuper.buttonPressed
if the default handling of the ok and cancel buttons is desired.- Parameters:
buttonId
- the id of the button that was pressed (seeIDialogConstants.*_ID
constants)
-
cancelPressed
protected void cancelPressed()Notifies that the cancel button of this dialog has been pressed.The
Dialog
implementation of this framework method sets this dialog's return code toWindow.CANCEL
and closes the dialog. Subclasses may override if desired. -
convertHeightInCharsToPixels
protected int convertHeightInCharsToPixels(int chars) Returns the number of pixels corresponding to the height of the given number of characters.This method may only be called after
initializeDialogUnits
has been called.Clients may call this framework method, but should not override it.
- Parameters:
chars
- the number of characters- Returns:
- the number of pixels
-
convertHorizontalDLUsToPixels
protected int convertHorizontalDLUsToPixels(int dlus) Returns the number of pixels corresponding to the given number of horizontal dialog units.This method may only be called after
initializeDialogUnits
has been called.Clients may call this framework method, but should not override it.
- Parameters:
dlus
- the number of horizontal dialog units- Returns:
- the number of pixels
-
convertVerticalDLUsToPixels
protected int convertVerticalDLUsToPixels(int dlus) Returns the number of pixels corresponding to the given number of vertical dialog units.This method may only be called after
initializeDialogUnits
has been called.Clients may call this framework method, but should not override it.
- Parameters:
dlus
- the number of vertical dialog units- Returns:
- the number of pixels
-
convertWidthInCharsToPixels
protected int convertWidthInCharsToPixels(int chars) Returns the number of pixels corresponding to the width of the given number of characters.This method may only be called after
initializeDialogUnits
has been called.Clients may call this framework method, but should not override it.
- Parameters:
chars
- the number of characters- Returns:
- the number of pixels
-
createButton
Creates a new button with the given id.The
Dialog
implementation of this framework method creates a standard push button, registers it for selection events including button presses, and registers default buttons with its shell. The button id is stored as the button's client data. If the button id isIDialogConstants.CANCEL_ID
, the new button will be accessible fromgetCancelButton()
. If the button id isIDialogConstants.OK_ID
, the new button will be accesible fromgetOKButton()
. Note that the parent's layout is assumed to be aGridLayout
and the number of columns in this layout is incremented. Subclasses may override.Note: The common button order is: {other buttons}, OK, Cancel. On some platforms,
initializeBounds()
will move the default button to the right.- Parameters:
parent
- the parent compositeid
- the id of the button (seeIDialogConstants.*_ID
constants for standard dialog button ids)label
- the label from the buttondefaultButton
-true
if the button is to be the default button, andfalse
otherwise- Returns:
- the new button
- See Also:
-
createButtonBar
Creates and returns the contents of this dialog's button bar.The
Dialog
implementation of this framework method lays out a button bar and calls thecreateButtonsForButtonBar
framework method to populate it. Subclasses may override.The returned control's layout data must be an instance of
GridData
.- Parameters:
parent
- the parent composite to contain the button bar- Returns:
- the button bar control
-
createButtonsForButtonBar
Adds buttons to this dialog's button bar.The
Dialog
implementation of this framework method adds standard ok and cancel buttons using thecreateButton
framework method. These standard buttons will be accessible fromgetCancelButton
, andgetOKButton
. Subclasses may override.Note: The common button order is: {other buttons}, OK, Cancel. On some platforms,
initializeBounds()
will move the default button to the right.- Parameters:
parent
- the button bar composite
-
initializeBounds
protected void initializeBounds()Initializes the location and size of this window's SWT shell after it has been created.This framework method is called by the
create
framework method. The default implementation callsgetInitialSize
andgetInitialLocation
and passes the results toShell.setBounds
. This is only done if the bounds of the shell have not already been modified. Subclasses may extend or reimplement.The implementation in
Dialog(org.eclipse.jface.window.IShellProvider)
also moves thedefault button
in thebutton bar
to the right if that's required by theplatform convention
.- Overrides:
initializeBounds
in classWindow
-
createContents
TheDialog
implementation of thisWindow
method creates and lays out the top level composite for the dialog, and determines the appropriate horizontal and vertical dialog units based on the font size. It then calls thecreateDialogArea
andcreateButtonBar
methods to create the dialog area and button bar, respectively. OverridingcreateDialogArea
andcreateButtonBar
are recommended rather than overriding this method.- Overrides:
createContents
in classWindow
- Parameters:
parent
- the parent composite for the controls in this window. The type of layout used is determined by getLayout()- Returns:
- the control that will be returned by subsequent calls to getContents()
-
createDialogArea
Creates and returns the contents of the upper part of this dialog (above the button bar).The
Dialog
implementation of this framework method creates and returns a newComposite
with standard margins and spacing.The returned control's layout data must be an instance of
GridData
. This method must not modify the parent's layout.Subclasses must override this method but may call
super
as in the following example:Composite composite = (Composite) super.createDialogArea(parent); //add controls to composite as necessary return composite;
- Parameters:
parent
- the parent composite to contain the dialog area- Returns:
- the dialog area control
-
getButton
Returns the button created by the methodcreateButton
for the specified ID as defined onIDialogConstants
. IfcreateButton
was never called with this ID, or ifcreateButton
is overridden, this method will returnnull
.- Parameters:
id
- the id of the button to look for- Returns:
- the button for the ID or
null
- Since:
- 2.0
- See Also:
-
getButtonBar
Returns the button bar control.Clients may call this framework method, but should not override it.
- Returns:
- the button bar, or
null
if the button bar has not been created yet
-
getCancelButton
Deprecated.UsegetButton(IDialogConstants.CANCEL_ID)
instead. This method will be removed soon.Returns the button created whencreateButton
is called with an ID ofIDialogConstants.CANCEL_ID
. IfcreateButton
was never called with this parameter, or ifcreateButton
is overridden,getCancelButton
will returnnull
.- Returns:
- the cancel button or
null
- Since:
- 2.0
- See Also:
-
getDialogArea
Returns the dialog area control.Clients may call this framework method, but should not override it.
- Returns:
- the dialog area, or
null
if the dialog area has not been created yet
-
getImage
Returns the standard dialog image with the given key. Note that these images are managed by the dialog framework, and must not be disposed by another party.- Parameters:
key
- one of theDialog.DLG_IMG_*
constants- Returns:
- the standard dialog image NOTE: Dialog does not use the following images in the registry DLG_IMG_ERROR DLG_IMG_INFO DLG_IMG_QUESTION DLG_IMG_WARNING They are now coming directly from SWT, see ImageRegistry. For backwards compatibility they are still supported, however new code should use SWT for these.
- See Also:
-
getOKButton
Deprecated.UsegetButton(IDialogConstants.OK_ID)
instead. This method will be removed soon.Returns the button created whencreateButton
is called with an ID ofIDialogConstants.OK_ID
. IfcreateButton
was never called with this parameter, or ifcreateButton
is overridden,getOKButton
will returnnull
.- Returns:
- the OK button or
null
- Since:
- 2.0
- See Also:
-
initializeDialogUnits
Initializes the computation of horizontal and vertical dialog units based on the size of current font.This method must be called before any of the dialog unit based conversion methods are called.
- Parameters:
control
- a control from which to obtain the current font
-
okPressed
protected void okPressed()Notifies that the ok button of this dialog has been pressed.The
Dialog
implementation of this framework method sets this dialog's return code toWindow.OK
and closes the dialog. Subclasses may override. -
setButtonLayoutData
Set the layout data of the button to a GridData with appropriate heights and widths.- Parameters:
button
- The button which layout data is to be set.
-
setButtonLayoutFormData
Set the layout data of the button to a FormData with appropriate heights and widths.- Parameters:
button
- The button which layout data is to be set.
-
close
public boolean close()Description copied from class:Window
Closes this window, disposes its shell, and removes this window from its window manager (if it has one).This framework method may be extended (
super.close
must be called).Note that in order to prevent recursive calls to this method it does not call
Shell#close()
. As a resultShellListener
s will not receive ashellClosed
event. -
applyDialogFont
Applies the dialog font to all controls that currently have the default font.- Parameters:
control
- the control to apply the font to. Font will also be applied to its children. If the control isnull
nothing happens.
-
dialogFontIsDefault
protected static boolean dialogFontIsDefault()Return whether or not the dialog font is currently the same as the default font.- Returns:
- boolean if the two are the same
-
create
public void create()Description copied from class:Window
Creates this window's widgetry in a new top-level shell.The default implementation of this framework method creates this window's shell (by calling
createShell
), and its controls (by callingcreateContents
), then initializes this window's shell bounds (by callinginitializeBounds
). -
getBlockedHandler
Get the IDialogBlockedHandler to be used by WizardDialogs and ModalContexts.- Returns:
- Returns the blockedHandler.
-
setBlockedHandler
Set the IDialogBlockedHandler to be used by WizardDialogs and ModalContexts.- Parameters:
blockedHandler
- The blockedHandler for the dialogs.
-
getDialogBoundsSettings
Gets the dialog settings that should be used for remembering the bounds of of the dialog, according to the dialog bounds strategy.- Returns:
- settings the dialog settings used to store the dialog's location
and/or size, or
null
if the dialog's bounds should never be stored. - Since:
- 3.2
- See Also:
-
getDialogBoundsStrategy
protected int getDialogBoundsStrategy()Get the integer constant that describes the strategy for persisting the dialog bounds. This strategy is ignored if the implementer does not also specify the dialog settings for storing the bounds in Dialog.getDialogBoundsSettings().- Returns:
- the constant describing the strategy for persisting the dialog bounds.
- Since:
- 3.2
- See Also:
-
getInitialSize
Returns the initial size to use for the shell. Overridden to check whether a size has been stored in dialog settings. If a size has been stored, it is returned.- Overrides:
getInitialSize
in classWindow
- Returns:
- the initial size of the shell
- Since:
- 3.2
- See Also:
-
getInitialLocation
Returns the initial location to use for the shell. Overridden to check whether the bounds of the dialog have been stored in dialog settings. If a location has been stored, it is returned.- Overrides:
getInitialLocation
in classWindow
- Parameters:
initialSize
- the initial size of the shell, as returned bygetInitialSize
.- Returns:
- the initial location of the shell
- Since:
- 3.2
- See Also:
-
isResizable
protected boolean isResizable()Returns a boolean indicating whether the dialog should be considered resizable when the shell style is initially set.This method is used to ensure that all style bits appropriate for resizable dialogs are added to the shell style. Individual dialogs may always set the shell style to ensure that a dialog is resizable, but using this method ensures that resizable dialogs will be created with the same set of style bits.
Style bits will never be removed based on the return value of this method. For example, if a dialog returns
false
, but also sets a style bit for a SWT.RESIZE border, the style bit will be honored.- Returns:
- a boolean indicating whether the dialog is resizable and should have the default style bits for resizable dialogs
- Since:
- 3.4
-