Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "E4/Doc/Preferences"
(→Motivation) |
|||
| Line 14: | Line 14: | ||
== Motivation == | == Motivation == | ||
| + | Over time there were lots of API's with varying degrees of completeness developed in Eclipse 3.x and earlier to manage user preferences. In E4, and effort was made to streamline the most common case while maintaining the functionality of older API's. | ||
| − | + | The most frequent case for preferences is simply 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. The framework will update the value of your preference variable as it is changed as well however through this method you are unable to be notified of these changes. | |
| − | + | The next case for preferences is when you need to set or create them. In E4 you can still access the existing IEclipsePreferences API through dependency injection as well. IEclipsePreferences will allow you, among other things, to create/modify preference values but also use "setters" on preferences and attach listeners to be notified when they change so you can react appropriately. | |
| + | |||
| + | Finally the framework allows you to set various scopes on the preferences (instance scope by default) as well as chain scopes for precedence through the use of IEclipsePreferences too. | ||
== Applicability == | == Applicability == | ||
Revision as of 01:03, 17 March 2010
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.
The ability for users to customize application features according to their individual requirements is often useful. 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 that specifies that a user would like to have a tool tip displayed on startup could 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.
- Eclipse instance - An Eclipse instance is synonymous with a workspace. In the context of preferences, an instance scope is valid while using a specific workspace.
Motivation
Over time there were lots of API's with varying degrees of completeness developed in Eclipse 3.x and earlier to manage user preferences. In E4, and effort was made to streamline the most common case while maintaining the functionality of older API's.
The most frequent case for preferences is simply 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. The framework will update the value of your preference variable as it is changed as well however through this method you are unable to be notified of these changes.
The next case for preferences is when you need to set or create them. In E4 you can still access the existing IEclipsePreferences API through dependency injection as well. IEclipsePreferences will allow you, among other things, to create/modify preference values but also use "setters" on preferences and attach listeners to be notified when they change so you can react appropriately.
Finally the framework allows you to set various scopes on the preferences (instance scope by default) as well as chain scopes for precedence through the use of IEclipsePreferences too.
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); }