Class Dialog

  • All Implemented Interfaces:
    IShellProvider
    Direct Known Subclasses:
    EditorSelectionDialog, IconAndMessageDialog, InputDialog, org.eclipse.compare.internal.ResizableDialog, TrayDialog, ViewSettingsDialog

    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.

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

    • Field Detail

      • DLG_IMG_ERROR

        @Deprecated
        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

        @Deprecated
        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

        @Deprecated
        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

        @Deprecated
        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
      • DLG_IMG_HELP

        public static final String DLG_IMG_HELP
        Image registry key for help image (value "dialog_help_image").
        Since:
        3.2
        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
      • DIALOG_DEFAULT_BOUNDS

        public static final 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.
        Since:
        3.2
        See Also:
        Constant Field Values
      • DIALOG_PERSISTLOCATION

        public static final int DIALOG_PERSISTLOCATION
        Persist the last location of the dialog.
        Since:
        3.2
        See Also:
        Constant Field Values
      • DIALOG_PERSISTSIZE

        public static final int DIALOG_PERSISTSIZE
        Persist the last known size of the dialog.
        Since:
        3.2
        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
      • Dialog

        protected Dialog​(IShellProvider parentShell)
        Creates a dialog with the given parent.
        Parameters:
        parentShell - object that returns the current parent shell
        Since:
        3.1
    • 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.

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

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

        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 getContents()
      • 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

        @Deprecated
        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 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:
        Display.getSystemImage(int)
      • getOKButton

        @Deprecated
        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 - The button which layout data is to be set.
      • setButtonLayoutFormData

        protected void setButtonLayoutFormData​(Button button)
        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 result ShellListeners will not receive a shellClosed event.

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

        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.
        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()
      • 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:
        DIALOG_PERSISTLOCATION, DIALOG_PERSISTSIZE, getDialogBoundsSettings()
      • getInitialLocation

        protected Point getInitialLocation​(Point initialSize)
        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 class Window
        Parameters:
        initialSize - the initial size of the shell, as returned by getInitialSize.
        Returns:
        the initial location of the shell
        Since:
        3.2
        See Also:
        getDialogBoundsSettings(), getDialogBoundsStrategy()
      • 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