org.eclipse.jface.dialogs
Class Dialog

java.lang.Object
  |
  +--org.eclipse.jface.window.Window
        |
        +--org.eclipse.jface.dialogs.Dialog

Direct Known Subclasses:

ErrorDialog, InputDialog, MessageDialog, PreferenceDialog, ProgressMonitorDialog, org.eclipse.compare.internal.ResizableDialog, SelectionDialog, TaskPropertiesDialog, TitleAreaDialog

public abstract class Dialog

extends Window

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 model dialog without a parent is not prevented from disappearing behind the application's other windows, making it very confusing for the user.

Nested Class Summary

Nested classes inherited from class org.eclipse.jface.window.Window

Window.IExceptionHandler

Field Summary

static String	DLG_IMG_ERROR Image registry key for error image (value "dialog_error_image").
static String	DLG_IMG_INFO Image registry key for info image (value "dialog_info_image").
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_messsage_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 Image registry key for question image (value "dialog_question_image").
static String	DLG_IMG_WARNING Image registry key for warning image (value "dialog_warning_image").

Fields inherited from class org.eclipse.jface.window.Window

CANCEL, OK

Constructor Summary

protected

Dialog(Shell parentShell) Creates a dialog instance.

Method Summary

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.
protected void	constrainShellSize() Constrain the shell size to be no larger than the display bounds.
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.
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 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	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.

Methods inherited from class org.eclipse.jface.window.Window

close, configureShell, create, createShell, getContents, getDefaultImage, getInitialLocation, getInitialSize, getParentShell, getReturnCode, getShell, getShellListener, getShellStyle, getWindowManager, handleFontChange, handleShellCloseEvent, initializeBounds, open, setBlockOnOpen, setDefaultImage, setExceptionHandler, setReturnCode, setShellStyle, setWindowManager

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DLG_IMG_ERROR

public static final String DLG_IMG_ERROR

Image registry key for error image (value "dialog_error_image").

See Also:

Constant Field Values

DLG_IMG_INFO

public static final String DLG_IMG_INFO

Image registry key for info image (value "dialog_info_image").

See Also:

Constant Field Values

DLG_IMG_QUESTION

public static final String DLG_IMG_QUESTION

Image registry key for question image (value "dialog_question_image").

See Also:

Constant Field Values

DLG_IMG_WARNING

public static final String DLG_IMG_WARNING

Image registry key for warning image (value "dialog_warning_image").

See Also:

Constant Field Values

DLG_IMG_MESSAGE_INFO

public static final String DLG_IMG_MESSAGE_INFO

Image registry key for info message image (value "dialog_messsage_info_image").

Since:

2.0

See Also:

Constant Field Values

DLG_IMG_MESSAGE_WARNING

public static final String DLG_IMG_MESSAGE_WARNING

Image registry key for info message image (value "dialog_messasge_warning_image").

Since:

2.0

See Also:

Constant Field Values

DLG_IMG_MESSAGE_ERROR

public static final String DLG_IMG_MESSAGE_ERROR

Image registry key for info message image (value "dialog_message_error_image").

Since:

2.0

See Also:

Constant Field Values

Constructor Detail

Dialog

protected Dialog(Shell parentShell)

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, or null to create a top-level shell

Method Detail

convertHeightInCharsToPixels

public static int convertHeightInCharsToPixels(FontMetrics fontMetrics,
                                               int chars)

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 conversion

chars - the number of characters

Returns:

the number of pixels

Since:

2.0

convertHorizontalDLUsToPixels

public static int convertHorizontalDLUsToPixels(FontMetrics fontMetrics,
                                                int dlus)

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 conversion

dlus - the number of horizontal dialog units

Returns:

the number of pixels

Since:

2.0

convertVerticalDLUsToPixels

public static int convertVerticalDLUsToPixels(FontMetrics fontMetrics,
                                              int dlus)

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 conversion

dlus - the number of vertical dialog units

Returns:

the number of pixels

Since:

2.0

convertWidthInCharsToPixels

public static int convertWidthInCharsToPixels(FontMetrics fontMetrics,
                                              int chars)

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 conversion

chars - the number of characters

Returns:

the number of pixels

Since:

2.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 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.

Parameters:

buttonId - the id of the button that was pressed (see IDialogConstants.*_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 to Window.CANCEL and closes the dialog. Subclasses may override if desired.

constrainShellSize

protected void constrainShellSize()

Constrain the shell size to be no larger than the display bounds. Reduce the shell size and move its origin as required.

Overrides:

constrainShellSize in class Window

Since:

2.0

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

protected Button createButton(Composite parent,
                              int id,
                              String label,
                              boolean defaultButton)

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 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.

Parameters:

parent - the parent composite

id - the id of the button (see IDialogConstants.*_ID constants for standard dialog button ids)

label - the label from the button

defaultButton - true if the button is to be the default button, and false otherwise

Returns:

the new button

See Also:

getCancelButton, getOKButton

createButtonBar

protected Control createButtonBar(Composite parent)

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 the createButtonsForButtonBar 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

protected void createButtonsForButtonBar(Composite parent)

Adds buttons to this dialog's button bar.

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.

Parameters:

parent - the button bar composite

createContents

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. 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.

Overrides:

createContents in class Window

Returns:

the control

createDialogArea

protected Control createDialogArea(Composite parent)

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 new Composite with standard margins and spacing.

The returned control's layout data must be an instance of GridData.

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

protected Button getButton(int id)

Returns the button created by the method 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.

Returns:

the button for the ID or null

Since:

2.0

See Also:

createButton

getButtonBar

protected Control 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

protected Button getCancelButton()

Deprecated. Use getButton(IDialogConstants.CANCEL_ID) instead. This method will be removed soon.

Returns the button created when 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.

Returns:

the cancel button or null

Since:

2.0

See Also:

createButton

getDialogArea

protected Control 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

public static Image getImage(String key)

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 the Dialog.DLG_IMG_* constants

Returns:

the standard dialog image

getOKButton

protected Button getOKButton()

Deprecated. Use getButton(IDialogConstants.OK_ID) instead. This method will be removed soon.

Returns the button created when 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.

Returns:

the OK button or null

Since:

2.0

See Also:

createButton

initializeDialogUnits

protected void initializeDialogUnits(Control control)

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 to Window.OK and closes the dialog. Subclasses may override.