Package org.eclipse.jface.dialogs

## Class PopupDialog

- java.lang.Object
- - org.eclipse.jface.window.Window
  - - org.eclipse.jface.dialogs.PopupDialog

All Implemented Interfaces:
  `IShellProvider`

Direct Known Subclasses:
  `DebugPopup`

    public class PopupDialog
    extends Window

A lightweight, transient dialog that is popped up to show contextual or temporal information and is easily dismissed. Clients control whether the dialog should be able to receive input focus. An optional title area at the top and an optional info area at the bottom can be used to provide additional information.

Because the dialog is short-lived, most of the configuration of the dialog is done in the constructor. Set methods are only provided for those values that are expected to be dynamically computed based on a particular instance's internal state.

Clients are expected to override the creation of the main dialog area, and may optionally override the creation of the title area and info area in order to add content. In general, however, the creation of stylistic features, such as the dialog menu, separator styles, and fonts, is kept private so that all popup dialogs will have a similar appearance.

Since:
  3.2

### Nested Class Summary

### Nested classes/interfaces inherited from class org.eclipse.jface.window.Window

`Window.IExceptionHandler`

### Field Summary

Fields
`static int` `HOVER_SHELLSTYLE` Shell style appropriate for a simple hover popup that cannot get focus.
`static int` `INFOPOPUP_SHELLSTYLE` Shell style appropriate for an info popup that can get focus.
`static int` `INFOPOPUPRESIZE_SHELLSTYLE` Shell style appropriate for a resizable info popup that can get focus.
`static int` `POPUP_HORIZONTALSPACING` Vertical spacing (in pixels) between cells in the layouts inside popup dialogs (value is 1).
`static String` `POPUP_IMG_MENU` Image registry key for menu image.
`static String` `POPUP_IMG_MENU_DISABLED` Image registry key for disabled menu image.
`static int` `POPUP_MARGINHEIGHT` Margin height (in pixels) to be used in layouts inside popup dialogs (value is 0).
`static int` `POPUP_MARGINWIDTH` Margin width (in pixels) to be used in layouts inside popup dialogs (value is 0).
`static int` `POPUP_VERTICALSPACING` Vertical spacing (in pixels) between cells in the layouts inside popup dialogs (value is 1).

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

`CANCEL, OK, resizeHasOccurred`

### Constructor Summary

Constructors
`PopupDialog​(Shell parent, int shellStyle, boolean takeFocusOnOpen, boolean persistSize, boolean persistLocation, boolean showDialogMenu, boolean showPersistActions, String titleText, String infoText)` Constructs a new instance of `PopupDialog`.
`PopupDialog​(Shell parent, int shellStyle, boolean takeFocusOnOpen, boolean persistBounds, boolean showDialogMenu, boolean showPersistActions, String titleText, String infoText)` Deprecated. As of 3.4, replaced by `PopupDialog(Shell, int, boolean, boolean, boolean, boolean, boolean, String, String)`

### Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
`protected void` `adjustBounds()` Adjust the bounds of the popup as necessary prior to opening the dialog.
`protected void` `applyBackgroundColor​(Color color, Control control)` Set the specified background color for the specified control and all of its children.
`protected void` `applyForegroundColor​(Color color, Control control)` Set the specified foreground color for the specified control and all of its children.
`boolean` `close()` Closes this window, disposes its shell, and removes this window from its window manager (if it has one).
`protected void` `configureShell​(Shell shell)` Configures the given shell in preparation for opening this window in it.
`protected Control` `createContents​(Composite parent)` The `PopupDialog` implementation of this `Window` method creates and lays out the top level composite for the dialog.
`protected Control` `createDialogArea​(Composite parent)` Creates and returns the contents of the dialog (the area below the title area and above the info text area.
`protected Control` `createInfoTextArea​(Composite parent)` Creates the optional info text area.
`protected Control` `createTitleControl​(Composite parent)` Creates the control to be used to represent the dialog's title text.
`protected Control` `createTitleMenuArea​(Composite parent)` Creates the title and menu area.
`protected void` `fillDialogMenu​(IMenuManager dialogMenu)` Fill the dialog's menu.
`protected Color` `getBackground()` Get the background color that should be used for this popup.
`protected List<Control>` `getBackgroundColorExclusions()` Return a list of controls which should never have their background color reset.
`protected Point` `getDefaultLocation​(Point initialSize)` Returns the default location to use for the shell.
`protected Point` `getDefaultSize()` Return the default size to use for the shell.
`protected IDialogSettings` `getDialogSettings()` Gets the dialog settings that should be used for remembering the bounds of the dialog.
`protected Control` `getFocusControl()` Returns the control that should get initial focus.
`protected Color` `getForeground()` Get the foreground color that should be used for this popup.
`protected List<Control>` `getForegroundColorExclusions()` Return a list of controls which should never have their foreground color reset.
`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 boolean` `getPersistBounds()` Deprecated. As of 3.4, please use `getPersistLocation()` or `getPersistSize()` to determine separately whether size or location should be persisted.
`protected boolean` `getPersistLocation()` Return a boolean indicating whether this dialog will persist its location.
`protected boolean` `getPersistSize()` Return a boolean indicating whether this dialog will persist its size.
`protected boolean` `hasInfoArea()` Returns a boolean indicating whether the popup should have an info area at the bottom of the dialog.
`protected boolean` `hasTitleArea()` Returns a boolean indicating whether the popup should have a title area at the top of the dialog.
`int` `open()` Opens this window, creating it first if it has not yet been created.
`protected void` `saveDialogBounds​(Shell shell)` Saves the bounds of the shell in the appropriate dialog settings.
`protected void` `setInfoText​(String text)` Set the text to be shown in the popup's info area.
`protected void` `setTabOrder​(Composite composite)` Sets the tab order for the popup.
`protected void` `setTitleText​(String text)` Set the text to be shown in the popup's title area.
`protected void` `showDialogMenu()` Show the dialog's menu.

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

`canHandleShellCloseEvent, constrainShellSize, create, createShell, getConstrainedShellBounds, getContents, getDefaultImage, getDefaultImages, getDefaultOrientation, getLayout, getParentShell, getReturnCode, getShell, getShellListener, getShellStyle, getWindowManager, handleFontChange, handleShellCloseEvent, initializeBounds, setBlockOnOpen, setDefaultImage, setDefaultImages, setDefaultModalParent, setDefaultOrientation, setExceptionHandler, setParentShell, setReturnCode, setShellStyle, setWindowManager`

### Methods inherited from class java.lang.Object

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

### Field Detail

#### HOVER_SHELLSTYLE

    public static final int HOVER_SHELLSTYLE

Shell style appropriate for a simple hover popup that cannot get focus.

See Also:
  Constant Field Values

#### INFOPOPUP_SHELLSTYLE

    public static final int INFOPOPUP_SHELLSTYLE

Shell style appropriate for an info popup that can get focus.

See Also:
  Constant Field Values

#### INFOPOPUPRESIZE_SHELLSTYLE

    public static final int INFOPOPUPRESIZE_SHELLSTYLE

Shell style appropriate for a resizable info popup that can get focus.

See Also:
  Constant Field Values

#### POPUP_MARGINWIDTH

    public static final int POPUP_MARGINWIDTH

Margin width (in pixels) to be used in layouts inside popup dialogs (value is 0).

See Also:
  Constant Field Values

#### POPUP_MARGINHEIGHT

    public static final int POPUP_MARGINHEIGHT

Margin height (in pixels) to be used in layouts inside popup dialogs (value is 0).

See Also:
  Constant Field Values

#### POPUP_VERTICALSPACING

    public static final int POPUP_VERTICALSPACING

Vertical spacing (in pixels) between cells in the layouts inside popup dialogs (value is 1).

See Also:
  Constant Field Values

#### POPUP_HORIZONTALSPACING

    public static final int POPUP_HORIZONTALSPACING

Vertical spacing (in pixels) between cells in the layouts inside popup dialogs (value is 1).

See Also:
  Constant Field Values

#### POPUP_IMG_MENU

    public static final String POPUP_IMG_MENU

Image registry key for menu image.

Since:
  3.4
See Also:
  Constant Field Values

#### POPUP_IMG_MENU_DISABLED

    public static final String POPUP_IMG_MENU_DISABLED

Image registry key for disabled menu image.

Since:
  3.4
See Also:
  Constant Field Values

### Constructor Detail

#### PopupDialog

    @Deprecated
    public PopupDialog​(Shell parent,
                       int shellStyle,
                       boolean takeFocusOnOpen,
                       boolean persistBounds,
                       boolean showDialogMenu,
                       boolean showPersistActions,
                       String titleText,
                       String infoText)

Deprecated.
As of 3.4, replaced by `PopupDialog(Shell, int, boolean, boolean, boolean, boolean, boolean, String, String)`
Constructs a new instance of `PopupDialog`.

Parameters:
  `parent` - The parent shell.
  `shellStyle` - The shell style.
  `takeFocusOnOpen` - A boolean indicating whether focus should be taken by this popup when it opens.
  `persistBounds` - A boolean indicating whether the bounds (size and location) of the dialog should be persisted upon close of the dialog. The bounds can only be persisted if the dialog settings for persisting the bounds are also specified. If a menu action will be provided that allows the user to control this feature, then the last known value of the user's setting will be used instead of this flag.
  `showDialogMenu` - A boolean indicating whether a menu for moving and resizing the popup should be provided.
  `showPersistActions` - A boolean indicating whether actions allowing the user to control the persisting of the dialog size and location should be shown in the dialog menu. This parameter has no effect if `showDialogMenu` is `false`.
  `titleText` - Text to be shown in an upper title area, or `null` if there is no title.
  `infoText` - Text to be shown in a lower info area, or `null` if there is no info area.
See Also:
  `getDialogSettings()`
Restriction:
  Planned for deletion see https://bugs.eclipse.org/bugs/show_bug.cgi?id=531913

#### PopupDialog

    public PopupDialog​(Shell parent,
                       int shellStyle,
                       boolean takeFocusOnOpen,
                       boolean persistSize,
                       boolean persistLocation,
                       boolean showDialogMenu,
                       boolean showPersistActions,
                       String titleText,
                       String infoText)

Constructs a new instance of `PopupDialog`.

Parameters:
  `parent` - The parent shell.
  `shellStyle` - The shell style.
  `takeFocusOnOpen` - A boolean indicating whether focus should be taken by this popup when it opens.
  `persistSize` - A boolean indicating whether the size should be persisted upon close of the dialog. The size can only be persisted if the dialog settings for persisting the bounds are also specified. If a menu action will be provided that allows the user to control this feature and the user hasn't changed that setting, then this flag is used as initial default for the menu.
  `persistLocation` - A boolean indicating whether the location should be persisted upon close of the dialog. The location can only be persisted if the dialog settings for persisting the bounds are also specified. If a menu action will be provided that allows the user to control this feature and the user hasn't changed that setting, then this flag is used as initial default for the menu. default for the menu until the user changed it.
  `showDialogMenu` - A boolean indicating whether a menu for moving and resizing the popup should be provided.
  `showPersistActions` - A boolean indicating whether actions allowing the user to control the persisting of the dialog bounds and location should be shown in the dialog menu. This parameter has no effect if `showDialogMenu` is `false`.
  `titleText` - Text to be shown in an upper title area, or `null` if there is no title.
  `infoText` - Text to be shown in a lower info area, or `null` if there is no info area.
Since:
  3.4
See Also:
  `getDialogSettings()`

### Method Detail

#### configureShell

    protected void configureShell​(Shell shell)

Description copied from class: `Window`
Configures the given shell in preparation for opening this window in it.

The default implementation of this framework method sets the shell's image and gives it a grid layout. Subclasses may extend or reimplement.

Overrides:
  `configureShell` in class `Window`
Parameters:
  `shell` - the shell

#### createContents

    protected Control createContents​(Composite parent)

The `PopupDialog` implementation of this `Window` method creates and lays out the top level composite for the dialog. It then calls the `createTitleMenuArea`, `createDialogArea`, and `createInfoTextArea` methods to create an optional title and menu area on the top, a dialog area in the center, and an optional info text area at the bottom. Overriding `createDialogArea` and (optionally) `createTitleMenuArea` and `createTitleMenuArea` are recommended rather than overriding this method.

Overrides:
  `createContents` in class `Window`
Parameters:
  `parent` - the composite used to parent the contents.
Returns:
  the control representing the contents.

#### createDialogArea

    protected Control createDialogArea​(Composite parent)

Creates and returns the contents of the dialog (the area below the title area and above the info text area.

The `PopupDialog` 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

#### getFocusControl

    protected Control getFocusControl()

Returns the control that should get initial focus. Subclasses may override this method.

Returns:
  the Control that should receive focus when the popup opens.

#### setTabOrder

    protected void setTabOrder​(Composite composite)

Sets the tab order for the popup. Clients should override to introduce specific tab ordering.

Parameters:
  `composite` - the composite in which all content, including the title area and info area, was created. This composite's parent is the shell.

#### hasTitleArea

    protected boolean hasTitleArea()

Returns a boolean indicating whether the popup should have a title area at the top of the dialog. Subclasses may override. Default behavior is to have a title area if there is to be a menu or title text.

Returns:
  `true` if a title area should be created, `false` if it should not.

#### hasInfoArea

    protected boolean hasInfoArea()

Returns a boolean indicating whether the popup should have an info area at the bottom of the dialog. Subclasses may override. Default behavior is to have an info area if info text was provided at the time of creation.

Returns:
  `true` if a title area should be created, `false` if it should not.

#### createTitleMenuArea

    protected Control createTitleMenuArea​(Composite parent)

Creates the title and menu area. Subclasses typically need not override this method, but instead should use the constructor parameters `showDialogMenu` and `showPersistAction` to indicate whether a menu should be shown, and `createTitleControl` to to customize the presentation of the title.

If this method is overridden, the returned control's layout data must be an instance of `GridData`. This method must not modify the parent's layout.

Parameters:
  `parent` - The parent composite.
Returns:
  The Control representing the title and menu area.

#### createTitleControl

    protected Control createTitleControl​(Composite parent)

Creates the control to be used to represent the dialog's title text. Subclasses may override if a different control is desired for representing the title text, or if something different than the title should be displayed in location where the title text typically is shown.

If this method is overridden, the returned control's layout data must be an instance of `GridData`. This method must not modify the parent's layout.

Parameters:
  `parent` - The parent composite.
Returns:
  The Control representing the title area.

#### createInfoTextArea

    protected Control createInfoTextArea​(Composite parent)

Creates the optional info text area. This method is only called if the `hasInfoArea()` method returns true. Subclasses typically need not override this method, but may do so.

If this method is overridden, the returned control's layout data must be an instance of `GridData`. This method must not modify the parent's layout.

Parameters:
  `parent` - The parent composite.
Returns:
  The control representing the info text area.
See Also:
  `hasInfoArea()`, `createTitleControl(Composite)`

#### fillDialogMenu

    protected void fillDialogMenu​(IMenuManager dialogMenu)

Fill the dialog's menu. Subclasses may extend or override.

Parameters:
  `dialogMenu` - The dialog's menu.

#### showDialogMenu

    protected void showDialogMenu()

Show the dialog's menu. This message has no effect if the receiver was not configured to show a menu. Clients may call this method in order to trigger the menu via keystrokes or other gestures. Subclasses typically do not override method.

#### setInfoText

    protected void setInfoText​(String text)

Set the text to be shown in the popup's info area. This message has no effect if there was no info text supplied when the dialog first opened. Subclasses may override this method.

Parameters:
  `text` - the text to be shown when the info area is displayed.

#### setTitleText

    protected void setTitleText​(String text)

Set the text to be shown in the popup's title area. This message has no effect if there was no title label specified when the dialog was originally opened. Subclasses may override this method.

Parameters:
  `text` - the text to be shown when the title area is displayed.

#### getPersistBounds

    @Deprecated
    protected boolean getPersistBounds()

Deprecated.
As of 3.4, please use `getPersistLocation()` or `getPersistSize()` to determine separately whether size or location should be persisted.
Return a boolean indicating whether this dialog will persist its bounds. This value is initially set in the dialog's constructor, but can be modified if the persist bounds action is shown on the menu and the user has changed its value. Subclasses may override this method.

Returns:
  `true` if the dialog's bounds will be persisted, `false` if it will not.
Restriction:
  Planned for deletion see https://bugs.eclipse.org/bugs/show_bug.cgi?id=531913

#### getPersistLocation

    protected boolean getPersistLocation()

Return a boolean indicating whether this dialog will persist its location. This value is initially set in the dialog's constructor, but can be modified if the persist location action is shown on the menu and the user has changed its value. Subclasses may override this method.

Returns:
  `true` if the dialog's location will be persisted, `false` if it will not.
Since:
  3.4
See Also:
  `getPersistSize()`

#### getPersistSize

    protected boolean getPersistSize()

Return a boolean indicating whether this dialog will persist its size. This value is initially set in the dialog's constructor, but can be modified if the persist size action is shown on the menu and the user has changed its value. Subclasses may override this method.

Returns:
  `true` if the dialog's size will be persisted, `false` if it will not.
Since:
  3.4
See Also:
  `getPersistLocation()`

#### open

    public int open()

Opens this window, creating it first if it has not yet been created.

This method is reimplemented for special configuration of PopupDialogs. It never blocks on open, immediately returning `OK` if the open is successful, or `CANCEL` if it is not. It provides framework hooks that allow subclasses to set the focus and tab order, and avoids the use of `shell.open()` in cases where the focus should not be given to the shell initially.

Overrides:
  `open` in class `Window`
Returns:
  the return code
See Also:
  `Window.open()`

#### close

    public boolean close()

Closes this window, disposes its shell, and removes this window from its window manager (if it has one).

This method is extended to save the dialog bounds and initialize widget state so that the widgets can be recreated if the dialog is reopened. This 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

#### getDialogSettings

    protected IDialogSettings getDialogSettings()

Gets the dialog settings that should be used for remembering the bounds of the dialog. Subclasses should override this method when they wish to persist the bounds of the dialog.

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.

#### saveDialogBounds

    protected void saveDialogBounds​(Shell shell)

Saves the bounds of the shell in the appropriate dialog settings. The bounds are recorded relative to the parent shell, if there is one, or display coordinates if there is no parent shell. Subclasses typically need not override this method, but may extend it (calling `super.saveDialogBounds` if additional bounds information should be stored. Clients may also call this method to persist the bounds at times other than closing the dialog.

Parameters:
  `shell` - The shell whose bounds are to be stored

#### getInitialSize

    protected Point getInitialSize()

Description copied from class: `Window`
Returns the initial size to use for the shell. The default implementation returns the preferred size of the shell, using `Shell.computeSize(SWT.DEFAULT, SWT.DEFAULT, true)`.

Overrides:
  `getInitialSize` in class `Window`
Returns:
  the initial size of the shell

#### getDefaultSize

    protected Point getDefaultSize()

Return the default size to use for the shell. This default size is used if the dialog does not have any persisted size to restore. The default implementation returns the preferred size of the shell. Subclasses should override this method when an alternate default size is desired, rather than overriding `getInitialSize()`.

Returns:
  the initial size of the shell
Since:
  3.4
See Also:
  `getPersistSize()`

#### getDefaultLocation

    protected Point getDefaultLocation​(Point initialSize)

Returns the default location to use for the shell. This default location is used if the dialog does not have any persisted location to restore. The default implementation uses the location computed by `Window.getInitialLocation(Point)`. Subclasses should override this method when an alternate default location is desired, rather than overriding `getInitialLocation(Point)`.

Parameters:
  `initialSize` - the initial size of the shell, as returned by `getInitialSize`.
Returns:
  the initial location of the shell
Since:
  3.4
See Also:
  `getPersistLocation()`

#### adjustBounds

    protected void adjustBounds()

Adjust the bounds of the popup as necessary prior to opening the dialog. Default is to do nothing, which honors any bounds set directly by clients or those that have been saved in the dialog settings. Subclasses should override this method when there are bounds computations that must be checked each time the dialog is opened.

#### getInitialLocation

    protected Point getInitialLocation​(Point initialSize)

Description copied from class: `Window`
Returns the initial location to use for the shell. The default implementation centers the shell horizontally (1/2 of the difference to the left and 1/2 to the right) and vertically (1/3 above and 2/3 below) relative to the parent shell, or display bounds if there is no parent shell.

Overrides:
  `getInitialLocation` in class `Window`
Parameters:
  `initialSize` - the initial size of the shell, as returned by `getInitialSize`.
Returns:
  the initial location of the shell

#### getForeground

    protected Color getForeground()

Get the foreground color that should be used for this popup. Subclasses may override.

Returns:
  the foreground color to be used. Should not be `null`.
Since:
  3.4
See Also:
  `getForegroundColorExclusions()`

#### getBackground

    protected Color getBackground()

Get the background color that should be used for this popup. Subclasses may override.

Returns:
  the background color to be used. Should not be `null`.
Since:
  3.4
See Also:
  `getBackgroundColorExclusions()`

#### applyForegroundColor

    protected void applyForegroundColor​(Color color,
                                        Control control)

Set the specified foreground color for the specified control and all of its children. Subclasses may override this method, but typically do not. If a subclass wishes to exclude a particular control in its contents from getting the specified foreground color, it may instead override `getForegroundColorExclusions()`.

Parameters:
  `color` - the color to use as the foreground color
  `control` - the control whose color is to be changed
See Also:
  `getForegroundColorExclusions()`

#### applyBackgroundColor

    protected void applyBackgroundColor​(Color color,
                                        Control control)

Set the specified background color for the specified control and all of its children. Subclasses may override this method, but typically do not. If a subclass wishes to exclude a particular control in its contents from getting the specified background color, it may instead override `getBackgroundColorExclusions()`

Parameters:
  `color` - the color to use as the background color
  `control` - the control whose color is to be changed
See Also:
  `getBackgroundColorExclusions()`

#### getForegroundColorExclusions

    protected List<Control> getForegroundColorExclusions()

Return a list of controls which should never have their foreground color reset. Subclasses may extend this method, but should always call `super.getForegroundColorExclusions` to aggregate the list.

Returns:
  the List of controls

#### getBackgroundColorExclusions

    protected List<Control> getBackgroundColorExclusions()

Return a list of controls which should never have their background color reset. Subclasses may extend this method, but should always call `super.getBackgroundColorExclusions` to aggregate the list.

Returns:
  the List of controls