Package org.eclipse.jface.preference

Interface IPreferenceStore

All Known Subinterfaces:

IPersistentPreferenceStore

All Known Implementing Classes:

ChainedPreferenceStore, OverlayPreferenceStore, 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

Field Summary

Fields

Modifier and Type	Field	Description
static final boolean	BOOLEAN_DEFAULT_DEFAULT	The default-default value for boolean preferences (false).
static final double	DOUBLE_DEFAULT_DEFAULT	The default-default value for double preferences (0.0).
static final String	FALSE	The string representation used for false ("false").
static final float	FLOAT_DEFAULT_DEFAULT	The default-default value for float preferences (0.0f).
static final int	INT_DEFAULT_DEFAULT	The default-default value for int preferences (0).
static final long	LONG_DEFAULT_DEFAULT	The default-default value for long preferences (0L).
static final String	STRING_DEFAULT_DEFAULT	The default-default value for String preferences ("").
static final String	TRUE	The string representation used for true ("true").

Method Summary

Modifier and Type	Method	Description
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.

Field Details

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

Method Details

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 integer.

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 effect if the listener is not registered.

Parameters:

listener - a property change listener, must not be null

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