maspack.properties

Class PropertyDesc

java.lang.Object

maspack.properties.PropertyDesc

All Implemented Interfaces:

PropertyInfo

Direct Known Subclasses:

FieldPropertyDesc

public class PropertyDesc
extends java.lang.Object
implements PropertyInfo

Provides information and implementation code for specific properties exported by a class.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PropertyDesc.TypeCode

Nested classes/interfaces inherited from interface maspack.properties.PropertyInfo

PropertyInfo.Edit, PropertyInfo.ExpandState

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	debug
static int	INHERITABLE
static int	READ_ONLY
static int	REGULAR

Constructor Summary

Constructors

Constructor and Description
PropertyDesc() Creates an empty PropertyDesc.
PropertyDesc(java.lang.String name, java.lang.Class<?> hostClass) Creates a new PropertyDesc object with a specific property name and host class.
PropertyDesc(java.lang.String name, java.lang.Class<?> hostClass, java.lang.Class<?> valueClass) Creates a new PropertyDesc for a property with a specified name, host class, and value class.

Method Summary

Modifier and Type	Method and Description
Property	createHandle(HasProperties host) Creates a handle to the property for a specified host object.
java.lang.Object	createInstance(HasProperties host)
java.util.List<java.lang.Class<?>>	getAllowedTypes() Returns a list of allowed classes that should be used for creating instances of this property.
boolean	getAutoWrite() Returns true if auto-writing is enabled for this property.
PropertyMode	getDefaultMode() Returns the default inheritance mode for the property.
NumericInterval	getDefaultNumericRange() Returns a default numeric range for this property, if any.
java.lang.Object	getDefaultValue() Returns the default value for the property, or Property.VoidValue if there is not default value.
java.lang.String	getDescription() Returns a text description of the property.
int	getDimension() Returns the numeric dimension of this property, or -1 if the property is not numeric or does not have a fixed dimension.
PropertyInfo.Edit	getEditing() Returns information describing the conditions under which this property should be interactively edited.
NumberFormat	getFormat() Returns the formatter used to convert numeric components of the property's value into text.
java.lang.Class<?>	getHostClass() Returns the host class of the property.
java.lang.Object	getKey() Returns the key for the property associated with this descriptor, or null if there is no key.
PropertyMode	getMode(HasProperties host)
java.lang.String	getName() Returns the name of the property associated with this descriptor.
boolean	getNullValueOK() Returns true if the property value may be null.
java.lang.String	getPrintFormat() Returns a format string used to convert numeric components of the property's value into text.
Range	getRange(HasProperties host)
static PropertyDesc.TypeCode	getTypeCode(java.lang.Class<?> cls)
java.lang.Object	getValue(HasProperties host)
java.lang.Class<?>	getValueClass() Returns the class type for the property's value.
PropertyInfo.ExpandState	getWidgetExpandState()
boolean	hasRestrictedRange() Returns true if the property has a restricted value range.
static boolean	initialize(PropertyDesc desc, java.lang.String nameAndMethods, java.lang.Object key, java.lang.Class<?> hostClass, java.lang.String descriptor, java.lang.Object defaultValue, java.lang.String options, int propType)
static boolean	initialize(PropertyDesc desc, java.lang.String name, java.lang.String methods, java.lang.Object key, java.lang.Class<?> hostClass, java.lang.String descriptor, java.lang.Object defaultValue, java.lang.String options, int propType)
boolean	isInheritable() Returns true if the property is a inheritable property.
boolean	isReadOnly() Returns true if the property is read-only.
boolean	isSharable() Returns true if the value of this property is sharable among several hosts.
boolean	isSliderAllowed() Returns true if a slider is allowed to be used in the interactive editing widget created for this property.
java.lang.Object	scanInstance(ReaderTokenizer rtok) For a property whose class type implements Scannable, attempts to create and return a class instance based on input from a tokenizer.
java.lang.Object	scanValue(ReaderTokenizer rtok) Scans a value of the type associated with the property from a ReaderTokenizer.
static java.lang.Object	scanValue(ReaderTokenizer rtok, PropertyDesc.TypeCode valueType, java.lang.Class<?> valueClass) Static version of scanValue(maspack.util.ReaderTokenizer, maspack.properties.PropertyDesc.TypeCode, java.lang.Class<?>), with the value type and class explicitly specified.
void	set(PropertyDesc desc, java.lang.Class<?> hostClass) Sets this PropertyDesc from an existing one and a a specified host class.
void	setAllowedTypes(java.util.List<java.lang.Class<?>> types)
void	setAutoWrite(boolean enable)
void	setDefaultValue(java.lang.Object value)
void	setDescription(java.lang.String text) Sets a text description for the property.
void	setDimension(int dim)
void	setEditing(PropertyInfo.Edit edit)
void	setFormat(NumberFormat fmt) Directly sets the formatter used to convert numeric components of the property's value into text.
void	setGetMethod(java.lang.String methodName)
void	setGetModeMethod(java.lang.String methodName)
void	setKey(java.lang.Object key) Sets a key for the property associated with this descriptor.
void	setMode(HasProperties host, PropertyMode mode)
void	setName(java.lang.String name) Sets the name of the property associated with this descriptor.
void	setNullValueOK(boolean allowed)
void	setNumericRange(NumericInterval rng) Sets a NumericRange for this property.
void	setPrintFormat(java.lang.String fmtStr) Sets the formatter used to convert numeric components of the property's value into text.
void	setSetMethod(java.lang.String methodName)
void	setSetModeMethod(java.lang.String methodName)
void	setSliderAllowed(boolean allowed)
void	setValue(HasProperties host, java.lang.Object value)
void	setWidgetExpandState(PropertyInfo.ExpandState state)
boolean	valueEqualsDefault(java.lang.Object value) Returns true if a specified value equals the default value of the property.
boolean	writeIfNonDefault(HasProperties host, java.io.PrintWriter pw, NumberFormat fmt, java.lang.Object ref)
void	writeValue(java.lang.Object value, java.io.PrintWriter pw, NumberFormat fmt, java.lang.Object ref) Writes a value of the type associated with the property out to a PrintWriter.
static boolean	writeValue(java.lang.Object value, java.io.PrintWriter pw, PropertyDesc.TypeCode valueType, java.lang.Class<?> valueClass, NumberFormat floatFmt, NumberFormat fmt, java.lang.Object ref)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

