edu.hws.jcm.awt
Class Animator

java.lang.Object
  |
  +--java.awt.Component
        |
        +--java.awt.Container
              |
              +--java.awt.Panel
                    |
                    +--edu.hws.jcm.awt.Animator

All Implemented Interfaces:

javax.accessibility.Accessible, java.awt.event.ActionListener, java.util.EventListener, java.awt.image.ImageObserver, InputObject, java.awt.event.ItemListener, java.awt.MenuContainer, java.lang.Runnable, java.io.Serializable, Tieable, Value

public class Animator

extends java.awt.Panel

implements Value, Tieable, InputObject, java.awt.event.ActionListener, java.awt.event.ItemListener, java.lang.Runnable

An Animator can change a value continuously, without user intervention, by running a separate Thread. By default, an animator appears as a "Start" button. When the button is pressed, the value of the animator starts counting 0, 1, 2, ... The button changes to a "Stop" button. When this is pressed, the value stops changing. A Controller can be set, by calling the setOnChange() method, to be notified whenever the value is changed. If this is done, then the value of the Animator will only change when its checkInput() method is called, so it should be added to a Controller which will call this method.

The getValueAsVariable() method can be called to get a Variable whose value is the value of the Animator. This variable can then be added to a Parser, so it can be used in expressions. An Animator is "Tieable", so it can share its value with another InputObject, such as a VariableSlider or a VariableIput.

There are many options: If maximum and minimum values are both specified, then the value of the Animator ranges between these values. By default, this interval is divided into 100 sub-intervals, so that there are 101 frames. However, the number of intervals can also be set. If no min or max is specified but a number of intervals is specified, then the value is an integer which ranges from 0 up to the specified number of intervals. If the number of frames is finite, then there are three possibities when the last frame is reached: The animation can stop; it can loop back to the the starting frame, or it can reverse direction and cycle back and forth. The behavior is controlled with the setLoopStyle() method.

An Animator is actually a Panel which can contain other controls in addition to or instead of the Start/Stop button. For example, it can contain a "Next" button or a pop-up menu to control the speed.

See Also:

Serialized Form

Inner classes inherited from class java.awt.Panel

java.awt.Panel.AccessibleAWTPanel

Inner classes inherited from class java.awt.Container

java.awt.Container.AccessibleAWTContainer

Inner classes inherited from class java.awt.Component

java.awt.Component.AccessibleAWTComponent

Field Summary

static int	BACK_AND_FORTH Represents a loop style in which the animation is cycled back and forth.
static int	HORIZONTAL Indicates that the components in the Animator panel are to be in a horizontal row.
static int	LOOP Represents a loop style in which the animation is played repeatedly.
static int	LOOP_CHOICE Used to add a component to the Animator Panel; can be used in a constructor or in the addControl() method.
static int	NEXT_BUTTON Used to add a component to the Animator Panel; can be used in a constructor or in the addControl() method.
static int	ONCE Represents a loop style in which the animation is played once.
static int	PAUSE_BUTTON Used to add a component to the Animator Panel; can be used in a constructor or in the addControl() method.
static int	PREV_BUTTON Used to add a component to the Animator Panel; can be used in a constructor or in the addControl() method.
static int	SPEED_CHOICE Used to add a component to the Animator Panel; can be used in a constructor or in the addControl() method.
static int	START_BUTTON Used to add a component to the Animator Panel; can be used in a constructor or in the addControl() method.
static int	START_STOP_BUTTON Used to add a component to the Animator Panel; can be used in a constructor or in the addControl() method.
static int	STOP_BUTTON Used to add a component to the Animator Panel; can be used in a constructor or in the addControl() method.
static int	VERTICAL Indicates that the components in the Animator panel are to be stacked vertically.

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

Animator()
Create a default Animator.

Animator(int controls)
Create an Animator containing the specified control.

Animator(int controls, int orientation)
Create an Animator containing specified controls.

Animator(int controls, int orientation, Value min, Value max, Value intervals)
Create an Animator with specified controls, orienation, range limits and number of intervals

Method Summary

