edu.umd.cs.piccolo.activities
Class PActivity

java.lang.Object
  edu.umd.cs.piccolo.activities.PActivity

Direct Known Subclasses:

PInterpolatingActivity

public class PActivity
extends Object

PActivity controls some time dependent aspect of Piccolo, such as animation. Once created activities must be scheduled with the PActivityScheduler managed by the PRoot to run. They are automatically removed from the scheduler when the animation has finished.

See the PNode.animate*() methods for an example of how to set up and run different activities.

Version:

1.0

Author:

Jesse Grosjean

Nested Class Summary

static interface

PActivity.PActivityDelegate PActivityDelegate is used by classes to learn about and act on the different states that a PActivity goes through, such as when the activity starts and stops stepping.

Field Summary

static int	TERMINATE_AND_FINISH Parameter for terminate that signifies that activity should bail out immediately, but flag activity as finished.
static int	TERMINATE_AND_FINISH_IF_STEPPING Parameter for terminate that signifies that activity should bail out immediately, if currently active.
static int	TERMINATE_WITHOUT_FINISHING Parameter for terminate that signifies that activity should bail out immediately without flagging activity as finished.

Constructor Summary

PActivity(long aDuration)
Constructs a new PActivity.

PActivity(long aDuration, long aStepRate)
Constructs a new PActivity.

PActivity(long aDuration, long aStepRate, long aStartTime)
Constructs a new PActivity.

Method Summary

protected void	activityFinished() This method is called after an activity is has finished running and the activity has been removed from the PActivityScheduler queue.
protected void	activityStarted() This method is called right before an activity is scheduled to start running.
protected void	activityStep(long elapsedTime) This is the method that most activities override to perform their behavior.
PActivityScheduler	getActivityScheduler() Returns the activity scheduler associated with this activity.
PActivity.PActivityDelegate	getDelegate() Get the delegate for this activity.
long	getDuration() Return the amount of time that this activity should take to complete, after the startStepping method is called.
long	getNextStepTime() Gets the next step time desired for this activity.
long	getStartTime() Return the time that this activity should start running in PRoot global time.
long	getStepRate() Return the amount of time that this activity should delay between steps.
long	getStopTime() Return the time when this activity should finish running.
protected boolean	isAnimation() Return true if this activity is performing an animation.
boolean	isStepping() Return true if this activity is stepping.
protected String	paramString() Deprecated. see http://code.google.com/p/piccolo2d/issues/detail?id=99
long	processStep(long currentTime) The activity scheduler calls this method and it is here that the activity decides if it should do a step or not for the given time.
void	setActivityScheduler(PActivityScheduler aScheduler) Informs the activity of the scheduler that will be responsible for scheduling it.
void	setDelegate(PActivity.PActivityDelegate delegate) Set the delegate for this activity.
void	setDuration(long aDuration) Set the amount of time that this activity should take to complete, after the startStepping method is called.
void	setStartTime(long aTriggerTime) Set the time that this activity should start running in PRoot global time.
void	setStepRate(long aStepRate) Set the amount of time that this activity should delay between steps.
void	startAfter(PActivity first) Schedules this activity to start after the first activity has finished.
void	terminate() Stop this activity immediately, and remove it from the activity scheduler.
void	terminate(int terminationBehavior) Stop this activity immediately, and remove it from the activity scheduler.

Methods inherited from class java.lang.Object

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

Field Detail

TERMINATE_WITHOUT_FINISHING

public static final int TERMINATE_WITHOUT_FINISHING

Parameter for terminate that signifies that activity should bail out immediately without flagging activity as finished.

See Also:

Constant Field Values

TERMINATE_AND_FINISH

public static final int TERMINATE_AND_FINISH

Parameter for terminate that signifies that activity should bail out immediately, but flag activity as finished.

See Also:

Constant Field Values

TERMINATE_AND_FINISH_IF_STEPPING

public static final int TERMINATE_AND_FINISH_IF_STEPPING

Parameter for terminate that signifies that activity should bail out immediately, if currently active.

See Also:

Constant Field Values

Constructor Detail

PActivity

public PActivity(long aDuration)

Constructs a new PActivity.

Parameters:

aDuration - the amount of time that this activity should take to complete, -1 for infinite.

PActivity

public PActivity(long aDuration,
                 long aStepRate)

Constructs a new PActivity.

Parameters:

aDuration - the amount of time that this activity should take to complete, -1 for infinite.

aStepRate - the maximum rate that this activity should receive step events.

PActivity

public PActivity(long aDuration,
                 long aStepRate,
                 long aStartTime)

Constructs a new PActivity.

Parameters:

aDuration - the amount of time that this activity should take to complete, -1 for infinite.

aStepRate - the maximum rate that this activity should receive step events.

