Package org.opensourcephysics.ejs.control

Class ControlElement

java.lang.Object

org.opensourcephysics.ejs.control.ControlElement

Direct Known Subclasses:

ControlDrawable, ControlSwingElement

public abstract class ControlElement
extends java.lang.Object

ControlElement is a base class for an object that can be managed using a series of configurable properties, hold actions that when invoked graphically call other objects' methods, and be responsible for the display and change of one or more internal variables.

ControlElements can be included into a GroupControl, thus acting in a coordinated way.

In fact, the best way to use a ControlElement, is to include it into a GroupControl and then configure it using the setProperty() method.

After this, the value common to several of these ControlElements can be set and retrived using a single setValue() or getValue() call from the ControlGroup.

You can also add any action you want to a ControlElement, but it is the implementing class' responsability to trigger an action in response to a user's gesture (with the mouse or keyboard)

See Also:

GroupControl

Field Summary

Fields

Modifier and Type	Field	Description
static int	ACTION
protected boolean	isUnderEjs
static int	METHOD_FOR_VARIABLE
static java.lang.String	METHOD_TRIGGER
protected GroupControl	myGroup
protected java.lang.Object	myObject
protected java.util.Hashtable<java.lang.String,java.lang.String>	myPropertiesTable
static int	NAME
static int	VARIABLE_CHANGED

Constructor Summary

Constructors

Constructor	Description
ControlElement(java.lang.Object _object)	Constructor ControlElement

Method Summary

Modifier and Type	Method	Description
ControlElement	addAction(int _type, java.lang.Object _target, java.lang.String _method)	Defines a generic action that can be invoked from this ControlElement.
ControlElement	addAction(int _type, java.lang.Object _target, java.lang.String _method, MethodWithOneParameter _secondAction)	This is an advanced form of addAction that allows for nested actions
ControlElement	addAction(int _type, java.lang.String _method)	Similar to the other addAction but extracts the target from the method, which must be of the form 'target.method:optional parameter', where target has been previously added to the list of targets of the group.
void	destroy()	Clears any trace of myself (specially in the group)
java.awt.Component	getComponent()	Provided for backwards compatibiliy only
GroupControl	getGroup()	Gets the GroupControl in which it operates
java.lang.Object	getObject()
java.lang.String	getProperty(java.lang.String _property)	Returns the value of a property.
abstract java.lang.String	getPropertyInfo(java.lang.String _property)	Returns information about a given property.
abstract java.util.ArrayList<java.lang.String>	getPropertyList()	Returns the list of all properties that can be set for this ControlElement.
Simulation	getSimulation()	Gets the Simulation in which it runs
Value	getValue(int _index)	Gets the value of any internal variable.
java.awt.Component	getVisual()	Provided for backwards compatibiliy only
boolean	implementsProperty(java.lang.String _property)	Whether the element implements a given property
void	initialize()	initializes the element.
void	invokeActions()	Invokes all actions of type ACTION
void	invokeActions(int _type)	Invokes all actions of this BasicControl of a given type
boolean	isActive()	Returns the active status of the ControlElement.
Value	parseConstant(java.lang.String _propertyType, java.lang.String _value)	Checks if a value can be considered a valid constant value for a property If not, it returns null, meaning the value can be considered to be a GroupVariable
boolean	propertyIsTypeOf(java.lang.String _property, java.lang.String _keyword)	Returns wether a property information contains a given keyword in its preamble
java.lang.String	propertyType(java.lang.String _property)	Returns the type of the property
void	removeAction(int _type, java.lang.Object _target, java.lang.String _method)	Removes an action.
void	removeAction(int _type, java.lang.String _method)	Similar to removeAction but extracts the target from the method
void	reset()	resets the element
void	setActive(boolean _act)	Sets whether a ControlElement actually invokes actions.
void	setDefaultValue(int _index)
void	setGroup(GroupControl _group)	Sets the GroupControl in which to operate
ControlElement	setProperties(java.lang.String _propertyList)	Sets more than one property at once.
ControlElement	setProperty(java.lang.String _property, java.lang.String _value)	Sets a property for this ControlElement.
void	setValue(int _index, Value _value)	Sets the value of the registered variables.
java.lang.String	toString()	Reports its name, if it has been set.
void	variableChanged(int _variableIndex, Value _value)	Reports changes of internal variables
void	variableChangedDoNotUpdate(int _variableIndex, Value _value)	Reports changes of internal variables but simulation doesn't update Needed by RadioButtons
void	variablePropertiesClear()	Clear all registered internal variable properties
void	variablesChanged(int[] _variableIndex, Value[] _value)	Reports changes of more than one internal variables

