Present by Wu Kun-Tse Simplifying Preference Pages with Field Editors

Outline Introduction When to use field editors (and when not to) Types of field editors How to use field editors Writing your own field editors Conclusion

Introduction A field editor is an object that presents the user with the value of a preference from a preference store. It implements the loading, storing, and validating of its associated value. Instance of FieldEditor are most often used in conjunction with a FieldEditorPreferencePage provides automatic validation handling and displays messages received from its field editors. We will discuss when field editors are most (and least) effective and briefly describe the available types of field editors.

When to use field editors (and when not to) Most of the field editor types supplied by JFace were created to handle simple preference types. Therefore, the simpler your preference page, the more useful field editors will be to you. If your preference page contains one or more complex widgets such as a List or Tree, a regular preference page can be a better solution. As a rule of thumb, use field editors whenever possible, but only use a FieldEditorPreferencePage if all the preference types on a page are supported by field editors or you are willing to write new field editors to support them.

Types of field editors JFace provides nine concrete subclasses of FieldEditor. Each corresponds to a common widget grouping used to present a preference. BooleanFieldEditor – This field editor takes the form of a checkbox with a label. It is used for presenting boolean preferences. IntegerFieldEditor – This field editor takes the form of a label and a text field. It is intended for presenting integers. StringFieldEditor – This field editor is a more general- purpose field editor with simpler validation rules. Normally, any string is valid.

Types of field editors (cont.) RadioGroupFieldEditor – This field editor takes the form of a group label and a set of radio buttons, each with a label of its own. It is used to present a set of mutually exclusive choices. ColorFieldEditor – This field editor is used to present color preference. ColorDialog allows the user to choose another color. FontFieldEditor – This field editor is used to select font preference. FontDialog allows the user to choose a new font, change the font’s style, and change it’s size.

Types of field editors (cont.) DirectoryFieldEditor – This field editor is used to display a directory path in the file system. Clicking on “Browse..” button allows the user to browse the file system and choose a new directory. FileFieldEditor – This field editor is similar to a DirectoryFieldEditor, but it allows the user to select a file instead of a directory. PathFieldEditor – This field editor is the most complex concrete field editor supplied by JFace. It consists of a title label, a list of directory paths, and a button bank to the left of the list with four buttons: “New…”, “Remove”, “Up”, “Down”.

Types of field editors (cont.)

How to use field editors This section will describe two example preference pages which make use of field editors. The two pages store the preferences for a simple HTML editor. The editor has the ability to auto-format HTML, display text in different colors based on context, open a web browser for visually checking HTML files, and perform some minimal error checking. HTMLEditorPlugin.java HTMLPreferencePage.java ErrorPreferencePage.java (ErrorPreferencePage2.java)

Using field editors with a FieldEditorPreferencePage The main preference page for the HTML editor is a subclass of FieldEditorPreferencePage, since all of the preferences on the page are of types supported by field editors. public class HTMLPreferencePage extends FieldEditorPreferencePage implements IWorkbenchPreferencePage { public HTMLPreferencePage() { … } protected void createFieldEditors() { … } public void init(IWorkbench workbench) {} }

HTMLPreferencePage() The constructors for FieldEditorPreferencePage each take as an argument an int representing the layout style of the page. The constant FieldEditorPreferencePage.GRID indicates that the controls of the field editors will be place into a single grid layout. The alternative constant is FieldEditorPreferencePage.FLAT, which indicates that each field editor is handled separately. A subclass of FieldEditorPreferencePage must instantiate and set a preference store for the preference page.

createFieldEditors() In this method, we instantiate all of the field editors on the page, and then add them to the page by calling FieldEditorPreferencePage.addField(FieldEditor). If field editors are instantiated but not added to the preference page, their values will not be saved in the preference store, and will therefore have no effect. A separate call is made to getFieldEditorParent() for each field editor. According to the method’s documentation, a new parent may be created each time the method is called. Caching the value disobeys the method’s contract.

Using field editors with a regular PreferencePage The HTML editor has a secondary page for controlling its error detecting facilities. The are two options: “Don’t show errors” and “Show error if a closing tag is missing”. RadioGroupFieldEditor is suited for this preference. The page also contains a list (a list of HTML tags for which a closing tag is not required), for which there is no suitable field editor, so we will subclass PreferencePage rather than FieldEditorPreferencePage.

Using field editors with a regular PreferencePage In addition to creating the preference store and instantiating field editors, we must write code to load preferences, store preferences, and restore defaults. When using field editors with a regular preference page, you should instantiate them in the createContents(Composite) method. Since we are using a regular preference page, we must also override performOK() and performDefaults(). Subclassing PreferencePage instead of FieldEditorPreferencePage requires more coding, but it allows you to mix field editor with other controls necessary to display all the preference.

Writing your own field editors If none of the concrete FieldEditor subclasses provided by JFace are suitable for your needs, you can always write your own type of field editor. In addition to the concrete subclasses already discussed before, there are two abstract field editors which may be useful: StringButtonFieldEditor – This field editor can be subclassed to produce field editors that consist of a label, a text field, and a button that performs some action. Both DirectoryFieldEditor and FileFieldEditor are subclasses of this class.

Writing your own field editors (cont.) ListEditor – This field editor can be subclassed to produce field editors that consist of a list of items and a button bank (“Add” and “Remove” buttons for adding and removing values, and “Up” and “Down” buttons to adjust the order of elements in the list). If you need a field editor just slightly different from an existing field editor subtype, you can subclass that type. If the field editor you need is not very similar to the subclasses provided by JFace, just subclass FieldEditor.

AddRemoveListFieldEditor For example, we can implement a field editor to replace the list, buttons, and text field in ErrorPreferencePage. When subclassing FieldEditor, there are six abstract methods that must be implemented. doLoad(), doLoadDefault(), doStore() – These are the methods which translate a preference in a preference store. getNumberOfControls() – just returns the highest number of controls that appear on one line in the field editor’s parent composite. adjustForNumColumns(int numColumns) – must ensure that the field editor is displayed correctly if the number of columns in the parent Composite changes after this field editor has been laid out. doFillIntoGrid(Composite parent, int numColumns) – initially lays out the field editor in the given parent Composite.

ErrorPreferencePage2 Now that we have a field editor that stores a list of string and allows the user to add items and remove them, the implementation of our error preference page becomes trivial. ErrorPreferencePage2 extends FieldEditorPreferencePage instead of PreferencePage and uses AddRemoveListFieldEditor to re-implement ErrorPreferencePage.

Conclusion This article has familiarized you with the different types of field editors and demonstrated their use. It has explained how field editors work so you can safely write your own. We encourage the use of field editors, and hope the knowledge provided by this article will help you easily implement cleaner preference pages for your plugins.

Reference From: Editors/field_editors.htmlhttp:// Editors/field_editors.html Source Code: field_editors.zipfield_editors.zip