ActionQueue

Kind of class: public class
Package:
Inherits from:
  • EventDispatcher
Implements:
Classpath: org.asaplibrary.util.actionqueue.ActionQueue
File last modified: Wednesday, 11 May 2011, 18:51:25
Creates a series of sequential animation/function calls, or "actions". Each action is performed one after the other. Actions are objects of type Action, IAction, TimedAction or ITimedAction or any subclass thereof. The actual function calling is done by ActionRunner. Use ActionQueue to create the action objects from input arguments, and to add ready-made elements like markers, loops pause and condition functions. What's new compared to the previous version in ASAP Framework (AS2)?
  • Total rewrite of the code
  • ActionQueue now runs generic Action objects (Command pattern)
  • ActionQueue actions can be ActionQueues in itself
  • Because of a (relatively small) syntax change, any call to a ready-made animation class like AQFade is now compile checked
  • Integrated looping from ExtendedActionQueue (now defunct)
  • Added markers and events from markers
  • Added conditions
  • Markers and conditions combined make it possible to synchronize separate queues
  • Method "addInAction" has been replaced with "addAsynchronousAction"; asynchronous actions still run in their own thread, but can be paused, stopped and quit by the main queue
Example
  • This ActionQueue moves a MovieClip, then lets it fade out to alpha 0 in .5 seconds: 
    my_mc.alpha = 0;
var queue:ActionQueue  = new ActionQueue();
var CURRENT:Number = Number.NaN;
queue.addAction(new AQMove().move(
my_mc, 1.0, CURRENT, CURRENT, 800, CURRENT, Cubic.easeOut
));
queue.addAction(new AQFade().fade(
my_mc, .5, CURRENT, 0
));
Events broadcasted to listeners

Summary

Instance methods
  • addAction (...args:Array) : void
    • Creates an Action from input arguments and adds it to the queue.
  • addAsynchronousAction (...args:Array) : void
    • Adds an Action that is run asynchronously: other actions will follow right after and will not wait for this action to finish.
  • getActions () : Array
  • isRunning () : Boolean
  • stop () : void
    • Stops the queue.
  • addCondition (inCondition:Condition) : void
    • Adds a Condition to the queue.
  • addPause (inDuration:Number = Number.NaN) : void
    • Use pause() to add a paused state to the queue; when this action is run the queue is paused until resume is called on it.
  • togglePlay () : void
    • Toggles the playing/paused state of the queue.
  • pause (inContinueWhereLeftOff:Boolean = true) : void
    • Pauses the current running action and all asynchronous actions.
  • resume () : void
    • Resumes a paused queue.
  • quit () : void
    • Quits the queue.
  • skip () : void
    • Skips to the next action (if any).
  • goToMarker (inMarkerName:String) : void
    • Jumps the action pointer to a marker.
  • addGoToMarker (inMarkerName:String) : void
    • Adds a "go to marker" action to the queue.
  • addMarker (inMarkerName:String) : void
    • Adds a marker to the queue.
  • addStartLoop (inLoopName:String, inLoopCount:int) : void
    • Adds a "start of loop" marker to the queue.
  • addEndLoop (inLoopName:String) : void
    • Adds a "end of loop" marker to the queue.
  • endLoop (inLoopName:String, inAbortLoop:Boolean = false) : void
    • Ends a current running loop.
  • lastVisitedMarker () : String
    • Name of the last visited marker.
  • didVisitMarker (inMarkerName:String) : Boolean
    • Check whether the queue did pass a marker.
  • isFinished () : Boolean
  • reset () : void
    • Resets the queue: stops current ActionRunners, removes all actions, clears the "visited markers" history.
  • isPaused () : Boolean
  • run () : *
    • Starts the queue.

Instance methods

addAction

function addAction(...args:Array) : void

Creates an Action from input arguments and adds it to the queue. This method accepts a number of argument configurations that are translated into an Action object. You can also directly add an Action or TimedAction object. Adding an Action object You can add any object of type Action, IAction, TimedAction and ITimedAction - including complete ActionQueues! public function addAction (inAction:IAction) : void Example: 