Methods inherited from class java.lang.Object

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

Field Detail

myGroup

protected GroupControl myGroup

myPropertiesTable

protected java.util.Hashtable<java.lang.String,java.lang.String> myPropertiesTable

myObject

protected java.lang.Object myObject

isUnderEjs

protected boolean isUnderEjs

NAME

public static final int NAME

See Also:

Constant Field Values

ACTION

public static final int ACTION

See Also:

Constant Field Values

VARIABLE_CHANGED

public static final int VARIABLE_CHANGED

See Also:

Constant Field Values

METHOD_FOR_VARIABLE

public static final int METHOD_FOR_VARIABLE

See Also:

Constant Field Values

METHOD_TRIGGER

public static final java.lang.String METHOD_TRIGGER

See Also:

Constant Field Values

Constructor Detail

ControlElement

public ControlElement(java.lang.Object _object)

Constructor ControlElement

Parameters:

_object -

Method Detail

getObject

public java.lang.Object getObject()

getPropertyList

public abstract java.util.ArrayList<java.lang.String> getPropertyList()

Returns the list of all properties that can be set for this ControlElement. Subclasses that add properties should implement this. Order is crucial here: Both for the presentation in an editor (f.i. ViewElement) and for the setValue() method.

getPropertyInfo

public abstract java.lang.String getPropertyInfo(java.lang.String _property)

Returns information about a given property. Subclasses that add properties should implement this. Order in the implementation is irrelevant.

The first keyword is ALWAYS the type. If more than one type is accepted, they are separated by | (do NOT use spaces!) The keyword CONSTANT applies to properties that can not be changed using the setValue() methods The keyword VARIABLE_EXPECTED is used when a String could be accepted, but a variable has priority. In this case, a String requires using inverted commas or quotes The keyword NotTrimmed specifies that leading or trailing spaces must be respected when present. This is useful for labels or titles, for instance The keyword BASIC is used by Ejs to group properties to the left hand side of the property editor The keyword HIDDEN is used by Ejs so that it does not display an entry in the editor field The keywords PREVIOUS and POSTPROCESS indicate that, when setting several properties at once (using setProperties()) the property must be process before, resp. after, the others

parseConstant

public Value parseConstant(java.lang.String _propertyType,
                           java.lang.String _value)

Checks if a value can be considered a valid constant value for a property If not, it returns null, meaning the value can be considered to be a GroupVariable

Parameters:

String - _property The property name

String - _value The proposed value for the property

setValue

public void setValue(int _index,
                     Value _value)

Sets the value of the registered variables. Subclasses with internal values should extend this Order is crucial here: it must match exactly that of the getPropertyList() method.

Parameters:

int - _index A keyword index that distinguishes among variables

Value - _value The object holding the value for the variable.

setDefaultValue

public void setDefaultValue(int _index)

getValue

public Value getValue(int _index)

Gets the value of any internal variable. Subclasses with internal values should extend this

Parameters:

int - _index A keyword index that distinguishes among variables

Returns:

Value _value The object holding the value for the variable.

setProperty

public ControlElement setProperty(java.lang.String _property,
                                  java.lang.String _value)

Sets a property for this ControlElement. Implementing classes are responsible of deciding (by declaring them in the getPropertyList() method) what properties turn into visual changes, or different behaviour, of the ControlElement.

However, every propery is accepted, even if it is not meaningful for a particular implementation of this interface. This can serve as a repository of information for future use.

Implementing classes should make sure that the following requirements are met:

Properties can be set in any order. The final result should not depend on the order. Exceptions must be explicitly documented. Any property can be modified. If so, the old value, and whatever meaning it had, is superseded by the new one. If the new one is null, the old one is simply removed and setDefaultValue(index) is called in case a precise default value should be used. When the element is part of a GroupControl, final users should not use this setProperty method directly, but go through the corresponding method of the group.