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
static String	PREF_DLG_TITLE_IMG Title area fields

Fields inherited from class org.eclipse.jface.dialogs.Dialog

DLG_IMG_ERROR, DLG_IMG_INFO, DLG_IMG_MESSAGE_ERROR, DLG_IMG_MESSAGE_INFO, DLG_IMG_MESSAGE_WARNING, DLG_IMG_QUESTION, DLG_IMG_WARNING

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).
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 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	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.
protected void	setSelectedNodePreference(String pageId) Get 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.

Methods inherited from class org.eclipse.jface.dialogs.Dialog

convertHeightInCharsToPixels, convertHeightInCharsToPixels, convertHorizontalDLUsToPixels, convertHorizontalDLUsToPixels, convertVerticalDLUsToPixels, convertVerticalDLUsToPixels, convertWidthInCharsToPixels, convertWidthInCharsToPixels, createButton, createButtonBar, getButton, getButtonBar, getCancelButton, getDialogArea, getImage, getOKButton, initializeDialogUnits

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

create, createShell, getContents, getDefaultImage, getInitialLocation, getInitialSize, getParentShell, getReturnCode, getShell, getShellListener, getShellStyle, getWindowManager, handleFontChange, initializeBounds, open, setBlockOnOpen, setDefaultImage, 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_TITLE_IMG

public static final String PREF_DLG_TITLE_IMG

Title area fields

See Also:

Constant Field Values

PREF_DLG_IMG_TITLE_ERROR

public static final String PREF_DLG_IMG_TITLE_ERROR

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:

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 Window

Returns:

true if the window is (or was already) closed, and false if it is still open

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: Dialog

Constrain the shell size to be no larger than the display bounds. Reduce the shell size and move its origin as required.

Overrides:

constrainShellSize in class Dialog

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

Returns:

the control

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.

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

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

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

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.

getSelectedNodePreference

protected String getSelectedNodePreference()

Get the name of the selected item preference

setSelectedNodePreference

protected void setSelectedNodePreference(String pageId)

Get the name of the selected item preference

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.

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(org.eclipse.swt.graphics.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()

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