Wrapped article in Nova skin and marked as deprecated.
diff --git a/Article-Preferences/article.html b/Article-Preferences/article.html
new file mode 100644
index 0000000..1763f8f
--- /dev/null
+++ b/Article-Preferences/article.html
@@ -0,0 +1,417 @@
+<html>
+
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
+
+
+<title>Preferences and Properties in the Eclipse Workbench UI</title>
+<link rel="stylesheet" type="text/css" href="../default_style.css">
+</head>
+
+<body>
+<DIV align=right><FONT face="Times New Roman, Times, serif"
+size=2>Copyright © 2001,2002 Object Technology International, Inc.</FONT> </DIV>
+<TABLE border=0 cellPadding=2 cellSpacing=0 width="100%">
+ <TBODY>
+ <TR>
+ <TD align=left bgColor=#0080c0 colSpan=2 vAlign=top><B><FONT
+ face=Arial,Helvetica><FONT color=#ffffff> Eclipse Corner
+ Article</FONT></FONT></B></TD></TR></TBODY></TABLE>
+<H1><img align=center
+src="images/Idea.jpg" width="120" height="86">
+<center>Preferences in the Eclipse Workbench UI</center></H1>
+<blockquote>
+<b>Summary</b><br>
+In the Eclipse Platform plug-in developers define preference pages for their plug-ins
+for use in the Workbench Preferences Dialog. This article explains when to use a
+preference and some of the features the Eclipse Platform provides to support
+preferences.
+ <p><b>By Tod Creasey, OTI<br>
+ </b> August 15, 2002</p>
+ <p>Editor's note: <strong>This article contains outdated information.</strong>
+ This article was originally published in December 2001 and
+ described Eclipse release 1.0. This revision reflects the minor enhancements
+ made to UI preferences in Eclipse release 2.0.
+ A revision of this article is scheduled for development. For more information,
+ or to contribute, please see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=143727">bug 43727</a>. </p>
+</blockquote>
+<HR width="100%">
+
+<h2>Introduction</h2>
+<p>The Eclipse Platform has support for preferences that are
+persisted along with the workspace. This article will discuss what type of data
+should be stored as a preference and will show how to develop and register a
+user interface to allow the user to set these preferences as well as how to
+store them independent of the workbench by use of the import and export
+functions. It will also cover
+how to initialize and retrieve preferences for use by other other plug-ins that
+use your plug-in. This functionality will be shown using an example that
+searches files for bad words. We will set our preferences for this tool
+using two preference pages, one simple one to set a highlight color and one more
+complex one to set the list of words.
+</p>
+<h2>When to Use a Preference
+</h2>
+<p>A preference is data that is persisted between workspace sessions to allow
+the user to keep the state of a plug-in consistent between Eclipse sessions. As
+of 2.0 Eclipse offers two varieties of preference, UI preferences (the same as
+in 1.0) and Core Preferences. This article is concerned only with how to use the
+UI preference store. Typical UI preferences are
+default values for new instances, colors for editors and paths. Core preferences
+are used for values that are not part of the user interface.
+</p>
+<p>Preferences are not intended to reference any resource currently defined in
+the workspace and instead should be used for editors, views or other objects that
+perform operations on a resource. Data persisted on a resource instance is better suited to be
+a property which will be discussed in a later article.
+</p>
+<p>A preference can be made available to any plug-in that has your plug-in as a
+prerequisite. The usual way to do that is to provide API on your plug-in that
+allows for access to the preferences you want to make available. The values of
+these preferences are stored in the .metadata/.plugins directory of the
+workspace on a per plug-in basis. We demonstrate
+how to do this below.
+</p>
+<h2>The Preference Store and the Plug-in</h2>
+<p>Every plug-in has it's own preference store provided by the workspace. For
+ this example we will define a plug-in and use its preference store for our preferences.
+ As we are going to use this plug-in within the UI we define it as a subclass
+ of AbstractUIPlugin. Our constructor (see <img border="0" src="images/tag_2.gif" width="24" height="13">)
+ will create a singleton to allow easy access to the plug-in instance in the
+ workbench. We also implement the method initializeDefaultPreferences() to set
+ up our default values for our two preferences. We are defining a preference
+ for the bad words and a preference for the color of the highlight. Each preference
+ value is looked up using a given key. In the code below the keys we are using
+ are defined by the constants in <img src="images/tag_1.gif" width="24" height="13">.
+</p>
+<p>The default value should be set for all preferences to be sure that there is
+ a value to use at all times. A default value also ensures that the UI can provide
+ a way to reset a preference value back to a reasonable initial setting via the
+ Restore Defaults button.The default value of the preference should be initialized
+ in the plug-in so that it is set before any of the UI is created. </p>
+<p> IAbstractWorkbenchPlugin defines a method called initializeDefaultPreferences(IPreferenceStore)
+ which is called when the preference store is created the first time. In this
+ method (see <img border="0" src="images/tag_3.gif" width="24" height="13">) you should
+ set the default value for all values that you will be using the preference store
+ for. We set a default color using the helper methods in the PreferenceConverter
+ which allows the plug-in developer to set and get values for a preference of
+ commonly stored types like FontData, Point etc. This API is provided because
+ preferences are stored and retrieved as Strings in a human readable format in
+ order to leverage the java properties mechanism. Our more complex bad
+ words preference is initialized using a set of preselected bad words defined
+ in the format we are going to store them in as we do not have API on the PreferenceConvertor
+ to store or retreive arrays of Strings.</p>
+<pre>Color color= Display.getDefault().getSystemColor(SWT.COLOR_BLUE);
+PreferenceConverter.setDefault(store, HIGHLIGHT_PREFERENCE, color.getRGB());</pre>
+<pre>public class BadWordCheckerPlugin extends AbstractUIPlugin {
+ //The shared instance.
+ private static BadWordCheckerPlugin plugin;
+
+ //The identifiers for the preferences
+<img border="0" src="images/tag_1.gif" width="24" height="13"> public static final String BAD_WORDS_PREFERENCE = "badwords";
+ public static final String HIGHLIGHT_PREFERENCE = "highlight";
+
+ //The default values for the preferences
+ public static final String DEFAULT_BAD_WORDS = "bug;bogus;hack;";
+ public static final int DEFAULT_HIGHLIGHT = SWT.COLOR_BLUE;
+
+ public BadWordCheckerPlugin(IPluginDescriptor descriptor) {
+ super(descriptor);
+<img border="0" src="images/tag_2.gif" width="24" height="13"> plugin = this;
+ }
+
+ public static BadWordCheckerPlugin getDefault() {
+ return plugin;
+ }
+
+ /**
+ * Initializes a preference store with default preference values
+ * for this plug-in.
+ */
+ protected void initializeDefaultPreferences(IPreferenceStore store) {
+<img border="0" src="images/tag_3.gif" width="24" height="13"> store.setDefault(BAD_WORDS_PREFERENCE, DEFAULT_BAD_WORDS);
+ Color color= Display.getDefault().getSystemColor(DEFAULT_HIGHLIGHT);
+ PreferenceConverter.setDefault(store, HIGHLIGHT_PREFERENCE, color.getRGB());
+
+ }
+}</pre>
+<h2>Defining Preference Pages in plugin.xml</h2>
+<p>Now that we have defined the preference we want to provide a way for the user
+to set the preference value. Preference pages for the workbench can be found in
+the preferences dialog. The preferences dialog is accessible via the Window->Preferences
+menu group. Plug-in developers should add their preference pages to this dialog using the plugin.xml of their
+plug-in in order to maintain a consistent look and feel with other Eclipse
+plug-ins. The definition of the preference pages within plugin.xml looks like
+this:
+</p>
+<pre><extension point="org.eclipse.ui.preferencePages">
+ <page id="BadWordsPreferencePage"
+<img border="0" src="images/tag_1.gif" width="24" height="13"> name="Bad Words"
+<img border="0" src="images/tag_2.gif" width="24" height="13"> class="org.eclipse.ui.articles.badwordchecker.BadWordsPreferencePage">
+ </page>
+
+ <page id="BadWordsColorPreferencePage"
+ name="Colors"
+ class="org.eclipse.ui.articles.badwordchecker.BadWordsColorPreferencePage"
+<img border="0" src="images/tag_3.gif" width="24" height="13"> category="BadWordsPreferencePage">
+ </page>
+</extension></pre>
+<p>The definition above sets the name (<img border="0" src="images/tag_1.gif" width="24" height="13">)
+of the preference page for use in the list
+of pages in the preference dialog and also specifies the class(<img border="0" src="images/tag_2.gif" width="24" height="13">) to be
+instantiated for creating the preference page. This class must conform to
+IWorkbenchPreferencePage.</p>
+<p>In the second definition there is a category (<img border="0" src="images/tag_3.gif" width="24" height="13">)
+tag which is used to make one
+page the child of another in the list in the preferences dialog. Preference
+pages can be stored as the children of other pages. This is useful
+for keeping a series of pages together that are related to each other and also
+reduces the clutter in the workbench preferences page. A page can be made the
+child of another page by setting the id of the parent page as the value of the
+category field in the plugin.xml. A page with no parent is displayed as a child
+with no root.</p>
+<p>With the above declarations in our plugin.xml the list of preference pages
+shown in the preference dialog will look like Figure 1.</p>
+<p align="center"><img border="0" src="images/tree.gif" width="187" height="291"></p>
+<p align="center"><b>Figure 1</b>:Preference dialog showing Bad Words and Colors
+ preferences</p>
+<h2>The Color Preference Page
+</h2>
+<p>The color preference page is an example of a simple page that uses a single
+JFace field editor to manage its values. Initially a preference page class is
+defined. All
+classes used in the preference dialog must conform to IWorkbenchPreferencePage.
+Eclipse includes the class PreferencePage which implements most of the necessary API
+for a preference page. PreferenceDialog will save the preference store whenever
+OK is pressed - if you wish to use PreferencePages in places other than the
+default dialog in Window->Preferences be sure that you save the preference
+store after changes have been applied.</p>
+<p>The class definition for our preference page is:</p>
+<pre>class BadWordsColorPreferencePage
+ extends PreferencePage
+ implements IWorkbenchPreferencePage</pre>
+<p>Once we have defined the page we want to initialize it. IWorkbenchPreferencePage
+specifies a message init(IWorkbench) for this purpose. We will not use the Workbench
+argument for this page. Our implementation only sets
+the preference store for the page.</p>
+<pre>public void init(IWorkbench workbench) {
+ //Initialize the preference store we wish to use
+ setPreferenceStore(BadWordCheckerPlugin.getDefault().getPreferenceStore());
+}</pre>
+<p>The other required method we must implement is createContents().
+All we are going to do is use a ColorFieldEditor
+to set our preference. It is also suggested that performDefaults is
+implemented so that the current state can be reset to the defaults defined in
+the plug-in. We also need to implement performOK so that the settings defined by the user are
+stored in the preference store for our plug-in. Our
+implementation is simple as the ColorFieldEditor has the code to load defaults
+and store the results of an apply for a preference already defined and performOK
+and performDefaults can call the corresponding methods on ColorFieldEditor. See
+figure 2 for the Colors preference page.</p>
+<pre>protected void performDefaults() {
+ colorEditor.loadDefault();
+}
+/**
+ * Save the color preference to the preference store.
+ */
+public boolean performOk() {
+ colorEditor.store();
+ return super.performOk();
+}</pre>
+<p> </p>
+<p align="center"><img border="0" src="images/colorpreference.gif" width="606" height="532"></p>
+<p align="center"><b>Figure 2</b>: Preference dialog showing Colors preference
+page</p>
+<h2>The Bad Words Preference Page
+</h2>
+<p>We have seen how to do a simple preference page with just a color and categorize it.
+Now we will show how to use a complex object as a
+preference and still have it persisted by the preference store and editable in a
+preference page. For this example
+we are going to add a bad words preference which is an array of Strings.
+</p>
+<p>As the PreferenceConverter does not have API for conversion of arrays of
+Strings we will implement it ourselves in the BadWordCheckerPlugin.
+By implementing it in the plug-in we put the API for the use of the preference in
+a place visible to all objects that have access to this plug-in. Normally we
+would use the PreferenceConverter for conversion to and from the storage format.</p>
+<p>Methods for getting the default value of the
+preference and a getter and a setter are
+defined first - getBadWordsDefaultPreference (which returns an array of Strings),
+getBadWordsPreference (which also returns an array of Strings) and
+setBadWordsPreference which takes an array of Strings as its argument. The
+String array is stored in the preference store as a single string separated by semicolons. We choose
+semicolons as this character is only ever used as punctuation and will therefore never
+be part of a word we are searching for.</p>
+<pre>/**
+ * Return the bad words preference default.
+ */
+public String[] getDefaultBadWordsPreference(){
+ return convert(getPreferenceStore().getDefaultString(BAD_WORDS_PREFERENCE));
+}
+
+/**
+ * Returns the bad words preference.
+ */
+public String[] getBadWordsPreference() {
+ return convert(getPreferenceStore().getString(BAD_WORDS_PREFERENCE));
+}
+
+/**
+ * Converts PREFERENCE_DELIMITER delimited String to a String array.
+ */
+private String[] convert(String preferenceValue) {
+ StringTokenizer tokenizer =
+ new StringTokenizer(preferenceValue, PREFERENCE_DELIMITER);
+ int tokenCount = tokenizer.countTokens();
+ String[] elements = new String[tokenCount];
+ for (int i = 0; i < tokenCount; i++) {
+ elements[i] = tokenizer.nextToken();
+ }
+
+ return elements;
+}
+
+/**
+ * Sets the bad words preference.
+ */
+public void setBadWordsPreference(String[] elements) {
+ StringBuffer buffer = new StringBuffer();
+ for (int i = 0; i < elements.length; i++) {
+ buffer.append(elements[i]);
+ buffer.append(PREFERENCE_DELIMITER);
+ }
+ getPreferenceStore().setValue(BAD_WORDS_PREFERENCE, buffer.toString());
+}
+</pre>
+<p>There is no field editor defined in JFace
+for editing String arrays so we will define a list that shows the
+items with widgets to add and remove them. Our performOK method will send the
+current contents of the list to the setBadWordsPreference method and the
+performDefaults method will reset the list of strings to be the result of
+getDefaultBadWordsPreference. Both methods are defined in BadWordCheckerPlugin. As a List widget takes an array of Strings as its
+content we can use the results of these helper methods directly
+in conjunction with the methods we defined for the bad words preference in the
+plug-in. The performOK and performDefaults for this preference page use these
+methods to update the preference and reset the values in the list widget
+respectively. See Figure 3 for the Bad Words preference page.
+</p>
+<pre>/**
+ * Sets the contents of the nameEntry field to be the default
+ */
+protected void performDefaults() {
+ badWordList.setItems(BadWordCheckerPlugin.getDefault().getDefaultBadWordsPreference());
+}
+/**
+ * Saves the author name to the preference store.
+ */
+public boolean performOk() {
+ BadWordCheckerPlugin.getDefault().setBadWordsPreference(badWordList.getItems());
+ return super.performOk();
+}</pre>
+<p align="center"><img border="0" src="images/badwordpreference.gif" width="606" height="532">
+</p>
+<p align="center"><b>Figure 3</b>: Preference dialog showing Bad Words preference
+ page </p>
+<h2>Propagating Values With IPropertyChangeListener
+</h2>
+<p>Frequently a preference is
+used to set a value in another object or needs to be applied to an open editor
+or view. When this is required you can listen for these changes with an
+IPropertyChangeListener. IPropertyChangeListener is a class that is used to add a listener to an
+IPropertyStore so that the listener is informed whenever a change is made. Change
+notifications are issued whenever a preference is changed in the preference
+store with setValue(); this typically happens when the user hits OK or Apply in a
+preference dialog, or when a previously saved preference setting is imported.</p>
+<p>In the bad word checker example we have implemented a view that displays the
+bad words for a file highlighted in the selected Color (see attached code). This
+view has a IPropertyChangeListener defined on it that updates the display color
+when it changes (see <img border="0" src="images/tag_1.gif" width="24" height="13">).
+When the view is created it is added as an IPropertyChangeListener on the
+preference store in the init(IViewSite) method (see <img border="0" src="images/tag_2.gif" width="24" height="13">).
+We also remove it as a listener on the preference store when we dispose of it so
+that any further changes to the preference store do not try and refer to a
+disposed page (see <img border="0" src="images/tag_3.gif" width="24" height="13">).
+The init(IViewSite) method is defined on IViewPart and the dispose() method is
+defined on IWorkbenchPart.
+</p>
+<pre>
+<img border="0" src="images/tag_1.gif" width="24" height="13"> new IPropertyChangeListener() {
+ public void propertyChange(PropertyChangeEvent event) {
+ if (event.getProperty().equals(BadWordCheckerPlugin.HIGHLIGHT_PREFERENCE)) {
+ //Update the colors by clearing the current color,
+ //updating the view and then disposing the old color.
+ Color oldForeground = foreground;
+ foreground = null;
+ setBadWordHighlights(text.getText());
+ oldForeground.dispose();
+ }
+ if (event.getProperty().equals(BadWordCheckerPlugin.BAD_WORDS_PREFERENCE))
+ //Only update the text if only the words have changed
+ setBadWordHighlights(text.getText());
+ }
+};</pre>
+
+<pre>
+<img border="0" src="images/tag_2.gif" width="24" height="13"> public void init(IViewSite site) throws PartInitException {
+ super.init(site);
+ site.getPage().addSelectionListener(...);
+ BadWordCheckerPlugin
+ .getDefault()
+ .getPreferenceStore()
+ .addPropertyChangeListener(preferenceListener);}
+</pre>
+<pre>
+<img border="0" src="images/tag_3.gif" width="24" height="13"> public void dispose() {
+ getSite().getPage().removeSelectionListener(...);
+ BadWordCheckerPlugin
+ .getDefault()
+ .getPreferenceStore()
+ .removePropertyChangeListener(preferenceListener);
+ if (foreground != null)
+ foreground.dispose();
+ super.dispose();
+}
+</pre>
+
+<h2>Importing and Exporting Preference Settings
+</h2>
+<p>As of Eclipse 2.0 there is now a facility to import and export your preferences so
+that you can reload them when you get a new workspace. This can be done by use
+of the Import and Export buttons on the preferences dialog. The currently set
+preferences are stored in a .epf file that you specify when you export. Any
+preference that is still set to it's default value will not be saved in this
+file. When you import from a .epf file any preferences defined in that file will
+be set to the value stored. Preferences not stored in the .epf file are not
+affected.
+</p>
+<p>If your preferences just
+use the preference store for storing and retrieving values then there is no more
+work to do to when writing your preferences as they will be saved and restored
+as part of the import and export support for preference stores. Should you need
+to have extra functionality executed when preferences are imported you can use
+an IPropertyChangeListener
+</p>
+
+<h2>Conclusions
+</h2>
+<p>In this article we have demonstrated how to use the preferences store and
+preferences pages provided by Eclipse to allow a plug-in to maintain and update
+preferences between Eclipse sessions and to import and export them using the
+preference dialog. By use of the preference store in
+conjunction with the preferences dialog and provided field editors a plug-in
+developer can quickly put together a user interface for managing preferences. To
+find out more about the preferences that Eclipse provides see the Platform
+Plug-in Developers Guide in the Help Perspective. The help information is in the
+Programmers Guide Preferences and Properties section.
+</p>
+<p>The full implementation of the example in this article can be found in <a href="preferences.zip">preferences.zip</a>.
+</p>
+
+<p><small>Java and all Java-based trademarks and logos are trademarks or registered
+trademarks of Sun Microsystems, Inc. in the United States, other countries, or
+both.</small></p>
+
+</body>
+
+</html>
diff --git a/Article-Preferences/info.xml b/Article-Preferences/info.xml
new file mode 100644
index 0000000..a3bcc63
--- /dev/null
+++ b/Article-Preferences/info.xml
@@ -0,0 +1,3 @@
+<article>
+ <outdated/>
+</article>
\ No newline at end of file
diff --git a/Article-Preferences/preferences.htm b/Article-Preferences/preferences.htm
index 1763f8f..91f62b8 100644
--- a/Article-Preferences/preferences.htm
+++ b/Article-Preferences/preferences.htm
@@ -1,417 +1,9 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
-
<head>
-<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
-
-
-<title>Preferences and Properties in the Eclipse Workbench UI</title>
-<link rel="stylesheet" type="text/css" href="../default_style.css">
-</head>
-
-<body>
-<DIV align=right><FONT face="Times New Roman, Times, serif"
-size=2>Copyright © 2001,2002 Object Technology International, Inc.</FONT> </DIV>
-<TABLE border=0 cellPadding=2 cellSpacing=0 width="100%">
- <TBODY>
- <TR>
- <TD align=left bgColor=#0080c0 colSpan=2 vAlign=top><B><FONT
- face=Arial,Helvetica><FONT color=#ffffff> Eclipse Corner
- Article</FONT></FONT></B></TD></TR></TBODY></TABLE>
-<H1><img align=center
-src="images/Idea.jpg" width="120" height="86">
-<center>Preferences in the Eclipse Workbench UI</center></H1>
-<blockquote>
-<b>Summary</b><br>
-In the Eclipse Platform plug-in developers define preference pages for their plug-ins
-for use in the Workbench Preferences Dialog. This article explains when to use a
-preference and some of the features the Eclipse Platform provides to support
-preferences.
- <p><b>By Tod Creasey, OTI<br>
- </b> August 15, 2002</p>
- <p>Editor's note: <strong>This article contains outdated information.</strong>
- This article was originally published in December 2001 and
- described Eclipse release 1.0. This revision reflects the minor enhancements
- made to UI preferences in Eclipse release 2.0.
- A revision of this article is scheduled for development. For more information,
- or to contribute, please see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=143727">bug 43727</a>. </p>
-</blockquote>
-<HR width="100%">
-
-<h2>Introduction</h2>
-<p>The Eclipse Platform has support for preferences that are
-persisted along with the workspace. This article will discuss what type of data
-should be stored as a preference and will show how to develop and register a
-user interface to allow the user to set these preferences as well as how to
-store them independent of the workbench by use of the import and export
-functions. It will also cover
-how to initialize and retrieve preferences for use by other other plug-ins that
-use your plug-in. This functionality will be shown using an example that
-searches files for bad words. We will set our preferences for this tool
-using two preference pages, one simple one to set a highlight color and one more
-complex one to set the list of words.
-</p>
-<h2>When to Use a Preference
-</h2>
-<p>A preference is data that is persisted between workspace sessions to allow
-the user to keep the state of a plug-in consistent between Eclipse sessions. As
-of 2.0 Eclipse offers two varieties of preference, UI preferences (the same as
-in 1.0) and Core Preferences. This article is concerned only with how to use the
-UI preference store. Typical UI preferences are
-default values for new instances, colors for editors and paths. Core preferences
-are used for values that are not part of the user interface.
-</p>
-<p>Preferences are not intended to reference any resource currently defined in
-the workspace and instead should be used for editors, views or other objects that
-perform operations on a resource. Data persisted on a resource instance is better suited to be
-a property which will be discussed in a later article.
-</p>
-<p>A preference can be made available to any plug-in that has your plug-in as a
-prerequisite. The usual way to do that is to provide API on your plug-in that
-allows for access to the preferences you want to make available. The values of
-these preferences are stored in the .metadata/.plugins directory of the
-workspace on a per plug-in basis. We demonstrate
-how to do this below.
-</p>
-<h2>The Preference Store and the Plug-in</h2>
-<p>Every plug-in has it's own preference store provided by the workspace. For
- this example we will define a plug-in and use its preference store for our preferences.
- As we are going to use this plug-in within the UI we define it as a subclass
- of AbstractUIPlugin. Our constructor (see <img border="0" src="images/tag_2.gif" width="24" height="13">)
- will create a singleton to allow easy access to the plug-in instance in the
- workbench. We also implement the method initializeDefaultPreferences() to set
- up our default values for our two preferences. We are defining a preference
- for the bad words and a preference for the color of the highlight. Each preference
- value is looked up using a given key. In the code below the keys we are using
- are defined by the constants in <img src="images/tag_1.gif" width="24" height="13">.
-</p>
-<p>The default value should be set for all preferences to be sure that there is
- a value to use at all times. A default value also ensures that the UI can provide
- a way to reset a preference value back to a reasonable initial setting via the
- Restore Defaults button.The default value of the preference should be initialized
- in the plug-in so that it is set before any of the UI is created. </p>
-<p> IAbstractWorkbenchPlugin defines a method called initializeDefaultPreferences(IPreferenceStore)
- which is called when the preference store is created the first time. In this
- method (see <img border="0" src="images/tag_3.gif" width="24" height="13">) you should
- set the default value for all values that you will be using the preference store
- for. We set a default color using the helper methods in the PreferenceConverter
- which allows the plug-in developer to set and get values for a preference of
- commonly stored types like FontData, Point etc. This API is provided because
- preferences are stored and retrieved as Strings in a human readable format in
- order to leverage the java properties mechanism. Our more complex bad
- words preference is initialized using a set of preselected bad words defined
- in the format we are going to store them in as we do not have API on the PreferenceConvertor
- to store or retreive arrays of Strings.</p>
-<pre>Color color= Display.getDefault().getSystemColor(SWT.COLOR_BLUE);
-PreferenceConverter.setDefault(store, HIGHLIGHT_PREFERENCE, color.getRGB());</pre>
-<pre>public class BadWordCheckerPlugin extends AbstractUIPlugin {
- //The shared instance.
- private static BadWordCheckerPlugin plugin;
-
- //The identifiers for the preferences
-<img border="0" src="images/tag_1.gif" width="24" height="13"> public static final String BAD_WORDS_PREFERENCE = "badwords";
- public static final String HIGHLIGHT_PREFERENCE = "highlight";
-
- //The default values for the preferences
- public static final String DEFAULT_BAD_WORDS = "bug;bogus;hack;";
- public static final int DEFAULT_HIGHLIGHT = SWT.COLOR_BLUE;
-
- public BadWordCheckerPlugin(IPluginDescriptor descriptor) {
- super(descriptor);
-<img border="0" src="images/tag_2.gif" width="24" height="13"> plugin = this;
- }
-
- public static BadWordCheckerPlugin getDefault() {
- return plugin;
- }
-
- /**
- * Initializes a preference store with default preference values
- * for this plug-in.
- */
- protected void initializeDefaultPreferences(IPreferenceStore store) {
-<img border="0" src="images/tag_3.gif" width="24" height="13"> store.setDefault(BAD_WORDS_PREFERENCE, DEFAULT_BAD_WORDS);
- Color color= Display.getDefault().getSystemColor(DEFAULT_HIGHLIGHT);
- PreferenceConverter.setDefault(store, HIGHLIGHT_PREFERENCE, color.getRGB());
-
- }
-}</pre>
-<h2>Defining Preference Pages in plugin.xml</h2>
-<p>Now that we have defined the preference we want to provide a way for the user
-to set the preference value. Preference pages for the workbench can be found in
-the preferences dialog. The preferences dialog is accessible via the Window->Preferences
-menu group. Plug-in developers should add their preference pages to this dialog using the plugin.xml of their
-plug-in in order to maintain a consistent look and feel with other Eclipse
-plug-ins. The definition of the preference pages within plugin.xml looks like
-this:
-</p>
-<pre><extension point="org.eclipse.ui.preferencePages">
- <page id="BadWordsPreferencePage"
-<img border="0" src="images/tag_1.gif" width="24" height="13"> name="Bad Words"
-<img border="0" src="images/tag_2.gif" width="24" height="13"> class="org.eclipse.ui.articles.badwordchecker.BadWordsPreferencePage">
- </page>
-
- <page id="BadWordsColorPreferencePage"
- name="Colors"
- class="org.eclipse.ui.articles.badwordchecker.BadWordsColorPreferencePage"
-<img border="0" src="images/tag_3.gif" width="24" height="13"> category="BadWordsPreferencePage">
- </page>
-</extension></pre>
-<p>The definition above sets the name (<img border="0" src="images/tag_1.gif" width="24" height="13">)
-of the preference page for use in the list
-of pages in the preference dialog and also specifies the class(<img border="0" src="images/tag_2.gif" width="24" height="13">) to be
-instantiated for creating the preference page. This class must conform to
-IWorkbenchPreferencePage.</p>
-<p>In the second definition there is a category (<img border="0" src="images/tag_3.gif" width="24" height="13">)
-tag which is used to make one
-page the child of another in the list in the preferences dialog. Preference
-pages can be stored as the children of other pages. This is useful
-for keeping a series of pages together that are related to each other and also
-reduces the clutter in the workbench preferences page. A page can be made the
-child of another page by setting the id of the parent page as the value of the
-category field in the plugin.xml. A page with no parent is displayed as a child
-with no root.</p>
-<p>With the above declarations in our plugin.xml the list of preference pages
-shown in the preference dialog will look like Figure 1.</p>
-<p align="center"><img border="0" src="images/tree.gif" width="187" height="291"></p>
-<p align="center"><b>Figure 1</b>:Preference dialog showing Bad Words and Colors
- preferences</p>
-<h2>The Color Preference Page
-</h2>
-<p>The color preference page is an example of a simple page that uses a single
-JFace field editor to manage its values. Initially a preference page class is
-defined. All
-classes used in the preference dialog must conform to IWorkbenchPreferencePage.
-Eclipse includes the class PreferencePage which implements most of the necessary API
-for a preference page. PreferenceDialog will save the preference store whenever
-OK is pressed - if you wish to use PreferencePages in places other than the
-default dialog in Window->Preferences be sure that you save the preference
-store after changes have been applied.</p>
-<p>The class definition for our preference page is:</p>
-<pre>class BadWordsColorPreferencePage
- extends PreferencePage
- implements IWorkbenchPreferencePage</pre>
-<p>Once we have defined the page we want to initialize it. IWorkbenchPreferencePage
-specifies a message init(IWorkbench) for this purpose. We will not use the Workbench
-argument for this page. Our implementation only sets
-the preference store for the page.</p>
-<pre>public void init(IWorkbench workbench) {
- //Initialize the preference store we wish to use
- setPreferenceStore(BadWordCheckerPlugin.getDefault().getPreferenceStore());
-}</pre>
-<p>The other required method we must implement is createContents().
-All we are going to do is use a ColorFieldEditor
-to set our preference. It is also suggested that performDefaults is
-implemented so that the current state can be reset to the defaults defined in
-the plug-in. We also need to implement performOK so that the settings defined by the user are
-stored in the preference store for our plug-in. Our
-implementation is simple as the ColorFieldEditor has the code to load defaults
-and store the results of an apply for a preference already defined and performOK
-and performDefaults can call the corresponding methods on ColorFieldEditor. See
-figure 2 for the Colors preference page.</p>
-<pre>protected void performDefaults() {
- colorEditor.loadDefault();
-}
-/**
- * Save the color preference to the preference store.
- */
-public boolean performOk() {
- colorEditor.store();
- return super.performOk();
-}</pre>
-<p> </p>
-<p align="center"><img border="0" src="images/colorpreference.gif" width="606" height="532"></p>
-<p align="center"><b>Figure 2</b>: Preference dialog showing Colors preference
-page</p>
-<h2>The Bad Words Preference Page
-</h2>
-<p>We have seen how to do a simple preference page with just a color and categorize it.
-Now we will show how to use a complex object as a
-preference and still have it persisted by the preference store and editable in a
-preference page. For this example
-we are going to add a bad words preference which is an array of Strings.
-</p>
-<p>As the PreferenceConverter does not have API for conversion of arrays of
-Strings we will implement it ourselves in the BadWordCheckerPlugin.
-By implementing it in the plug-in we put the API for the use of the preference in
-a place visible to all objects that have access to this plug-in. Normally we
-would use the PreferenceConverter for conversion to and from the storage format.</p>
-<p>Methods for getting the default value of the
-preference and a getter and a setter are
-defined first - getBadWordsDefaultPreference (which returns an array of Strings),
-getBadWordsPreference (which also returns an array of Strings) and
-setBadWordsPreference which takes an array of Strings as its argument. The
-String array is stored in the preference store as a single string separated by semicolons. We choose
-semicolons as this character is only ever used as punctuation and will therefore never
-be part of a word we are searching for.</p>
-<pre>/**
- * Return the bad words preference default.
- */
-public String[] getDefaultBadWordsPreference(){
- return convert(getPreferenceStore().getDefaultString(BAD_WORDS_PREFERENCE));
-}
-
-/**
- * Returns the bad words preference.
- */
-public String[] getBadWordsPreference() {
- return convert(getPreferenceStore().getString(BAD_WORDS_PREFERENCE));
-}
-
-/**
- * Converts PREFERENCE_DELIMITER delimited String to a String array.
- */
-private String[] convert(String preferenceValue) {
- StringTokenizer tokenizer =
- new StringTokenizer(preferenceValue, PREFERENCE_DELIMITER);
- int tokenCount = tokenizer.countTokens();
- String[] elements = new String[tokenCount];
- for (int i = 0; i < tokenCount; i++) {
- elements[i] = tokenizer.nextToken();
- }
-
- return elements;
-}
-
-/**
- * Sets the bad words preference.
- */
-public void setBadWordsPreference(String[] elements) {
- StringBuffer buffer = new StringBuffer();
- for (int i = 0; i < elements.length; i++) {
- buffer.append(elements[i]);
- buffer.append(PREFERENCE_DELIMITER);
- }
- getPreferenceStore().setValue(BAD_WORDS_PREFERENCE, buffer.toString());
-}
-</pre>
-<p>There is no field editor defined in JFace
-for editing String arrays so we will define a list that shows the
-items with widgets to add and remove them. Our performOK method will send the
-current contents of the list to the setBadWordsPreference method and the
-performDefaults method will reset the list of strings to be the result of
-getDefaultBadWordsPreference. Both methods are defined in BadWordCheckerPlugin. As a List widget takes an array of Strings as its
-content we can use the results of these helper methods directly
-in conjunction with the methods we defined for the bad words preference in the
-plug-in. The performOK and performDefaults for this preference page use these
-methods to update the preference and reset the values in the list widget
-respectively. See Figure 3 for the Bad Words preference page.
-</p>
-<pre>/**
- * Sets the contents of the nameEntry field to be the default
- */
-protected void performDefaults() {
- badWordList.setItems(BadWordCheckerPlugin.getDefault().getDefaultBadWordsPreference());
-}
-/**
- * Saves the author name to the preference store.
- */
-public boolean performOk() {
- BadWordCheckerPlugin.getDefault().setBadWordsPreference(badWordList.getItems());
- return super.performOk();
-}</pre>
-<p align="center"><img border="0" src="images/badwordpreference.gif" width="606" height="532">
-</p>
-<p align="center"><b>Figure 3</b>: Preference dialog showing Bad Words preference
- page </p>
-<h2>Propagating Values With IPropertyChangeListener
-</h2>
-<p>Frequently a preference is
-used to set a value in another object or needs to be applied to an open editor
-or view. When this is required you can listen for these changes with an
-IPropertyChangeListener. IPropertyChangeListener is a class that is used to add a listener to an
-IPropertyStore so that the listener is informed whenever a change is made. Change
-notifications are issued whenever a preference is changed in the preference
-store with setValue(); this typically happens when the user hits OK or Apply in a
-preference dialog, or when a previously saved preference setting is imported.</p>
-<p>In the bad word checker example we have implemented a view that displays the
-bad words for a file highlighted in the selected Color (see attached code). This
-view has a IPropertyChangeListener defined on it that updates the display color
-when it changes (see <img border="0" src="images/tag_1.gif" width="24" height="13">).
-When the view is created it is added as an IPropertyChangeListener on the
-preference store in the init(IViewSite) method (see <img border="0" src="images/tag_2.gif" width="24" height="13">).
-We also remove it as a listener on the preference store when we dispose of it so
-that any further changes to the preference store do not try and refer to a
-disposed page (see <img border="0" src="images/tag_3.gif" width="24" height="13">).
-The init(IViewSite) method is defined on IViewPart and the dispose() method is
-defined on IWorkbenchPart.
-</p>
-<pre>
-<img border="0" src="images/tag_1.gif" width="24" height="13"> new IPropertyChangeListener() {
- public void propertyChange(PropertyChangeEvent event) {
- if (event.getProperty().equals(BadWordCheckerPlugin.HIGHLIGHT_PREFERENCE)) {
- //Update the colors by clearing the current color,
- //updating the view and then disposing the old color.
- Color oldForeground = foreground;
- foreground = null;
- setBadWordHighlights(text.getText());
- oldForeground.dispose();
- }
- if (event.getProperty().equals(BadWordCheckerPlugin.BAD_WORDS_PREFERENCE))
- //Only update the text if only the words have changed
- setBadWordHighlights(text.getText());
- }
-};</pre>
-
-<pre>
-<img border="0" src="images/tag_2.gif" width="24" height="13"> public void init(IViewSite site) throws PartInitException {
- super.init(site);
- site.getPage().addSelectionListener(...);
- BadWordCheckerPlugin
- .getDefault()
- .getPreferenceStore()
- .addPropertyChangeListener(preferenceListener);}
-</pre>
-<pre>
-<img border="0" src="images/tag_3.gif" width="24" height="13"> public void dispose() {
- getSite().getPage().removeSelectionListener(...);
- BadWordCheckerPlugin
- .getDefault()
- .getPreferenceStore()
- .removePropertyChangeListener(preferenceListener);
- if (foreground != null)
- foreground.dispose();
- super.dispose();
-}
-</pre>
-
-<h2>Importing and Exporting Preference Settings
-</h2>
-<p>As of Eclipse 2.0 there is now a facility to import and export your preferences so
-that you can reload them when you get a new workspace. This can be done by use
-of the Import and Export buttons on the preferences dialog. The currently set
-preferences are stored in a .epf file that you specify when you export. Any
-preference that is still set to it's default value will not be saved in this
-file. When you import from a .epf file any preferences defined in that file will
-be set to the value stored. Preferences not stored in the .epf file are not
-affected.
-</p>
-<p>If your preferences just
-use the preference store for storing and retrieving values then there is no more
-work to do to when writing your preferences as they will be saved and restored
-as part of the import and export support for preference stores. Should you need
-to have extra functionality executed when preferences are imported you can use
-an IPropertyChangeListener
-</p>
-
-<h2>Conclusions
-</h2>
-<p>In this article we have demonstrated how to use the preferences store and
-preferences pages provided by Eclipse to allow a plug-in to maintain and update
-preferences between Eclipse sessions and to import and export them using the
-preference dialog. By use of the preference store in
-conjunction with the preferences dialog and provided field editors a plug-in
-developer can quickly put together a user interface for managing preferences. To
-find out more about the preferences that Eclipse provides see the Platform
-Plug-in Developers Guide in the Help Perspective. The help information is in the
-Programmers Guide Preferences and Properties section.
-</p>
-<p>The full implementation of the example in this article can be found in <a href="preferences.zip">preferences.zip</a>.
-</p>
-
-<p><small>Java and all Java-based trademarks and logos are trademarks or registered
-trademarks of Sun Microsystems, Inc. in the United States, other countries, or
-both.</small></p>
-
-</body>
-
-</html>
+<title>Build and Test Automation for plug-ins and features</title>
+<meta http-equiv="REFRESH" content="0;url=../article.php?file=Article-PDE-Automation/article.html"></HEAD>
+<BODY>
+Redirecting...
+</BODY>
+</HTML>
\ No newline at end of file
