vmm.core
Class Parameter

java.lang.Object
  vmm.core.Parameter

Direct Known Subclasses:

ComplexParam, IntegerParam, RealParam

public abstract class Parameter
extends java.lang.Object

Represents a settable numeric parameter associated with another object, such as a View or Exhibit. A parameter is meant to be an attribute of a single object, which is its "owner." The owner implements interface Parameterizable, which defines a method Parameterizable.parameterChanged(Parameter, Object, Object). When a Parameter's value is changed, it calls this method in its owner.

The value of a parameter can be set from a String that represents a constant expression. When the value is set in this way, the String is saved so that it can be returned when the parameter is converted to string form with the getValueAsString method. This allows parameters to have values such as "2*pi".

In addition to its value, a parameter has a "default value" that is used (in the VMM core) only when the user clicks the "Defaults" button in a ParameterDialog. The default value is set the first time the parameter's value is set, and it can be explicitely reset later.

Parameters can be (at least) integers, real numbers, or complex numbers. These possibilities are repesented by different subclasses. Some parameters are "animated"; animated parameters implement the interface Animateable.

Constructor Summary

protected	Parameter(java.lang.String name, java.lang.Object value) Creates a parameter with a specified name and value object.
	Parameter(java.lang.String name, java.lang.String valueAsString) Create a parameter with a specified name and value, where the value is given as a string.

Method Summary

ParameterInput	createParameterInput(int inputType) Returns an input box for getting the value, animation start value, or animation end value from the user.
java.lang.String	getDefaultValueAsString() Returns a non-null string representation of this Parameter's default value.
java.lang.Object	getDefaultValueObject() Returns the default value of this parameter.
java.lang.String	getHint() The text returned by this method, if any, is used as a ToolTip on the name of the parameter in parameter dialogs.
java.lang.String	getName() Returns the name of this parameter.
Parameterizable	getOwner() Returns the owner of this parameter.
java.lang.String	getTitle() This method is meant to return a human-readable title or description for this parameter (one that could be used in a menu, for example).
java.lang.String	getValueAsString() Returns a non-null string representation of this Parameter's value.
java.lang.Object	getValueObject() Returns the value of this object as an Object.
protected void	reset(java.lang.Object value) Set both the value and the default value of the parameter to the specified value Object, as if that object had been passed to the constructor.
void	reset(java.lang.String valueAsString) Set both the value and the default value of the parameter to the value encoded in the given string, as if that string had been passed to the constructor.
void	setDefaultValueFromString(java.lang.String valueAsString) Sets the default value of this parameter from a string representation of the value.
void	setDefaultValueObject(java.lang.Object object) Explicitely set the default value object for this Parameter.
void	setName(java.lang.String name) Sets the name of this object.
void	setOwner(Parameterizable owner) Sets the owner of this parameter.
void	setValueAndDefaultFromString(java.lang.String valueAsString) Sets both the value and the default value of this parameter from a string representation of the value.
void	setValueFromString(java.lang.String valueAsString) Sets the value of this parameter from a string representation of the value.
void	setValueObject(java.lang.Object value) Sets a new value for this parameter and calls the parameterChanged method in the parameter's owner (if there is an owner).
protected abstract java.lang.Object	stringToValueObject(java.lang.String str) Convert a string rerpesentation of a parameter value to a representation of that same value as an object.
java.lang.String	toString() Returns a string including both the title and value of this Parameter.
protected java.lang.String	valueObjectToString(java.lang.Object obj) Returns a string representation of this Parameter's value.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Parameter

protected Parameter(java.lang.String name,
                    java.lang.Object value)

Creates a parameter with a specified name and value object. The owner of the Parameter is initially set to null. Ordinarily, it will be set automatically when the parameter is associated with Parameterizable object. This is done, for example, in the View and Exhibit classes, so that most programmers don't have to think about the owner.

Parameters:

name - The name for the parameter. If null, the parameter has no name.

value - The initial value and default value for this parameter. This should be of the correct type for the particular kind of parameter that is being constructed. If this is null, the parameter is considered to have value zero.

