edu.hws.jcm.awt
Class Controller

java.lang.Object
  |
  +--edu.hws.jcm.awt.Controller

All Implemented Interfaces:

java.awt.event.ActionListener, java.awt.event.AdjustmentListener, Computable, java.util.EventListener, InputObject, java.awt.event.ItemListener, java.io.Serializable, java.awt.event.TextListener

public class Controller

extends java.lang.Object

implements java.io.Serializable, Computable, InputObject, java.awt.event.AdjustmentListener, java.awt.event.ActionListener, java.awt.event.TextListener, java.awt.event.ItemListener

Controllers are the focus of all the action in the JCM system. A Controller can be set to listen for changes (generally changes in user input). This is done by registering the Controller with (usally) an InputObject. For example, if a Controller, c, is to respond when the user presses return in a VariableInput, v, then v.setOnUserAction(c) should be called to arrange to have the Controller listen for such actions. VariableSliders, ExpressionInputs, MouseTrackers, Animators have a similar methods. It is also possible to set the Controller to listen for events of type AdjustmentEvent, ActionEvent, TextEvent, or ItemEvent (but this feature is left over from an older version of JCM, and I'm not sure whether it's necessary). Whenever a Controller learns of some change, it will process any InputObjects, Ties, and Computables that have been registered with it.

InputObjects and Computables have to be added to a Controller to be processed, using the Controller's add method. (If you build your inteface out of JCMPanels, then this is done automatically.) (Note that an InputObject is added to a Controller to have its value checked -- This is separate from registering the Controller to listen for changes in the InputObject. Often, you have to do both.) The gatherInputs() method in class JCMPanel can be used to do most of this registration automaticaly.

A Tie that synchronizes two or more Values, to be effective, has to be added to a Controller. See the Tie class for inforamtion about what Ties are and how they are used.

A Controller can have an associated ErrorReporter, which is used to report any errors that occur during the processing. Currently, an ErrorReporter is either a DisplayCanvas or a MessagePopup.

A Controller can be added to another Controller, which then becomes a sub-controller. Whenever the main Controller hears some action, it also notifies all its sub-controllers about the action. Furthermore, it can report errors that occur in the sub-controllers, if they don't have their own error reporters. (Usually, you will just set an error reporter for the top-level Controller.)

See Also:

Serialized Form

Field Summary

protected java.util.Vector	computables Computable objects controlled by this controller.
protected java.lang.String	errorMessage If non-null, this is an error message that has been reported and not yet cleared.
protected ErrorReporter	errorReporter Used for reporting errors that occur in the compute() method of this controller.
protected java.util.Vector	inputs InputObjects controlled by this controller.
protected Controller	parent The parent of this controller, if any.
protected java.util.Vector	ties Ties that have been added to this controller.

Constructor Summary

Controller()
Create a Controller.

Method Summary

void	actionPerformed(java.awt.event.ActionEvent evt) Simply calls compute when the Controller hears an ActionEvent.
void	add(java.lang.Object obj) Add an object to be controlled by this controller.
void	adjustmentValueChanged(java.awt.event.AdjustmentEvent evt) Simply calls compute when the Controller hears an AdjustmantEvent.
void	checkInput() Call checkInput() of each InputObject.
protected void	clearErrorMessage() Clear the error message.
void	compute() When an contoller computes, it first calls checkInput() for any InputOjects that it controls (including those in sub-controllers).
protected void	doCompute() Compute the Computables in this controller and its sub-controllers.
protected void	doTies() Check the Ties in this controller and its sub-controllers.
void	errorCleared() Should be called by the ErrorReporter if the ErrorReporter clears the error itself.
void	gatherInputs() Calles notifyControllerOnChange(this).
ErrorReporter	getErrorReporter() Get the ErrorReporter for this Controller.
void	itemStateChanged(java.awt.event.ItemEvent evt) Simply calls compute when the Controller hears an ItemEvent.
void	notifyControllerOnChange(Controller c) Method required by InputObject interface; in this class, calls the same method recursively on any input objects controlled by this controller.
void	remove(java.lang.Object obj) Remove the object from the controller (if present).
void	removeFromParent() If this controller has a parent, remove it from its parent.
void	reportError(java.lang.String message) Report the specified error message.
void	setErrorReporter(ErrorReporter r) Set the ErrorReporter used to report errors that occur when the compute() method of this Controller is executed.
void	textValueChanged(java.awt.event.TextEvent evt) Simply calls compute when the Controller hears a TextEvent.

Methods inherited from class java.lang.Object

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