void	actionPerformed(java.awt.event.ActionEvent evt) Respond to button clicks.
java.awt.Component	addControl(int controlCode) Add one of the possible control buttons or pop-up menus to the Animator.
void	checkInput() Part of the IputObject interface.
java.awt.Component	getControl(int controlCode) Get one of controls associated with the Animator.
Value	getIntervals() Get the Value object that specifies the number of frames in the animation.
int	getLoopStyle() Get the loop style, which determines what happens when the final frame of the animation is reached.
Value	getMax() Get the Value object that specifies the final value of the Animator.
int	getMillisPerFrame() Get the nominal number of milliseconds per frame.
Value	getMin() Get the Value object that specifies the starting value of the Animator.
Computable	getOnChange() Get the Controller that is notified (by calling its compute() method) whenever the frame changes.
int	getOrientation() Get the constant, VERTICAL or HORIZONTAL, that was used to specify whether the components in the animator are arranged veritcally or horizontally.
long	getSerialNumber() Part of the Tieable interface.
boolean	getUndefinedWhenNotRunning() Get the value of the undefinedWhenNotRunning property.
double	getVal() Get the current value of the Animator.
Variable	getValueAsVariable() Get a variable whose value is always equal to the value of the animator.
Variable	getValueAsVariable(java.lang.String name) Get a variable whose value is always equal to the value of the animator.
void	itemStateChanged(java.awt.event.ItemEvent evt) Respond to clicks on pop-up menus.
void	next() Advance the animation by one frame.
void	notifyControllerOnChange(Controller c) Method required by the InputObject interface.
void	pause() Pause the animation, if it is running.
void	prev() Advance the animation BACK one frame.
void	run() The method that is run by the animation thread.
void	setIntervals(int intervals) A convenience method that simply calls setIntervals(new Constant(d)).
void	setIntervals(Value intervals) Set the Value object that specifies the number of frames in the animation.
void	setLoopStyle(int style) Set the loop style, which determines what happens when the final frame of the animation is reached.
void	setMax(double d) A convenience method that simply calls setMax(new Constant(d)).
void	setMax(Value max) Set the Value object that gives the final value of the Animator.
void	setMillisPerFrame(int millis) Set the nominal number of milliseconds per frame.
void	setMin(double d) A convenience method that simply calls setMin(new Constant(d)).
void	setMin(Value min) Set the Value object that gives the starting value of the Animator.
void	setOnChange(Computable onChange) Set the Controller that is notified (by calling its compute() method) whenever the frame changes.
void	setOrientation(int orientation) Set the orientation of the components in the Animator panel.
void	setStartButtonName(java.lang.String name) The name of the Start/Stop button is managed by the Animator, so changing it directly makes no sense.
void	setStopButtonName(java.lang.String name) The name of the Start/Stop button is managed by the Animator, so changing it directly makes no sense.
void	setUndefinedWhenNotRunning(boolean undefinedWhenNotRunning) Set the value of the undefinedWhenNotRunning property.
void	setVal(double val) Set the value of the animation.
void	start() Start the animation from the first frame, or continue it if it was paused.
void	stop() Stop the animation, if it is running or paused.
void	sync(Tie tie, Tieable newest) Part of the Tieable interface.

Methods inherited from class java.awt.Panel

addNotify, getAccessibleContext

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getInsets, getLayout, getListeners, getMaximumSize, getMinimumSize, getPreferredSize, insets, invalidate, isAncestorOf, layout, list, list, locate, minimumSize, paint, paintComponents, paramString, preferredSize, print, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, removeNotify, setFont, setLayout, update, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addPropertyChangeListener, addPropertyChangeListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, getBackground, getBounds, getBounds, getColorModel, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getInputContext, getInputMethodRequests, getLocale, getLocation, getLocation, getLocationOnScreen, getName, getParent, getPeer, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isDisplayable, isDoubleBuffered, isEnabled, isFocusTraversable, isLightweight, isOpaque, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, reshape, resize, resize, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setForeground, setLocale, setLocation, setLocation, setName, setSize, setSize, setVisible, show, show, size, toString, transferFocus

Methods inherited from class java.lang.Object

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

Field Detail

START_STOP_BUTTON

public static final int START_STOP_BUTTON

Used to add a component to the Animator Panel; can be used in a constructor or in the addControl() method. Can also be used in the getControl() method to specify which component is to be retrieved.

START_BUTTON

public static final int START_BUTTON

Used to add a component to the Animator Panel; can be used in a constructor or in the addControl() method. Can also be used in the getControl() method to specify which component is to be retrieved.

PAUSE_BUTTON

public static final int PAUSE_BUTTON

Used to add a component to the Animator Panel; can be used in a constructor or in the addControl() method. Can also be used in the getControl() method to specify which component is to be retrieved.

STOP_BUTTON

public static final int STOP_BUTTON

