E4/Doc/Preferences

Under Construction: Please read first!

The evolution of this document is a collaborative effort between a team of students at the University of Manitoba and the wider Eclipse community. Details about the project can be found here and on our Blog.

Your input is not just welcome; it is needed! Please contribute as your expertise allows, while adhering to our template. To send your feedback and any questions or comments you may have please email us. Also, while we do our very best to be as accurate and precise as possible, it is worth noting that we are students with limited exposure to the Eclipse platform, so if you see any incorrect technical details please let us know.

A diagram of the most common use of Preferences

Legend

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

In the most common case, a user preference is simply a key-value pair associated with an Eclipse instance. For example, the preference which specifies whether the 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 scope 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.

Motivation

Preferences is most commonly used to retrieve a value that has already been set. The framework can retrieve the value at runtime through a dependency injection, 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
• persisting preference changes

You can implement these features using the IEclipsePreferences API through dependency injection. In addition, you can use IEclipsePreferences to attach listeners which are notified of preference changes. By default all values are stored in the "instance scope" of the corresponding bundle (plugin).

Finally you can use IEclipsePreferences to not only set various scopes on preferences, but also to chain scopes for precedence. 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.

History

Eclipse 3.x and earlier offered a number of API's with varying degrees of completeness allowing to manage user preferences. Eclipse e4 streamlines the most common use case while maintaining the functionality of older API's. You can still access the existing IEclipsePreferences API through dependency injection if you need to implement more specific features.

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.