var queue:ActionQueue = new ActionQueue();
var action:Action = new Action(createShapes, 10);
queue.addAction(action);    
queue.run();
Adding a local function Will be called in local scope. public function addAction (inFunction:Function, argument1, argument2, ...) : void Example: 
var queue:ActionQueue = new ActionQueue();
queue.addAction(createShapes, 10);    
queue.run();
Adding a object's method Will be called in the object's scope. public function addAction (inMethod:Function, argument1, argument2, ...) : void Example: 
var queue:ActionQueue = new ActionQueue();
queue.addAction(mShapeCreator.createShapes, 10);
queue.run();
Adding a object's method by name Will be called in the object's scope. The method must have public access. public function addAction (inMethodOwner:Object, inMethodName:String, argument1, argument2, ...) : void Example: 
var queue:ActionQueue = new ActionQueue();
queue.addAction(mShapeCreator, "createShapes", 10);    
queue.run();
Using ready-made animation methods You can use any function that returns a TimedAction, or use one of the ready made class metods from these classes: AQAddMove AQBlink AQFade AQFollowMouse AQMove AQPulse AQFunction AQScale AQSet AQTimeline Example: This example will fade out a MovieClip from the current alpha to 0 in 0.5 seconds: 
var queue:ActionQueue = new ActionQueue();
var CURRENT:Number = Number.NaN;
queue.addAction(new AQFade().fade(my_mc, .5, CURRENT, 0));
queue.run();
Custom timed actions Similar to "Adding an Action": add a TimedAction object. Example: 
var action:TimedAction = new TimedAction(doMoveAndScale, duration, effect);
queue.addAction(action);
... where function doMoveAndScale performs the animation based on the percentage value it receives: 
protected function doMoveAndScale (inValue:Number) : Boolean {
    
var percentage:Number = 1-inValue; // end of animation: inValue == 0
    
tClip.x = NumberUtils.percentageValue(initX, mClipData.endx, percentage);
tClip.y = NumberUtils.percentageValue(initY, mClipData.endy, percentage);
tClip.scaleX = tClip.scaleY = NumberUtils.percentageValue(1, mClipData.endscale, percentage);
    
return true; // if false the action will stop
}

Parameters
args:argument list

addAsynchronousAction

function addAsynchronousAction(...args:Array) : void

Adds an Action that is run asynchronously: other actions will follow right after and will not wait for this action to finish. Asynchronous actions can be paused and stopped with pause and stop.

Parameters
args:argument list; see addAction

addCondition

function addCondition(inCondition:Condition) : void

