package org.eclipse.jface.preference; | |
/* | |
* (c) Copyright IBM Corp. 2000, 2001. | |
* All Rights Reserved. | |
*/ | |
import org.eclipse.jface.util.IPropertyChangeListener; | |
/** | |
* The <code>IPreferenceStore</code> 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: | |
* <ul> | |
* <li><code>boolean</code> = <code>false</code></li> | |
* <li><code>double</code> = <code>0.0</code></li> | |
* <li><code>float</code> = <code>0.0f</code></li> | |
* <li><code>int</code> = <code>0</code></li> | |
* <li><code>long</code> = <code>0</code></li> | |
* <li><code>String</code> = <code>""</code> (the empty string)</li> | |
* </ul> | |
* <p> | |
* 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. | |
* </p> | |
* <p> | |
* A property change event is reported whenever a preferences current | |
* value actually changes (whether through <code>setValue</code>, | |
* <code>setToDefault</code>, or other unspecified means). Note, however, | |
* that manipulating default values (with <code>setDefault</code>) | |
* does not cause such events to be reported. | |
* </p> | |
* <p> | |
* Clients who need a preference store may implement this interface or | |
* instantiate the standard implementation <code>PreferenceStore</code>. | |
* </p> | |
* | |
* @see PreferenceStore | |
*/ | |
public interface IPreferenceStore { | |
/** | |
* The default-default value for boolean preferences (<code>false</code>). | |
*/ | |
public static final boolean BOOLEAN_DEFAULT_DEFAULT = false; | |
/** | |
* The default-default value for double preferences (<code>0.0</code>). | |
*/ | |
public static final double DOUBLE_DEFAULT_DEFAULT = 0.0; | |
/** | |
* The default-default value for float preferences (<code>0.0f</code>). | |
*/ | |
public static final float FLOAT_DEFAULT_DEFAULT = 0.0f; | |
/** | |
* The default-default value for int preferences (<code>0</code>). | |
*/ | |
public static final int INT_DEFAULT_DEFAULT = 0; | |
/** | |
* The default-default value for long preferences (<code>0L</code>). | |
*/ | |
public static final long LONG_DEFAULT_DEFAULT = 0L; | |
/** | |
* The default-default value for String preferences (<code>""</code>). | |
*/ | |
public static final String STRING_DEFAULT_DEFAULT = new String(); | |
/** | |
* The string representation used for <code>true</code> (<code>"true"</code>). | |
*/ | |
public static final String TRUE = "true"; //$NON-NLS-1$ | |
/** | |
* The string representation used for <code>false</code> (<code>"false"</code>). | |
*/ | |
public static final String FALSE = "false"; //$NON-NLS-1$ | |
/** | |
* Adds a property change listener to this preference store. | |
* | |
* @param listener a property change listener | |
*/ | |
public void addPropertyChangeListener(IPropertyChangeListener listener); | |
/** | |
* Returns whether the named preference is known to this preference | |
* store. | |
* | |
* @param name the name of the preference | |
* @return <code>true</code> if either a current value or a default | |
* value is known for the named preference, and <code>false</code>otherwise | |
*/ | |
public boolean contains(String name); | |
/** | |
* Fires a property change event corresponding to a change to the | |
* current value of the preference with the given name. | |
* <p> | |
* This method is provided on this interface to simplify the implementation | |
* of decorators. There is normally no need to call this method since | |
* <code>setValue</code> and <code>setToDefault</code> report such | |
* events in due course. Implementations should funnel all preference | |
* changes through this method. | |
* </p> | |
* | |
* @param name the name of the preference, to be used as the property | |
* in the event object | |
* @param oldValue the old value | |
* @param newValue the new value | |
*/ | |
public void firePropertyChangeEvent(String name, Object oldValue, Object newValue); | |
/** | |
* Returns the current value of the boolean-valued preference with the | |
* given name. | |
* Returns the default-default value (<code>false</code>) if there | |
* is no preference with the given name, or if the current value | |
* cannot be treated as a boolean. | |
* | |
* @param name the name of the preference | |
* @return the boolean-valued preference | |
*/ | |
public boolean getBoolean(String name); | |
/** | |
* Returns the default value for the boolean-valued preference | |
* with the given name. | |
* Returns the default-default value (<code>false</code>) if there | |
* is no default preference with the given name, or if the default | |
* value cannot be treated as a boolean. | |
* | |
* @param name the name of the preference | |
* @return the default value of the named preference | |
*/ | |
public boolean getDefaultBoolean(String name); | |
/** | |
* Returns the default value for the double-valued preference | |
* with the given name. | |
* Returns the default-default value (<code>0.0</code>) if there | |
* is no default preference with the given name, or if the default | |
* value cannot be treated as a double. | |
* | |
* @param name the name of the preference | |
* @return the default value of the named preference | |
*/ | |
public double getDefaultDouble(String name); | |
/** | |
* Returns the default value for the float-valued preference | |
* with the given name. | |
* Returns the default-default value (<code>0.0f</code>) if there | |
* is no default preference with the given name, or if the default | |
* value cannot be treated as a float. | |
* | |
* @param name the name of the preference | |
* @return the default value of the named preference | |
*/ | |
public float getDefaultFloat(String name); | |
/** | |
* Returns the default value for the integer-valued preference | |
* with the given name. | |
* Returns the default-default value (<code>0</code>) if there | |
* is no default preference with the given name, or if the default | |
* value cannot be treated as an integer. | |
* | |
* @param name the name of the preference | |
* @return the default value of the named preference | |
*/ | |
public int getDefaultInt(String name); | |
/** | |
* Returns the default value for the long-valued preference | |
* with the given name. | |
* Returns the default-default value (<code>0L</code>) if there | |
* is no default preference with the given name, or if the default | |
* value cannot be treated as a long. | |
* | |
* @param name the name of the preference | |
* @return the default value of the named preference | |
*/ | |
public long getDefaultLong(String name); | |
/** | |
* Returns the default value for the string-valued preference | |
* with the given name. | |
* Returns the default-default value (the empty string <code>""</code>) | |
* is no default preference with the given name, or if the default | |
* value cannot be treated as a string. | |
* | |
* @param name the name of the preference | |
* @return the default value of the named preference | |
*/ | |
public String getDefaultString(String name); | |
/** | |
* Returns the current value of the double-valued preference with the | |
* given name. | |
* Returns the default-default value (<code>0.0</code>) if there | |
* is no preference with the given name, or if the current value | |
* cannot be treated as a double. | |
* | |
* @param name the name of the preference | |
* @return the double-valued preference | |
*/ | |
public double getDouble(String name); | |
/** | |
* Returns the current value of the float-valued preference with the | |
* given name. | |
* Returns the default-default value (<code>0.0f</code>) if there | |
* is no preference with the given name, or if the current value | |
* cannot be treated as a float. | |
* | |
* @param name the name of the preference | |
* @return the float-valued preference | |
*/ | |
public float getFloat(String name); | |
/** | |
* Returns the current value of the integer-valued preference with the | |
* given name. | |
* Returns the default-default value (<code>0</code>) if there | |
* is no preference with the given name, or if the current value | |
* cannot be treated as an integter. | |
* | |
* @param name the name of the preference | |
* @return the int-valued preference | |
*/ | |
public int getInt(String name); | |
/** | |
* Returns the current value of the long-valued preference with the | |
* given name. | |
* Returns the default-default value (<code>0L</code>) if there | |
* is no preference with the given name, or if the current value | |
* cannot be treated as a long. | |
* | |
* @param name the name of the preference | |
* @return the long-valued preference | |
*/ | |
public long getLong(String name); | |
/** | |
* Returns the current value of the string-valued preference with the | |
* given name. | |
* Returns the default-default value (the empty string <code>""</code>) | |
* if there is no preference with the given name, or if the current value | |
* cannot be treated as a string. | |
* | |
* @param name the name of the preference | |
* @return the string-valued preference | |
*/ | |
public String getString(String name); | |
/** | |
* Returns whether the current value of the preference with the given name | |
* has the default value. | |
* | |
* @param name the name of the preference | |
* @return <code>true</code> if the preference has a known default value | |
* and its current value is the same, and <code>false</code> otherwise | |
* (including the case where the preference is unknown to this store) | |
*/ | |
public boolean isDefault(String name); | |
/** | |
* Returns whether the current values in this property store | |
* require saving. | |
* | |
* @return <code>true</code> if at least one of the preferences | |
* known to this store has a current value different from its | |
* default value, and <code>false</code> otherwise | |
*/ | |
public boolean needsSaving(); | |
/** | |
* Sets the current value of the preference with the given name to | |
* the given string value. | |
* <p> | |
* This method is provided on this interface to simplify the implementation | |
* of decorators, and does not report a property change event. | |
* Normal clients should instead call <code>setValue</code>. | |
* </p> | |
* | |
* @param name the name of the preference | |
* @param value the new current value of the preference | |
*/ | |
public void putValue(String name, String value); | |
/** | |
* Removes the given listener from this preference store. | |
* Has no affect if the listener is not registered. | |
* | |
* @param listener a property change listener | |
*/ | |
public void removePropertyChangeListener(IPropertyChangeListener listener); | |
/** | |
* Sets the default value for the double-valued preference with the | |
* given name. | |
* <p> | |
* 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. | |
* </p> | |
* | |
* @param name the name of the preference | |
* @param value the new default value for the preference | |
*/ | |
public void setDefault(String name, double value); | |
/** | |
* Sets the default value for the float-valued preference with the | |
* given name. | |
* <p> | |
* 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. | |
* </p> | |
* | |
* @param name the name of the preference | |
* @param value the new default value for the preference | |
*/ | |
public void setDefault(String name, float value); | |
/** | |
* Sets the default value for the integer-valued preference with the | |
* given name. | |
* <p> | |
* 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. | |
* </p> | |
* | |
* @param name the name of the preference | |
* @param value the new default value for the preference | |
*/ | |
public void setDefault(String name, int value); | |
/** | |
* Sets the default value for the long-valued preference with the | |
* given name. | |
* <p> | |
* 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. | |
* </p> | |
* | |
* @param name the name of the preference | |
* @param value the new default value for the preference | |
*/ | |
public void setDefault(String name, long value); | |
/** | |
* Sets the default value for the string-valued preference with the | |
* given name. | |
* <p> | |
* 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. | |
* </p> | |
* | |
* @param name the name of the preference | |
* @param value the new default value for the preference | |
*/ | |
public void setDefault(String name, String defaultObject); | |
/** | |
* Sets the default value for the boolean-valued preference with the | |
* given name. | |
* <p> | |
* 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. | |
* </p> | |
* | |
* @param name the name of the preference | |
* @param value the new default value for the preference | |
*/ | |
public void setDefault(String name, boolean value); | |
/** | |
* Sets the current value of the preference with the given name back | |
* to its default value. | |
* <p> | |
* Note that the preferred way of re-initializing a preference to the | |
* appropriate default value is to call <code>setToDefault</code>. | |
* This is implemented by removing the named value from the store, | |
* thereby exposing the default value. | |
* </p> | |
* | |
* @param name the name of the preference | |
*/ | |
public void setToDefault(String name); | |
/** | |
* Sets the current value of the double-valued preference with the | |
* given name. | |
* <p> | |
* 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. | |
* </p> | |
* <p> | |
* Note that the preferred way of re-initializing a preference to its | |
* default value is to call <code>setToDefault</code>. | |
* </p> | |
* | |
* @param name the name of the preference | |
* @param value the new current value of the preference | |
*/ | |
public void setValue(String name, double value); | |
/** | |
* Sets the current value of the float-valued preference with the | |
* given name. | |
* <p> | |
* 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. | |
* </p> | |
* <p> | |
* Note that the preferred way of re-initializing a preference to its | |
* default value is to call <code>setToDefault</code>. | |
* </p> | |
* | |
* @param name the name of the preference | |
* @param value the new current value of the preference | |
*/ | |
public void setValue(String name, float value); | |
/** | |
* Sets the current value of the integer-valued preference with the | |
* given name. | |
* <p> | |
* 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. | |
* </p> | |
* <p> | |
* Note that the preferred way of re-initializing a preference to its | |
* default value is to call <code>setToDefault</code>. | |
* </p> | |
* | |
* @param name the name of the preference | |
* @param value the new current value of the preference | |
*/ | |
public void setValue(String name, int value); | |
/** | |
* Sets the current value of the long-valued preference with the | |
* given name. | |
* <p> | |
* 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. | |
* </p> | |
* <p> | |
* Note that the preferred way of re-initializing a preference to its | |
* default value is to call <code>setToDefault</code>. | |
* </p> | |
* | |
* @param name the name of the preference | |
* @param value the new current value of the preference | |
*/ | |
public void setValue(String name, long value); | |
/** | |
* Sets the current value of the string-valued preference with the | |
* given name. | |
* <p> | |
* 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. | |
* </p> | |
* <p> | |
* Note that the preferred way of re-initializing a preference to its | |
* default value is to call <code>setToDefault</code>. | |
* </p> | |
* | |
* @param name the name of the preference | |
* @param value the new current value of the preference | |
*/ | |
public void setValue(String name, String value); | |
/** | |
* Sets the current value of the boolean-valued preference with the | |
* given name. | |
* <p> | |
* 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. | |
* </p> | |
* <p> | |
* Note that the preferred way of re-initializing a preference to its | |
* default value is to call <code>setToDefault</code>. | |
* </p> | |
* | |
* @param name the name of the preference | |
* @param value the new current value of the preference | |
*/ | |
public void setValue(String name, boolean value); | |
} |