debug

public static boolean debug

REGULAR

public static final int REGULAR

See Also:

Constant Field Values

READ_ONLY

public static final int READ_ONLY

See Also:

Constant Field Values

INHERITABLE

public static final int INHERITABLE

See Also:

Constant Field Values

Constructor Detail

PropertyDesc

public PropertyDesc()

Creates an empty PropertyDesc.

PropertyDesc

public PropertyDesc(java.lang.String name,
                    java.lang.Class<?> hostClass)

Creates a new PropertyDesc object with a specific property name and host class.

Parameters:

name - name of the property.

hostClass - host class for the property.

PropertyDesc

public PropertyDesc(java.lang.String name,
                    java.lang.Class<?> hostClass,
                    java.lang.Class<?> valueClass)

Creates a new PropertyDesc for a property with a specified name, host class, and value class.

Parameters:

name - property name

hostClass - class object for the host class.

valueClass - class object for the value.

Method Detail

set

public void set(PropertyDesc desc,
                java.lang.Class<?> hostClass)

Sets this PropertyDesc from an existing one and a a specified host class.

getTypeCode

public static PropertyDesc.TypeCode getTypeCode(java.lang.Class<?> cls)

getValueClass

public java.lang.Class<?> getValueClass()

Returns the class type for the property's value.

Specified by:

getValueClass in interface PropertyInfo

Returns:

property value class type

getName

public java.lang.String getName()

Returns the name of the property associated with this descriptor.

Specified by:

getName in interface PropertyInfo

Returns:

name of the property

setName

public void setName(java.lang.String name)

Sets the name of the property associated with this descriptor.

Parameters:

name - new name of the property

getKey

public java.lang.Object getKey()

Returns the key for the property associated with this descriptor, or null if there is no key.

Returns:

key for the property

setKey

public void setKey(java.lang.Object key)

Sets a key for the property associated with this descriptor. If present, a key is passed as an additonal (leading) argument to the various set/get accessors.

Parameters:

key - new key for the property

getDescription

public java.lang.String getDescription()