Parameter

public Parameter(java.lang.String name,
                 java.lang.String valueAsString)

Create a parameter with a specified name and value, where the value is given as a string. The string will be run through the stringToValueObject method to convert the string to a numerical object; this can generate an error if the string does not represent a legal value. The owner of the Parameter is initially set to null. Ordinarily, the owner will be set automatically when the parameter is associated with Parameterizable object.

For "animated" parameters, this constructor should also set the animation start and end values equal to the value.

Parameters:

name - The name for the parameter. If null, the parameter has no name.

valueAsString - The value of the parameter, as a string that will be parsed to get the numeric value. This value also becomes the default value of the parameter. If null, the parameter is considered to have value zero.

Method Detail

reset

protected void reset(java.lang.Object value)

Set both the value and the default value of the parameter to the specified value Object, as if that object had been passed to the constructor. For animated parameters, this should include setting the animation start and end values and default values to the same value.

reset

public void reset(java.lang.String valueAsString)

Set both the value and the default value of the parameter to the value encoded in the given string, as if that string had been passed to the constructor. For animated parameters, this should include setting the animation start and end values and default values to the same value. This is primarily meant to be called in the constructor of an Exhibit when it wants to change the value of a parameter that is inherited from a superclass.

Note: In this class, this method simply calls setValueAndDefaultFromString(valueAsString).

See Also:

reset(Object), stringToValueObject(String)

valueObjectToString

protected java.lang.String valueObjectToString(java.lang.Object obj)

Returns a string representation of this Parameter's value. It shoudl be possible to pass the string that is returned by this method to the setValueFromString method to restore the value of the Parameter. In the top-level Parameter class, the return value is computed using the toString method of the value object, except that if the value object is null, then the return value is the string "0". This should be OK, but subclasses can override this method if necessary.

This method is called in the Parameter class to convert betweeen the object and the string representation of a parameter's value and default value.

Parameters:

obj - A parameter value represented as an object.

Returns:

A string representation of the value.

See Also:

stringToValueObject(String)

stringToValueObject

protected abstract java.lang.Object stringToValueObject(java.lang.String str)

Convert a string rerpesentation of a parameter value to a representation of that same value as an object. The object will be of the correct type for this parameter, presumably Integer, Double, or Complex, depending on the parameter type. The value should be obtained by parsing the string to allow for constant expressions such as "2*pi". This parsing might generate an error. If an error is generated, it should be of type NumberFormatException.

Parameters:

str - A string representation of a value for the parameter, possibly as a constant expression such as "2*pi"

Returns:

An object representing the value, presumably of type Integer, Double, or Complex.

getOwner

public Parameterizable getOwner()

Returns the owner of this parameter. The value will be null if this parameter has no owner.

setOwner

public void setOwner(Parameterizable owner)

Sets the owner of this parameter. The owner can be null, meaning that the parameter has no owner. This method is called automatically when the parameter is added to an Exhibit or View.

getValueObject

public java.lang.Object getValueObject()

Returns the value of this object as an Object. The value can be null. It is not guaranteed that the value will be of the correct type, but subclasses might provide such a guarantee.

setValueObject

public void setValueObject(java.lang.Object value)

Sets a new value for this parameter and calls the parameterChanged method in the parameter's owner (if there is an owner). In this class, "owner.parameterChanged()" is called only if the value of the parameter actually does change; the equals() method is used to check for object equality. No other method is provided for setting the private value object, so all changes to the value object must go throught this method.

Parameters:

value - The new value of this parameter. The value is set without checking whether the value is of the correct type for this parameter. A type-cast error might result at some later time. Subclasses might override this method to guarantee that the object is of the correct type.

setDefaultValueObject

public void setDefaultValueObject(java.lang.Object object)

Explicitely set the default value object for this Parameter. The default value is also set, automatically, the first time that a non-null value object is specified, either in the constructor or in a call to setValueObject(). The value is set without checking whether the value of the correct type for this parameter. Note that only a pointer to the specified value is saved -- if the object is modified later, the default value of the parameter will change. The default value is used only in the getDefaultValueObject method.

