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