Java tutorial
/******************************************************************************* * Copyright (c) 2000, 2015 IBM Corporation and others. * * This program and the accompanying materials * are made available under the terms of the Eclipse Public License 2.0 * which accompanies this distribution, and is available at * https://www.eclipse.org/legal/epl-2.0/ * * SPDX-License-Identifier: EPL-2.0 * * Contributors: * IBM Corporation - initial API and implementation *******************************************************************************/ package org.eclipse.jface.preference; 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>). */ boolean BOOLEAN_DEFAULT_DEFAULT = false; /** * The default-default value for double preferences (<code>0.0</code>). */ double DOUBLE_DEFAULT_DEFAULT = 0.0; /** * The default-default value for float preferences (<code>0.0f</code>). */ float FLOAT_DEFAULT_DEFAULT = 0.0f; /** * The default-default value for int preferences (<code>0</code>). */ int INT_DEFAULT_DEFAULT = 0; /** * The default-default value for long preferences (<code>0L</code>). */ long LONG_DEFAULT_DEFAULT = 0L; /** * The default-default value for String preferences (<code>""</code>). */ String STRING_DEFAULT_DEFAULT = ""; //$NON-NLS-1$ /** * The string representation used for <code>true</code> (<code>"true"</code>). */ String TRUE = "true"; //$NON-NLS-1$ /** * The string representation used for <code>false</code> (<code>"false"</code>). */ String FALSE = "false"; //$NON-NLS-1$ /** * <p> * Adds a property change listener to this preference store. * </p> * <p> * <b>Note</b> 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. * </p> * <p> * 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). * </p> * <p> * 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. * </p> * * @param listener a property change listener * @see org.eclipse.jface.util.PropertyChangeEvent * @see #setToDefault(String) * @see #setValue(String, boolean) * @see #setValue(String, double) * @see #setValue(String, float) * @see #setValue(String, int) * @see #setValue(String, long) * @see #setValue(String, String) */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 integer. * * @param name * the name of the preference * @return the int-valued preference */ 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 */ 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 */ 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) */ boolean isDefault(String name); /** * Returns whether the current values in this property store * require saving. * * @return <code>true</code> if at least one of values of * the preferences known to this store has changed and * requires saving, and <code>false</code> otherwise. */ boolean needsSaving(); /** * Sets the current value of the preference with the given name to * the given string value without sending a property change. * <p> * 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. * </p> * * @param name the name of the preference * @param value the new current value of the preference */ void putValue(String name, String value); /** * Removes the given listener from this preference store. Has no effect if the listener is not * registered. * * @param listener a property change listener, must not be <code>null</code> */ 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 */ 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 */ 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 */ 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 */ 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 defaultObject the new default value for the preference */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ void setValue(String name, boolean value); }