Used to add a component to the Animator Panel; can be used in a constructor or in the addControl() method. Can also be used in the getControl() method to specify which component is to be retrieved.

NEXT_BUTTON

public static final int NEXT_BUTTON

Used to add a component to the Animator Panel; can be used in a constructor or in the addControl() method. Can also be used in the getControl() method to specify which component is to be retrieved.

PREV_BUTTON

public static final int PREV_BUTTON

Used to add a component to the Animator Panel; can be used in a constructor or in the addControl() method. Can also be used in the getControl() method to specify which component is to be retrieved.

SPEED_CHOICE

public static final int SPEED_CHOICE

Used to add a component to the Animator Panel; can be used in a constructor or in the addControl() method. Can also be used in the getControl() method to specify which component is to be retrieved.

LOOP_CHOICE

public static final int LOOP_CHOICE

Used to add a component to the Animator Panel; can be used in a constructor or in the addControl() method. Can also be used in the getControl() method to specify which component is to be retrieved.

VERTICAL

public static final int VERTICAL

Indicates that the components in the Animator panel are to be stacked vertically. (Can be used in a constructor and in the setOrientation method.)

HORIZONTAL

public static final int HORIZONTAL

Indicates that the components in the Animator panel are to be in a horizontal row. (Can be used in a constructor and in the setOrientation method.)

ONCE

public static final int ONCE

Represents a loop style in which the animation is played once. When the final frame is reached, the animation ends. Use in the setLoopStyle() method.

LOOP

public static final int LOOP

Represents a loop style in which the animation is played repeatedly. When the final frame is reached, the animation returns to the first frame. Use in the setLoopStyle() method.

BACK_AND_FORTH

public static final int BACK_AND_FORTH

Represents a loop style in which the animation is cycled back and forth. When the final frame is reached, the animation reverses direction. Use in the setLoopStyle() method.

Constructor Detail

Animator

public Animator()

Create a default Animator. If no changes are made by calling other methods, it will appear as a Start/Stop button. When Start is pressed, the value will count 0, 1, 2, 3, ..., until the Stop button is pressed. Restarting the animation starts the value again at zero.

Animator

public Animator(int controls)

Create an Animator containing the specified control. The parameter can consist of one or more of the following constants, or'ed together: START_STOP_BUTTON, START_BUTTON, STOP_BUTTON, PAUSE_BUTTON, NEXT_BUTTON, PREV_BUTTON, SPEED_CHOICE, LOOP_CHOICE. If no changes are made by calling other methods, the value of the Animator will be 0, 1, 2, 3, .... The components are arranged into one horizontal row, using a GridLayout.

Animator

public Animator(int controls,
                int orientation)

Create an Animator containing specified controls. (See the one-parameter constructor.) The second parameter should be one of the constants HORIZONTAL or VERTICAL, to specify how the components are arranged in the Animator panel.

Animator

public Animator(int controls,
                int orientation,
                Value min,
                Value max,
                Value intervals)

Create an Animator with specified controls, orienation, range limits and number of intervals

Parameters:

controls - Specify the controls to add to the Animator. Can consist of one or more of the following constants, or'ed together: START_STOP_BUTTON, START_BUTTON, STOP_BUTTON, PAUSE_BUTTON, NEXT_BUTTON, PREV_BUTTON, SPEED_CHOICE, LOOP_CHOICE.

orientation - How the controls are arranged in the panel. One of the constants VERTICAL or HORIZONTAL.

min - If BOTH min and max are non-null, they specify the range of values of the Animator.

max - If BOTH min and max are non-null, they specify the range of values of the Animator.

intervals - If non-null, specifies the number of intervals into which the range of values is divided. Note that the value will be rounded to the nearest integer and clamped to the range 0 to 100000. The number of frames is the number of intervals, plus one. If min and max are non-null and intervals is null, then a default value of 100 is used. If either min or max is null and intervals is non-null, then the Animator takes on the values 0, 1, 2, ..., intervals.

Method Detail

getControl

public java.awt.Component getControl(int controlCode)

Get one of controls associated with the Animator. Usually, these are displayed in the Animator panel, but you could get a control and add it to another panel if you want. Even if you do this, the control will still be managed by the Animator (which will respond to it and enable/disable it, for example). You might also want to get one of the Animator's buttons so that you can change its label. The value of the parameter should be one of the constants START_STOP_BUTTON, START_BUTTON, STOP_BUTTON, PAUSE_BUTTON, NEXT_BUTTON, PREV_BUTTON, SPEED_CHOICE, LOOP_CHOICE. If the parameter is not one of these values, then null is returned.

