org.opensourcephysics.ejs.control
Class GroupControl

java.lang.Object
  extended by org.opensourcephysics.ejs.control.GroupControl
Direct Known Subclasses:
EjsControl

public class GroupControl
extends java.lang.Object

A base class to group several ControlElements, connect them to one or more target objects in a unified form, and build a graphic interface with all of them.


Field Summary
static int DEBUG_ALL
           
static int DEBUG_CONTROL
           
static int DEBUG_CONTROL_VERBOSE
           
static int DEBUG_DRAWING
           
static int DEBUG_DRAWING_VERBOSE
           
static int DEBUG_ELEMENTS
           
static int DEBUG_NONE
           
static int DEBUG_SET_AND_GET
           
static int DEBUG_SYSTEM
           
static int DEBUG_SYSTEM_VERBOSE
           
protected  java.awt.Frame replaceOwnerFrame
           
protected  java.lang.String replaceOwnerName
           
 
Constructor Summary
GroupControl()
          The default constructor.
GroupControl(java.lang.Object _target)
          The constructor.
GroupControl(java.lang.Object _simulation, java.lang.String _replaceName, java.awt.Frame _replaceOwnerFrame)
          A specialized constructor for Ejs use.
 
Method Summary
 ControlElement add(java.lang.String _type)
          Creates a new ControlElement
 ControlElement add(java.lang.String _type, java.lang.String _propertyList)
          Creates a new ControlElement and gives it a name
 void addListener(java.lang.String _name, java.lang.String _method)
           
 void addListener(java.lang.String _name, java.lang.String _method, java.lang.Object _anObject)
          Instructs the group to invoke a method (with an optional parameter) when a variable changes.
 ControlElement addNamed(java.lang.String _type, java.lang.String _name)
          Creates a new ControlElement with a given name This is a special feature that is used by LauncherApplet, so that if the name coincides with a given one, a Frame becomes a Panel, so that it can be captured!
 ControlElement addObject(java.lang.Object _object, java.lang.String _type)
          Creates a new ControlElement that wrapps an existing object If the object is not of the right class it will print a warning and ignore the object provided.
 ControlElement addObject(java.lang.Object _object, java.lang.String _type, java.lang.String _propertyList)
          Creates a new ControlElement that wrapps an existing object If the object is not of the right class it will print a warning and ignore the object provided.
 void addTarget(java.lang.String _name, java.lang.Object _target)
          Adds an object to be controlled.
 void appendPrefixPath(java.lang.String _prefix)
          Adds a prefix 'path' for unqualified elements.
 void clear()
          Destroy all elements
 void clearPrefixPath()
          Clears the list of default package name for unqualified elements
 void clearVariables()
          Clears all variables
 void destroy(ControlElement _element)
          Completely destroy a ControlElement
 void destroy(java.lang.String _name)
          Completely destroy a ControlElement by name
 boolean getBoolean(java.lang.String _name)
          A convenience method to get a value as a boolean
 java.awt.Component getComponent(java.lang.String _name)
          Returns the component of a control element by name
 java.awt.Container getContainer(java.lang.String _name)
          Returns the container of a control element by name
 ControlElement getControl(java.lang.String _name)
           
 int getDebugLevel()
          Returns the current debug level
 java.util.Vector<java.lang.String> getDefaultPrefixList()
          Returns the list (actually, a vector) of prefix
 double getDouble(java.lang.String _name)
          A convenience method to get a value as a double
 ControlElement getElement(java.lang.String _name)
          Returns a control element by name
 int getInt(java.lang.String _name)
          A convenience method to get a value as an int
