acm.util
Class Animator

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

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.

Field Summary

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

Constructor Summary

Animator()

Method Summary

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.
void	delay() Delays the calling thread according to the speed.
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.
void	run() Specifies the code for the animator.
void	setSpeed(double speed) Sets the speed parameter for the animator.
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.

Field Detail

public static final int CALLING

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

See Also:

Constant Field Values

public static final int FINISHED

Constant indicating that the animator has finished its run method.

See Also:

Constant Field Values

public static final int INITIAL

Constant indicating that the animator has not yet started.

See Also:

Constant Field Values

public static final int RUNNING

Constant indicating that the animator is running.

See Also:

Constant Field Values

public static final int STEPPING

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

See Also:

Constant Field Values

public static final int STOPPED

Constant indicating that the animator is suspended waiting for restart.

See Also:

Constant Field Values

public static final int STOPPING

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

See Also:

Constant Field Values

public static final int TERMINATING

Constant indicating that the animator has been asked to terminate.

See Also:

Constant Field Values

Constructor Detail

public Animator()

Creates a new Animator object.

Usage:

Animator animator = new Animator();

Method Detail

public void breakpoint()

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

Usage:

animator.breakpoint();

public boolean buttonAction(String actionCommand)

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

Usage:

boolean ok = animator.buttonAction(actionCommand);

Parameter:

actionCommand

The action command from the button

Returns:

true if the action command is recognized

public void callAction()

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

Usage:

animator.callAction();

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.

Usage:

checkForTermination();

public void delay()

Delays the calling thread according to the speed.

Usage:

animator.delay();

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.

Usage:	int state = animator.getAnimatorState();
Returns:	The current state of the animator

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.

Usage:	double speed = animator.getSpeed();
Returns:	A double between 0.0 (slow) and 1.0 (fast)

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

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.

Usage:

animator.pause(milliseconds);

Parameter:

milliseconds

The sleep time in milliseconds

public void registerSpeedBar(JScrollBar scrollBar)

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

Usage:

registerSpeedBar(scrollBar);

Parameter:

scrollBar

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

public void registerSpeedBar(JSlider slider)

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

Usage:

registerSpeedBar(slider);

Parameter:

slider

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

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.

Usage:

requestTermination();

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

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.

Usage:

animator.setSpeed(speed);

Parameter:

speed

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

public void start()

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

Usage:

animator.start();

public void startAction()

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

Usage:

animator.startAction();

public void stepAction()

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

Usage:

animator.stepAction();

public void stopAction()

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

Usage:

animator.stopAction();

public void trace()

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

Usage:

animator.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.

Usage:

animator.trace(depth);

Parameter:

depth

The current call stack depth.