org.eclipse.jface.preference
Class FieldEditor

java.lang.Object
  |
  +--org.eclipse.jface.preference.FieldEditor

Direct Known Subclasses:

BooleanFieldEditor, ColorFieldEditor, FontFieldEditor, ListEditor, RadioGroupFieldEditor, 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

protected static int	HORIZONTAL_GAP Gap between label and control.
static 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.
static String	VALUE Property name constant (value "field_editor_value") to signal a change in the value of this field editor.

Constructor Summary

protected	FieldEditor() Creates a new field editor.
protected	FieldEditor(String name, String labelText, Composite parent) Creates a new field editor.

Method Summary

protected abstract void	adjustForNumColumns(int numColumns) Adjusts the horizontal span of this field editor's basic controls
protected void	applyFont() 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	clearErrorMessage() Clears the error message from the message line.
protected void	clearMessage() Clears the normal message from the message line.
protected int	convertHorizontalDLUsToPixels(Control control, int dlus) Returns the number of pixels corresponding to the given number of horizontal dialog units.
protected int	convertVerticalDLUsToPixels(Control control, int dlus) Returns the number of pixels corresponding to the given number of vertical dialog units.
protected void	createControl(Composite parent) Creates this field editor's main control containing all of its basic controls.
void	dispose() 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	doLoad() Initializes this field editor with the preference value from the preference store.
protected abstract void	doLoadDefault() Initializes this field editor with the default preference value from the preference store.
protected abstract void	doStore() 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.
String	getFieldEditorFontName() Returns the symbolic font name used by this field editor.
protected Label	getLabelControl() Returns the label control.
Label	getLabelControl(Composite parent) Returns this field editor's label component.
String	getLabelText() Returns this field editor's label text.
abstract int	getNumberOfControls() Returns the number of basic controls this field editor consists of.
String	getPreferenceName() Returns the name of the preference this field editor operates on.
protected PreferencePage	getPreferencePage() Returns the preference page in which this field editor appears.
IPreferenceStore	getPreferenceStore() Returns the preference store used by this field editor.
protected void	init(String name, String labelText) Initialize the field editor with the given preference name and label.
boolean	isValid() Returns whether this field editor contains a valid value.
void	load() Initializes this field editor with the preference value from the preference store.
void	loadDefault() Initializes this field editor with the default preference value from the preference store.
boolean	presentsDefaultValue() Returns whether this field editor currently presents the default value for its preference.
protected void	refreshValidState() Refreshes this field editor's valid state after a value change and fires an IS_VALID property change event if warranted.
void	setFocus() Sets the focus to this field editor.
void	setLabelText(String text) Sets this field editor's label text.
void	setPreferenceName(String name) Sets the name of the preference this field editor operates on.
void	setPreferencePage(PreferencePage preferencePage) Sets the preference page in which this field editor appears.
void	setPreferenceStore(IPreferenceStore store) Sets the preference store used by this field editor.
protected void	setPresentsDefaultValue(boolean b) Sets whether this field editor is presenting the default value.
void	setPropertyChangeListener(IPropertyChangeListener listener) Sets or removes the property change listener for this field editor.
protected void	showErrorMessage(String msg) Shows the given error message in the page for this field editor if it has one.
protected void	showMessage(String msg) Shows the given message in the page for this field editor if it has one.
void	store() 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 Detail

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:

Constant Field Values

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:

Constant Field Values

HORIZONTAL_GAP

protected static final int HORIZONTAL_GAP

Gap between label and control.

See Also:

Constant Field Values

Constructor Detail

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 Detail

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.

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

protected PreferencePage getPreferencePage()

Returns the preference page in which this field editor appears.

getPreferenceStore

public IPreferenceStore getPreferenceStore()

Returns the preference store used by this field editor.

Returns:

the preference store, or null if none

See Also:

setPreferenceStore(org.eclipse.jface.preference.IPreferenceStore)

init

protected void init(String name,
                    String labelText)

Initialize the field editor with the given preference name and label.

Parameters:

name - the name of the preference this field editor works on

labelText - 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:

refreshValidState()

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:

isValid()

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

public void setPreferencePage(PreferencePage preferencePage)

Sets the preference page in which this field editor appears.

Parameters:

preferencePage - the preference page, or null if none

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:

getPreferenceStore()

setPresentsDefaultValue

protected void setPresentsDefaultValue(boolean b)

Sets whether this field editor is presenting the default value.

Returns:

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.