public abstract class Dialog extends Window
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()
.
Window.IExceptionHandler
Modifier and Type | Field and Description |
---|---|
static IDialogBlockedHandler |
blockedHandler
Create a default instance of the blocked handler which does not do
anything.
|
Control |
buttonBar
The button bar;
null until dialog is layed out. |
static int |
DIALOG_DEFAULT_BOUNDS
A value that can be used for stored dialog width or height that
indicates that the default bounds should be used.
|
static int |
DIALOG_PERSISTLOCATION
Persist the last location of the dialog.
|
static int |
DIALOG_PERSISTSIZE
Persist the last known size of the dialog.
|
protected Control |
dialogArea
The dialog area;
null until dialog is layed out. |
static String |
DLG_IMG_ERROR
Deprecated.
use
org.eclipse.swt.widgets.Display.getSystemImage(SWT.ICON_ERROR)
|
static String |
DLG_IMG_HELP
Image registry key for help image (value
"dialog_help_image" ). |
static String |
DLG_IMG_INFO
Deprecated.
use
org.eclipse.swt.widgets.Display.getSystemImage(SWT.ICON_INFORMATION)
|
static String |
DLG_IMG_MESSAGE_ERROR
Image registry key for info message image (value
"dialog_message_error_image" ). |
static String |
DLG_IMG_MESSAGE_INFO
Image registry key for info message image (value
"dialog_messasge_info_image" ). |
static String |
DLG_IMG_MESSAGE_WARNING
Image registry key for info message image (value
"dialog_messasge_warning_image" ). |
static String |
DLG_IMG_QUESTION
Deprecated.
org.eclipse.swt.widgets.Display.getSystemImage(SWT.ICON_QUESTION)
|
static String |
DLG_IMG_WARNING
Deprecated.
use
org.eclipse.swt.widgets.Display.getSystemImage(SWT.ICON_WARNING)
|
static String |
ELLIPSIS
The ellipsis is the string that is used to represent shortened text.
|
CANCEL, OK, resizeHasOccurred
Modifier | Constructor and Description |
---|---|
protected |
Dialog(IShellProvider parentShell)
Creates a dialog with the given parent.
|
protected |
Dialog(Shell parentShell)
Creates a dialog instance.
|
Modifier and Type | Method and Description |
---|---|
static 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 |
cancelPressed()
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).
|
static int |
convertHeightInCharsToPixels(FontMetrics fontMetrics,
int chars)
Returns the number of pixels corresponding to the height of the given
number of characters.
|
protected int |
convertHeightInCharsToPixels(int chars)
Returns the number of pixels corresponding to the height of the given
number of characters.
|
static int |
convertHorizontalDLUsToPixels(FontMetrics fontMetrics,
int dlus)
Returns the number of pixels corresponding to the given number of
horizontal dialog units.
|
protected int |
convertHorizontalDLUsToPixels(int dlus)
Returns the number of pixels corresponding to the given number of
horizontal 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 |
convertVerticalDLUsToPixels(int dlus)
Returns the number of pixels corresponding to the given number of
vertical dialog units.
|
static int |
convertWidthInCharsToPixels(FontMetrics fontMetrics,
int chars)
Returns the number of pixels corresponding to the width of the given
number of characters.
|
protected int |
convertWidthInCharsToPixels(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)
The
Dialog implementation of this Window
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 |
dialogFontIsDefault()
Return whether or not the dialog font is currently the same as the
default font.
|
static IDialogBlockedHandler |
getBlockedHandler()
Get the IDialogBlockedHandler to be used by WizardDialogs and
ModalContexts.
|
protected Button |
getButton(int id)
Returns the button created by the method
createButton for
the specified ID as defined on IDialogConstants . |
protected Control |
getButtonBar()
Returns the button bar control.
|
protected Button |
getCancelButton()
Deprecated.
Use
getButton(IDialogConstants.CANCEL_ID)
instead. This method will be removed soon. |
protected Control |
getDialogArea()
Returns the dialog area control.
|
protected IDialogSettings |
getDialogBoundsSettings()
Gets the dialog settings that should be used for remembering the bounds of
of the dialog, according to the dialog bounds strategy.
|
protected int |
getDialogBoundsStrategy()
Get the integer constant that describes the strategy for persisting the
dialog bounds.
|
static Image |
getImage(String key)
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 |
getInitialSize()
Returns the initial size to use for the shell.
|
protected Button |
getOKButton()
Deprecated.
Use
getButton(IDialogConstants.OK_ID) instead.
This method will be removed soon. |
protected void |
initializeBounds()
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 |
isResizable()
Returns a boolean indicating whether the dialog should be
considered resizable when the shell style is initially
set.
|
protected void |
okPressed()
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)
Shortens the given text
textValue so that its width in
pixels does not exceed the width of the given control. |
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
@Deprecated public static final String DLG_IMG_ERROR
"dialog_error_image"
).@Deprecated public static final String DLG_IMG_INFO
"dialog_info_image"
).@Deprecated public static final String DLG_IMG_QUESTION
"dialog_question_image"
).@Deprecated public static final String DLG_IMG_WARNING
"dialog_warning_image"
).public static final String DLG_IMG_MESSAGE_INFO
"dialog_messasge_info_image"
).public static final String DLG_IMG_MESSAGE_WARNING
"dialog_messasge_warning_image"
).public static final String DLG_IMG_MESSAGE_ERROR
"dialog_message_error_image"
).public static final String DLG_IMG_HELP
"dialog_help_image"
).public static final String ELLIPSIS
public static final int DIALOG_DEFAULT_BOUNDS
public static final int DIALOG_PERSISTLOCATION
public static final int DIALOG_PERSISTSIZE
protected Control dialogArea
null
until dialog is layed out.public Control buttonBar
null
until dialog is layed out.public static IDialogBlockedHandler blockedHandler
protected Dialog(Shell parentShell)
open
blocks for dialogs.parentShell
- the parent shell, or null
to create a top-level
shellprotected Dialog(IShellProvider parentShell)
parentShell
- object that returns the current parent shellpublic static int convertHeightInCharsToPixels(FontMetrics fontMetrics, int chars)
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();
fontMetrics
- used in performing the conversionchars
- the number of characterspublic static int convertHorizontalDLUsToPixels(FontMetrics fontMetrics, int dlus)
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();
fontMetrics
- used in performing the conversiondlus
- the number of horizontal dialog unitspublic static int convertVerticalDLUsToPixels(FontMetrics fontMetrics, int dlus)
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();
fontMetrics
- used in performing the conversiondlus
- the number of vertical dialog unitspublic static int convertWidthInCharsToPixels(FontMetrics fontMetrics, int chars)
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();
fontMetrics
- used in performing the conversionchars
- the number of characterspublic static String shortenText(String textValue, Control control)
textValue
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 a null
value is given, null
is returned.textValue
- the original string or null
control
- the control the string will be displayed onnull
if null was passed
inprotected void buttonPressed(int buttonId)
The Dialog
implementation of this framework method calls
okPressed
if the ok button is the pressed, and
cancelPressed
if the cancel button is the pressed. All
other button presses are ignored. Subclasses may override to handle other
buttons, but should call super.buttonPressed
if the
default handling of the ok and cancel buttons is desired.
buttonId
- the id of the button that was pressed (see
IDialogConstants.*_ID
constants)protected void cancelPressed()
The Dialog
implementation of this framework method sets
this dialog's return code to Window.CANCEL
and closes the
dialog. Subclasses may override if desired.
protected int convertHeightInCharsToPixels(int chars)
This method may only be called after initializeDialogUnits
has been called.
Clients may call this framework method, but should not override it.
chars
- the number of charactersprotected int convertHorizontalDLUsToPixels(int dlus)
This method may only be called after initializeDialogUnits
has been called.
Clients may call this framework method, but should not override it.
dlus
- the number of horizontal dialog unitsprotected int convertVerticalDLUsToPixels(int dlus)
This method may only be called after initializeDialogUnits
has been called.
Clients may call this framework method, but should not override it.
dlus
- the number of vertical dialog unitsprotected int convertWidthInCharsToPixels(int chars)
This method may only be called after initializeDialogUnits
has been called.
Clients may call this framework method, but should not override it.
chars
- the number of charactersprotected Button createButton(Composite parent, int id, String label, boolean defaultButton)
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 is
IDialogConstants.CANCEL_ID
, the new button will be
accessible from getCancelButton()
. If the button id is
IDialogConstants.OK_ID
, the new button will be accesible
from getOKButton()
. Note that the parent's layout is
assumed to be a GridLayout
and the number of columns in
this layout is incremented. Subclasses may override.
parent
- the parent compositeid
- the id of the button (see IDialogConstants.*_ID
constants for standard dialog button ids)label
- the label from the buttondefaultButton
- true
if the button is to be the default button,
and false
otherwisegetCancelButton()
,
getOKButton()
protected Control createButtonBar(Composite parent)
The Dialog
implementation of this framework method lays
out a button bar and calls the createButtonsForButtonBar
framework method to populate it. Subclasses may override.
The returned control's layout data must be an instance of
GridData
.
parent
- the parent composite to contain the button barprotected void createButtonsForButtonBar(Composite parent)
The Dialog
implementation of this framework method adds
standard ok and cancel buttons using the createButton
framework method. These standard buttons will be accessible from
getCancelButton
, and getOKButton
.
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.
parent
- the button bar compositeprotected void initializeBounds()
This framework method is called by the create
framework
method. The default implementation calls getInitialSize
and getInitialLocation
and passes the results to
Shell.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 the
default button
in the
button bar
to the right
if that's required by the
platform convention
.
initializeBounds
in class Window
protected Control createContents(Composite parent)
Dialog
implementation of this Window
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 the createDialogArea
and
createButtonBar
methods to create the dialog area and
button bar, respectively. Overriding createDialogArea
and
createButtonBar
are recommended rather than overriding
this method.createContents
in class Window
parent
- the parent composite for the controls in this window. The type
of layout used is determined by getLayout()protected Control createDialogArea(Composite parent)
The Dialog
implementation of this framework method creates
and returns a new Composite
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;
parent
- the parent composite to contain the dialog areaprotected Button getButton(int id)
createButton
for
the specified ID as defined on IDialogConstants
. If
createButton
was never called with this ID, or if
createButton
is overridden, this method will return
null
.id
- the id of the button to look fornull
createButton(Composite, int, String, boolean)
protected Control getButtonBar()
Clients may call this framework method, but should not override it.
null
if the button bar has not
been created yet@Deprecated protected Button getCancelButton()
getButton(IDialogConstants.CANCEL_ID)
instead. This method will be removed soon.createButton
is called
with an ID of IDialogConstants.CANCEL_ID
. If
createButton
was never called with this parameter, or if
createButton
is overridden, getCancelButton
will return null
.null
createButton(Composite, int, String, boolean)
protected Control getDialogArea()
Clients may call this framework method, but should not override it.
null
if the dialog area has
not been created yetpublic static Image getImage(String key)
key
- one of the Dialog.DLG_IMG_*
constantsDisplay.getSystemImage(int)
@Deprecated protected Button getOKButton()
getButton(IDialogConstants.OK_ID)
instead.
This method will be removed soon.createButton
is called
with an ID of IDialogConstants.OK_ID
. If
createButton
was never called with this parameter, or if
createButton
is overridden, getOKButton
will return null
.null
createButton(Composite, int, String, boolean)
protected void initializeDialogUnits(Control control)
This method must be called before any of the dialog unit based conversion methods are called.
control
- a control from which to obtain the current fontprotected void okPressed()
The Dialog
implementation of this framework method sets
this dialog's return code to Window.OK
and closes the
dialog. Subclasses may override.
protected void setButtonLayoutData(Button button)
button
- protected void setButtonLayoutFormData(Button button)
button
- public boolean close()
Window
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 result ShellListener
s
will not receive a shellClosed
event.
close
in class Window
true
if the window is (or was already) closed, and
false
if it is still openWindow.close()
public static void applyDialogFont(Control control)
control
- the control to apply the font to. Font will also be applied to
its children. If the control is null
nothing
happens.protected static boolean dialogFontIsDefault()
public void create()
Window
The default implementation of this framework method creates this window's
shell (by calling createShell
), and its controls (by
calling createContents
), then initializes this window's
shell bounds (by calling initializeBounds
).
public static IDialogBlockedHandler getBlockedHandler()
public static void setBlockedHandler(IDialogBlockedHandler blockedHandler)
blockedHandler
- The blockedHandler for the dialogs.protected IDialogSettings getDialogBoundsSettings()
null
if the dialog's bounds should
never be stored.getDialogBoundsStrategy()
protected int getDialogBoundsStrategy()
DIALOG_PERSISTLOCATION
,
DIALOG_PERSISTSIZE
,
getDialogBoundsSettings()
protected Point getInitialSize()
getInitialSize
in class Window
getDialogBoundsSettings()
,
getDialogBoundsStrategy()
protected Point getInitialLocation(Point initialSize)
getInitialLocation
in class Window
initialSize
- the initial size of the shell, as returned by
getInitialSize
.getDialogBoundsSettings()
,
getDialogBoundsStrategy()
protected boolean isResizable()
false
, but also sets a style bit for a
SWT.RESIZE border, the style bit will be honored.
Copyright (c) 2000, 2014 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.