org.eclipse.jface.preference
Interface IPreferenceStore
-
All Known Subinterfaces:
-
IPersistentPreferenceStore
-
All Known Implementing Classes:
-
ChainedPreferenceStore,
PreferenceStore,
ScopedPreferenceStore
-
public interface IPreferenceStore
The IPreferenceStore
interface represents a table mapping
named preferences to values. If there is no value for a given name,
then that preferences's default value is returned; and if there is no
default value for that preference, then a default-default value is returned.
The default-default values for the primitive types are as follows:
-
boolean
= false
-
double
= 0.0
-
float
= 0.0f
-
int
= 0
-
long
= 0
-
String
= ""
(the empty string)
Thus a preference store maintains two values for each of a set of
names: a current value and a default value.
The typical usage is to establish the defaults for all known preferences
and then restore previously stored values for preferences whose values
were different from their defaults. After the current values of
the preferences have been modified, it is a simple matter to write
out only those preferences whose values are different from their defaults.
This two-tiered approach to saving and restoring preference setting
minimized the number of preferences that need to be persisted; indeed,
the normal starting state does not require storing any preferences
at all.
A property change event is reported whenever a preferences current
value actually changes (whether through setValue
,
setToDefault
, or other unspecified means). Note, however,
that manipulating default values (with setDefault
)
does not cause such events to be reported.
Clients who need a preference store may implement this interface or
instantiate the standard implementation PreferenceStore
.
-
See Also:
-
PreferenceStore
Method Summary
|
void
|
addPropertyChangeListener
(
IPropertyChangeListener listener)
Adds a property change listener to this preference store. |
boolean
|
contains
(
String name)
Returns whether the named preference is known to this preference
store. |
void
|
firePropertyChangeEvent
(
String name,
Object oldValue,
Object newValue)
Fires a property change event corresponding to a change to the
current value of the preference with the given name. |
boolean
|
getBoolean
(
String name)
Returns the current value of the boolean-valued preference with the
given name. |
boolean
|
getDefaultBoolean
(
String name)
Returns the default value for the boolean-valued preference
with the given name. |
double
|
getDefaultDouble
(
String name)
Returns the default value for the double-valued preference
with the given name. |
float
|
getDefaultFloat
(
String name)
Returns the default value for the float-valued preference
with the given name. |
int
|
getDefaultInt
(
String name)
Returns the default value for the integer-valued preference
with the given name. |
long
|
getDefaultLong
(
String name)
Returns the default value for the long-valued preference
with the given name. |
String
|
getDefaultString
(
String name)
Returns the default value for the string-valued preference
with the given name. |
double
|
getDouble
(
String name)
Returns the current value of the double-valued preference with the
given name. |
float
|
getFloat
(
String name)
Returns the current value of the float-valued preference with the
given name. |
int
|
getInt
(
String name)
Returns the current value of the integer-valued preference with the
given name. |
long
|
getLong
(
String name)
Returns the current value of the long-valued preference with the
given name. |
String
|
getString
(
String name)
Returns the current value of the string-valued preference with the
given name. |
boolean
|
isDefault
(
String name)
Returns whether the current value of the preference with the given name
has the default value. |
boolean
|
needsSaving
()
Returns whether the current values in this property store
require saving. |
void
|
putValue
(
String name,
String value)
Sets the current value of the preference with the given name to
the given string value without sending a property change. |
void
|
removePropertyChangeListener
(
IPropertyChangeListener listener)
Removes the given listener from this preference store. |
void
|
setDefault
(
String name,
boolean value)
Sets the default value for the boolean-valued preference with the
given name. |
void
|
setDefault
(
String name,
double value)
Sets the default value for the double-valued preference with the
given name. |
void
|
setDefault
(
String name,
float value)
Sets the default value for the float-valued preference with the
given name. |
void
|
setDefault
(
String name,
int value)
Sets the default value for the integer-valued preference with the
given name. |
void
|
setDefault
(
String name,
long value)
Sets the default value for the long-valued preference with the
given name. |
void
|
setDefault
(
String name,
String defaultObject)
Sets the default value for the string-valued preference with the
given name. |
void
|
setToDefault
(
String name)
Sets the current value of the preference with the given name back
to its default value. |
void
|
setValue
(
String name,
boolean value)
Sets the current value of the boolean-valued preference with the
given name. |
void
|
setValue
(
String name,
double value)
Sets the current value of the double-valued preference with the
given name. |
void
|
setValue
(
String name,
float value)
Sets the current value of the float-valued preference with the
given name. |
void
|
setValue
(
String name,
int value)
Sets the current value of the integer-valued preference with the
given name. |
void
|
setValue
(
String name,
long value)
Sets the current value of the long-valued preference with the
given name. |
void
|
setValue
(
String name,
String value)
Sets the current value of the string-valued preference with the
given name. |
BOOLEAN_DEFAULT_DEFAULT
static final boolean BOOLEAN_DEFAULT_DEFAULT
- The default-default value for boolean preferences (
false
).
-
See Also:
-
Constant Field Values
DOUBLE_DEFAULT_DEFAULT
static final double DOUBLE_DEFAULT_DEFAULT
- The default-default value for double preferences (
0.0
).
-
See Also:
-
Constant Field Values
FLOAT_DEFAULT_DEFAULT
static final float FLOAT_DEFAULT_DEFAULT
- The default-default value for float preferences (
0.0f
).
-
See Also:
-
Constant Field Values
INT_DEFAULT_DEFAULT
static final int INT_DEFAULT_DEFAULT
- The default-default value for int preferences (
0
).
-
See Also:
-
Constant Field Values
LONG_DEFAULT_DEFAULT
static final long LONG_DEFAULT_DEFAULT
- The default-default value for long preferences (
0L
).
-
See Also:
-
Constant Field Values
STRING_DEFAULT_DEFAULT
static final
String STRING_DEFAULT_DEFAULT
- The default-default value for String preferences (
""
).
-
See Also:
-
Constant Field Values
TRUE
static final
String TRUE
- The string representation used for
true
("true"
).
-
See Also:
-
Constant Field Values
FALSE
static final
String FALSE
- The string representation used for
false
("false"
).
-
See Also:
-
Constant Field Values
addPropertyChangeListener
void addPropertyChangeListener(
IPropertyChangeListener listener)
-
Adds a property change listener to this preference store.
Note The types of the oldValue and newValue of the
generated PropertyChangeEvent are determined by whether
or not the typed API in IPreferenceStore was called.
If values are changed via setValue(name,type) the
values in the PropertyChangedEvent will be of that type.
If they are set using a non typed API (i.e. #setToDefault
or using the OSGI Preferences) the values will be unconverted
Strings.
A listener will be called in the same Thread
that it is invoked in. Any Thread dependant listeners (such as
those who update an SWT widget) will need to update in the
correct Thread. In the case of an SWT update you can update
using Display#syncExec(Runnable) or Display#asyncExec(Runnable).
Likewise any application that updates an IPreferenceStore
from a Thread other than the UI Thread should be aware of
any listeners that require an update in the UI Thread.
-
-
Parameters:
-
listener
- a property change listener -
See Also:
-
PropertyChangeEvent
,
setToDefault(String)
,
setValue(String, boolean)
,
setValue(String, double)
,
setValue(String, float)
,
setValue(String, int)
,
setValue(String, long)
,
setValue(String, String)
contains
boolean contains(
String name)
- Returns whether the named preference is known to this preference
store.
-
-
Parameters:
-
name
- the name of the preference
-
Returns:
-
true
if either a current value or a default
value is known for the named preference, and false
otherwise
firePropertyChangeEvent
void firePropertyChangeEvent(
String name,
Object oldValue,
Object newValue)
- Fires a property change event corresponding to a change to the
current value of the preference with the given name.
This method is provided on this interface to simplify the implementation
of decorators. There is normally no need to call this method since
setValue
and setToDefault
report such
events in due course. Implementations should funnel all preference
changes through this method.
-
-
Parameters:
-
name
- the name of the preference, to be used as the property
in the event object -
oldValue
- the old value -
newValue
- the new value
getBoolean
boolean getBoolean(
String name)
- Returns the current value of the boolean-valued preference with the
given name.
Returns the default-default value (
false
) if there
is no preference with the given name, or if the current value
cannot be treated as a boolean.
-
-
Parameters:
-
name
- the name of the preference
-
Returns:
- the boolean-valued preference
getDefaultBoolean
boolean getDefaultBoolean(
String name)
- Returns the default value for the boolean-valued preference
with the given name.
Returns the default-default value (
false
) if there
is no default preference with the given name, or if the default
value cannot be treated as a boolean.
-
-
Parameters:
-
name
- the name of the preference
-
Returns:
- the default value of the named preference
getDefaultDouble
double getDefaultDouble(
String name)
- Returns the default value for the double-valued preference
with the given name.
Returns the default-default value (
0.0
) if there
is no default preference with the given name, or if the default
value cannot be treated as a double.
-
-
Parameters:
-
name
- the name of the preference
-
Returns:
- the default value of the named preference
getDefaultFloat
float getDefaultFloat(
String name)
- Returns the default value for the float-valued preference
with the given name.
Returns the default-default value (
0.0f
) if there
is no default preference with the given name, or if the default
value cannot be treated as a float.
-
-
Parameters:
-
name
- the name of the preference
-
Returns:
- the default value of the named preference
getDefaultInt
int getDefaultInt(
String name)
- Returns the default value for the integer-valued preference
with the given name.
Returns the default-default value (
0
) if there
is no default preference with the given name, or if the default
value cannot be treated as an integer.
-
-
Parameters:
-
name
- the name of the preference
-
Returns:
- the default value of the named preference
getDefaultLong
long getDefaultLong(
String name)
- Returns the default value for the long-valued preference
with the given name.
Returns the default-default value (
0L
) if there
is no default preference with the given name, or if the default
value cannot be treated as a long.
-
-
Parameters:
-
name
- the name of the preference
-
Returns:
- the default value of the named preference
getDefaultString
String getDefaultString(
String name)
- Returns the default value for the string-valued preference
with the given name.
Returns the default-default value (the empty string
""
)
is no default preference with the given name, or if the default
value cannot be treated as a string.
-
-
Parameters:
-
name
- the name of the preference
-
Returns:
- the default value of the named preference
getDouble
double getDouble(
String name)
- Returns the current value of the double-valued preference with the
given name.
Returns the default-default value (
0.0
) if there
is no preference with the given name, or if the current value
cannot be treated as a double.
-
-
Parameters:
-
name
- the name of the preference
-
Returns:
- the double-valued preference
getFloat
float getFloat(
String name)
- Returns the current value of the float-valued preference with the
given name.
Returns the default-default value (
0.0f
) if there
is no preference with the given name, or if the current value
cannot be treated as a float.
-
-
Parameters:
-
name
- the name of the preference
-
Returns:
- the float-valued preference
getInt
int getInt(
String name)
- Returns the current value of the integer-valued preference with the
given name.
Returns the default-default value (
0
) if there
is no preference with the given name, or if the current value
cannot be treated as an integter.
-
-
Parameters:
-
name
- the name of the preference
-
Returns:
- the int-valued preference
getLong
long getLong(
String name)
- Returns the current value of the long-valued preference with the
given name.
Returns the default-default value (
0L
) if there
is no preference with the given name, or if the current value
cannot be treated as a long.
-
-
Parameters:
-
name
- the name of the preference
-
Returns:
- the long-valued preference
getString
String getString(
String name)
- Returns the current value of the string-valued preference with the
given name.
Returns the default-default value (the empty string
""
)
if there is no preference with the given name, or if the current value
cannot be treated as a string.
-
-
Parameters:
-
name
- the name of the preference
-
Returns:
- the string-valued preference
isDefault
boolean isDefault(
String name)
- Returns whether the current value of the preference with the given name
has the default value.
-
-
Parameters:
-
name
- the name of the preference
-
Returns:
-
true
if the preference has a known default value
and its current value is the same, and false
otherwise
(including the case where the preference is unknown to this store)
needsSaving
boolean needsSaving()
- Returns whether the current values in this property store
require saving.
-
-
Returns:
-
true
if at least one of values of
the preferences known to this store has changed and
requires saving, and false
otherwise.
putValue
void putValue(
String name,
String value)
- Sets the current value of the preference with the given name to
the given string value without sending a property change.
This method does not fire a property change event and
should only be used for setting internal preferences
that are not meant to be processed by listeners.
Normal clients should instead call #setValue.
-
-
Parameters:
-
name
- the name of the preference -
value
- the new current value of the preference
removePropertyChangeListener
void removePropertyChangeListener(
IPropertyChangeListener listener)
- Removes the given listener from this preference store.
Has no affect if the listener is not registered.
-
-
Parameters:
-
listener
- a property change listener
setDefault
void setDefault(
String name,
double value)
- Sets the default value for the double-valued preference with the
given name.
Note that the current value of the preference is affected if
the preference's current value was its old default value, in which
case it changes to the new default value. If the preference's current
is different from its old default value, its current value is
unaffected. No property change events are reported by changing default
values.
-
-
Parameters:
-
name
- the name of the preference -
value
- the new default value for the preference
setDefault
void setDefault(
String name,
float value)
- Sets the default value for the float-valued preference with the
given name.
Note that the current value of the preference is affected if
the preference's current value was its old default value, in which
case it changes to the new default value. If the preference's current
is different from its old default value, its current value is
unaffected. No property change events are reported by changing default
values.
-
-
Parameters:
-
name
- the name of the preference -
value
- the new default value for the preference
setDefault
void setDefault(
String name,
int value)
- Sets the default value for the integer-valued preference with the
given name.
Note that the current value of the preference is affected if
the preference's current value was its old default value, in which
case it changes to the new default value. If the preference's current
is different from its old default value, its current value is
unaffected. No property change events are reported by changing default
values.
-
-
Parameters:
-
name
- the name of the preference -
value
- the new default value for the preference
setDefault
void setDefault(
String name,
long value)
- Sets the default value for the long-valued preference with the
given name.
Note that the current value of the preference is affected if
the preference's current value was its old default value, in which
case it changes to the new default value. If the preference's current
is different from its old default value, its current value is
unaffected. No property change events are reported by changing default
values.
-
-
Parameters:
-
name
- the name of the preference -
value
- the new default value for the preference
setDefault
void setDefault(
String name,
String defaultObject)
- Sets the default value for the string-valued preference with the
given name.
Note that the current value of the preference is affected if
the preference's current value was its old default value, in which
case it changes to the new default value. If the preference's current
is different from its old default value, its current value is
unaffected. No property change events are reported by changing default
values.
-
-
Parameters:
-
name
- the name of the preference -
defaultObject
- the new default value for the preference
setDefault
void setDefault(
String name,
boolean value)
- Sets the default value for the boolean-valued preference with the
given name.
Note that the current value of the preference is affected if
the preference's current value was its old default value, in which
case it changes to the new default value. If the preference's current
is different from its old default value, its current value is
unaffected. No property change events are reported by changing default
values.
-
-
Parameters:
-
name
- the name of the preference -
value
- the new default value for the preference
setToDefault
void setToDefault(
String name)
- Sets the current value of the preference with the given name back
to its default value.
Note that the preferred way of re-initializing a preference to the
appropriate default value is to call setToDefault
.
This is implemented by removing the named value from the store,
thereby exposing the default value.
-
-
Parameters:
-
name
- the name of the preference
setValue
void setValue(
String name,
double value)
- Sets the current value of the double-valued preference with the
given name.
A property change event is reported if the current value of the
preference actually changes from its previous value. In the event
object, the property name is the name of the preference, and the
old and new values are wrapped as objects.
Note that the preferred way of re-initializing a preference to its
default value is to call setToDefault
.
-
-
Parameters:
-
name
- the name of the preference -
value
- the new current value of the preference
setValue
void setValue(
String name,
float value)
- Sets the current value of the float-valued preference with the
given name.
A property change event is reported if the current value of the
preference actually changes from its previous value. In the event
object, the property name is the name of the preference, and the
old and new values are wrapped as objects.
Note that the preferred way of re-initializing a preference to its
default value is to call setToDefault
.
-
-
Parameters:
-
name
- the name of the preference -
value
- the new current value of the preference
setValue
void setValue(
String name,
int value)
- Sets the current value of the integer-valued preference with the
given name.
A property change event is reported if the current value of the
preference actually changes from its previous value. In the event
object, the property name is the name of the preference, and the
old and new values are wrapped as objects.
Note that the preferred way of re-initializing a preference to its
default value is to call setToDefault
.
-
-
Parameters:
-
name
- the name of the preference -
value
- the new current value of the preference
setValue
void setValue(
String name,
long value)
- Sets the current value of the long-valued preference with the
given name.
A property change event is reported if the current value of the
preference actually changes from its previous value. In the event
object, the property name is the name of the preference, and the
old and new values are wrapped as objects.
Note that the preferred way of re-initializing a preference to its
default value is to call setToDefault
.
-
-
Parameters:
-
name
- the name of the preference -
value
- the new current value of the preference
setValue
void setValue(
String name,
String value)
- Sets the current value of the string-valued preference with the
given name.
A property change event is reported if the current value of the
preference actually changes from its previous value. In the event
object, the property name is the name of the preference, and the
old and new values are wrapped as objects.
Note that the preferred way of re-initializing a preference to its
default value is to call setToDefault
.
-
-
Parameters:
-
name
- the name of the preference -
value
- the new current value of the preference
setValue
void setValue(
String name,
boolean value)
- Sets the current value of the boolean-valued preference with the
given name.
A property change event is reported if the current value of the
preference actually changes from its previous value. In the event
object, the property name is the name of the preference, and the
old and new values are wrapped as objects.
Note that the preferred way of re-initializing a preference to its
default value is to call setToDefault
.
-
-
Parameters:
-
name
- the name of the preference -
value
- the new current value of the preference
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.