Preference Pages
As an eclipse user you must have used preferences on many occasions. A Preference is a data which is persisted between workspace sessions.
Preferences are used in Eclipse to take preferences from user on the fly rather than hard cording them in plug-in itself. In order to view preferences go to window > preferences. Following figure show how preferences dialog look like.
In this chapter we will create a new preference page which will take Folder name preference from user. This folder name will be used in Properties view instead of hard coding “Workspace Property Files”.
Property File Manager Preference Page
Eclipse provide a wizard for creating preference pages. Open plugin.xml. Navigate to the Extensions page followed by clicking "Add" button then click on org.eclipse.ui.preferencePages. Now select Preference Page in list of available templates as shown below.
Click next button and provide values as shown in figure below and click finish.
After you click finish, open up com.myplugin.rmp.preferences.PropertyManagerPreferencePage class to see the default implementation. We will discuss default implementation in sections to follow. At this time we will launch new runtime workbench to see how Property Manager Preference page looks like. Once you launch new Runtime workbench, open preference dialog (Window > preferences) and you will see something as shown in figure below.
Note about FieldEditor and FieldEditorPreferencePage
Field editors are basically used to make UI of a preference page. A field editor can be thought of as an item which is used to show the user with the value of a preference. FieldEditor is mostly used together with a FieldEditorPreferencePage, Eclipse provides many ready-to-use field editors as shown in figure below.
FieldEditorPreferencePage is a special abstract preference page to host field editors. Our preference page extends FieldEditorPreferencePage, which, along with the various editor classes helps in capturing preferences. Following figure shows complete hierarchy of FieldEditorPreferencePage. Please refer to Eclipse API Specification to know about methods available in this class.
Reviewing the generated code
Armed with the knowledge of field editors and FieldEditorPreferencePage we are now ready to review the generated code. Open com.myplugin.rmp.preferences.PropertyManagerPreferencePage class. Notice that the default implementation (generated by wizard) extends FieldEditorPreferencePage and implements IWorkbenchPreferencePage interface.
1. public class PropertyManagerPreferencePage
2. extends FieldEditorPreferencePage
3. implements IWorkbenchPreferencePage {
4. public PropertyManagerPreferencePage() {
5. super(GRID);
6. setPreferenceStore(RmpPlugin.getDefault().getPreferenceStore());
7. setDescription("A demonstration of a preference page implementation");
8. }
9. public void createFieldEditors() {
10. addField(new DirectoryFieldEditor(PreferenceConstants.P_PATH,
11. "&Directory preference:", getFieldEditorParent()));
12. addField(
13. new BooleanFieldEditor(
14. PreferenceConstants.P_BOOLEAN,
15. "&An example of a boolean preference",
16. getFieldEditorParent()));
17. addField(new RadioGroupFieldEditor(
18. PreferenceConstants.P_CHOICE,
19. "An example of a multiple-choice preference",
20. 1,
21. new String[][] { { "&Choice 1", "choice1" }, {
22. "C&hoice 2", "choice2" }
23. }, getFieldEditorParent()));
24. addField(
25. new StringFieldEditor(PreferenceConstants.P_STRING,
"A &text preference:", getFieldEditorParent()));
26. }
27. public void init(IWorkbench workbench) {
28. }
29.}
Line 5: GRID is a layout constant defined in FieldEditorPreferencePage. Layout constant (value 1) indicates that the field editors' basic controls are put into a grid layout. Read SWT chapter for more on layouts.
Line 6: Sets the preference store for this preference page. We are using RmpPlugin.getDefault().getPreferenceStore() to retrieve the preference store for this Resource Manager Plugin. getDefault method returns the shared instance of plug-in. every plug-in has its own preference store. Preferences are stored in a <runtimeworkspace>\.metadata\.plugins\<pluginid>\pref_store.ini file.
Line 7: Set Description method is used to set the description title on the top of preference window.
Line 9 -26: createFieldEditors method is used to create GUI of the preference page. In this method we are creating four field editors (Directory, Boolean, Radio and String). AddField method is used to add the filed editor to preference page.
DirectoryFieldEditor
This editor is used to create a directory filed with in the preference page. First argument to constructor is the name of this field. This name is defined as a constant in com.myplugin.rmp.preferences.PreferenceConstants which was generated by preference page creation wizard. These names are also used to retrieve values of a specific preference from preference store. Last argument specifies the parent of the field editor's control. We are using getFieldEditorParent() defined in FieldEditorPreferencePage to retrieve the parent control.
BooleanFieldEditor
This editor is used to create a Boolean field. It creates a checkbox in the preference page. Arguments are same as described in directory filed editor.
RadioFieldEditor
This editor is used to create a radio button field. Third argument is the numColumns - the number of columns for the radio button presentation.
In our case it is one. Next argument is the labelAndValues list of radio button [label, value] entries. The value is returned when the radio button is selected.
StringFieldEditor
This editor is used to create a Text box which takes a String as input. Arguments are same as described in DirectoryFieldEditor.
Lines 27 – 28: We have not used this method. However, it can be used to Initialize this preference page for the given workbench.