Present by Wu Kun-Tse

1
Simplifying Preference Pages with Field Editors

• Present by Wu Kun-Tse

2
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

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

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

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

6
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 fonts
  style, and change its size.

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

8
Types of field editors (cont.)
9
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)

10
Using field editors with a FieldEditorPreferencePa
ge

• 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)
11
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.

12
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 methods
  documentation, a new parent may be created each
  time the method is called. Caching the value
  disobeys the methods contract.

13
Using field editors with a regular PreferencePage

• The HTML editor has a secondary page for
  controlling its error detecting facilities.
• The are two options Dont 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.

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

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

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

17
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 editors 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.

18
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 FieldEditorPreference
  Page instead of PreferencePage and uses
  AddRemoveListFieldEditor to re-implement
  ErrorPreferencePage.

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

20
Reference

• From http//www.eclipse.org/articles/Article-Fiel
  d-Editors/field_editors.html
• Source Code field_editors.zip