org.eclipse.jface.preference
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
|
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. |
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. |
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. |
Methods inherited from class java.lang.
Object
|
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
|
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
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
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
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:
-
setPreferenceStore(org.eclipse.jface.preference.IPreferenceStore)
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:
-
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)
-
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
- -
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:
-
getPreferenceStore()
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.
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.