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

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

ControlElement(java.lang.Object _object)
Constructor ControlElement

Method Summary

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.

Parameters:

String - _property The property name

String - _value The value desired for the property

Returns:

This same element. This is useful to nest more than one call to setProperty

See Also:

GroupControl

setProperties

public final ControlElement setProperties(java.lang.String _propertyList)

Sets more than one property at once. The pairs property=value must be separated by ';'. If any value has a ';' in it, then it must be set in a separate setProperty call.

Parameters:

String - _propertyList The list of properties and Values to be set

Returns:

This same element. This is useful to nest more than one call to setProperties

getProperty

public final java.lang.String getProperty(java.lang.String _property)

Returns the value of a property.

Parameters:

String - _property The property name

propertyIsTypeOf

public final boolean propertyIsTypeOf(java.lang.String _property,
                                      java.lang.String _keyword)

Returns wether a property information contains a given keyword in its preamble

Parameters:

String - _property The property name

String - _keyword The keyword to look for

propertyType

public final java.lang.String propertyType(java.lang.String _property)

Returns the type of the property

Parameters:

String - _property The property name

Returns:

String The type of the property

getComponent

public java.awt.Component getComponent()

Provided for backwards compatibiliy only

getVisual

public java.awt.Component getVisual()

Provided for backwards compatibiliy only

reset

public void reset()

resets the element

initialize

public void initialize()

initializes the element. A kind of soft reset()

implementsProperty

public boolean implementsProperty(java.lang.String _property)

Whether the element implements a given property

Parameters:

_property - the property

variablePropertiesClear

public final void variablePropertiesClear()

Clear all registered internal variable properties

toString

public java.lang.String toString()

Reports its name, if it has been set. If not, returns a standard value.

Overrides:

toString in class java.lang.Object

destroy

public void destroy()

Clears any trace of myself (specially in the group)

addAction

public final ControlElement addAction(int _type,
                                      java.lang.Object _target,
                                      java.lang.String _method)

Defines a generic action that can be invoked from this ControlElement. It is the responsability of implementing classes to decide what actions types can be invoked and how.

If the method field is not a valid method for this target object it will ignore the command (and perhaps print an error message).

Parameters:

int - _type The action type

Object - _target The object whose method will be invoked

String - _method The method to call in the target object. The method can accept a single CONSTANT parameter, either boolean, int, double or String. See MethodWithOneParameter for more details.

Returns:

This same element. This is useful to nest it with other calls to setProperty or adAction.

addAction

public final 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

addAction

public final 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.

removeAction

public final void removeAction(int _type,
                               java.lang.Object _target,
                               java.lang.String _method)

Removes an action. If the action does not exists, it does nothing.

Parameters:

int - _type The action type

Object - _target The object whose method will be invoked

String - _method The method to call in the target object.

See Also:

addAction(int,Object,String)

removeAction

public final void removeAction(int _type,
                               java.lang.String _method)

Similar to removeAction but extracts the target from the method

invokeActions

public final void invokeActions()

Invokes all actions of type ACTION

invokeActions

public final void invokeActions(int _type)

Invokes all actions of this BasicControl of a given type

Parameters:

int - _type The action type

variableChangedDoNotUpdate

public final void variableChangedDoNotUpdate(int _variableIndex,
                                             Value _value)

Reports changes of internal variables but simulation doesn't update Needed by RadioButtons

Parameters:

int - _variableIndex the index of the internal variable that changed

Value - _value the new value for the variable

variableChanged

public final void variableChanged(int _variableIndex,
                                  Value _value)

Reports changes of internal variables

Parameters:

int - _variableIndex the index of the internal variable that changed

Value - _value the new value for the variable

variablesChanged

public final void variablesChanged(int[] _variableIndex,
                                   Value[] _value)

Reports changes of more than one internal variables

Parameters:

int[] - _variableIndexes the indexes of the internal variables that changed

Value[] - _value the new values for the variables

setActive

public final void setActive(boolean _act)

Sets whether a ControlElement actually invokes actions. The default is true.

Parameters:

boolean - _active Whether it is active

isActive

public final boolean isActive()

Returns the active status of the ControlElement.

setGroup

public final void setGroup(GroupControl _group)

Sets the GroupControl in which to operate

Parameters:

GroupControl - _group The GroupControl

getGroup

public final GroupControl getGroup()

Gets the GroupControl in which it operates

Returns:

the GroupControl

getSimulation

public final Simulation getSimulation()

Gets the Simulation in which it runs

Returns:

the Simulation