acm.util
Class Animator

java.lang.Object
  java.lang.Thread
      acm.util.Animator

All Implemented Interfaces:

Runnable

public class Animator
extends Thread

This class extends Thread to provide several features that make it easier to build animations. These features include a pause method that does not raise an exception and a requestTermination method that signals that the execution of this thread should stop at its next opportunity. It also includes hooks to support a start/stop/single-step model for algorithm animation.

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Thread

Thread.State, Thread.UncaughtExceptionHandler

Field Summary

static int	CALLING Constant indicating that the animator is running until the end of the current call.
static int	FINISHED Constant indicating that the animator has finished its run method.
static int	INITIAL Constant indicating that the animator has not yet started.
static int	RUNNING Constant indicating that the animator is running.
static int	STEPPING Constant indicating that the animator is running in single-step mode.
static int	STOPPED Constant indicating that the animator is suspended waiting for restart.
static int	STOPPING Constant indicating that the animator should stop at the next trace point.
static int	TERMINATING Constant indicating that the animator has been asked to terminate.

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

Animator()
Creates a new Animator object.

Animator(Runnable runnable)
Creates a new Animator object with the specified runnable object.

Animator(ThreadGroup group)
Creates a new Animator object and assigns it to the specified thread group.

Animator(ThreadGroup group, Runnable runnable)
Creates a new Animator object with the specified runnable object and assigns it to the specified thread group.

Method Summary

protected void	breakHook() This method is called before the animator executes a breakpoint.
void	breakpoint() Suspends the animator until one of the restart actions is triggered.
boolean	buttonAction(String actionCommand) Triggers an action for the action specified by the action command.
void	callAction() Triggers a "call" action, as if the Call button is pushed.
void	checkForTermination() Checks to see whether this Animator has been asked to terminate.
protected void	controllerHook() This method is called before the animator changes state in a way that might interest a controller.
void	delay() Delays the calling thread according to the speed.
protected void	delayHook() This method is called before the animator enters a timing delay.
int	getAnimatorState() Returns the state of the animator.
double	getSpeed() Returns the speed parameter for the animator.
Component	getSpeedBar() Returns the speed bar for the animator, if any.
void	pause(double milliseconds) Delays this thread for the specified time, which is expressed in milliseconds.
void	registerSpeedBar(JScrollBar scrollBar) Registers the specified scroll bar as the delay controller for the animator.
void	registerSpeedBar(JSlider slider) Registers the specified slider as the delay controller for the animator.
void	requestTermination() Signals the Animator that it should stop running at the next available opportunity, which is when the client next calls pause or checkForTermination.
protected void	resumeHook() This method is called before the animator starts or restarts after a breakpoint.
void	run() Specifies the code for the animator.
void	setSpeed(double speed) Sets the speed parameter for the animator.
static void	shutdown(Applet applet) Destroys all animator threads started by the specified applet.
void	start() Starts the thread.
void	startAction() Triggers a "start" action, as if the Start button is pushed.
void	stepAction() Triggers a "step" action, as if the Step button is pushed.
void	stopAction() Triggers a "stop" action, as if the Stop button is pushed.
void	trace() Checks the state of the animator and executes any actions have been requested.
void	trace(int depth) Checks the state of the animator and executes any actions have been requested to occur at the specified call stack depth.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

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

Field Detail

CALLING

public static final int CALLING

Constant indicating that the animator is running until the end of the current call.

See Also:

Constant Field Values

FINISHED

public static final int FINISHED

Constant indicating that the animator has finished its run method.

See Also:

Constant Field Values

INITIAL

public static final int INITIAL

Constant indicating that the animator has not yet started.

See Also:

Constant Field Values

RUNNING

public static final int RUNNING

Constant indicating that the animator is running.

See Also:

Constant Field Values

STEPPING

public static final int STEPPING

Constant indicating that the animator is running in single-step mode.

See Also:

Constant Field Values

STOPPED

public static final int STOPPED

Constant indicating that the animator is suspended waiting for restart.

See Also:

Constant Field Values

STOPPING

public static final int STOPPING

Constant indicating that the animator should stop at the next trace point.

See Also:

Constant Field Values

TERMINATING

public static final int TERMINATING

Constant indicating that the animator has been asked to terminate.

See Also:

Constant Field Values

Constructor Detail

Animator

public Animator()

Creates a new Animator object.

Animator

public Animator(Runnable runnable)

Creates a new Animator object with the specified runnable object.

Parameters:

runnable - Any object that implements the Runnable interface

Animator

public Animator(ThreadGroup group)

Creates a new Animator object and assigns it to the specified thread group.

Parameters:

group - The ThreadGroup to which the new thread is assigned

