Class FieldEditor

java.lang.Object
org.eclipse.jface.preference.FieldEditor
Direct Known Subclasses:
AbstractEncodingFieldEditor, BooleanFieldEditor, ColorFieldEditor, ComboFieldEditor, FontFieldEditor, ListEditor, RadioGroupFieldEditor, ScaleFieldEditor, StringFieldEditor

public abstract class FieldEditor extends Object
Abstract base class for all field editors.

A field editor presents the value of a preference to the end user. The value is loaded from a preference store; if modified by the end user, the value is validated and eventually stored back to the preference store. A field editor reports an event when the value, or the validity of the value, changes.

Field editors should be used in conjunction with a field editor preference page (FieldEditorPreferencePage) which coordinates everything and provides the message line which display messages emanating from the editor.

This package contains ready-to-use field editors for various types of preferences:

  • BooleanFieldEditor - booleans
  • IntegerFieldEditor - integers
  • StringFieldEditor - text strings
  • RadioGroupFieldEditor - enumerations
  • ColorFieldEditor - RGB colors
  • FontFieldEditor - fonts
  • DirectoryFieldEditor - directories
  • FileFieldEditor - files
  • PathEditor - paths
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected static final int
    Gap between label and control.
    static final String
    Property name constant (value "field_editor_is_valid") to signal a change in the validity of the value of this field editor.
    static final String
    Property name constant (value "field_editor_value") to signal a change in the value of this field editor.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Creates a new field editor.
    protected
    FieldEditor(String name, String labelText, Composite parent)
    Creates a new field editor.
  • Method Summary

    Modifier and Type
    Method
    Description
    protected abstract void
    adjustForNumColumns(int numColumns)
    Adjusts the horizontal span of this field editor's basic controls.
    protected void
    Applies a font.
    protected void
    checkParent(Control control, Composite parent)
    Checks if the given parent is the current parent of the supplied control; throws an (unchecked) exception if they are not correctly related.
    protected void
    Clears the error message from the message line.
    protected void
    Clears the normal message from the message line.
    protected int
    Returns the number of pixels corresponding to the given number of horizontal dialog units.
    protected int
    Returns the number of pixels corresponding to the given number of vertical dialog units.
    protected void
    Creates this field editor's main control containing all of its basic controls.
    void
    Disposes the SWT resources used by this field editor.
    protected abstract void
    doFillIntoGrid(Composite parent, int numColumns)
    Fills this field editor's basic controls into the given parent.
    protected abstract void
    Initializes this field editor with the preference value from the preference store.
    protected abstract void
    Initializes this field editor with the default preference value from the preference store.
    protected abstract void
    Stores the preference value from this field editor into the preference store.
    void
    fillIntoGrid(Composite parent, int numColumns)
    Fills this field editor's basic controls into the given parent.
    protected void
    fireStateChanged(String property, boolean oldValue, boolean newValue)
    Informs this field editor's listener, if it has one, about a change to one of this field editor's boolean-valued properties.
    protected void
    fireValueChanged(String property, Object oldValue, Object newValue)
    Informs this field editor's listener, if it has one, about a change to one of this field editor's properties.
    Returns the symbolic font name used by this field editor.
    protected Label
    Returns the label control.
    Returns this field editor's label component.
    Returns this field editor's label text.
    abstract int
    Returns the number of basic controls this field editor consists of.
    protected DialogPage
    Return the DialogPage that the receiver is sending updates to.
    Returns the name of the preference this field editor operates on.
    protected PreferencePage
    Deprecated.
    use #getPage()
    Returns the preference store used by this field editor.
    protected void
    init(String name, String text)
    Initialize the field editor with the given preference name and label.
    boolean
    Returns whether this field editor contains a valid value.
    void
    Initializes this field editor with the preference value from the preference store.
    void
    Initializes this field editor with the default preference value from the preference store.
    boolean
    Returns whether this field editor currently presents the default value for its preference.
    protected void
    Refreshes this field editor's valid state after a value change and fires an IS_VALID property change event if warranted.
    protected void
    Set the GridData on button to be one that is spaced for the current font.
    void
    setEnabled(boolean enabled, Composite parent)
    Set whether or not the controls in the field editor are enabled.
    void
    Sets the focus to this field editor.
    void
    Sets this field editor's label text.
    void
    setPage(DialogPage dialogPage)
    Set the page to be the receiver.
    void
    Sets the name of the preference this field editor operates on.
    void
    Deprecated.
    use #setPage(DialogPage)
    void
    Sets the preference store used by this field editor.
    protected void
    setPresentsDefaultValue(boolean booleanValue)
    Sets whether this field editor is presenting the default value.
    void
    Sets or removes the property change listener for this field editor.
    protected void
    Shows the given error message in the page for this field editor if it has one.
    protected void
    Shows the given message in the page for this field editor if it has one.
    void
    Stores this field editor's value back into the preference store.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • IS_VALID

      public static final String IS_VALID
      Property name constant (value "field_editor_is_valid") to signal a change in the validity of the value of this field editor.
      See Also:
    • VALUE

      public static final String VALUE
      Property name constant (value "field_editor_value") to signal a change in the value of this field editor.
      See Also:
    • HORIZONTAL_GAP

      protected static final int HORIZONTAL_GAP
      Gap between label and control.
      See Also:
  • Constructor Details

    • FieldEditor

      protected FieldEditor()
      Creates a new field editor.
    • FieldEditor

      protected FieldEditor(String name, String labelText, Composite parent)
      Creates a new field editor.
      Parameters:
      name - the name of the preference this field editor works on
      labelText - the label text of the field editor
      parent - the parent of the field editor's control
  • Method Details

    • adjustForNumColumns

      protected abstract void adjustForNumColumns(int numColumns)
      Adjusts the horizontal span of this field editor's basic controls.

      Subclasses must implement this method to adjust the horizontal span of controls so they appear correct in the given number of columns.

      The number of columns will always be equal to or greater than the value returned by this editor's getNumberOfControls method.

      Parameters:
      numColumns - the number of columns
    • applyFont

      protected void applyFont()
      Applies a font.

      The default implementation of this framework method does nothing. Subclasses should override this method if they want to change the font of the SWT control to a value different than the standard dialog font.

    • checkParent

      protected void checkParent(Control control, Composite parent)
      Checks if the given parent is the current parent of the supplied control; throws an (unchecked) exception if they are not correctly related.
      Parameters:
      control - the control
      parent - the parent control
    • clearErrorMessage

      protected void clearErrorMessage()
      Clears the error message from the message line.
    • clearMessage

      protected void clearMessage()
      Clears the normal message from the message line.
    • convertHorizontalDLUsToPixels

      protected int convertHorizontalDLUsToPixels(Control control, int dlus)
      Returns the number of pixels corresponding to the given number of horizontal dialog units.

      Clients may call this framework method, but should not override it.

      Parameters:
      control - the control being sized
      dlus - the number of horizontal dialog units
      Returns:
      the number of pixels
    • convertVerticalDLUsToPixels

      protected int convertVerticalDLUsToPixels(Control control, int dlus)
      Returns the number of pixels corresponding to the given number of vertical dialog units.

      Clients may call this framework method, but should not override it.

      Parameters:
      control - the control being sized
      dlus - the number of vertical dialog units
      Returns:
      the number of pixels
    • createControl

      protected void createControl(Composite parent)
      Creates this field editor's main control containing all of its basic controls.
      Parameters:
      parent - the parent control
    • dispose

      public void dispose()
      Disposes the SWT resources used by this field editor.
    • doFillIntoGrid

      protected abstract void doFillIntoGrid(Composite parent, int numColumns)
      Fills this field editor's basic controls into the given parent.

      Subclasses must implement this method to create the controls for this field editor.

      Note this method may be called by the constructor, so it must not access fields on the receiver object because they will not be fully initialized.

      Parameters:
      parent - the composite used as a parent for the basic controls; the parent's layout must be a GridLayout
      numColumns - the number of columns
    • doLoad

      protected abstract void doLoad()
      Initializes this field editor with the preference value from the preference store.

      Subclasses must implement this method to properly initialize the field editor.

    • doLoadDefault

      protected abstract void doLoadDefault()
      Initializes this field editor with the default preference value from the preference store.

      Subclasses must implement this method to properly initialize the field editor.

    • doStore

      protected abstract void doStore()
      Stores the preference value from this field editor into the preference store.

      Subclasses must implement this method to save the entered value into the preference store.

    • fillIntoGrid

      public void fillIntoGrid(Composite parent, int numColumns)
      Fills this field editor's basic controls into the given parent.
      Parameters:
      parent - the composite used as a parent for the basic controls; the parent's layout must be a GridLayout
      numColumns - the number of columns
    • fireStateChanged

      protected void fireStateChanged(String property, boolean oldValue, boolean newValue)
      Informs this field editor's listener, if it has one, about a change to one of this field editor's boolean-valued properties. Does nothing if the old and new values are the same.
      Parameters:
      property - the field editor property name, such as VALUE or IS_VALID
      oldValue - the old value
      newValue - the new value
    • fireValueChanged

      protected void fireValueChanged(String property, Object oldValue, Object newValue)
      Informs this field editor's listener, if it has one, about a change to one of this field editor's properties.
      Parameters:
      property - the field editor property name, such as VALUE or IS_VALID
      oldValue - the old value object, or null
      newValue - the new value, or null
    • getFieldEditorFontName

      public String getFieldEditorFontName()
      Returns the symbolic font name used by this field editor.
      Returns:
      the symbolic font name
    • getLabelControl

      protected Label getLabelControl()
      Returns the label control.
      Returns:
      the label control, or null if no label control has been created
    • getLabelControl

      public Label getLabelControl(Composite parent)
      Returns this field editor's label component.

      The label is created if it does not already exist

      Parameters:
      parent - the parent
      Returns:
      the label control
    • getLabelText

      public String getLabelText()
      Returns this field editor's label text.
      Returns:
      the label text
    • getNumberOfControls

      public abstract int getNumberOfControls()
      Returns the number of basic controls this field editor consists of.
      Returns:
      the number of controls
    • getPreferenceName

      public String getPreferenceName()
      Returns the name of the preference this field editor operates on.
      Returns:
      the name of the preference
    • getPreferencePage

      @Deprecated protected PreferencePage getPreferencePage()
      Deprecated.
      use #getPage()
      Returns the preference page in which this field editor appears.
      Returns:
      the preference page, or null if none
    • getPage

      protected DialogPage getPage()
      Return the DialogPage that the receiver is sending updates to.
      Returns:
      DialogPage or null if it has not been set.
      Since:
      3.1
    • getPreferenceStore

      public IPreferenceStore getPreferenceStore()
      Returns the preference store used by this field editor.
      Returns:
      the preference store, or null if none
      See Also:
    • init

      protected void init(String name, String text)
      Initialize the field editor with the given preference name and label.
      Parameters:
      name - the name of the preference this field editor works on
      text - the label text of the field editor
    • isValid

      public boolean isValid()
      Returns whether this field editor contains a valid value.

      The default implementation of this framework method returns true. Subclasses wishing to perform validation should override both this method and refreshValidState.

      Returns:
      true if the field value is valid, and false if invalid
      See Also:
    • load

      public void load()
      Initializes this field editor with the preference value from the preference store.
    • loadDefault

      public void loadDefault()
      Initializes this field editor with the default preference value from the preference store.
    • presentsDefaultValue

      public boolean presentsDefaultValue()
      Returns whether this field editor currently presents the default value for its preference.
      Returns:
      true if the default value is presented, and false otherwise
    • refreshValidState

      protected void refreshValidState()
      Refreshes this field editor's valid state after a value change and fires an IS_VALID property change event if warranted.

      The default implementation of this framework method does nothing. Subclasses wishing to perform validation should override both this method and isValid.

      See Also:
    • setFocus

      public void setFocus()
      Sets the focus to this field editor.

      The default implementation of this framework method does nothing. Subclasses may reimplement.

    • setLabelText

      public void setLabelText(String text)
      Sets this field editor's label text. The label is typically presented to the left of the entry field.
      Parameters:
      text - the label text
    • setPreferenceName

      public void setPreferenceName(String name)
      Sets the name of the preference this field editor operates on.

      The ability to change this allows the same field editor object to be reused for different preferences.

      For example:

              ...
        editor.setPreferenceName("font");
              editor.load();
       
      Parameters:
      name - the name of the preference
    • setPreferencePage

      @Deprecated public void setPreferencePage(PreferencePage preferencePage)
      Deprecated.
      use #setPage(DialogPage)
      Sets the preference page in which this field editor appears.
      Parameters:
      preferencePage - the preference page, or null if none
    • setPage

      public void setPage(DialogPage dialogPage)
      Set the page to be the receiver.
      Parameters:
      dialogPage - the new receiver
      Since:
      3.1
    • setPreferenceStore

      public void setPreferenceStore(IPreferenceStore store)
      Sets the preference store used by this field editor.
      Parameters:
      store - the preference store, or null if none
      See Also:
    • setPresentsDefaultValue

      protected void setPresentsDefaultValue(boolean booleanValue)
      Sets whether this field editor is presenting the default value.
      Parameters:
      booleanValue - true if the default value is being presented, and false otherwise
    • setPropertyChangeListener

      public void setPropertyChangeListener(IPropertyChangeListener listener)
      Sets or removes the property change listener for this field editor.

      Note that field editors can support only a single listener.

      Parameters:
      listener - a property change listener, or null to remove
    • showErrorMessage

      protected void showErrorMessage(String msg)
      Shows the given error message in the page for this field editor if it has one.
      Parameters:
      msg - the error message
    • showMessage

      protected void showMessage(String msg)
      Shows the given message in the page for this field editor if it has one.
      Parameters:
      msg - the message
    • store

      public void store()
      Stores this field editor's value back into the preference store.
    • setButtonLayoutData

      protected void setButtonLayoutData(Button button)
      Set the GridData on button to be one that is spaced for the current font.
      Parameters:
      button - the button the data is being set on.
    • setEnabled

      public void setEnabled(boolean enabled, Composite parent)
      Set whether or not the controls in the field editor are enabled.
      Parameters:
      enabled - The enabled state.
      parent - The parent of the controls in the group. Used to create the controls if required.