Difference between revisions of "E4/Doc/Preferences"

Revision as of 22:26, 4 April 2010

A placeholder diagram.

Users often require the ability to customize application features according to their individual needs or preferences. Eclipse e4 provides a mechanism to persist and retrieve these customizations, known as Preferences, within a range of scopes.

In the most common case, a user preference is simply a key-value pair that is associated with an Eclipse instance. For example, the preference which specifies that a user would like a tool tip displayed on startup may be stored as "showToolTip=true".

Relevant Terms

• Key - A key is a unique string identifier for a preference setting.
• Value - A value is the current preference setting associated with a key, within a specific scope.
• Instance scope - Preferences in this scope are specific to a single Eclipse workspace.
• Configuration scope - Preferences stored in this scope are shared by all workspaces that are launched using a particular configuration of Eclipse plug-ins. On a single-user installation, this serves to capture preferences that are common to all workspaces launched by the user. On a multi-user installation, these preferences are shared by all users of the configuration.
• Workbench model - an XML file specifying the injections.

Motivation

Eclipse 3.x and earlier offered a number of API's with varying degrees of completeness allowing to manage user preferences. In E4, an effort was made to streamline the most common case while maintaining the functionality of older API's.

The most frequent use case for preferences is retrieving a value that has already been set. This is easily done through dependency injection by the framework at runtime, using the appropriate JSR Annotations. Eclipse also allows the value of a preference to be injected into the component without persistence.

Other use cases are: creating preferences, setting values of particular keys and persisting preference changes. In e4 developers can still access the existing IEclipsePreferences API through dependency injection in order to implement the aforementioned features. In addition, IEclipsePreferences allows the attachment of listeners which are notified upon preference changes. By default all values are stored in the "instance scope" of the corresponding bundle (plugin).

Finally the framework allows developers to set various scopes on preferences as well as to chain scopes for precedence through the use of IEclipsePreferences. Preferences associated with the currently running Eclipse instance can also be retrieved.

Applicability

The applications of preferences are many:

• UI customization: fonts, window & pane properties, and colors
• Installation settings: locations of resources, working directories
• Application settings: internationalization selections, program parameters

Implementation

In the most common case, e4 permits preference retrieval through dependency injection. By specifying an injection with a @Preference qualifier key, the qualifier's corresponding preference value is retrieved and injected.

For example, in the following Java code, a default username preference is retrieved to populate a field in a login window.

public class LoginWindow
 
@Inject @Preference(MyPrefConstants.DEFAULT_USERNAME) String username;
 
public LoginWindow(){
   getUserNameInput.setText(username);
}

Preference values are stored in files, one file per plugin. If the developer is intending to create, view or modify preferences valid for all workspaces, the Equinox bundle can be used to access preferences stored at the level of the install. In addition, the Java IDE for example offers project specific settings; a "team" scope can also be specified. The lower level API can be used to implement chaining of various scopes.

Related Services

Persisting UI State - related to the instance of a UI component (for example column width of a SearchView, previous search query, etc.). The Persisting UI State also involves the storage of keys and values but at a different scope and does not allow scope chaining.