Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.eclipse.jface.dialogs
Class Dialog

    java.lang.Object
      org.eclipse.jface.window.Window
          org.eclipse.jface.dialogs.Dialog

Direct Known Subclasses:
  IconAndMessageDialog, InputDialog, PreferenceDialog, 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 modal 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 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(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 org.eclipse.jface.window.Window
`canHandleShellCloseEvent, configureShell, constrainShellSize, createShell, getConstrainedShellBounds, getContents, getDefaultImage, getDefaultImages, getInitialLocation, getInitialSize, getLayout, getParentShell, getReturnCode, getShell, getShellListener, getShellStyle, getWindowManager, handleFontChange, handleShellCloseEvent, open, setBlockOnOpen, setDefaultImage, setDefaultImages, 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

  Deprecated. use org.eclipse.swt.widgets.Display.getSystemImage(SWT.ICON_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

  Deprecated. use org.eclipse.swt.widgets.Display.getSystemImage(SWT.ICON_INFORMATION)

  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

  Deprecated. org.eclipse.swt.widgets.Display.getSystemImage(SWT.ICON_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

  Deprecated. use org.eclipse.swt.widgets.Display.getSystemImage(SWT.ICON_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_messasge_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

### ELLIPSIS

    public static final String ELLIPSIS

  The ellipsis is the string that is used to represent shortened text.

  Since:
    3.0
  See Also:
    Constant Field Values

### dialogArea

    protected Control dialogArea

  The dialog area; `null` until dialog is layed out.

### buttonBar

    public Control buttonBar

  The button bar; `null` until dialog is layed out.

### blockedHandler

    public static IDialogBlockedHandler blockedHandler

  Create a default instance of the blocked handler which does not do anything.

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

### shortenText

    public 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. Overrides characters in the center of the original string with an ellipsis ("...") if necessary. If a `null` value is given, `null` is returned.

  Parameters:
    `textValue` - the original string or `null`
    `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 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.

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

### initializeBounds

    protected void initializeBounds()

  Description copied from class: `Window`
  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 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.

  Overrides:
    `initializeBounds` in class `Window`

### 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`
  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 getControl()

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

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

  Parameters:
    `id` - the id of the button to look for
  Returns:
    the button for the ID or `null`
  Since:
    2.0
  See Also:
    `createButton(Composite, int, String, boolean)`

### 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(Composite, int, String, boolean)`

### 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(Composite, int, String, boolean)`

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

### setButtonLayoutData

    protected void setButtonLayoutData(Button button)

  Set the layout data of the button to a GridData with appropriate heights and widths.

  Parameters:
    `button` -

### setButtonLayoutFormData

    protected void setButtonLayoutFormData(Button button)

  Set the layout data of the button to a FormData with appropriate heights and widths.

  Parameters:
    `button` -

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

  Overrides:
    `close` in class `Window`
  Returns:
    `true` if the window is (or was already) closed, and `false` if it is still open
  See Also:
    `Window.close()`

### applyDialogFont

    public static void applyDialogFont(Control control)

  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 is `null` 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 calling `createContents`), then initializes this window's shell bounds (by calling `initializeBounds`).

  Overrides:
    `create` in class `Window`

### getBlockedHandler

    public static IDialogBlockedHandler getBlockedHandler()

  Get the IDialogBlockedHandler to be used by WizardDialogs and ModalContexts.

  Returns:
    Returns the blockedHandler.

### setBlockedHandler

    public static void setBlockedHandler(IDialogBlockedHandler blockedHandler)

  Set the IDialogBlockedHandler to be used by WizardDialogs and ModalContexts.

  Parameters:
    `blockedHandler` - The blockedHandler for the dialogs.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
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, 2004. All rights reserved.