org.eclipse.jface.preference.IPreferenceStore Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jface Show documentation
JFace is a UI toolkit with classes for handling many common UI programming tasks. JFace is window-system-independent in both its API and implementation, and is designed to work with SWT without hiding it. JFace includes the usual UI toolkit components of image and font registries, text, dialog, preference and wizard frameworks, and progress reporting for long running operations. Two of its more interesting features are actions and viewers. The action mechanism allows user commands to be defined independently from their exact whereabouts in the UI. Viewers are model based adapters for certain SWT widgets, simplifying the presentation of application data structured as lists, tables or trees.
The newest version!
/*******************************************************************************
 * Copyright (c) 2000, 2006 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.jface.preference;

import org.eclipse.jface.util.IPropertyChangeListener;

/**
 * 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 PreferenceStore
 */
public interface IPreferenceStore {

    /**
     * The default-default value for boolean preferences (false).
     */
    public static final boolean BOOLEAN_DEFAULT_DEFAULT = false;

    /**
     * The default-default value for double preferences (0.0).
     */
    public static final double DOUBLE_DEFAULT_DEFAULT = 0.0;

    /**
     * The default-default value for float preferences (0.0f).
     */
    public static final float FLOAT_DEFAULT_DEFAULT = 0.0f;

    /**
     * The default-default value for int preferences (0).
     */
    public static final int INT_DEFAULT_DEFAULT = 0;

    /**
     * The default-default value for long preferences (0L).
     */
    public static final long LONG_DEFAULT_DEFAULT = 0L;

    /**
     * The default-default value for String preferences ("").
     */
    public static final String STRING_DEFAULT_DEFAULT = ""; //$NON-NLS-1$

    /**
     * The string representation used for true ("true").
     */
    public static final String TRUE = "true"; //$NON-NLS-1$

    /**
     * The string representation used for false ("false").
     */
    public static final String FALSE = "false"; //$NON-NLS-1$

    /**
     * 
     * 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. 
     * 
     *
     * @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)
     */
    public void addPropertyChangeListener(IPropertyChangeListener listener);

    /**
     * Returns whether the named preference is known to this preference
     * store.
     *
     * @param name the name of the preference
     * @return true if either a current value or a default
     *  value is known for the named preference, and false 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.
     * 
     * 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.
     * 
     *
     * @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 (false) 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 (false) 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 (0.0) 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 (0.0f) 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 (0) 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 (0L) 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 "") 
     * 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 (0.0) 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 (0.0f) 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 (0) 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 (0L) 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 "")
     * 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 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)
     */
    public boolean isDefault(String name);

    /**
     * Returns whether the current values in this property store
     * require saving.
     *
     * @return true if at least one of values of 
     *  the preferences known to this store has changed and 
     *  requires saving, and false otherwise.
     */
    public boolean needsSaving();

    /**
     * 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.
     * 
     *
     * @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. 
     * 
     * 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.
     * 
     *
     * @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. 
     * 
     * 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.
     * 
     *
     * @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. 
     * 
     * 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.
     * 
     *
     * @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. 
     * 
     * 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.
     * 
     *
     * @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. 
     * 
     * 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.
     * 
     *
     * @param name the name of the preference
     * @param defaultObject 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. 
     * 
     * 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.
     * 
     *
     * @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.
     * 
     * 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.
     * 
     *
     * @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.
     * 
     * 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.
     * 
     *
     * @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.
     * 
     * 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.
     * 
     *
     * @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.
     * 
     * 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.
     * 
     *
     * @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.
     * 
     * 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.
     * 
     *
     * @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.
     * 
     * 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.
     * 
     *
     * @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.
     * 
     * 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.
     * 
     *
     * @param name the name of the preference
     * @param value the new current value of the preference
     */
    public void setValue(String name, boolean value);
}