aStartTime - the time (relative to System.currentTimeMillis()) that this activity should start.

Method Detail

getStartTime

public long getStartTime()

Return the time that this activity should start running in PRoot global time. When this time is reached (or soon after) this activity will have its startStepping() method called.

Returns:

time at which this activity should start in PRoot global time.

setStartTime

public void setStartTime(long aTriggerTime)

Set the time that this activity should start running in PRoot global time. When this time is reached (or soon after) this activity will have its startStepping() method called.

Parameters:

aTriggerTime - time at which you want this activity to begin in PRoot global time

getStepRate

public long getStepRate()

Return the amount of time that this activity should delay between steps.

Returns:

the desired milliseconds between steps

setStepRate

public void setStepRate(long aStepRate)

Set the amount of time that this activity should delay between steps.

Parameters:

aStepRate - desired step rate in milliseconds between steps

getNextStepTime

public long getNextStepTime()

Gets the next step time desired for this activity. Exists since some steps might eat into the step rate otherwise.

Returns:

next calculated step time

getDuration

public long getDuration()

Return the amount of time that this activity should take to complete, after the startStepping method is called.

Returns:

time that this activity should take to complete

setDuration

public void setDuration(long aDuration)

Set the amount of time that this activity should take to complete, after the startStepping method is called.

Parameters:

aDuration - desired duration this activity should take (-1 for infinite) once it begins stepping

getActivityScheduler

public PActivityScheduler getActivityScheduler()

Returns the activity scheduler associated with this activity.

Returns:

associated scheduler

setActivityScheduler

public void setActivityScheduler(PActivityScheduler aScheduler)

Informs the activity of the scheduler that will be responsible for scheduling it.

Parameters:

aScheduler - scheduler to associate with this activity

isStepping

public boolean isStepping()

Return true if this activity is stepping.

Returns:

whether this activity is stepping

isAnimation

protected boolean isAnimation()

Return true if this activity is performing an animation. This is used by the PCanvas to determine if it should set the render quality to PCanvas.animatingRenderQuality or not for each frame it renders.

Returns:

whether this activity is an animation, subclasses can override this.

activityStarted

protected void activityStarted()

This method is called right before an activity is scheduled to start running. After this method is called step() will be called until the activity finishes.

activityStep

protected void activityStep(long elapsedTime)

This is the method that most activities override to perform their behavior. It will be called repeatedly when the activity is running.

Parameters:

elapsedTime - the amount of time that has passed relative to the activities startTime.

activityFinished

protected void activityFinished()

This method is called after an activity is has finished running and the activity has been removed from the PActivityScheduler queue.

getDelegate

public PActivity.PActivityDelegate getDelegate()

Get the delegate for this activity. The delegate is notified when the activity starts and stops stepping.

Returns:

delegate of this activity, may be null

setDelegate

public void setDelegate(PActivity.PActivityDelegate delegate)

Set the delegate for this activity. The delegate is notified when the activity starts and stops stepping.

Parameters:

delegate - delegate that should be informed of activity events

startAfter

public void startAfter(PActivity first)

Schedules this activity to start after the first activity has finished. Note that no link is created between these activities, if the startTime or duration of the first activity is later changed this activities start time will not be updated to reflect that change.

Parameters:

first - activity after which this activity should be scheduled

terminate

public void terminate()

Stop this activity immediately, and remove it from the activity scheduler. The default termination behavior is call activityFinished if the activity is currently stepping. Use terminate(terminationBehavior) use a different termination behavior.

terminate

public void terminate(int terminationBehavior)

Stop this activity immediately, and remove it from the activity scheduler. The termination behavior determines when and if activityStarted and activityFinished get called. The possible termination behaviors are as follow: TERMINATE_WITHOUT_FINISHING - The method activityFinished will never get called and so the activity will be terminated midway. TERMINATE_AND_FINISH - The method activityFinished will always get called. And so the activity will always end in it's completed state. If the activity has not yet started the method activityStarted will also be called. TERMINATE_AND_FINISH_IF_STEPPING - The method activityFinished will only be called if the activity has previously started.

Parameters:

terminationBehavior - behavior to use regarding delegate notification and event firing

processStep

public long processStep(long currentTime)

The activity scheduler calls this method and it is here that the activity decides if it should do a step or not for the given time.

Parameters:

currentTime - in global root time

Returns:

number of milliseconds in global root time before processStep should be called again, -1 if never

getStopTime

public long getStopTime()

Return the time when this activity should finish running. At this time (or soon after) the stoppedStepping method will be called

Returns:

time at which this activity should be stopped

paramString

protected String paramString()

Deprecated. see http://code.google.com/p/piccolo2d/issues/detail?id=99

Returns:

string representation of this activity