Package org.eclipse.jface.preference

Class PreferenceDialog

java.lang.Object
org.eclipse.jface.window.Window
org.eclipse.jface.dialogs.Dialog
org.eclipse.jface.dialogs.TrayDialog
org.eclipse.jface.preference.PreferenceDialog
All Implemented Interfaces:
IPageChangeProvider, IPreferencePageContainer, IShellProvider
public class PreferenceDialog extends TrayDialog implements IPreferencePageContainer, IPageChangeProvider
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.

  • Field Details

  • Constructor Details

    • 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 Details

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

      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 Dialog
      Returns:
      true if the window is (or was already) closed, and false if it is still open
      See Also:

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

      Note: The common button order is: {other buttons}, OK, Cancel. On some platforms, Dialog.initializeBounds() will move the default button to the right.

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

    • createSash

      protected Sash createSash(Composite composite, Control rightControl)
      Create the sash with right control on the right. Note that this method assumes GridData for the layout data of the rightControl.
      Parameters:
      composite - the parent composite
      rightControl - control for the right part of the created sash
      Returns:
      Sash
      Since:
      3.1

    • createPageContainer

      protected Composite createPageContainer(Composite parent)
      Creates the inner page container.
      Parameters:
      parent - the parent composite
      Returns:
      Composite

    • getPageLayout

      protected Layout getPageLayout()
      Return the layout for the composite that contains the pages.
      Returns:
      PageLayout
      Since:
      3.1

    • createTitleArea

      protected Composite createTitleArea(Composite parent)
      Creates the wizard's title area.
      Parameters:
      parent - the SWT parent for the title area composite.
      Returns:
      the created title area composite.

    • 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

    • addListeners

      protected void addListeners(TreeViewer viewer)
      Add the listeners to the tree viewer.
      Parameters:
      viewer - viewer to add listeners to
      Since:
      3.1

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

    • getLastRightWidth

      protected int getLastRightWidth()
      Get the last known right side width.
      Returns:
      the width.

    • 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

      public TreeViewer getTreeViewer()
      Returns:
      the TreeViewer for this dialog.
      Since:
      3.3

    • 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 TrayDialog

    • 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

    • 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

      public void setMinimumPageSize(Point size)
      Sets the minimum page size.
      Parameters:
      size - the page size encoded as new Point(width,height)
      See Also:

    • setPreferenceStore

      public void setPreferenceStore(IPreferenceStore store)
      Sets the preference store for this preference dialog.
      Parameters:
      store - the preference store
      See Also:

    • 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

    • createPage

      protected void createPage(IPreferenceNode node)
      Create the page for the node.
      Parameters:
      node - the node to create page for
      Since:
      3.1

    • getPage

      protected IPreferencePage getPage(IPreferenceNode node)
      Get the page for the node.
      Parameters:
      node - the node to get page for
      Returns:
      IPreferencePage
      Since:
      3.1

    • 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

    • getCurrentPage

      protected IPreferencePage getCurrentPage()
      Returns the currentPage.
      Returns:
      IPreferencePage
      Since:
      3.1

    • setCurrentPage

      protected void setCurrentPage(IPreferencePage currentPage)
      Sets the current page.
      Parameters:
      currentPage - page to set
      Since:
      3.1

    • setTreeViewer

      protected void setTreeViewer(TreeViewer treeViewer)
      Set the treeViewer.
      Parameters:
      treeViewer - viewer to set
      Since:
      3.1

    • getPageContainer

      protected Composite getPageContainer()
      Get the composite that is showing the page.
      Returns:
      Composite.
      Since:
      3.1

    • setPageContainer

      protected void setPageContainer(Composite pageContainer)
      Set the composite that is showing the page.
      Parameters:
      pageContainer - Composite
      Since:
      3.1

    • createPageControl

      protected void createPageControl(IPreferencePage page, Composite parent)
      Create the page control for the supplied page.
      Parameters:
      page - - the preference page to be shown
      parent - - the composite to parent the page
      Since:
      3.1

    • getSelectedPage

      public Object getSelectedPage()
      Description copied from interface: IPageChangeProvider
      Returns the currently selected page in the dialog.
      Specified by:
      getSelectedPage in interface IPageChangeProvider
      Returns:
      the selected page in the dialog or null if none is selected. The type may be domain specific. In the JFace provided dialogs this will be an instance of IDialogPage.
      Since:
      3.1
      See Also:

    • addPageChangedListener

      public void addPageChangedListener(IPageChangedListener listener)
      Description copied from interface: IPageChangeProvider
      Adds a listener for page changes in this page change provider. Has no effect if an identical listener is already registered.
      Specified by:
      addPageChangedListener in interface IPageChangeProvider
      Parameters:
      listener - a page changed listener
      Since:
      3.1
      See Also:

    • removePageChangedListener

      public void removePageChangedListener(IPageChangedListener listener)
      Description copied from interface: IPageChangeProvider
      Removes the given page change listener from this page change provider. Has no effect if an identical listener is not registered.
      Specified by:
      removePageChangedListener in interface IPageChangeProvider
      Parameters:
      listener - a page changed listener
      Since:
      3.1
      See Also:

    • firePageChanged

      protected void firePageChanged(PageChangedEvent event)
      Notifies any selection changed listeners that the selected page has changed. Only listeners registered at the time this method is called are notified.
      Parameters:
      event - a selection changed event
      Since:
      3.1
      See Also:

    • isResizable

      protected boolean isResizable()
      Description copied from class: Dialog
      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.

      Overrides:
      isResizable in class Dialog
      Returns:
      a boolean indicating whether the dialog is resizable and should have the default style bits for resizable dialogs