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.preference
Class PreferenceDialog

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

All Implemented Interfaces:
  IPreferencePageContainer

public class PreferenceDialog
extends Dialog
implements IPreferencePageContainer

A preference dialog is a hierarchical presentation of preference pages. Each page is represented by a node in the tree shown on the left hand side of the dialog; when a node is selected, the corresponding page is shown on the right hand side.

Nested Class Summary

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

Field Summary
`static String` | `PREF_DLG_IMG_TITLE_ERROR` Indentifier for the error image
`static String` | `PREF_DLG_TITLE_IMG` Title area fields

Fields inherited from class org.eclipse.jface.dialogs.Dialog
`blockedHandler, buttonBar, dialogArea, DLG_IMG_ERROR, DLG_IMG_INFO, DLG_IMG_MESSAGE_ERROR, DLG_IMG_MESSAGE_INFO, DLG_IMG_MESSAGE_WARNING, DLG_IMG_QUESTION, DLG_IMG_WARNING, ELLIPSIS`

Fields inherited from class org.eclipse.jface.window.Window
`CANCEL, OK`

Constructor Summary
`PreferenceDialog(Shell parentShell, PreferenceManager manager)` Creates a new preference dialog under the control of the given preference manager.

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.
`boolean` | `close()` Closes this window, disposes its shell, and removes this window from its window manager (if it has one).
`protected void` | `configureShell(Shell newShell)` Configures the given shell in preparation for opening this window in it.
`protected void` | `constrainShellSize()` Constrain the shell size to be no larger than the display bounds.
`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 Control` | `createTreeAreaContents(Composite parent)`
`protected TreeViewer` | `createTreeViewer(Composite parent)` Create a new `TreeViewer`.
`protected IPreferenceNode` | `findNodeMatching(String nodeId)` Find the `IPreferenceNode` that has data the same id as the supplied value.
`PreferenceManager` | `getPreferenceManager()` Returns the preference mananger used by this preference dialog.
`IPreferenceStore` | `getPreferenceStore()` Returns the preference store.
`protected String` | `getSelectedNodePreference()` Get the name of the selected item preference
`protected IPreferenceNode` | `getSingleSelection(ISelection selection)`
`protected TreeViewer` | `getTreeViewer()`
`protected void` | `handleSave()` Save the values specified in the pages.
`protected void` | `handleShellCloseEvent()` Notifies that the window's close button was pressed, the close menu was selected, or the ESCAPE key pressed.
`protected void` | `helpPressed()` Notifies of the pressing of the Help button.
`protected boolean` | `isCurrentPageValid()` Returns whether the current page is valid.
`protected void` | `layoutTreeAreaControl(Control control)`
`protected void` | `okPressed()` The preference dialog implementation of this `Dialog` framework method sends `performOk` to all pages of the preference dialog, then calls `handleSave` on this dialog to save any state, and then calls `close` to close this dialog.
`protected void` | `selectSavedItem()` Selects the saved item in the tree of preference pages.
`void` | `setErrorMessage(String newErrorMessage)` Display the given error message.
`void` | `setHelpAvailable(boolean b)` Sets whether a Help button is available for this dialog.
`void` | `setMessage(String newMessage)` Set the message text.
`void` | `setMessage(String newMessage, int newType)` Sets the message for this dialog with an indication of what type of message it is.
`void` | `setMinimumPageSize(int minWidth, int minHeight)` Sets the minimum page size.
`void` | `setMinimumPageSize(Point size)` Sets the minimum page size.
`void` | `setPreferenceStore(IPreferenceStore store)` Sets the preference store for this preference dialog.
`void` | `setSelectedNode(String pageId)` Sets the name of the selected item preference.
`protected void` | `setSelectedNodePreference(String pageId)` Sets the name of the selected item preference.
`protected boolean` | `showPage(IPreferenceNode node)` Shows the preference page corresponding to the given preference node.
`protected void` | `update()` Updates this dialog's controls to reflect the current page.
`void` | `updateButtons()` Adjusts the enable state of the OK button to reflect the state of the currently active page in this container.
`void` | `updateMessage()` Updates the message (or error message) shown in the message line to reflect the state of the currently active page in this container.
`void` | `updateTitle()` Updates the title to reflect the state of the currently active page in this container.
`protected void` | `updateTreeFont(Font dialogFont)` Update the tree to use the specified `Font`.

Methods inherited from class org.eclipse.jface.dialogs.Dialog
`applyDialogFont, convertHeightInCharsToPixels, convertHeightInCharsToPixels, convertHorizontalDLUsToPixels, convertHorizontalDLUsToPixels, convertVerticalDLUsToPixels, convertVerticalDLUsToPixels, convertWidthInCharsToPixels, convertWidthInCharsToPixels, create, createButton, createButtonBar, dialogFontIsDefault, getBlockedHandler, getButton, getButtonBar, getCancelButton, getDialogArea, getImage, getOKButton, initializeBounds, initializeDialogUnits, setBlockedHandler, setButtonLayoutData, setButtonLayoutFormData, shortenText`

