Jump to: navigation, search

Difference between revisions of "FAQ How do I load and save plug-in preferences?"

m
(I'm hardly an expert.. Heck, I'm not even sure the above code runs.)
Line 1: Line 1:
Each plug-in has a local workspace preference store for saving arbitrary primitive data types and strings. Preferences displayed in the Workbench Preferences dialog are typically stored in these local plug-in preference stores. The '''Import''' and '''Export''' buttons in the Workbench Preferences page also operate on these plug-in preference stores.  
+
Each plug-in has a local workspace preference store for saving arbitrary primitive data types and strings. Preferences displayed in the Workbench Preferences dialog are typically stored in these local plug-in preference stores. The '''Import''' and '''Export''' buttons in the Workbench Preferences page also operate on these plug-in preference stores.  
  
Retrieving values from plug-in preferences is fairly straightforward:
+
Retrieving values from plug-in preferences is fairly straightforward:  
 
+
<pre>   Plugin plugin = ExamplesPlugin.getDefault();
<pre>
+
   <strike>Preferences</strike> prefs = plugin.<strike>getPluginPreferences</strike>();
  Plugin plugin = ExamplesPlugin.getDefault();
+
   Preferences prefs = plugin.getPluginPreferences();
+
 
   int value = prefs.getInt("some.key");
 
   int value = prefs.getInt("some.key");
</pre>
+
</pre>  
 +
When preferences are changed, the preference store must be explicitly saved to disk:
 +
<pre>  prefs.setValue("some.key", 5);
 +
  plugin.<strike>savePluginPreferences</strike>();
 +
</pre>
 +
The plug-in preference store can also store default values for any preference in that plug-in. If a value has not been explicitly set for a given key, the default value is returned. If the key has no default value set, a default default value is used: zero for numeric preferences, <tt>false</tt> for Boolean preferences, and the empty string for string preferences. If the default default is not appropriate for your preference keys, you should establish a default value for each key by overriding the <tt>initializeDefaultPluginPreferences</tt> method in your <tt>Plugin</tt> subclass:
 +
<pre>  protected void initializeDefaultPluginPreferences() {
 +
      prefs = plugin.<strike>getPluginPreferences</strike>();
 +
      prefs.setDefault("some,key", 1);
 +
  }
 +
</pre>
 +
Although you can change default values at any time, it is generally advised to keep them consistent so that users know what to expect when they revert preferences to their default values. Programmatically reverting a preference to its default value is accomplished with the <tt>setToDefault</tt> method.
  
When preferences are changed, the preference store must be
 
explicitly saved to disk:
 
  
<pre>
 
  prefs.setValue("some.key", 5);
 
  plugin.savePluginPreferences();
 
</pre>
 
  
The plug-in preference store can also store default values for any preference in that plug-inIf a value has not been explicitly set for a given key, the default value is returnedIf the key has no default value set, a default default value is used: zero for numeric preferences, <tt>false</tt> for Boolean preferences, and the empty string for string preferences. If the default default is not appropriate for your preference keys, you should establish a default value for each key by overriding the <tt>initializeDefaultPluginPreferences</tt> method in your <tt>Plugin</tt> subclass:
+
== Current Practice ==
 +
IPreferencesService service = Platform.getPreferencesService();
 +
  Preferences prefs = service.getRootNode().node("my.plugin.id");
 +
   
 +
  if (storing) {       
 +
  prefs.put(SOME_KEY, someValue);
 +
} else {
 +
  someValue = prefs.get(SOME_KEY, "default value" );
 +
}
 +
 
 +
org.osgi.service.prefs.Preferences support int, long, boolean, byte[], float, and double as well as the above String example.
 +
 
 +
The above example is a tad unrealistic in that it uses ''storing'' as an excuse to show both ''get()'' and ''set()''.  Normally these could be called from within a plugin's ''start()'' and ''stop()'' overrides instead.
 +
 
  
<pre>
 
  protected void initializeDefaultPluginPreferences() {
 
      prefs = plugin.getPluginPreferences();
 
      prefs.setDefault("some,key", 1);
 
  }
 
</pre>
 
  
Although you can change default values at any time, it is generally advised to keep them consistent so that users know what to expect when they revert preferences to their default values. Programmatically reverting a preference to its default value is accomplished with the <tt>setToDefault</tt> method.
+
== See Also:  ==
  
== See Also: ==
 
 
*[[FAQ How do I use the preference service?]]
 
*[[FAQ How do I use the preference service?]]
  
 
{{Template:FAQ_Tagline}}
 
{{Template:FAQ_Tagline}}

Revision as of 18:35, 7 July 2010

Each plug-in has a local workspace preference store for saving arbitrary primitive data types and strings. Preferences displayed in the Workbench Preferences dialog are typically stored in these local plug-in preference stores. The Import and Export buttons in the Workbench Preferences page also operate on these plug-in preference stores.

Retrieving values from plug-in preferences is fairly straightforward:

   Plugin plugin = ExamplesPlugin.getDefault();
   <strike>Preferences</strike> prefs = plugin.<strike>getPluginPreferences</strike>();
   int value = prefs.getInt("some.key");

When preferences are changed, the preference store must be explicitly saved to disk:

   prefs.setValue("some.key", 5);
   plugin.<strike>savePluginPreferences</strike>();

The plug-in preference store can also store default values for any preference in that plug-in. If a value has not been explicitly set for a given key, the default value is returned. If the key has no default value set, a default default value is used: zero for numeric preferences, false for Boolean preferences, and the empty string for string preferences. If the default default is not appropriate for your preference keys, you should establish a default value for each key by overriding the initializeDefaultPluginPreferences method in your Plugin subclass:

   protected void initializeDefaultPluginPreferences() {
      prefs = plugin.<strike>getPluginPreferences</strike>();
      prefs.setDefault("some,key", 1);
   }

Although you can change default values at any time, it is generally advised to keep them consistent so that users know what to expect when they revert preferences to their default values. Programmatically reverting a preference to its default value is accomplished with the setToDefault method.


Current Practice

IPreferencesService service = Platform.getPreferencesService();
Preferences prefs = service.getRootNode().node("my.plugin.id");

if (storing) {        
  prefs.put(SOME_KEY, someValue);
} else {
  someValue = prefs.get(SOME_KEY, "default value" );
}

org.osgi.service.prefs.Preferences support int, long, boolean, byte[], float, and double as well as the above String example.

The above example is a tad unrealistic in that it uses storing as an excuse to show both get() and set(). Normally these could be called from within a plugin's start() and stop() overrides instead.


See Also:


This FAQ was originally published in Official Eclipse 3.0 FAQs. Copyright 2004, Pearson Education, Inc. All rights reserved. This text is made available here under the terms of the Eclipse Public License v1.0.