Dialog Settings, Preferences, and User Settings

Chapter 17, Dialog Settings, Preferences, and User Settings, presented the many options for storing keyed values as part of the Eclipse platform. You learned how to initialize defaults and use either the PreferenceStore, Preferences, or user settings APIs to get and set stored values. The example in the com.ibm.jdg2e.usersettings project demonstrates the basic techniques for how stored values can be accessed from a preference page, property page, or elsewhere in your plug-in. In doing so, this example also serves as a demonstration of how a preference page, property page, and preference initializer can be implemented.

Running the Example

This example is best run as a project in a test workspace. This is because you are manipulating stored values that need to be cleared to reset the testing cycle. This is easy when launching the runtime Workbench for testing, but harder to do if the plug-in is installed.

First, setup the launch configuration to both clear the configuration area and start with a new workspace by doing the following.

Open the launch configuration dialog for an Eclipse Application (Run > Run...).
Select the Configuration tab and choose the Clear the configuration area before launching toggle option. This tells Eclipse to erase any stored configuration and user setting data when starting the runtime Workbench instance.
Return to the Arguments tab and either select the Clear workspace data before launching option or specify a new workspace subdirectory in the Location field.

Second, find each component of the example:

Launch the a runtime Workbench.
Create two simple projects in the workspace.
Open the User Settings API Demo view, if required. Select a project in the Navigator view and note the displayed values for each key.

The values for two keys are shown in this view. Each value instance represents a different type of call for the given key. The Default, Configuration, Instance, and Project values represent direct calls to a specific node. For Key 1 the defined default is used as the default-default value. For Key 2 a hard-coded default-default value is used. The Cascaded Project value is the result of reading the key through a sequence of nodes (project, instance, configuration, default).

Find and select the JDG2E: User Settings API Demo preference page.

The preference page displays two keyed values that can be modified. If modified the instance values for the keys are changed. Leave them as-is for now.

The initial value for Key 1 is set using the preference store API (instance level) in the preference initializer defined by extension in the plug-in's manifest file. The Key 2 value is set as part of the preference page logic. It is now different than what was originally displayed in the view.

Close the Preferences dialog and check the view again (select a project to force the view to refresh). The Default and Cascaded Project values for Key 2 have changed as a default was established. Key 1 already had a default.
Select a project and open the Properties dialog, then select the JDG2E: User Settings API Demo property page.

The Configuration, Instance, and Project values for each key can be modified here.

Using the property page, modify the Project value for Key 1 and the Configuration value for Key 2 and then close the dialog.
Return to the view and check the values for the same project. The Default, Configuration, and Instance values for Key 1 are unchanged, but a new Project and Cascaded Project value exist. For Key 2 the Configuration and Cascaded Project values are now different.
Select a different project and check the values. Key 1 should not have anything but default values while Key 2 still shows the same as for the previous project selection.
Use the property page to change the instance value for Key 1. This should now be reflected in the view for each project selected.
If you shutdown the test environment and restart without changing any invocation settings, then Key 1 will retain the Instance and Project values while Key 2 will lose its customization. Key 2 loses the Instance default defined in the preference page as this initialize logic must run every time. The Configuration level setting was lost as the runtime Workbench was launched with the option to clear the configuration.

Note: The runtime Workbench mimics the behavior of an installed version of Eclipse by keeping user settings information around between launches. Working from the bottom up, each plug-in has a file for their settings in an appropriate location.

Project specific settings are kept in the project directory ([project]/.settings).
Just like the regular runtime environment, instance level settings are kept in the state directory for the Eclipse Platform runtime plug-in (.metadata/.plugins/org.eclipse.core.runtime).
Configuration level settings for runtime are kept in the Eclipse configuration directory (eclipse/configuration/.settings). During testing these are managed by the Plug-in Development Environment and are hidden in the state directory for the org.eclipse.core.pde plug-in. Check you active workspace and its .metadata directory to hunt them down.

Roadmap of the Example

The User Settings API Demonstration plug-in is designed to show the behavior of the user settings API in various circumstances. The preference page, property page, and view user interfaces are designed to expose values in certain circumstances and let you better understand the scope of a given node for storing keyed values.

The plug-in manifest file includes the extension definitions for the preference page, property page, and view and an extension for the runtime preference initializer that is called when the plug-in is activated. The table below contains the key classes from the com.ibm.jdg2e.usersettings package that are used to implement the user interface and user settings control logic.

Class (All)	Description
`CommonSettingsUI`	Reusable component for the UI shown in the view, preference page, and property page.
`SettingsView`	This class implements the view's user interface and function.
`PreferencePageSettingsDemo`	Preference page implementation that includes localized default value initialization and support for Instance value modification (uses Preference Store API).
`PropertyPageSettingsDemo`	Property page implementation that includes ability to modify Configuration, Instance, and Project nodes for the supported keyed values.
`ValueDefaults`	Runtime Preference Initializer as identified by extension for this plug-in.