|
Eclipse Platform Release 3.1 |
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.eclipse.jface.window.Window
org.eclipse.jface.dialogs.Dialog
A dialog is a specialized window used for narrow-focused communication with the user.
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 there is 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.
Nested Class Summary |
---|
Nested classes inherited from class org.eclipse.jface.window.Window |
---|
Window.IExceptionHandler |
Field Summary | |
---|---|
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. |
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_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. |
Fields inherited from class org.eclipse.jface.window.Window |
---|
CANCEL, OK |
Constructor Summary | |
---|---|
protected |
Dialog(IShellProvider parentShell)
Creates a dialog with the given parent. |
protected |
Dialog(Shell parentShell)
Creates a dialog instance. |
Method Summary | |
---|---|
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. |
static Image |
getImage(String key)
Returns the standard dialog image with the given key. |
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 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. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public static final String DLG_IMG_ERROR
"dialog_error_image"
).
public static final String DLG_IMG_INFO
"dialog_info_image"
).
public static final String DLG_IMG_QUESTION
"dialog_question_image"
).
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 ELLIPSIS
protected Control dialogArea
null
until dialog is layed out.
public Control buttonBar
null
until dialog is layed out.
public static IDialogBlockedHandler blockedHandler
Constructor Detail |
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 shellMethod Detail |
public 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 characters
public 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 units
public 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 units
public 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 characters
public 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 on
null
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 characters
protected 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 units
protected 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 units
protected 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 characters
protected 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
otherwise
getCancelButton()
,
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 bar
protected 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.
parent
- the button bar compositeprotected void initializeBounds()
Window
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.
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 area
protected 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 for
null
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 yetprotected 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_*
constants
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).
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
).
create
in class Window
public static IDialogBlockedHandler getBlockedHandler()
public static void setBlockedHandler(IDialogBlockedHandler blockedHandler)
blockedHandler
- The blockedHandler for the dialogs.
|
Eclipse Platform Release 3.1 |
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Guidelines for using Eclipse APIs.
Copyright (c) IBM Corp. and others 2000, 2005. All rights reserved.