Methods inherited from class org.eclipse.jface.window.Window
`canHandleShellCloseEvent, createShell, getConstrainedShellBounds, getContents, getDefaultImage, getDefaultImages, getInitialLocation, getInitialSize, getLayout, getParentShell, getReturnCode, getShell, getShellListener, getShellStyle, getWindowManager, handleFontChange, 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

### PREF_DLG_IMG_TITLE_ERROR

    public static final String PREF_DLG_IMG_TITLE_ERROR

  Indentifier for the error image

  See Also:
    Constant Field Values

### PREF_DLG_TITLE_IMG

    public static final String PREF_DLG_TITLE_IMG

  Title area fields

  See Also:
    Constant Field Values

Constructor Detail

### PreferenceDialog

    public PreferenceDialog(Shell parentShell,
                            PreferenceManager manager)

  Creates a new preference dialog under the control of the given preference manager.

Parameters:
  `parentShell` - the parent shell
  `manager` - the preference manager

Method Detail

### buttonPressed

    protected void buttonPressed(int buttonId)

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

  Overrides:
    `buttonPressed` in class `Dialog`
  Parameters:
    `buttonId` - the id of the button that was pressed (see `IDialogConstants.*_ID` constants)

### cancelPressed

    protected void cancelPressed()

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

  Overrides:
    `cancelPressed` in class `Dialog`

### 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 `Dialog`
  See Also:
    `Window.close()`

### configureShell

    protected void configureShell(Shell newShell)

  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:
    `newShell` - the shell

### constrainShellSize

    protected void constrainShellSize()

  Description copied from class: `Window`
  Constrain the shell size to be no larger than the display bounds.

  Overrides:
    `constrainShellSize` in class `Window`

### createButtonsForButtonBar

    protected void createButtonsForButtonBar(Composite parent)

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

  Overrides:
    `createButtonsForButtonBar` in class `Dialog`
  Parameters:
    `parent` - the button bar composite

### createContents

    protected Control createContents(Composite parent)

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

### createDialogArea

    protected Control createDialogArea(Composite parent)

  Description copied from class: `Dialog`
  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;

  Overrides:
    `createDialogArea` in class `Dialog`
  Parameters:
    `parent` - the parent composite to contain the dialog area
  Returns:
    the dialog area control

### createTreeAreaContents

    protected Control createTreeAreaContents(Composite parent)

  Parameters:
    `parent` - the SWT parent for the tree area controls.
  Returns:
    the new `Control`.
  Since:
    3.0

### createTreeViewer

    protected TreeViewer createTreeViewer(Composite parent)

  Create a new `TreeViewer`.

  Parameters:
    `parent` - the parent `Composite`.
  Returns:
    the `TreeViewer`.
  Since:
    3.0

### findNodeMatching

    protected IPreferenceNode findNodeMatching(String nodeId)

  Find the `IPreferenceNode` that has data the same id as the supplied value.

  Parameters:
    `nodeId` - the id to search for.
  Returns:
    `IPreferenceNode` or `null` if not found.

### getPreferenceManager

    public PreferenceManager getPreferenceManager()

  Returns the preference mananger used by this preference dialog.

  Returns:
    the preference mananger

### getPreferenceStore

    public IPreferenceStore getPreferenceStore()

  Description copied from interface: `IPreferencePageContainer`
  Returns the preference store.

  Specified by:
    `getPreferenceStore` in interface `IPreferencePageContainer`
  Returns:
    the preference store, or `null` if none

### getSelectedNodePreference

    protected String getSelectedNodePreference()

  Get the name of the selected item preference

  Returns:
    String

### getSingleSelection

    protected IPreferenceNode getSingleSelection(ISelection selection)

  Parameters:
    `selection` - the `ISelection` to examine.
  Returns:
    the first element, or null if empty.

### getTreeViewer

    protected TreeViewer getTreeViewer()

  Returns:
    the `TreeViewer` for this dialog.
  Since:
    3.0

### handleSave

    protected void handleSave()

  Save the values specified in the pages.

  The default implementation of this framework method saves all pages of type `PreferencePage` (if their store needs saving and is a `PreferenceStore`).

  Subclasses may override.

### handleShellCloseEvent

    protected void handleShellCloseEvent()

  Notifies that the window's close button was pressed, the close menu was selected, or the ESCAPE key pressed.

  The default implementation of this framework method sets the window's return code to `CANCEL` and closes the window using `close`. Subclasses may extend or reimplement.

  Overrides:
    `handleShellCloseEvent` in class `Window`

### helpPressed

    protected void helpPressed()

  Notifies of the pressing of the Help button.

  The default implementation of this framework method calls `performHelp` on the currently active page.

### isCurrentPageValid

    protected boolean isCurrentPageValid()

  Returns whether the current page is valid.

  Returns:
    `false` if the current page is not valid, or or `true` if the current page is valid or there is no current page

### layoutTreeAreaControl

    protected void layoutTreeAreaControl(Control control)

  Parameters:
    `control` - the `Control` to lay out.
  Since:
    3.0

### okPressed

    protected void okPressed()

  The preference dialog implementation of this `Dialog` framework method sends `performOk` to all pages of the preference dialog, then calls `handleSave` on this dialog to save any state, and then calls `close` to close this dialog.

  Overrides:
    `okPressed` in class `Dialog`

### selectSavedItem

    protected void selectSavedItem()

  Selects the saved item in the tree of preference pages. If it cannot do this it saves the first one.

### setErrorMessage

    public void setErrorMessage(String newErrorMessage)

  Display the given error message. The currently displayed message is saved and will be redisplayed when the error message is set to `null`.

  Parameters:
    `newErrorMessage` - the errorMessage to display or `null`

### setHelpAvailable

    public void setHelpAvailable(boolean b)

  Sets whether a Help button is available for this dialog.

  Clients must call this framework method before the dialog's control has been created.

  Parameters:
    `b` - `true` to include a Help button, and `false` to not include one (the default)

### setMessage

    public void setMessage(String newMessage)

  Set the message text. If the message line currently displays an error, the message is stored and will be shown after a call to clearErrorMessage

  Shortcut for `setMessage(newMessage, NONE)`

  Parameters:
    `newMessage` - the message, or `null` to clear the message

### setMessage

    public void setMessage(String newMessage,
                           int newType)

  Sets the message for this dialog with an indication of what type of message it is.

  The valid message types are one of `NONE`, `INFORMATION`,`WARNING`, or `ERROR`.

  Note that for backward compatibility, a message of type `ERROR` is different than an error message (set using `setErrorMessage`). An error message overrides the current message until the error message is cleared. This method replaces the current message and does not affect the error message.

  Parameters:
    `newMessage` - the message, or `null` to clear the message
    `newType` - the message type
  Since:
    2.0

### setMinimumPageSize

    public void setMinimumPageSize(int minWidth,
                                   int minHeight)

  Sets the minimum page size.

  Parameters:
    `minWidth` - the minimum page width
    `minHeight` - the minimum page height
  See Also:
    `setMinimumPageSize(Point)`

### setMinimumPageSize

    public void setMinimumPageSize(Point size)

  Sets the minimum page size.

  Parameters:
    `size` - the page size encoded as `new Point(width,height)`
  See Also:
    `setMinimumPageSize(int,int)`

### setPreferenceStore

    public void setPreferenceStore(IPreferenceStore store)

  Sets the preference store for this preference dialog.

  Parameters:
    `store` - the preference store
  See Also:
    `getPreferenceStore()`

### setSelectedNode

    public void setSelectedNode(String pageId)

  Sets the name of the selected item preference. Public equivalent to `setSelectedNodePreference`.

  Parameters:
    `pageId` - The identifier for the page
  Since:
    3.0

### setSelectedNodePreference

    protected void setSelectedNodePreference(String pageId)

  Sets the name of the selected item preference.

  Parameters:
    `pageId` - The identifier for the page

### showPage

    protected boolean showPage(IPreferenceNode node)

  Shows the preference page corresponding to the given preference node. Does nothing if that page is already current.

  Parameters:
    `node` - the preference node, or `null` if none
  Returns:
    `true` if the page flip was successful, and `false` is unsuccessful

### update

    protected void update()

  Updates this dialog's controls to reflect the current page.

### updateButtons

    public void updateButtons()

  Description copied from interface: `IPreferencePageContainer`
  Adjusts the enable state of the OK button to reflect the state of the currently active page in this container.

  This method is called by the container itself when its preference page changes and may be called by the page at other times to force a button state update.

  Specified by:
    `updateButtons` in interface `IPreferencePageContainer`

### updateMessage

    public void updateMessage()

  Description copied from interface: `IPreferencePageContainer`
  Updates the message (or error message) shown in the message line to reflect the state of the currently active page in this container.

  This method is called by the container itself when its preference page changes and may be called by the page at other times to force a message update.

  Specified by:
    `updateMessage` in interface `IPreferencePageContainer`

### updateTitle

    public void updateTitle()

  Description copied from interface: `IPreferencePageContainer`
  Updates the title to reflect the state of the currently active page in this container.

  This method is called by the container itself when its page changes and may be called by the page at other times to force a title update.

  Specified by:
    `updateTitle` in interface `IPreferencePageContainer`

### updateTreeFont

    protected void updateTreeFont(Font dialogFont)

  Update the tree to use the specified `Font`.

  Parameters:
    `dialogFont` - the `Font` to use.
  Since:
    3.0

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.