Animator

public Animator(ThreadGroup group,
                Runnable runnable)

Creates a new Animator object with the specified runnable object and assigns it to the specified thread group.

Parameters:

group - The ThreadGroup to which the new thread is assigned

runnable - Any object that implements the Runnable interface

Method Detail

breakHook

protected void breakHook()

This method is called before the animator executes a breakpoint. Subclasses should override this method if they need to perform some kind of action at this point, such as updating the display.

breakpoint

public void breakpoint()

Suspends the animator until one of the restart actions is triggered.

buttonAction

public boolean buttonAction(String actionCommand)

Triggers an action for the action specified by the action command.

Parameters:

actionCommand - The action command from the button

Returns:

true if the action command is recognized

callAction

public void callAction()

Triggers a "call" action, as if the Call button is pushed.

checkForTermination

public void checkForTermination()

Checks to see whether this Animator has been asked to terminate. If so, the Animator stops running, and the call never returns. If not, other threads are given a chance to run, after which this Animator will return to the caller.

controllerHook

protected void controllerHook()

This method is called before the animator changes state in a way that might interest a controller. Subclasses will typically override this hook to update the enabled status of buttons and menu items.

delay

public void delay()

Delays the calling thread according to the speed.

delayHook

protected void delayHook()

This method is called before the animator enters a timing delay. Subclasses should override this method if they need to perform some kind of action at this point, such as updating the display.

getAnimatorState

public int getAnimatorState()

Returns the state of the animator. This value will be one of the constants INITIAL, RUNNING, STEPPING, CALLING, STOPPING, STOPPED, FINISHED, or TERMINATING, as defined in this class.

Returns:

The current state of the animator

getSpeed

public double getSpeed()

Returns the speed parameter for the animator. The speed is a double between 0.0 and 1.0, for which 0.0 is very slow and 1.0 is as fast as the system can manage.

Returns:

A double between 0.0 (slow) and 1.0 (fast)

getSpeedBar

public Component getSpeedBar()

Returns the speed bar for the animator, if any. The speed bar can be a JSlider or a JScrollBar; it is the caller's responsibility to cast the result to the appropriate class.

Returns:

The speed bar, or null if none exists

pause

public void pause(double milliseconds)

Delays this thread for the specified time, which is expressed in milliseconds. Unlike Thread.sleep, this method never throws an exception.

Parameters:

milliseconds - The sleep time in milliseconds

registerSpeedBar

public void registerSpeedBar(JScrollBar scrollBar)

Registers the specified scroll bar as the delay controller for the animator.

Parameters:

scrollBar - The scroll bar which will serve as the speed bar for this animator

registerSpeedBar

public void registerSpeedBar(JSlider slider)

Registers the specified slider as the delay controller for the animator.

Parameters:

slider - The slider which will serve as the speed bar for this animator

requestTermination

public void requestTermination()

Signals the Animator that it should stop running at the next available opportunity, which is when the client next calls pause or checkForTermination. Making this check at well-managed times makes it possible for the client to ensure that objects are left in a consistent state and thereby avoids the problems that led Sun to deprecate Thread.stop.

resumeHook

protected void resumeHook()

This method is called before the animator starts or restarts after a breakpoint. Subclasses should override this method if they need to perform some kind of action at this point.

run

public void run()

Specifies the code for the animator. Subclasses should override this method with the code they need to execute to implement the animator's function.

Specified by:

run in interface Runnable

Overrides:

run in class Thread

setSpeed

public void setSpeed(double speed)

Sets the speed parameter for the animator. The speed is a double between 0.0 and 1.0, for which 0.0 is very slow and 1.0 is as fast as the system can manage.

Parameters:

speed - A double between 0.0 (slow) and 1.0 (fast)

shutdown

public static void shutdown(Applet applet)

Destroys all animator threads started by the specified applet. This method ensures that applet cleanup occurs in browsers that refuse to terminate an applet that still has threads running.

Parameters:

applet - The applet that is ending its execution

start

public void start()

Starts the thread. The only difference in this method is that it also sets the state.

Overrides:

start in class Thread

startAction

public void startAction()

Triggers a "start" action, as if the Start button is pushed.

stepAction

public void stepAction()

Triggers a "step" action, as if the Step button is pushed.

stopAction

public void stopAction()

Triggers a "stop" action, as if the Stop button is pushed.

trace

public void trace()

Checks the state of the animator and executes any actions have been requested.

trace

public void trace(int depth)

Checks the state of the animator and executes any actions have been requested to occur at the specified call stack depth. This method is useful only to clients who are making use of the Call button functionality.

Parameters:

depth - The current call stack depth.