# HG changeset patch # User Frank Benoit # Date 1206725229 -3600 # Node ID 103ab03b77eb04d11308c7cb57e051d141264234 # Parent c876179528478f8eb30ad8e89f8860c5e2cab94d jface commands diff -r c87617952847 -r 103ab03b77eb dwtx/jface/commands/ActionHandler.d --- /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 + *******************************************************************************/ +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; + +/** + *

+ * This class adapts instances of IAction to + * IHandler. + *

+ * + * @since 3.1 + */ +public final class ActionHandler : AbstractHandler { + + /** + * The wrapped action. This value is never null. + */ + 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 + * IAction. + * + * @param action + * the action. Must not be null. + */ + 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 ~ ")"; + } +} diff -r c87617952847 -r 103ab03b77eb dwtx/jface/commands/PersistentState.d --- /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 + *******************************************************************************/ + +module dwtx.jface.commands.PersistentState; + +import dwtx.core.commands.State; +import dwtx.jface.preference.IPreferenceStore; + +import dwt.dwthelper.utils; + +/** + *

+ * This is a state that can be made persistent. A state is persisted to a + * preference store. + *

+ *

+ * Clients may extend this class. + *

+ * + * @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 null. + * @param preferenceKey + * The key at which the state is stored; must not be + * null. + */ + 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 + * null. + * @param preferenceKey + * The key at which the state should be stored; must not be + * null. + */ + 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 true if this state should be persisted; + * false otherwise. + */ + public bool shouldPersist() { + return persisted; + } +} diff -r c87617952847 -r 103ab03b77eb dwtx/jface/commands/RadioState.d --- /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 + *******************************************************************************/ + +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; + +/** + *

+ * 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}. + *

+ *

+ * 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. + *

+ *

+ * Clients may instantiate or extend this interface. + *

+ * + * @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 + * null. + */ + private RadioState active = null; + + /** + * The current members in this group. If there are no members, then + * this value is nlistenerull. + */ + 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 + * null. + */ + 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 null. + */ + 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 null. + */ + 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 (String). + * The radio states is either a single RadioState + * instance or a Collection of RadioState + * 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 null. + * @param state + * The state to activate; must not be null. + */ + 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 + * null. + * @param state + * The state to register; must not be null. + */ + 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 + * null. + * @param state + * The state to unregister; must not be null. + */ + 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 null 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 + * null 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 bool. + */ + 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); + } +} diff -r c87617952847 -r 103ab03b77eb dwtx/jface/commands/ToggleState.d --- /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 + *******************************************************************************/ + +module dwtx.jface.commands.ToggleState; + +import dwtx.jface.menus.IMenuStateIds; +import dwtx.jface.preference.IPreferenceStore; + +import dwtx.jface.commands.PersistentState; + +import dwt.dwthelper.utils; + +/** + *

+ * A piece of state storing a {@link bool}. + *

+ *

+ * 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. + *

+ *

+ * Clients may instantiate this class, but must not extend. + *

+ * + * @since 3.2 + */ +public class ToggleState : PersistentState { + + /** + * Constructs a new ToggleState. By default, the toggle is + * off (e.g., false). + */ + 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); + } +} diff -r c87617952847 -r 103ab03b77eb dwtx/jface/menus/IMenuStateIds.d --- /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 + *******************************************************************************/ + +module dwtx.jface.menus.IMenuStateIds; + +import dwtx.core.commands.INamedHandleStateIds; +// import dwtx.jface.commands.RadioState; +// import dwtx.jface.commands.ToggleState; + +import dwt.dwthelper.utils; + +/** + *

+ * 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. + *

+ *

+ * Clients may implement or extend this class. + *

+ * + * @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$ +} diff -r c87617952847 -r 103ab03b77eb dwtx/jface/preference/IPreferenceStore.d --- /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 + *******************************************************************************/ +module dwtx.jface.preference.IPreferenceStore; + +import dwtx.jface.util.IPropertyChangeListener; + +import dwt.dwthelper.utils; + +/** + * 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: + *
    + *
  • bool = 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 bool preferences (false). + */ + public static const bool BOOLEAN_DEFAULT_DEFAULT = false; + + /** + * The default-default value for double preferences (0.0). + */ + public static const double DOUBLE_DEFAULT_DEFAULT = 0.0; + + /** + * The default-default value for float preferences (0.0f). + */ + public static const float FLOAT_DEFAULT_DEFAULT = 0.0f; + + /** + * The default-default value for int preferences (0). + */ + public static const int INT_DEFAULT_DEFAULT = 0; + + /** + * The default-default value for long preferences (0L). + */ + public static const long LONG_DEFAULT_DEFAULT = 0L; + + /** + * The default-default value for String preferences (""). + */ + public static const String STRING_DEFAULT_DEFAULT = ""; //$NON-NLS-1$ + + /** + * The string representation used for true ("true"). + */ + public static const String TRUE = "true"; //$NON-NLS-1$ + + /** + * The string representation used for false ("false"). + */ + public static const 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 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). + *

+ *

+ * 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 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 true if either a current value or a default + * value is known for the named preference, and false 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. + *

+ * 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 bool-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 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 (false) 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 (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 bool 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 bool 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 bool-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, bool 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 bool-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, bool value); +}