Returns a text description of the property. This can be used for generating documentation, GUI tool tips, etc.

Specified by:

getDescription in interface PropertyInfo

Returns:

text description of the property

See Also:

setDescription(java.lang.String)

setDescription

public void setDescription(java.lang.String text)

Sets a text description for the property.

Parameters:

text - new text description

See Also:

getDescription()

getHostClass

public java.lang.Class<?> getHostClass()

Returns the host class of the property.

Specified by:

getHostClass in interface PropertyInfo

Returns:

host class of the property

setPrintFormat

public void setPrintFormat(java.lang.String fmtStr)

Sets the formatter used to convert numeric components of the property's value into text. The formatter is specified using a C printf-style format string. For a description of the format string syntax, see NumberFormat. The format should be consistent with the numeric type (e.g., %d or %x for integers, %g, $f or %e for floats).

Parameters:

fmtStr - numeric format string for the property

Throws:

java.lang.IllegalArgumentException - if the format string syntax is invalid

See Also:

getFormat()

setFormat

public void setFormat(NumberFormat fmt)

Directly sets the formatter used to convert numeric components of the property's value into text.

Parameters:

fmt - numeric formatter for the property

See Also:

getFormat(), setPrintFormat(String)

getFormat

public NumberFormat getFormat()

Returns the formatter used to convert numeric components of the property's value into text. The formatter may be null if there is no numeric data associated with the property.

Returns:

numeric formatter

See Also:

setFormat(NumberFormat), setPrintFormat(String)

getPrintFormat

public java.lang.String getPrintFormat()

Returns a format string used to convert numeric components of the property's value into text. This string may be null if there is no numeric data associated with the property.

Specified by:

getPrintFormat in interface PropertyInfo

Returns:

numeric format string

See Also:

setFormat(NumberFormat), setPrintFormat(String)

getAutoWrite

public boolean getAutoWrite()

Returns true if auto-writing is enabled for this property. Auto-writing means that the property and it's value should be written out by the method PropertyList.writeProps.

Specified by:

getAutoWrite in interface PropertyInfo

Returns:

true if auto-writing is enabled for this property

setAutoWrite

public void setAutoWrite(boolean enable)

getNullValueOK

public boolean getNullValueOK()

Returns true if the property value may be null.

Specified by:

getNullValueOK in interface PropertyInfo

Returns:

true if the property value may be null

setNullValueOK

public void setNullValueOK(boolean allowed)

getEditing

public PropertyInfo.Edit getEditing()

Returns information describing the conditions under which this property should be interactively edited.

Specified by:

getEditing in interface PropertyInfo

Returns:

conditions for interactive editing.

setEditing

public void setEditing(PropertyInfo.Edit edit)

getWidgetExpandState

public PropertyInfo.ExpandState getWidgetExpandState()

Specified by:

getWidgetExpandState in interface PropertyInfo

setWidgetExpandState

public void setWidgetExpandState(PropertyInfo.ExpandState state)

isSliderAllowed

public boolean isSliderAllowed()

Returns true if a slider is allowed to be used in the interactive editing widget created for this property. In addition to this, creation of sliders also require that the property have a numeric value and a valid range.

Specified by:

isSliderAllowed in interface PropertyInfo

Returns:

true if a slider is allowed in the widget

setSliderAllowed

public void setSliderAllowed(boolean allowed)

isReadOnly

public boolean isReadOnly()

Returns true if the property is read-only. A property is read-only if it's value cannot be set using the the Property.set method. getAutoWrite should return false for read-only properties, since it makes no sense to try to save such properties in persistent storage.

Specified by:

isReadOnly in interface PropertyInfo

Returns:

true if the property is read-only

hasRestrictedRange

public boolean hasRestrictedRange()

Returns true if the property has a restricted value range. If the property has a restricted range, the Property.getRange() method can be used to obtain a Range object to determine whether or not a particular value is legal.

Specified by:

hasRestrictedRange in interface PropertyInfo

Returns:

true if the property has a restricted value range

getDimension

public int getDimension()

Returns the numeric dimension of this property, or -1 if the property is not numeric or does not have a fixed dimension.

Specified by:

getDimension in interface PropertyInfo

setDimension

public void setDimension(int dim)

isSharable

