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 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 retrieved 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' responsibility to trigger an action in response to a user's gesture (with the mouse or keyboard)

See Also:

  • Field Details

  • Constructor Details

    • ControlElement

      public ControlElement(Object _object)
      Constructor ControlElement
      Parameters:
      _object -

  • Method Details

    • getObject

      public Object getObject()

    • getPropertyList

      public abstract ArrayList<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 String getPropertyInfo(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(String _propertyType, 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(String _property, 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:

    • setProperties

      public final ControlElement setProperties(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 String getProperty(String _property)
      Returns the value of a property.
      Parameters:
      String - _property The property name

    • propertyIsTypeOf

      public final boolean propertyIsTypeOf(String _property, String _keyword)
      Returns whether 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 String propertyType(String _property)
      Returns the type of the property
      Parameters:
      String - _property The property name
      Returns:
      String The type of the property

    • getComponent

      public Component getComponent()
      Provided for backwards compatibiliy only

    • getVisual

      public 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(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 String toString()
      Reports its name, if it has been set. If not, returns a standard value.
      Overrides:
      toString in class Object

    • destroy

      public void destroy()
      Clears any trace of myself (specially in the group)

    • addAction

      public final ControlElement addAction(int _type, Object _target, String _method)
      Defines a generic action that can be invoked from this ControlElement. It is the responsibility 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, Object _target, String _method, MethodWithOneParameter _secondAction)
      This is an advanced form of addAction that allows for nested actions

    • addAction

      public final ControlElement addAction(int _type, 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, Object _target, 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:

    • removeAction

      public final void removeAction(int _type, 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