Class FieldEditor
- Direct Known Subclasses:
AbstractEncodingFieldEditor
,BooleanFieldEditor
,ColorFieldEditor
,ComboFieldEditor
,FontFieldEditor
,ListEditor
,RadioGroupFieldEditor
,ScaleFieldEditor
,StringFieldEditor
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
- paths
-
Field Summary
Modifier and TypeFieldDescriptionprotected 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
ModifierConstructorDescriptionprotected
Creates a new field editor.protected
FieldEditor
(String name, String labelText, Composite parent) Creates a new field editor. -
Method Summary
Modifier and TypeMethodDescriptionprotected 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
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
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.Returns the symbolic font name used by this field editor.protected Label
Returns the label control.getLabelControl
(Composite parent) 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
getPage()
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
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
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 anIS_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
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
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.
-
Field Details
-
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
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_GAPGap between label and control.- See Also:
-
-
Constructor Details
-
FieldEditor
protected FieldEditor()Creates a new field editor. -
FieldEditor
Creates a new field editor.- Parameters:
name
- the name of the preference this field editor works onlabelText
- the label text of the field editorparent
- 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
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 controlparent
- 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
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 sizeddlus
- the number of horizontal dialog units- Returns:
- the number of pixels
-
convertVerticalDLUsToPixels
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 sizeddlus
- the number of vertical dialog units- Returns:
- the number of pixels
-
createControl
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
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 aGridLayout
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
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 aGridLayout
numColumns
- the number of columns
-
fireStateChanged
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 asVALUE
orIS_VALID
oldValue
- the old valuenewValue
- the new value
-
fireValueChanged
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 asVALUE
orIS_VALID
oldValue
- the old value object, ornull
newValue
- the new value, ornull
-
getFieldEditorFontName
Returns the symbolic font name used by this field editor.- Returns:
- the symbolic font name
-
getLabelControl
Returns the label control.- Returns:
- the label control, or
null
if no label control has been created
-
getLabelControl
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
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
Returns the name of the preference this field editor operates on.- Returns:
- the name of the preference
-
getPreferencePage
Deprecated.use #getPage()Returns the preference page in which this field editor appears.- Returns:
- the preference page, or
null
if none
-
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
Returns the preference store used by this field editor.- Returns:
- the preference store, or
null
if none - See Also:
-
init
Initialize the field editor with the given preference name and label.- Parameters:
name
- the name of the preference this field editor works ontext
- 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 andrefreshValidState
.- Returns:
true
if the field value is valid, andfalse
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, andfalse
otherwise
-
refreshValidState
protected void refreshValidState()Refreshes this field editor's valid state after a value change and fires anIS_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
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
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.use #setPage(DialogPage)Sets the preference page in which this field editor appears.- Parameters:
preferencePage
- the preference page, ornull
if none
-
setPage
Set the page to be the receiver.- Parameters:
dialogPage
- the new receiver- Since:
- 3.1
-
setPreferenceStore
Sets the preference store used by this field editor.- Parameters:
store
- the preference store, ornull
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, andfalse
otherwise
-
setPropertyChangeListener
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, ornull
to remove
-
showErrorMessage
Shows the given error message in the page for this field editor if it has one.- Parameters:
msg
- the error message
-
showMessage
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
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
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.
-