Adds a Condition to the queue. A running queue is automatically halted as long as the condition is not met. The condition will be checked on each frame update (using FramePulse events.

Parameters
inCondition:the condition to add
Example 
  • var q1:ActionQueue = new ActionQueue();
var q2:ActionQueue = new ActionQueue();
var q3:ActionQueue = new ActionQueue();

var condition:Function = function () : Boolean {
return (q1.didVisitMarker("BAR1")
&& q2.didVisitMarker("BAR1")
&& q3.didVisitMarker("BAR1"));
}
var condition:Condition = new Condition (condition);
var rightPos:Number = 800;
var duration:Number = 4.0;
var CURRENT:Number = Number.NaN;
q1.addAction(new AQMove().move(my_mc1, duration1, CURRENT, CURRENT, rightPos, CURRENT));
q1.addMarker("BAR1");
q1.addCondition(condition1);
// q1 will continue here as soon as the condition is met

// ... (similar for other queues)

q1.run();
q2.run();
q3.run();
Implementation note

addEndLoop

function addEndLoop(inLoopName:String) : void

Adds a "end of loop" marker to the queue.

Parameters
inLoopName:name of the loop (should be unique for this queue)
See also

addGoToMarker

function addGoToMarker(inMarkerName:String) : void

Adds a "go to marker" action to the queue.

Parameters
inMarkerName:name of the marker

addMarker

function addMarker(inMarkerName:String) : void

Adds a marker to the queue. Markers can be used to receive an event when the queue passes a marker, or to jump to a specific point in the queue.

Parameters
inMarkerName:name of the marker
Example
  • This example shows how to listen for marker events: 
    var queue:ActionQueue = new ActionQueue();
var CURRENT:Number = Number.NaN;
queue.addAction(new AQMove().move(my_mc, duration, CURRENT, CURRENT, marker1_mc.x, marker1_mc.y));
queue.addMarker("MARKER_1");
queue.addAction(new AQMove().move(my_mc, duration, CURRENT, CURRENT, marker2_mc.x, marker2_mc.y));
queue.addMarker("MARKER_2");
    Add a listener: 
    queue.addEventListener(ActionEvent._EVENT, onActionEvent);
queue.run();

    public function onActionEvent (e:ActionEvent) : void {
switch (e.subtype) {
case ActionEvent.MARKER_VISITED:
handleMarkerPassed(e);
break;
}
}

public function handleMarkerPassed (e:ActionEvent) : void {
// do something
}

addPause

function addPause(inDuration:Number = Number.NaN) : void

Use pause() to add a paused state to the queue; when this action is run the queue is paused until resume is called on it. Use pause(duration) to add a waiting action to the queue.

Parameters
inDuration:pause time in seconds; use 0 to pause indeterminately.

addStartLoop

function addStartLoop(inLoopName:String, inLoopCount:int) : void

Adds a "start of loop" marker to the queue.

Parameters
inLoopName :name of the loop (should be unique for this queue)
inLoopCount:(optional) the number of times the looped section should run; default 0 (infinite)
Example
  • This example shows how to set loop markers to run a section 3 times: 
    var queue:ActionQueue = new ActionQueue();
queue.addAction(new AQMove().move(loop_mc, duration, CURRENT, CURRENT, marker1_mc.x, marker1_mc.y));
queue.addStartLoop("MY_LOOP", 3);
queue.addAction(new AQMove().move(loop_mc, duration, CURRENT, CURRENT, marker2_mc.x, marker2_mc.y));
queue.addAction(new AQMove().move(loop_mc, duration, CURRENT, CURRENT, marker3_mc.x, marker3_mc.y));
queue.addAction(new AQMove().move(loop_mc, duration, CURRENT, CURRENT, marker1_mc.x, marker1_mc.y));
queue.addEndLoop("MY_LOOP");
queue.run();
See also

didVisitMarker

function didVisitMarker(inMarkerName:String) : Boolean

Check whether the queue did pass a marker. The marker has to be 'run' - any jumps over in-between markers will not mark it as 'passed'.

Parameters
inMarkerName:name of the marker
Returns
  • True if the marker action with name was visited; otherwise false.

endLoop

function endLoop(inLoopName:String, inAbortLoop:Boolean = false) : void

Ends a current running loop.

Parameters
inLoopName :name of the loop (should be unique for this queue)
inFinishLoopFirst:true if the loop should be run to the end; false if the loop should be aborted - the action pointer jumps to the first action after the "end of loop" marker; any currently running action will be finished first

getActions

function getActions() : Array
Returns
  • The list of queued actions (including already run actions).

goToMarker

function goToMarker(inMarkerName:String) : void

Jumps the action pointer to a marker.

Parameters
inMarkerName:name of the marker

isFinished

function isFinished() : Boolean
Returns
  • True when all Actions (including asynchronous actions) are finished.

isPaused

function isPaused() : Boolean
Returns
  • True when the main runner is paused.

isRunning

function isRunning() : Boolean
Returns
  • True if the main ActionRunner is (still) running; false if it is stopped or finished. A paused but running queue will return true.

lastVisitedMarker

function lastVisitedMarker() : String

Name of the last visited marker.

pause

function pause(inContinueWhereLeftOff:Boolean = true) : void

Pauses the current running action and all asynchronous actions.

Parameters
inContinueWhereLeftOff:(optional) whether the running Action should continue where it left off when the queue is resumed
Events broadcasted to listeners

quit

function quit() : void

Quits the queue.

Events broadcasted to listeners

reset

function reset() : void

Resets the queue: stops current ActionRunners, removes all actions, clears the "visited markers" history.

resume

function resume() : void

Resumes a paused queue.

Events broadcasted to listeners

run

function run() : *

Starts the queue.

Events broadcasted to listeners

stop

function stop() : void

Stops the queue.

Implementation note
Events broadcasted to listeners

togglePlay

function togglePlay() : void

Toggles the playing/paused state of the queue.