getDefaultValueObject

public java.lang.Object getDefaultValueObject()

Returns the default value of this parameter.

See Also:

setDefaultValueObject(Object)

setName

public void setName(java.lang.String name)

Sets the name of this object. The name is used internally in programs. It is not meant to be human-readable. In many cases, it will be in a format that can be used as a key in a properties file, which can map the name to a human-readable "title". The name can be null. A typical name might consist of the class name of the owner combined with a name for this particular parameter of the owner. In general, the name of a parameter should uniquely identify the parameters among all parameters associated with an Exhibit and with any View that displays that Exhibit.

getName

public java.lang.String getName()

Returns the name of this parameter. The name can be null.

getTitle

public java.lang.String getTitle()

This method is meant to return a human-readable title or description for this parameter (one that could be used in a menu, for example). In this class, the title is obtained by calling the method I18n.tr(name) where "name" is the name of this parameter as returned by getName, or is "unnamed.parameter" if the name is null. Note that as a result of the definition of I18n.tr, if the name is non-null and is not mapped to a property, then the title will be the same as the name.

See Also:

setName(String), I18n.tr(String)

getHint

public java.lang.String getHint()

The text returned by this method, if any, is used as a ToolTip on the name of the parameter in parameter dialogs. If the return value in this class is null, no ToolTip is associated with the parameter name. The method in this class returns the value of I18n.trIfFound(getName() + ".hint"). If the name is null, the return value is null.

getValueAsString

public final java.lang.String getValueAsString()

Returns a non-null string representation of this Parameter's value. It should be possible to use the returned value as a parameter to setValueFromString to restore the parameter to the same value. The value is obtained as follows: If this parameter's value was set most recently from a String, then that string is returned. Otherwise, if the parameter's value object is null, then the string "0" is returned. And if not, then the return value is obtained by applying the valueObjectToString method to the value object.

See Also:

valueObjectToString(Object)

getDefaultValueAsString

public java.lang.String getDefaultValueAsString()

Returns a non-null string representation of this Parameter's default value. If the Parameter's default value was set from a String, then that string is returned. Otherwise, if this Parameter's default value object is null, the return value is the string "0", and if not, then the return value is constructed by applying the valueObjectToString method to the default value object.

setValueFromString

public final void setValueFromString(java.lang.String valueAsString)

Sets the value of this parameter from a string representation of the value. The actual value is obtained from the stringToValueObject method.

Parameters:

valueAsString - A string representing the new value for this parameter. This string is passed to the stringToValueObject method to get the actual parameter value. This might result in a NumberFormatExcpetion or other error if the string does not represent a legal value for this parameter.

See Also:

stringToValueObject(String)

setDefaultValueFromString

public final void setDefaultValueFromString(java.lang.String valueAsString)

Sets the default value of this parameter from a string representation of the value. The actual value is obtained from the stringToValueObject method.

Parameters:

valueAsString - A string representing the new default value for this parameter. This string is passed to the stringToValueObject method to get the actual default value. This might result in an error if the string does not represent a legal value.

See Also:

stringToValueObject(String)

setValueAndDefaultFromString

public final void setValueAndDefaultFromString(java.lang.String valueAsString)

Sets both the value and the default value of this parameter from a string representation of the value.

Parameters:

valueAsString - string representing the value. This string is passed to the stringToValueObject method to get the actual value.

createParameterInput

public ParameterInput createParameterInput(int inputType)

Returns an input box for getting the value, animation start value, or animation end value from the user.

Parameters:

inputType - One of the constants ParameterInput.VALUE, ParameterInput.ANIMATION_START or ParameterInput.ANIMATION_END, indicating which type of value this method is meant to return.

Returns:

a ParameterInput consructed by calling new ParameterInput(this,inputType).

toString

public java.lang.String toString()

Returns a string including both the title and value of this Parameter. The string is constructed as: getTitle() + "(" + getValueAsString() + ")".

Overrides:

toString in class java.lang.Object

See Also:

getValueAsString()