public boolean isSharable()

Description copied from interface: PropertyInfo

Returns true if the value of this property is sharable among several hosts. This implies that the host does not maintain an internal copy of the value. Changes to the value itself may therefore effect several hosts.

Specified by:

isSharable in interface PropertyInfo

Returns:

true if the property value can be shared by several hosts

setGetMethod

public void setGetMethod(java.lang.String methodName)

setSetMethod

public void setSetMethod(java.lang.String methodName)

setGetModeMethod

public void setGetModeMethod(java.lang.String methodName)

setSetModeMethod

public void setSetModeMethod(java.lang.String methodName)

setDefaultValue

public void setDefaultValue(java.lang.Object value)

getDefaultValue

public java.lang.Object getDefaultValue()

Description copied from interface: PropertyInfo

Returns the default value for the property, or Property.VoidValue if there is not default value.

Specified by:

getDefaultValue in interface PropertyInfo

Returns:

property's default value

createHandle

public Property createHandle(HasProperties host)

Creates a handle to the property for a specified host object. The host must export the property (i.e., it must be an instance of the class returned by getHostClass).

Specified by:

createHandle in interface PropertyInfo

Returns:

property handle

createInstance

public java.lang.Object createInstance(HasProperties host)
                                throws java.lang.InstantiationException,
                                       java.lang.IllegalAccessException

Throws:

java.lang.InstantiationException

java.lang.IllegalAccessException

getValue

public java.lang.Object getValue(HasProperties host)

getRange

public Range getRange(HasProperties host)

setValue

public void setValue(HasProperties host,
                     java.lang.Object value)

getMode

public PropertyMode getMode(HasProperties host)

setMode

public void setMode(HasProperties host,
                    PropertyMode mode)

initialize

public static boolean initialize(PropertyDesc desc,
                                 java.lang.String nameAndMethods,
                                 java.lang.Object key,
                                 java.lang.Class<?> hostClass,
                                 java.lang.String descriptor,
                                 java.lang.Object defaultValue,
                                 java.lang.String options,
                                 int propType)

initialize

public static boolean initialize(PropertyDesc desc,
                                 java.lang.String name,
                                 java.lang.String methods,
                                 java.lang.Object key,
                                 java.lang.Class<?> hostClass,
                                 java.lang.String descriptor,
                                 java.lang.Object defaultValue,
                                 java.lang.String options,
                                 int propType)

valueEqualsDefault

public boolean valueEqualsDefault(java.lang.Object value)

Description copied from interface: PropertyInfo

Returns true if a specified value equals the default value of the property.

Specified by:

valueEqualsDefault in interface PropertyInfo

Parameters:

value - value to check against the default

Returns:

true if the value equals the default value

getDefaultNumericRange

public NumericInterval getDefaultNumericRange()

Returns a default numeric range for this property, if any. If there is no default numeric range, null is returned.

If a getRangeMethod is not defined for the property, and the property has a numeric type, then the default numeric range is returned by the property's getRange method. The default numeric range is also used to determine bounds on slider widgets for manipulating the property's value, in case the upper or lower limits returned by the getRange method are unbounded.

Specified by:

getDefaultNumericRange in interface PropertyInfo

Returns:

default numeric range for this property

See Also:

setNumericRange(maspack.util.NumericInterval)

setNumericRange

public void setNumericRange(NumericInterval rng)

Sets a NumericRange for this property. A null argument will cause any existing NumericRange to be removed. At present, numeric ranges are mainly used when automatically creating GUI sliders to manipulate property values.

Parameters:

rng - new numeric range for this property (value is copied).

writeIfNonDefault

public boolean writeIfNonDefault(HasProperties host,
                                 java.io.PrintWriter pw,
                                 NumberFormat fmt,
                                 java.lang.Object ref)
                          throws java.io.IOException

Specified by:

writeIfNonDefault in interface PropertyInfo

Throws:

java.io.IOException

writeValue

public static boolean writeValue(java.lang.Object value,
                                 java.io.PrintWriter pw,
                                 PropertyDesc.TypeCode valueType,
                                 java.lang.Class<?> valueClass,
                                 NumberFormat floatFmt,
                                 NumberFormat fmt,
                                 java.lang.Object ref)
                          throws java.io.IOException