addControl

public java.awt.Component addControl(int controlCode)

Add one of the possible control buttons or pop-up menus to the Animator. The possible values of the parameter and their meanings are as follows:

START_STOP_BUTTON: When clicked, animation starts and name of button changes; when clicked again, animation stops.

START_BUTTON: When clicked, animation starts.

STOP_BUTTON: When clicked, animaton stops.

PAUSE_BUTTON: When clicked, animation is paused; this is different from stopping the animation since a paused animation can be resumed from the same point while a stopped animation can only be restarted from the beginning.

NEXT_BUTTON: When clicked, the animation advances one frame; this is disabled when the animation is running.

PREV_BUTTON: When clicked, the animation is moved back one frame; this is disabled when the animation is running.

SPEED_CHOICE: A pop-up menu whose value controls the speed at which the animation plays.

LOOP_CHOICE: A pop-up menu that controls the style of animation, that is, what happens when the animation reaches its final frame; values are Play Once, Loop, and Back and Forth.

If the parameter is not one of these constants, then nothing is done. Ordinarily, this will be called during initialization. (If you call it at some other time, you will have to validate the panel yourself.) The return value is the component that is added, or null if the parameter value is not legal.

setStartButtonName

public void setStartButtonName(java.lang.String name)

The name of the Start/Stop button is managed by the Animator, so changing it directly makes no sense. This method can be used to specify the label displayed by the Start/Stop button when the animation is NOT running. This name is also used for the Start button. This method should ordinarily be called during initialization. In any case, it should not be called while an animation is running, since it changes the name of the Start/Stop button to the specified value.

setStopButtonName

public void setStopButtonName(java.lang.String name)

The name of the Start/Stop button is managed by the Animator, so changing it directly makes no sense. This method can be used to specify the label displayed by the Start/Stop button when the animation IS running. This name is also used for the Stop button. This method should ordinarily be called during initialization. In any case, it should not be called while an animation is running, since it does not change the name of the Start/Stop button.

getOrientation

public int getOrientation()

Get the constant, VERTICAL or HORIZONTAL, that was used to specify whether the components in the animator are arranged veritcally or horizontally.

setOrientation

public void setOrientation(int orientation)

Set the orientation of the components in the Animator panel. The parameter should be one of the constants HORIZONTAL or VERTICAL. This just sets the layout for the panel to be a GridLayout with one row or one column and validates the panel. You could also set the layout to be something else, such as a FlowLayout, using the setLayout() method.

getMax

public Value getMax()

Get the Value object that specifies the final value of the Animator. This object can be null.

setMax

public void setMax(Value max)

Set the Value object that gives the final value of the Animator. If both min and max are non-null, the value of the Animator ranges from min to max as the animation procedes. (It is not required that max be greater than min. They should probably be calles startVal and endVal.)

setMax

public void setMax(double d)

A convenience method that simply calls setMax(new Constant(d)).

getMin

public Value getMin()

Get the Value object that specifies the starting value of the Animator. This object can be null.

setMin

public void setMin(Value min)

Set the Value object that gives the starting value of the Animator. If both min and max are non-null, the value ranges from min to max as the animation procedes. (It is not required that max be greater than min.)

setMin

public void setMin(double d)

A convenience method that simply calls setMin(new Constant(d)).

getIntervals

public Value getIntervals()

Get the Value object that specifies the number of frames in the animation. This can be null.

setIntervals

public void setIntervals(Value intervals)

Set the Value object that specifies the number of frames in the animation. If non-null, then the value is rounded to the nearest integer and clamped to the range 1 to 100000. If it is null and min and max are non-null, then a default value of 100 is used. If it is null and min or max is null, then the number of frames is unlimited and the values taken on by the animator are 0, 1, 2, 3, ..., that is, the value of the animator is the frame number. If min or max is null and intervals is non-null, then the values taken on by the animator are 0, 1, 2, ..., intervals. Note that the number of frames is (intervals+1).

setIntervals

public void setIntervals(int intervals)

A convenience method that simply calls setIntervals(new Constant(d)).

getMillisPerFrame

public int getMillisPerFrame()

Get the nominal number of milliseconds per frame. The actual time between frames can be longer because of the work that is done processing the frame or on other tasks.

setMillisPerFrame

public void setMillisPerFrame(int millis)

