Mercurial > projects > dwt-addons
changeset 5:103ab03b77eb
jface commands
author | Frank Benoit <benoit@tionex.de> |
---|---|
date | Fri, 28 Mar 2008 18:27:09 +0100 |
parents | c87617952847 |
children | 1a6747be662d |
files | dwtx/jface/commands/ActionHandler.d dwtx/jface/commands/PersistentState.d dwtx/jface/commands/RadioState.d dwtx/jface/commands/ToggleState.d dwtx/jface/menus/IMenuStateIds.d dwtx/jface/preference/IPreferenceStore.d |
diffstat | 6 files changed, 1228 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/dwtx/jface/commands/ActionHandler.d Fri Mar 28 18:27:09 2008 +0100 @@ -0,0 +1,164 @@ +/******************************************************************************* + * Copyright (c) 2004, 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 + * Port to the D programming language: + * Frank Benoit <benoit@tionex.de> + *******************************************************************************/ +module dwtx.jface.commands.ActionHandler; + + +import dwt.widgets.Event; +import dwtx.core.commands.AbstractHandler; +import dwtx.core.commands.ExecutionEvent; +import dwtx.core.commands.ExecutionException; +import dwtx.core.commands.HandlerEvent; +import dwtx.core.commands.IHandlerListener; +import dwtx.jface.action.IAction; +import dwtx.jface.util.IPropertyChangeListener; +import dwtx.jface.util.PropertyChangeEvent; + +import dwt.dwthelper.utils; + +/** + * <p> + * This class adapts instances of <code>IAction</code> to + * <code>IHandler</code>. + * </p> + * + * @since 3.1 + */ +public final class ActionHandler : AbstractHandler { + + /** + * The wrapped action. This value is never <code>null</code>. + */ + private const IAction action; + + /** + * The property change listener hooked on to the action. This is initialized + * when the first listener is attached to this handler, and is removed when + * the handler is disposed or the last listener is removed. + */ + private IPropertyChangeListener propertyChangeListener; + + /** + * Creates a new instance of this class given an instance of + * <code>IAction</code>. + * + * @param action + * the action. Must not be <code>null</code>. + */ + public this(IAction action) { + if (action is null) { + throw new NullPointerException(); + } + + this.action = action; + } + + public final void addHandlerListener(IHandlerListener handlerListener) { + if (!hasListeners()) { + attachListener(); + } + + super.addHandlerListener(handlerListener); + } + + /** + * When a listener is attached to this handler, then this registers a + * listener with the underlying action. + * + * @since 3.1 + */ + private final void attachListener() { + if (propertyChangeListener is null) { + propertyChangeListener = new class() IPropertyChangeListener { + public final void propertyChange( + PropertyChangeEvent propertyChangeEvent) { + String property = propertyChangeEvent.getProperty(); + fireHandlerChanged(new HandlerEvent(this.outer, + IAction.ENABLED.equals(property), IAction.HANDLED + .equals(property))); + } + }; + } + + this.action.addPropertyChangeListener(propertyChangeListener); + } + + /** + * When no more listeners are registered, then this is used to removed the + * property change listener from the underlying action. + */ + private final void detachListener() { + this.action.removePropertyChangeListener(propertyChangeListener); + propertyChangeListener = null; + } + + /** + * Removes the property change listener from the action. + * + * @see dwtx.core.commands.IHandler#dispose() + */ + public final void dispose() { + if (hasListeners()) { + action.removePropertyChangeListener(propertyChangeListener); + } + } + + public final Object execute(ExecutionEvent event) { + if ((action.getStyle() is IAction.AS_CHECK_BOX) + || (action.getStyle() is IAction.AS_RADIO_BUTTON)) { + action.setChecked(!action.isChecked()); + } + Object trigger = event.getTrigger(); + try { + if (auto ev = cast(Event)trigger) { + action.runWithEvent(ev); + } else { + action.runWithEvent(new Event()); + } + } catch (Exception e) { + throw new ExecutionException( + "While executing the action, an exception occurred", e); //$NON-NLS-1$ + } + return null; + } + + /** + * Returns the action associated with this handler + * + * @return the action associated with this handler (not null) + * @since 3.1 + */ + public final IAction getAction() { + return action; + } + + public final bool isEnabled() { + return action.isEnabled(); + } + + public final bool isHandled() { + return action.isHandled(); + } + + public final void removeHandlerListener( + IHandlerListener handlerListener) { + super.removeHandlerListener(handlerListener); + + if (!hasListeners()) { + detachListener(); + } + } + + public final String toString() { + return "ActionHandler(" ~ (cast(Object)action).toString ~ ")"; + } +}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/dwtx/jface/commands/PersistentState.d Fri Mar 28 18:27:09 2008 +0100 @@ -0,0 +1,88 @@ +/******************************************************************************* + * Copyright (c) 2005, 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 + * Port to the D programming language: + * Frank Benoit <benoit@tionex.de> + *******************************************************************************/ + +module dwtx.jface.commands.PersistentState; + +import dwtx.core.commands.State; +import dwtx.jface.preference.IPreferenceStore; + +import dwt.dwthelper.utils; + +/** + * <p> + * This is a state that can be made persistent. A state is persisted to a + * preference store. + * </p> + * <p> + * Clients may extend this class. + * </p> + * + * @since 3.2 + */ +public abstract class PersistentState : State { + + /** + * Whether this state should be persisted. + */ + private bool persisted; + + /** + * Loads this state from the preference store, given the location at which + * to look. This method must be symmetric with a call to + * {@link #save(IPreferenceStore, String)}. + * + * @param store + * The store from which to read; must not be <code>null</code>. + * @param preferenceKey + * The key at which the state is stored; must not be + * <code>null</code>. + */ + public abstract void load(IPreferenceStore store, + String preferenceKey); + + /** + * Saves this state to the preference store, given the location at which to + * write. This method must be symmetric with a call to + * {@link #load(IPreferenceStore, String)}. + * + * @param store + * The store to which the state should be written; must not be + * <code>null</code>. + * @param preferenceKey + * The key at which the state should be stored; must not be + * <code>null</code>. + */ + public abstract void save(IPreferenceStore store, + String preferenceKey); + + /** + * Sets whether this state should be persisted. + * + * @param persisted + * Whether this state should be persisted. + */ + public void setShouldPersist(bool persisted) { + this.persisted = persisted; + } + + /** + * Whether this state should be persisted. Subclasses should check this + * method before loading or saving. + * + * @return <code>true</code> if this state should be persisted; + * <code>false</code> otherwise. + */ + public bool shouldPersist() { + return persisted; + } +}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/dwtx/jface/commands/RadioState.d Fri Mar 28 18:27:09 2008 +0100 @@ -0,0 +1,271 @@ +/******************************************************************************* + * Copyright (c) 2005, 2007 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 + * Port to the D programming language: + * Frank Benoit <benoit@tionex.de> + *******************************************************************************/ + +module dwtx.jface.commands.RadioState; + +import tango.util.collection.HashMap; +import tango.util.collection.HashSet; +import tango.util.collection.model.Map; +import tango.util.collection.model.Set; + +import dwtx.core.commands.IStateListener; +import dwtx.core.commands.State; +import dwtx.jface.menus.IMenuStateIds; + +import dwtx.jface.commands.ToggleState; + +import dwt.dwthelper.utils; + +/** + * <p> + * A piece of bool state grouped with other bool states. Of these states, + * only one may have a value of {@link bool#TRUE} at any given point in time. + * The values of all other states must be {@link bool#FALSE}. + * </p> + * <p> + * If this state is registered using {@link IMenuStateIds#STYLE}, then it will + * control the presentation of the command if displayed in the menus, tool bars + * or status line. + * </p> + * <p> + * Clients may instantiate or extend this interface. + * </p> + * + * @since 3.2 + */ +public class RadioState : ToggleState { + + /** + * The manager of radio groups within the application. This ensures that + * only one member of a radio group is active at any one time, and tracks + * group memberships. + */ + private static final class RadioStateManager { + + /** + * A group of radio states with the same identifier. + */ + private static final class RadioGroup : IStateListener { + + /** + * The active state. If there is no active state, then this value is + * <code>null</code>. + */ + private RadioState active = null; + + /** + * The current members in this group. If there are no members, then + * this value is <code>nlistenerull</code>. + */ + private Set!(RadioState) members = null; + + /** + * Activates a memeber. This checks to see if there are any other + * active members. If there are, they are deactivated. + * + * @param state + * The state that should become active; must not be + * <code>null</code>. + */ + private final void activateMember(RadioState state) { + if (active !is null && active !is state) { + active.setValue( new ValueWrapperBool( false )); + } + active = state; + } + + /** + * Adds a member to this radio group. If the state being added is + * active, then it replaces the currently active group memeber as + * the active state. + * + * @param state + * The state to add; must not be <code>null</code>. + */ + private final void addMember(RadioState state) { + if (members is null) { + members = new HashSet!(RadioState); + } + + members.add(state); + state.addListener(this); + + Object value = state.getValue(); + if ( auto v = cast(ValueWrapperBool)value ) { + if (v.value) { + activateMember(state); + } + } + } + + public final void handleStateChange(State state, + Object oldValue) { + Object newValue = state.getValue(); + if ( auto v = cast(ValueWrapperBool)newValue) { + if (v.value) { + activateMember(cast(RadioState) state); + } + } + } + + /** + * Removes a member from this radio group. If the state was the + * active state, then there will be no active state. + * + * @param state + * The state to remove; must not be <code>null</code>. + */ + private final void removeMember(RadioState state) { + state.removeListener(this); + if (active is state) { + active = null; + } + + if (members is null) { + return; + } + members.remove(state); + } + } + + /** + * The map of radio states indexed by identifier (<code>String</code>). + * The radio states is either a single <code>RadioState</code> + * instance or a <code>Collection</code> of <code>RadioState</code> + * instances. + */ + private static Map!(String,RadioState) radioStatesById = null; + + /** + * Activates a particular state within a given group. + * + * @param identifier + * The identifier of the group to which the state belongs; + * must not be <code>null</code>. + * @param state + * The state to activate; must not be <code>null</code>. + */ + private static final void activateGroup(String identifier, + RadioState state) { + if (radioStatesById is null) { + return; + } + + auto currentValue = radioStatesById.get(identifier); + if ( auto grp = cast(RadioGroup)currentValue) { + RadioGroup radioGroup = grp; + radioGroup.activateMember(state); + } + } + + /** + * Registers a piece of state with the radio manager. + * + * @param identifier + * The identifier of the radio group; must not be + * <code>null</code>. + * @param state + * The state to register; must not be <code>null</code>. + */ + private static final void registerState(String identifier, + RadioState state) { + if (radioStatesById is null) { + radioStatesById = new HashMap!(String,RadioState); + } + + auto currentValue = radioStatesById.get(identifier); + RadioGroup radioGroup; + if ( auto grp = cast(RadioGroup)currentValue) { + radioGroup = grp; + } else { + radioGroup = new RadioGroup(); + } + radioGroup.addMember(state); + } + + /** + * Unregisters a piece of state from the radio manager. + * + * @param identifier + * The identifier of the radio group; must not be + * <code>null</code>. + * @param state + * The state to unregister; must not be <code>null</code>. + */ + private static final void unregisterState(String identifier, + RadioState state) { + if (radioStatesById is null) { + return; + } + + auto currentValue = radioStatesById.get(identifier); + if ( auto grp = cast(RadioGroup)currentValue ) { + final RadioGroup radioGroup = grp; + radioGroup.removeMember(state); + } + } + } + + /** + * The identifier of the radio group to which this state belongs. This value + * may be <code>null</code> if this state doesn't really belong to a group + * (yet). + */ + private String radioGroupIdentifier = null; + + /** + * Unregisters this state from the manager, which detaches the listeners. + */ + public void dispose() { + setRadioGroupIdentifier(null); + } + + /** + * Sets the identifier of the radio group for this piece of state. If the + * identifier is cleared, then the state is unregistered. + * + * @param identifier + * The identifier of the radio group for this state; may be + * <code>null</code> if the identifier is being cleared. + * + */ + public final void setRadioGroupIdentifier(String identifier) { + if (identifier is null) { + RadioStateManager.unregisterState(radioGroupIdentifier, this); + radioGroupIdentifier = null; + } else { + radioGroupIdentifier = identifier; + RadioStateManager.registerState(identifier, this); + } + } + + /** + * Sets the value for this object. This notifies the radio state manager of + * the change. + * + * @param value + * The new value; should be a <code>bool</code>. + */ + public void setValue(Object value) { + if (!( cast(ValueWrapperBool)value )) { + throw new IllegalArgumentException( + "RadioState takes a bool as a value"); //$NON-NLS-1$ + } + + if (( cast(ValueWrapperBool)value ).value && (radioGroupIdentifier !is null)) { + RadioStateManager.activateGroup(radioGroupIdentifier, this); + } + + super.setValue(value); + } +}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/dwtx/jface/commands/ToggleState.d Fri Mar 28 18:27:09 2008 +0100 @@ -0,0 +1,76 @@ +/******************************************************************************* + * Copyright (c) 2005, 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 + * Port to the D programming language: + * Frank Benoit <benoit@tionex.de> + *******************************************************************************/ + +module dwtx.jface.commands.ToggleState; + +import dwtx.jface.menus.IMenuStateIds; +import dwtx.jface.preference.IPreferenceStore; + +import dwtx.jface.commands.PersistentState; + +import dwt.dwthelper.utils; + +/** + * <p> + * A piece of state storing a {@link bool}. + * </p> + * <p> + * If this state is registered using {@link IMenuStateIds#STYLE}, then it will + * control the presentation of the command if displayed in the menus, tool bars + * or status line. + * </p> + * <p> + * Clients may instantiate this class, but must not extend. + * </p> + * + * @since 3.2 + */ +public class ToggleState : PersistentState { + + /** + * Constructs a new <code>ToggleState</code>. By default, the toggle is + * off (e.g., <code>false</code>). + */ + public this() { + setValue(new ValueWrapperBool(false)); + } + + public final void load(IPreferenceStore store, + String preferenceKey) { + bool currentValue = (cast(ValueWrapperBool) getValue()).value; + store.setDefault(preferenceKey, currentValue); + if (shouldPersist() && (store.contains(preferenceKey))) { + bool value = store.getBoolean(preferenceKey); + setValue( new ValueWrapperBool( value )); + } + } + + public final void save(IPreferenceStore store, + String preferenceKey) { + if (shouldPersist()) { + Object value = getValue(); + if ( auto v = cast(ValueWrapperBool)value ) { + store.setValue(preferenceKey, v.value); + } + } + } + + public void setValue(Object value) { + if (!(cast(ValueWrapperBool)value)) { + throw new IllegalArgumentException( + "ToggleState takes a bool as a value"); //$NON-NLS-1$ + } + + super.setValue(value); + } +}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/dwtx/jface/menus/IMenuStateIds.d Fri Mar 28 18:27:09 2008 +0100 @@ -0,0 +1,42 @@ +/******************************************************************************* + * Copyright (c) 2005, 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 + * Port to the D programming language: + * Frank Benoit <benoit@tionex.de> + *******************************************************************************/ + +module dwtx.jface.menus.IMenuStateIds; + +import dwtx.core.commands.INamedHandleStateIds; +// import dwtx.jface.commands.RadioState; +// import dwtx.jface.commands.ToggleState; + +import dwt.dwthelper.utils; + +/** + * <p> + * State identifiers that should be understood by items and renderers of items. + * The state is associated with the command, and then interpreted by the menu + * renderer. + * </p> + * <p> + * Clients may implement or extend this class. + * </p> + * + * @since 3.2 + */ +public interface IMenuStateIds : INamedHandleStateIds { + + /** + * The state id used for indicating the widget style of a command presented + * in the menus and tool bars. This state must be an instance of + * {@link ToggleState} or {@link RadioState}. + */ + public static String STYLE = "STYLE"; //$NON-NLS-1$ +}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/dwtx/jface/preference/IPreferenceStore.d Fri Mar 28 18:27:09 2008 +0100 @@ -0,0 +1,587 @@ +/******************************************************************************* + * 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 + * Port to the D programming language: + * Frank Benoit <benoit@tionex.de> + *******************************************************************************/ +module dwtx.jface.preference.IPreferenceStore; + +import dwtx.jface.util.IPropertyChangeListener; + +import dwt.dwthelper.utils; + +/** + * 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>bool</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 bool preferences (<code>false</code>). + */ + public static const bool BOOLEAN_DEFAULT_DEFAULT = false; + + /** + * The default-default value for double preferences (<code>0.0</code>). + */ + public static const double DOUBLE_DEFAULT_DEFAULT = 0.0; + + /** + * The default-default value for float preferences (<code>0.0f</code>). + */ + public static const float FLOAT_DEFAULT_DEFAULT = 0.0f; + + /** + * The default-default value for int preferences (<code>0</code>). + */ + public static const int INT_DEFAULT_DEFAULT = 0; + + /** + * The default-default value for long preferences (<code>0L</code>). + */ + public static const long LONG_DEFAULT_DEFAULT = 0L; + + /** + * The default-default value for String preferences (<code>""</code>). + */ + public static const String STRING_DEFAULT_DEFAULT = ""; //$NON-NLS-1$ + + /** + * The string representation used for <code>true</code> (<code>"true"</code>). + */ + public static const String TRUE = "true"; //$NON-NLS-1$ + + /** + * The string representation used for <code>false</code> (<code>"false"</code>). + */ + public static const 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 DWT widget) will need to update in the + * correct Thread. In the case of an DWT 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 dwtx.jface.util.PropertyChangeEvent + * @see #setToDefault(String) + * @see #setValue(String, bool) + * @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 <code>true</code> if either a current value or a default + * value is known for the named preference, and <code>false</code> otherwise + */ + public bool 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 bool-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 bool. + * + * @param name the name of the preference + * @return the bool-valued preference + */ + public bool getBoolean(String name); + + /** + * Returns the default value for the bool-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 bool. + * + * @param name the name of the preference + * @return the default value of the named preference + */ + public bool 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 bool 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. + */ + public bool 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 + */ + 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 defaultObject the new default value for the preference + */ + public void setDefault(String name, String defaultObject); + + /** + * Sets the default value for the bool-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, bool 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 bool-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, bool value); +}