Throws:

java.io.IOException

writeValue

public void writeValue(java.lang.Object value,
                       java.io.PrintWriter pw,
                       NumberFormat fmt,
                       java.lang.Object ref)
                throws java.io.IOException

Writes a value of the type associated with the property out to a PrintWriter.

Specified by:

writeValue in interface PropertyInfo

Parameters:

value - value to be written

pw - PrintWriter to which value is written

fmt - Numeric formatting information. This is only used when the value to be written is itself Scannable, in which case it is passed to that value's write method.

ref - Reference object. This is only used when the value to be written is itself Scannable, in which case it is passed to that value's write method.

Throws:

java.io.IOException - if an I/O error occurred, or the value has a type which PropertyInfo does not know about

scanValue

public static java.lang.Object scanValue(ReaderTokenizer rtok,
                                         PropertyDesc.TypeCode valueType,
                                         java.lang.Class<?> valueClass)
                                  throws java.io.IOException

Static version of scanValue(maspack.util.ReaderTokenizer, maspack.properties.PropertyDesc.TypeCode, java.lang.Class<?>), with the value type and class explicitly specified.

Parameters:

rtok - ReaderTokenizer supplying input tokens used to specify the property value

valueType - Code specifying the class type of the value. It is possible to obtain this from valueClass by calling getTypeCode(java.lang.Class<?>).

valueClass - Class type for the value

Returns:

scanned object value

Throws:

java.io.IOException - if the input is not in the correct format, an I/O error occurred, or the value has a type which PropertyInfo does not know about

scanInstance

public java.lang.Object scanInstance(ReaderTokenizer rtok)
                              throws java.io.IOException

For a property whose class type implements Scannable, attempts to create and return a class instance based on input from a tokenizer.

1. If the next token is a word, then this token is read. If it is "null", then no instance is created and null is returned. Otherwise, the word is assumed to be the name of a class for which an instance is created and returned. The class must equal or be a subclass of the property's value class.
2. If the next token is not a word, then no token is read and an instance of the property's value class is created and returned.

Any returned value instance will need to subsequently scan itself from the input stream using its scan method. As mentioned above, it is assumed the initial token required for this scan is a '['.

Since this method temporarily changes the accepted word characters in order to read a class name, it should not be called if the next available token might have been pushed back on the token stream using pushBack().

Specified by:

scanInstance in interface PropertyInfo

Parameters:

rtok - ReaderTokenizer supplying input tokens

Returns:

A new instance of the property type (or specified subclass), or null if "null" appears as the next token.

Throws:

java.io.IOException - if no class is found for the class name specified in the input stream, or the class is not equal to, or a subclass of, the property's value class, or the class cannot be instantiated.

scanValue

public java.lang.Object scanValue(ReaderTokenizer rtok)
                           throws java.io.IOException

Scans a value of the type associated with the property from a ReaderTokenizer.

Since this method temporarily changes the accepted word characters in order to read a class name, it should not be called if the next available token might have been pushed back on the token stream using pushBack().

Specified by:

scanValue in interface PropertyInfo

Parameters:

rtok - ReaderTokenizer supplying input tokens used to specify the property value

Throws:

java.io.IOException - if the input is not in the correct format, an I/O error occurred, or the value has a type which PropertyInfo does not know about

isInheritable

public boolean isInheritable()

Returns true if the property is a inheritable property.

Specified by:

isInheritable in interface PropertyInfo

getDefaultMode

public PropertyMode getDefaultMode()

Returns the default inheritance mode for the property. If the property is not inheritable, then this method should return PropertyMode.Explicit.

Specified by:

getDefaultMode in interface PropertyInfo

Returns:

default inheritance mode

setAllowedTypes

public void setAllowedTypes(java.util.List<java.lang.Class<?>> types)

getAllowedTypes

public java.util.List<java.lang.Class<?>> getAllowedTypes()

Returns a list of allowed classes that should be used for creating instances of this property. All classes should be subclasses of the calss returned by PropertyInfo.getValueClass(). If there are no restrictions, this method should return null. At present, this method is intended as a hint for use in widgets that manipulate the property value.

Specified by:

getAllowedTypes in interface PropertyInfo

Returns:

list of allowed classes