Set the nominal number of milliseconds per frame. The actual time between frames can be longer because of the work that is done processing the frame or on other tasks. Values less than 5 are effectively equivalent to 5. Realistic values are 25 or more, but it depends on what system the program is running on and how complicated each frame is.

getLoopStyle

public int getLoopStyle()

Get the loop style, which determines what happens when the final frame of the animation is reached.

setLoopStyle

public void setLoopStyle(int style)

Set the loop style, which determines what happens when the final frame of the animation is reached. The parameter can be one of the constants: ONCE (animation stops when final frame is reached), LOOP (animation cycles back to the first frame and continues from there); or BACK_AND_FORTH (animation reverses direction and cycles back and forth).

setVal

public void setVal(double val)

Set the value of the animation. Note that the value does not have to be one of the values that would ordinarily occur in the animation. Of course, if the animation is running, then the new value won't be around for long since it will change as soon as the next frame comes up.

getVal

public double getVal()

Get the current value of the Animator.

Specified by:

getVal in interface Value

getValueAsVariable

public Variable getValueAsVariable()

Get a variable whose value is always equal to the value of the animator. The name of the variable will be k.

getValueAsVariable

public Variable getValueAsVariable(java.lang.String name)

Get a variable whose value is always equal to the value of the animator. The name of the variable is specified by the parameter.

getOnChange

public Computable getOnChange()

Get the Controller that is notified (by calling its compute() method) whenever the frame changes. This can be null.

setOnChange

public void setOnChange(Computable onChange)

Set the Controller that is notified (by calling its compute() method) whenever the frame changes. If null, no Controller is notified. NOTE: Animators are different from InputObjects in that when onChange is null, the value of animator and its associated Variable will change without checkInput() being called. However, if the onChange is not null, then checkInput() must be called for the value to change. (So the Animation to be added to the Controller by calling the Controller's add() method. Then, the Controller will call the checkInput() method.)

notifyControllerOnChange

public void notifyControllerOnChange(Controller c)

Method required by the InputObject interface. It just calls setOnChange(c). This is meant to be called by the gatherInputs() method in JCMPanel.

Specified by:

notifyControllerOnChange in interface InputObject

getUndefinedWhenNotRunning

public boolean getUndefinedWhenNotRunning()

Get the value of the undefinedWhenNotRunning property.

setUndefinedWhenNotRunning

public void setUndefinedWhenNotRunning(boolean undefinedWhenNotRunning)

Set the value of the undefinedWhenNotRunning property. If this is true, then the value of the Animator is Double.NaN except when the animation is running (or paused), (or if it has been set by a call to the setVal() method). The default value is false.

start

public void start()

Start the animation from the first frame, or continue it if it was paused. This is called when the Start button or Start/Stop button is pressed, but it could also be called directly.

pause

public void pause()

Pause the animation, if it is running. This is called when the Pause button is pressed, but it could also be called directly.

next

public void next()

Advance the animation by one frame. This will start the animation from the first frame if it is stopped. This has no effect unless the animation is stopped or paused. This is called when the Next button pressed, but it could also be called directly.

prev

public void prev()

Advance the animation BACK one frame. This will start the animation from the first frame if it is stopped. This has no effect unless the animation is stopped or paused. This is called when the Prev button pressed, but it could also be called directly.

stop

public void stop()

Stop the animation, if it is running or paused. This is called when the Stop button or the StartStop button is pressed, but it could also be called directly. NOTE: If the Animator is in an applet, then it is a good idea to call the stop() method of the Animator from the applet's destroy() method.

actionPerformed

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

Respond to button clicks. This is not meant to be called directly.

Specified by:

actionPerformed in interface java.awt.event.ActionListener

itemStateChanged

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

Respond to clicks on pop-up menus. This is not meant to be called directly.

Specified by:

itemStateChanged in interface java.awt.event.ItemListener

checkInput

public void checkInput()

Part of the IputObject interface. This is meant to be called by a Controller.

Specified by:

checkInput in interface InputObject

getSerialNumber

public long getSerialNumber()

Part of the Tieable interface. This is meant to be called by other Tieable objects as part of object synchronization.

Specified by:

getSerialNumber in interface Tieable

sync

public void sync(Tie tie,
                 Tieable newest)

Part of the Tieable interface. This is meant to be called by Tie objects as part of object synchronization.

Specified by:

sync in interface Tieable

run

public void run()

The method that is run by the animation thread. This is not meant to be called directly.

Specified by:

run in interface java.lang.Runnable