09 - Eclipse Plugin Preference Pages Tutorial

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.

      Eclipse preference dialog

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.

      Selecting Preference Page

Click next button and provide values as shown in figure below and click finish.

        Eclipse Plugin Sample Preference Page.

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.

       Eclipse Plugin Property Manager Preferences.

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.

        Eclipse Ready to use Field Editors.

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. }

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. 


        Eclipse Directory Field Editor.

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.



     Eclipse Bollean Field Editor

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. 


     Eclipse Plugin Radio Field Editor

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.


      Eclipse String Fild Editor

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.

Like us on Facebook