static XML.ObjectLoader getLoader()
          Returns an XML.ObjectLoader to save and load data for this object.
 java.lang.Object getObject(java.lang.String _name)
          A convenience method to get a value as an Object
 java.awt.Frame getOwnerFrame()
          Returns the owner frame for all subsequent Dialogs
 java.awt.Frame getReplaceOwnerFrame()
          Returns the replacement for the owner frame for all subsequent Dialogs
 java.lang.String getReplaceOwnerName()
          Returns the name of the replacement for the owner frame for all subsequent Dialogs
 Simulation getSimulation()
          Returns the simulation under which the control is running This is used to up date the simulation whenever an Element changes a variable (See variableChanged in ControlElement
 java.lang.String getString(java.lang.String _name)
          A convenience method to get a value as a String
 java.lang.Object getTarget(java.lang.String _name)
          Returns one of the registered target objects
 java.awt.Container getTopLevelAncestor(java.lang.String _name)
          Returns the top-level ancestor of an element (either the containing Window or Applet), or null if the element has not been added to any container.
 Value getValue(java.lang.String _name)
          Returns the group value of a variable.
 java.awt.Component getVisual(java.lang.String _name)
          Returns the visual of a control element by name
 void initialize()
          Initialize all elements
 boolean isVariableRegistered(java.lang.String _name)
          Tells whether a variable is associated to any element.
 GroupVariable registerVariable(java.lang.String _name, ControlElement _element, int _index, Value _value)
          Associates an element internal value with a variable name.
 void removeTarget(java.lang.String _name)
          Removes a target object
 void rename(ControlElement _element, java.lang.String _name)
          Renaming a ControlElement
 void replaceOwnerFrame(java.lang.String _replaceName, java.awt.Frame _replaceOwnerFrame)
           
 void reset()
          Reset all elements
 void setActive(boolean _active)
          Set the active state of all elements
 void setDebugLevel(int _level)
          Sets the debug level
 void setOwnerFrame(java.awt.Frame _frame)
          Sets the owner frame for all subsequent Dialogs
 void setSimulation(Simulation _sim)
          Sets the simulation under which the control is running This is used to up date the simulation whenever an Element changes a variable (See variableChanged in ControlElement)
 void setValue(java.lang.String _name, boolean _value)
          A convenience method to set a value to a boolean
 void setValue(java.lang.String _name, double _value)
          A convenience method to set a value to a double
 void setValue(java.lang.String _name, int _value)
          A convenience method to set a value to an int
 void setValue(java.lang.String _name, java.lang.Object _value)
          A convenience method to set a value to any Object
 void setValue(java.lang.String _name, java.lang.String _value)
          A convenience method to set a value to a String
 void setValue(java.lang.String _name, Value _value)
          Sets the group value for a variable.
 void update()
          Refresh all elements
 void variableChanged(GroupVariable _variable, ControlElement _element, Value _value)
          Invoked by ControlElements when their internal variables change.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEBUG_NONE

public static final int DEBUG_NONE
See Also:
Constant Field Values

DEBUG_SET_AND_GET

public static final int DEBUG_SET_AND_GET
See Also:
Constant Field Values

DEBUG_ELEMENTS

public static final int DEBUG_ELEMENTS
See Also:
Constant Field Values

DEBUG_CONTROL

public static final int DEBUG_CONTROL
See Also:
Constant Field Values

DEBUG_CONTROL_VERBOSE

public static final int DEBUG_CONTROL_VERBOSE
See Also:
Constant Field Values

DEBUG_DRAWING

public static final int DEBUG_DRAWING
See Also:
Constant Field Values

DEBUG_DRAWING_VERBOSE

public static final int DEBUG_DRAWING_VERBOSE
See Also:
Constant Field Values

DEBUG_SYSTEM

public static final int DEBUG_SYSTEM
See Also:
Constant Field Values

DEBUG_SYSTEM_VERBOSE

public static final int DEBUG_SYSTEM_VERBOSE
See Also:
Constant Field Values

DEBUG_ALL

public static final int DEBUG_ALL
See Also:
Constant Field Values

replaceOwnerName

protected java.lang.String replaceOwnerName

replaceOwnerFrame

protected java.awt.Frame replaceOwnerFrame
Constructor Detail

GroupControl

public GroupControl()
The default constructor.


GroupControl

public GroupControl(java.lang.Object _target)
The constructor.

Parameters:
_target -

GroupControl

public GroupControl(java.lang.Object _simulation,
                    java.lang.String _replaceName,
                    java.awt.Frame _replaceOwnerFrame)
A specialized constructor for Ejs use. This adds elements to it in the ususal way, but replaces a Frame element of a given name by the prescribed frame.

Parameters:
_simulation -
_replaceName -
_replaceOwnerFrame -
Method Detail

setOwnerFrame

public void setOwnerFrame(java.awt.Frame _frame)
Sets the owner frame for all subsequent Dialogs

Parameters:
Frame - _frame The frame that should own next Dialogs (if there are Dialogs in this group)

getOwnerFrame

public java.awt.Frame getOwnerFrame()
Returns the owner frame for all subsequent Dialogs


replaceOwnerFrame

public void replaceOwnerFrame(java.lang.String _replaceName,
                              java.awt.Frame _replaceOwnerFrame)

getReplaceOwnerName

public java.lang.String getReplaceOwnerName()
Returns the name of the replacement for the owner frame for all subsequent Dialogs


getReplaceOwnerFrame

public java.awt.Frame getReplaceOwnerFrame()
Returns the replacement for the owner frame for all subsequent Dialogs


clearPrefixPath

public void clearPrefixPath()
Clears the list of default package name for unqualified elements


appendPrefixPath

public void appendPrefixPath(java.lang.String _prefix)
Adds a prefix 'path' for unqualified elements. Hence "Frame" becomes _prefix + "Frame". The default list includes "org.opensourcephysics.ejs.control.swing.Control" and "org.opensourcephysics.ejs.control.drawables.Control"

Parameters:
String - _prefix The prefix to be added to list

getDefaultPrefixList

public java.util.Vector<java.lang.String> getDefaultPrefixList()
Returns the list (actually, a vector) of prefix


setSimulation

public void setSimulation(Simulation _sim)
Sets the simulation under which the control is running This is used to up date the simulation whenever an Element changes a variable (See variableChanged in ControlElement)

Parameters:
Simulation - _sim The simulation

getSimulation

public Simulation getSimulation()
Returns the simulation under which the control is running This is used to up date the simulation whenever an Element changes a variable (See variableChanged in ControlElement


setDebugLevel

public void setDebugLevel(int _level)
Sets the debug level

Parameters:
int - _level The minimim level that should produce debug mesagges. Must be one of DEBUG_NONE, DEBUG_SET_AND_GET, DEBUG_ELEMENTS, DEBUG_ALL=255

getDebugLevel

public int getDebugLevel()
Returns the current debug level

Returns:
The actual minimim level that produces debug messages

getTarget

public java.lang.Object getTarget(java.lang.String _name)
Returns one of the registered target objects

Parameters:
String - _name The name given to the target when it was added

addTarget

public void addTarget(java.lang.String _name,
                      java.lang.Object _target)
Adds an object to be controlled. Actions can then refer to methods of the form 'name.method:parameter'

Parameters:
String - _name A name to refer to the target
Object - _target A target object

removeTarget

public void removeTarget(java.lang.String _name)
Removes a target object


setValue

public void setValue(java.lang.String _name,
                     Value _value)
Sets the group value for a variable. This includes the value in all the elements of this group that are registered to this variable name.

Parameters:
String - _name The variable name
Value - _value The value as a Value object

getValue

public Value getValue(java.lang.String _name)
Returns the group value of a variable.

Parameters:
String - _name The variable name
Returns:
the Value object of the variable. If the variable has never been set, it returns null.

registerVariable

public GroupVariable registerVariable(java.lang.String _name,
                                      ControlElement _element,
                                      int _index,
                                      Value _value)
Associates an element internal value with a variable name. Later on, when the user sets the value for this variable, either programmatically or by interaction with a given element, all registered elements will be informed of the change. Invoked by ControlElements when processing the 'variable' property. Not to be used directly by users.

Parameters:
String - _name The name of the variable
ControlElement - _element The element to be registered
int - _index An indentifier for the element internal value
Value - _value The initial value if the variable doesn't already exist

isVariableRegistered

public boolean isVariableRegistered(java.lang.String _name)
Tells whether a variable is associated to any element. Invoked by EjsControl's method 'setValue/getValue'. Not to be used directly by users.

Parameters:
ControlElement - _element The element to be included
String - _variable The variable name

variableChanged

public void variableChanged(GroupVariable _variable,
                            ControlElement _element,
                            Value _value)
Invoked by ControlElements when their internal variables change. Not be used directly by users.


addListener

public void addListener(java.lang.String _name,
                        java.lang.String _method)

addListener

public void addListener(java.lang.String _name,
                        java.lang.String _method,
                        java.lang.Object _anObject)
Instructs the group to invoke a method (with an optional parameter) when a variable changes.

Parameters:
String - _name The name of the variable that may change
String - _method The method that should be called in the controlled
Object - _anObject the object to pass in the special case the method is method(#CONTROL#) object.

rename

public void rename(ControlElement _element,
                   java.lang.String _name)
Renaming a ControlElement

Parameters:
String - _name The new name for the element.

addNamed

public final ControlElement addNamed(java.lang.String _type,
                                     java.lang.String _name)
Creates a new ControlElement with a given name This is a special feature that is used by LauncherApplet, so that if the name coincides with a given one, a Frame becomes a Panel, so that it can be captured!

Parameters:
String - _type The class name of the new element.
String - _name The name of the new element.

add

public final ControlElement add(java.lang.String _type)
Creates a new ControlElement

Parameters:
String - _type The class name of the new element. If it is not qualified, then it is given the prefix (see above)

add

public final ControlElement add(java.lang.String _type,
                                java.lang.String _propertyList)
Creates a new ControlElement and gives it a name

Parameters:
String - _type The class name of the new element. If it is not qualified, then it is given the default prefix (see above)
String - _propertyList A list of properties and Values to be set (see ControlElement.setProperties())

addObject

public final ControlElement addObject(java.lang.Object _object,
                                      java.lang.String _type)
Creates a new ControlElement that wrapps an existing object If the object is not of the right class it will print a warning and ignore the object provided.

Parameters:
Object - _object The element to be wrapped
String - _type The class name of the new element. If it is not qualified, then it is given the prefix (see above)

addObject

public ControlElement addObject(java.lang.Object _object,
                                java.lang.String _type,
                                java.lang.String _propertyList)
Creates a new ControlElement that wrapps an existing object If the object is not of the right class it will print a warning and ignore the object provided.

Parameters:
Object - _object The element to be wrapped
String - _type The class name of the new element. If it is not qualified, then it is given the prefix (see above)
String - _propertyList A list of properties and Values to be set (see ControlElement.setProperties())

getElement

public ControlElement getElement(java.lang.String _name)
Returns a control element by name

Parameters:
String - _name The name of the control element
Returns:
the ControlElement if found, null otherwise.

getControl

public ControlElement getControl(java.lang.String _name)

getVisual

public java.awt.Component getVisual(java.lang.String _name)
Returns the visual of a control element by name

Parameters:
String - _name The name of the control element
Returns:
the java.awt.Component visual of the element if found, null otherwise.

getComponent

public java.awt.Component getComponent(java.lang.String _name)
Returns the component of a control element by name

Parameters:
String - _name The name of the control element
Returns:
the java.awt.Component component of the element if found, null otherwise.

getContainer

public java.awt.Container getContainer(java.lang.String _name)
Returns the container of a control element by name

Parameters:
String - _name The name of the control element
Returns:
the java.awt.Container visual of the element if found, and the element is a container, null otherwise.

destroy

public void destroy(java.lang.String _name)
Completely destroy a ControlElement by name

Parameters:
String - _name The name of the ControlElement to be destroyed

destroy

public void destroy(ControlElement _element)
Completely destroy a ControlElement

Parameters:
ControlElement - _element The ControlElement to be destroyed

reset

public void reset()
Reset all elements


initialize

public void initialize()
Initialize all elements


update

public void update()
Refresh all elements


setActive

public void setActive(boolean _active)
Set the active state of all elements


clearVariables

public void clearVariables()
Clears all variables


clear

public void clear()
Destroy all elements


getTopLevelAncestor

public java.awt.Container getTopLevelAncestor(java.lang.String _name)
Returns the top-level ancestor of an element (either the containing Window or Applet), or null if the element has not been added to any container. If no element name is provided, the first control element whose component is a Window is returned.

Parameters:
String - _name The name of the control element
Returns:
the Container if found, null otherwise.

setValue

public void setValue(java.lang.String _name,
                     boolean _value)
A convenience method to set a value to a boolean

Parameters:
_name -
_value -

setValue

public void setValue(java.lang.String _name,
                     int _value)
A convenience method to set a value to an int

Parameters:
_name -
_value -

setValue

public void setValue(java.lang.String _name,
                     double _value)
A convenience method to set a value to a double

Parameters:
_name -
_value -

setValue

public void setValue(java.lang.String _name,
                     java.lang.String _value)
A convenience method to set a value to a String

Parameters:
_name -
_value -

setValue

public void setValue(java.lang.String _name,
                     java.lang.Object _value)
A convenience method to set a value to any Object

Parameters:
_name -
_value -

getBoolean

public boolean getBoolean(java.lang.String _name)
A convenience method to get a value as a boolean

Parameters:
_name -

getInt

public int getInt(java.lang.String _name)
A convenience method to get a value as an int

Parameters:
_name -

getDouble

public double getDouble(java.lang.String _name)
A convenience method to get a value as a double

Parameters:
_name -

getString

public java.lang.String getString(java.lang.String _name)
A convenience method to get a value as a String

Parameters:
_name -

getObject

public java.lang.Object getObject(java.lang.String _name)
A convenience method to get a value as an Object

Parameters:
_name -

getLoader

public static XML.ObjectLoader getLoader()
Returns an XML.ObjectLoader to save and load data for this object.

Returns:
the object loader