public abstract class FieldEditor extends Object
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
- booleansIntegerFieldEditor
- integersStringFieldEditor
- text stringsRadioGroupFieldEditor
- enumerationsColorFieldEditor
- RGB colorsFontFieldEditor
- fontsDirectoryFieldEditor
- directoriesFileFieldEditor
- filesPathEditor
- pathsModifier and Type | Field and Description |
---|---|
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. |
Modifier | Constructor and Description |
---|---|
protected |
FieldEditor()
Creates a new field editor.
|
protected |
FieldEditor(String name,
String labelText,
Composite parent)
Creates a new field editor.
|
Modifier and Type | Method and Description |
---|---|
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.
|
protected DialogPage |
getPage()
Return the DialogPage that the receiver is sending
updates to.
|
String |
getPreferenceName()
Returns the name of the preference this field editor operates on.
|
protected PreferencePage |
getPreferencePage()
Deprecated.
use #getPage()
|
IPreferenceStore |
getPreferenceStore()
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 |
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. |
protected void |
setButtonLayoutData(Button button)
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 |
setFocus()
Sets the focus to this field editor.
|
void |
setLabelText(String text)
Sets this field editor's label text.
|
void |
setPage(DialogPage dialogPage)
Set the page to be the receiver.
|
void |
setPreferenceName(String name)
Sets the name of the preference this field editor operates on.
|
void |
setPreferencePage(PreferencePage preferencePage)
Deprecated.
use #setPage(DialogPage)
|
void |
setPreferenceStore(IPreferenceStore store)
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 |
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.
|
public static final String IS_VALID
"field_editor_is_valid"
)
to signal a change in the validity of the value of this field editor.public static final String VALUE
"field_editor_value"
)
to signal a change in the value of this field editor.protected static final int HORIZONTAL_GAP
protected abstract void adjustForNumColumns(int numColumns)
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.
numColumns
- the number of columnsprotected void applyFont()
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.
protected void checkParent(Control control, Composite parent)
control
- the controlparent
- the parent controlprotected void clearErrorMessage()
protected void clearMessage()
protected int convertHorizontalDLUsToPixels(Control control, int dlus)
Clients may call this framework method, but should not override it.
control
- the control being sizeddlus
- the number of horizontal dialog unitsprotected int convertVerticalDLUsToPixels(Control control, int dlus)
Clients may call this framework method, but should not override it.
control
- the control being sizeddlus
- the number of vertical dialog unitsprotected void createControl(Composite parent)
parent
- the parent controlpublic void dispose()
protected abstract void doFillIntoGrid(Composite parent, int numColumns)
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.
parent
- the composite used as a parent for the basic controls;
the parent's layout must be a GridLayout
numColumns
- the number of columnsprotected abstract void doLoad()
Subclasses must implement this method to properly initialize the field editor.
protected abstract void doLoadDefault()
Subclasses must implement this method to properly initialize the field editor.
protected abstract void doStore()
Subclasses must implement this method to save the entered value into the preference store.
public void fillIntoGrid(Composite parent, int numColumns)
parent
- the composite used as a parent for the basic controls;
the parent's layout must be a GridLayout
numColumns
- the number of columnsprotected void fireStateChanged(String property, boolean oldValue, boolean newValue)
property
- the field editor property name,
such as VALUE
or IS_VALID
oldValue
- the old valuenewValue
- the new valueprotected void fireValueChanged(String property, Object oldValue, Object newValue)
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
public String getFieldEditorFontName()
protected Label getLabelControl()
null
if no label control has been createdpublic Label getLabelControl(Composite parent)
The label is created if it does not already exist
parent
- the parentpublic String getLabelText()
public abstract int getNumberOfControls()
public String getPreferenceName()
@Deprecated protected PreferencePage getPreferencePage()
null
if noneprotected DialogPage getPage()
null
if it
has not been set.public IPreferenceStore getPreferenceStore()
null
if nonesetPreferenceStore(org.eclipse.jface.preference.IPreferenceStore)
protected void init(String name, String text)
name
- the name of the preference this field editor works ontext
- the label text of the field editorpublic boolean isValid()
The default implementation of this framework method
returns true
. Subclasses wishing to perform
validation should override both this method and
refreshValidState
.
true
if the field value is valid,
and false
if invalidrefreshValidState()
public void load()
public void loadDefault()
public boolean presentsDefaultValue()
true
if the default value is presented,
and false
otherwiseprotected void refreshValidState()
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
.
isValid()
public void setFocus()
The default implementation of this framework method does nothing. Subclasses may reimplement.
public void setLabelText(String text)
text
- the label textpublic void setPreferenceName(String name)
The ability to change this allows the same field editor object to be reused for different preferences.
For example:
... editor.setPreferenceName("font"); editor.load();
name
- the name of the preference@Deprecated public void setPreferencePage(PreferencePage preferencePage)
preferencePage
- the preference page, or null
if nonepublic void setPage(DialogPage dialogPage)
dialogPage
- public void setPreferenceStore(IPreferenceStore store)
store
- the preference store, or null
if nonegetPreferenceStore()
protected void setPresentsDefaultValue(boolean booleanValue)
booleanValue
- true
if the default value is being presented,
and false
otherwisepublic void setPropertyChangeListener(IPropertyChangeListener listener)
Note that field editors can support only a single listener.
listener
- a property change listener, or null
to removeprotected void showErrorMessage(String msg)
msg
- the error messageprotected void showMessage(String msg)
msg
- the messagepublic void store()
protected void setButtonLayoutData(Button button)
button
- the button the data is being set on.public void setEnabled(boolean enabled, Composite parent)
enabled
- The enabled state.parent
- The parent of the controls in the group.
Used to create the controls if required.
Copyright (c) 2000, 2015 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.