Eclipse icon

Preference Pages

The implementation of a preference page requires that you define an extension in your plug-in and provide an implementation of the extension. The plugin.xml defines two preference page extensions. One is a custom page implemented as a subclass of PreferencePage that implements IWorkbenchPreferencePage. The second page is built using the FieldEditor framework, so it is a subclass of FieldEditorPreferencePage. When using the FieldEditor framework the user interface constructed with controls implemented using FieldEditor subtypes.

Running the Solution

To run the example, launch the run-time instance of Eclipse (Run > Run As > Run-time Workbench).

  1. Open the Preferences dialog (Window -> Preferences) and select the node titled Soln: Basic Preference Page, you will see the custom preference page implemented by the MyPrefPageBasic class:



    The recent edits and text field settings are default values established by the plug-in's initializeDefaultPreferences method as part of the preference store life cycle.

    Modify the values shown and select Apply. The performOk method will store the values in the plug-in's preference store.

  2. Open the the node titled Soln: Basic Preference SubPage and you will see the field editor preference page implemented by the MyPrefPageFieldEditor class. This example preference page shows how you can quickly create simple pages that handle much of the layout, retrieval, and saving of preferences using the field editors preference page framework:

    Use the controls shown to select values for the different preference settings and then select Apply. The field editor framework automatically stores the values in the plug-in's preference store.

  3. When Apply or OK are selected on a preference page the preference settings are updated in the preference store object. If your tool logic needs to be aware of such updates, you can use preference change listeners. To demonstrate this, open the Soln: Preference Control SubPage preference page. The MyPrefPageControl class that will report when preferences in the com.ibm.soln.dialogs plug-in have changed:

    Note: This is not a true preference page, in fact we are technically misusing the construct. This page does not save any preferences (which is why we used the noDefaultAndApplyButton method to hide those buttons). This page exists to provide a convenient place to demonstrate the code that interact with the preference store.

  4. Select the toggle to add the change listener:


  5. Return to one of the two previously visited preference pages, modify one preference value, and select Apply. The property change listener that you enabled in the previous step will report the change:


  6. If you modify two preference values, two dialogs will be displayed. Each change is reported as it is made. You can remove the change listener by returning to the Soln: Preference Control SubPage and deselecting the toggle..

    Note: The preference values are not saved on disk until you shut down Eclipse, unless you have added save processing logic to your preference page implementation. By default, this example plug-in will save the preference store as part of the shutdown method inherited from AbstractUIPlugin.

  7. Using the Soln: Preference Control SubPage you can force the preference settings to be saved immediately (as opposed to when Eclipse is shut down). Open the page and select Save com.ibm.soln.dialogs Preference Store.

    The preference settings are saved to disk. You can find them by opening this file in your workspace directory:
      \.metadata\.plugins\com.ibm.lab.soln.dialogs\pref_store.in
    The .ini file will contain something like this:
    #Sun Feb 02 23:45:06 EST 2003
    BOOLEAN_KEY=true
    Recent_Edits_Limit=12
    text_field_key=qrs
    FILE_KEY=E\:\\aEclipseBase\\edu.jar
    COLOR_KEY=128,0,128
    DIR_KEY=D\:\\Eclipse_Jumpstart

Roadmap to the Solution

This example includes two preference page extensions that demonstrate two ways of building the user interface. It also demonstrates the use of a plug-in's preference store, and the ability to determine when preference store values change. The extension definitions can be found in the plugin.xml. The classes that implement these extensions and capabilities are shown below.

Extension / Object Implementation
Preference page extensions The Basic preference page is implemented by the MyPrefPageBasic class.
The field editor preference page is implemented by the MyPrefPageFieldEditor class.
The control preference page, which is only used to start and stop a preference change listener and force the save of preference store values, is implemented by the MyPrefPageControl class.
Preference Value Change Listener The property change listener for preference changes is implemented by PreferenceListener, a DialogsPlugin inner class.

© Copyright International Business Machines Corporation, 2003.
All rights reserved.