Field Detail

computables

protected java.util.Vector computables

Computable objects controlled by this controller. Note that Controllers are Computables, so this list can include sub-controllers.

inputs

protected java.util.Vector inputs

InputObjects controlled by this controller. Note that Controllers are InputObjects, so this list can include sub-controllers.

ties

protected java.util.Vector ties

Ties that have been added to this controller.

errorReporter

protected ErrorReporter errorReporter

Used for reporting errors that occur in the compute() method of this controller. If the errorReporter is null and if this controller has a parent, then the parent will report the error. If no ancestor has an errorReporter, the error message is written to standard output.

parent

protected Controller parent

The parent of this controller, if any. This is set automatically when one controller is added to another.

errorMessage

protected java.lang.String errorMessage

If non-null, this is an error message that has been reported and not yet cleared.

Constructor Detail

Controller

public Controller()

Create a Controller.

Method Detail

setErrorReporter

public void setErrorReporter(ErrorReporter r)

Set the ErrorReporter used to report errors that occur when the compute() method of this Controller is executed.

getErrorReporter

public ErrorReporter getErrorReporter()

Get the ErrorReporter for this Controller. Return null if there is none.

add

public void add(java.lang.Object obj)

Add an object to be controlled by this controller. It should be of one or more of the types InputObject, Computable, Tie. If it is a Controller, then this Controller becomes its parent.

remove

public void remove(java.lang.Object obj)

Remove the object from the controller (if present).

removeFromParent

public void removeFromParent()

If this controller has a parent, remove it from its parent. (Then, a call to the former parent's compute() method will not call this controller's compute().)

actionPerformed

public void actionPerformed(java.awt.event.ActionEvent evt)

Simply calls compute when the Controller hears an ActionEvent. This is not meant to be called directly.

Specified by:

actionPerformed in interface java.awt.event.ActionListener

textValueChanged

public void textValueChanged(java.awt.event.TextEvent evt)

Simply calls compute when the Controller hears a TextEvent. This is not meant to be called directly.

Specified by:

textValueChanged in interface java.awt.event.TextListener

adjustmentValueChanged

public void adjustmentValueChanged(java.awt.event.AdjustmentEvent evt)

Simply calls compute when the Controller hears an AdjustmantEvent. This is not meant to be called directly.

Specified by:

adjustmentValueChanged in interface java.awt.event.AdjustmentListener

itemStateChanged

public void itemStateChanged(java.awt.event.ItemEvent evt)

Simply calls compute when the Controller hears an ItemEvent. This is not meant to be called directly.

Specified by:

itemStateChanged in interface java.awt.event.ItemListener

compute

public void compute()

When an contoller computes, it first calls checkInput() for any InputOjects that it controls (including those in sub-controllers). It then handles any Ties. Finally, it calls the compute() method of any Computables. If an error occurs, it reports it. JCMErrors (which should represent errors on the part of the user) will generally only occur during the checkInput() phase. Internal, programmer errors can occur at any time and might leave the sytem in an unhappy state. They are reported as debugging aids for the programmer. When one occurs, a stack trace is printed to standard output.

Specified by:

compute in interface Computable

checkInput

public void checkInput()

Call checkInput() of each InputObject. Can throw a JCMError. This is mostly meant to be called by Controller.compute(). Note that this will recurse though any sub-controllers of this controller, so that when comput() is called, all the InputObjects in the sub-controllers are processed before ANY Tie or Computable is processed. Similarly, the Ties and Computables in the sub-controllers are processed in separate passes.

Specified by:

checkInput in interface InputObject

doTies

protected void doTies()

Check the Ties in this controller and its sub-controllers.

doCompute

protected void doCompute()

Compute the Computables in this controller and its sub-controllers.

reportError

public void reportError(java.lang.String message)

Report the specified error message.

clearErrorMessage

protected void clearErrorMessage()

Clear the error message.

errorCleared

public void errorCleared()

Should be called by the ErrorReporter if the ErrorReporter clears the error itself. (This is only used to avoid repeatedly setting the same error message, during an animation for example.)

notifyControllerOnChange

public void notifyControllerOnChange(Controller c)

Method required by InputObject interface; in this class, calls the same method recursively on any input objects controlled by this controller. This is meant to be called by JCMPanel.gatherInputs().

Specified by:

notifyControllerOnChange in interface InputObject

gatherInputs

public void gatherInputs()

Calles notifyControllerOnChange(this). That is, it sets all the InputObjects in this Controller, and in subcontrollers, to notify this Controller when they change.