Articles:PropertyTween

From CASA Framework

Contents 1 PropertyTween Tutorial Overview 1.1 Preface 1.2 Tutorial Downloads 1.3 Setting Up Your Files 1.4 The Tutorial Example 2 PropertyTween 2.1 Setting up a PropertyTween 2.2 Controlling a PropertyTween 2.2.1 start 2.2.2 stop 2.2.3 resume 2.2.4 destroy 2.3 Adding Event Observers 2.3.1 EVENT_PROGRESS 2.3.2 EVENT_COMPLETE 2.4 Setting a Timeout 3 Conclusion

[edit] PropertyTween Tutorial Overview

(This article is using the CASA Framework)

[edit] Preface

PropertyTween is a versatile and elementary tool that is an essential component of the CASA framework. This tutorial will go over the basics of setting up PropertyTweens, adding event observers, and implementing garbage collection.

[edit] Tutorial Downloads

• Download the tutorial's assets: PropertyTween_Tutorial.zip.

You'll need these additional assets to compile the tutorial outlined in this article:

• The latest release of the CASA Framework (1.0.3 or higher)
• Robert Penner's ActionScript 2.0 Easing Equations

[edit] Setting Up Your Files

Download and familiarize yourself with the tutorial FLA. Make sure to modify the FLA's classpaths to match your specific set up. I'll be referring to specific line numbers in the FLA, so resist the urge to format the code differently.

[edit] The Tutorial Example

The example below utilizes PropertyTween's dispatched events to observe the status of a PropertyTween. The example also uses CASA's Interval class's setTimeout method to trigger a one time firing of a function at a specified delay. Once each animation has completed, it goes through a garbage collection routine to keep the memory usage low.

On the example's stage there are four MovieClips containing circles that will have their _x properties tweened across the stage. The second and third clips' PropertyTweens are triggered by event observers registered to the first PropertyTween. The fourth clip's PropertyTween is triggered by a the Interval's timeout.

[edit] PropertyTween

This section will go over the basics of configuring a PropertyTween and controlling it, as well as adding event observers and using the Interval class's setTimeout to delay controls.

[edit] Setting up a PropertyTween

I've created all the PropertyTweens (PT) between line 36 and 39 of the code, their names where declared on lines 13 thru 16 (an extensive breakdown of how the Class constructor works can be found in the CASA Documentation). For clarity, I have named each PT after the clip it's associated with and have appended "_pt" to its name. So the PT for the MovieClip circle1_mc is circle1_pt.

this.circle1_pt = new PropertyTween(this.circle1_mc, "_x", Linear.easeNone, this.endPosition, 4);

The above line of code defines the variable circle1_pt to reference the new PropertyTween, which tells the MovieClip circle1_mc to tween it's _x property with no easing (Linear.easeNone) to the endPosition of 650 (defined on line 10) and take 4 seconds to complete.

[edit] Controlling a PropertyTween

For this tutorial we will be focusing on four of PropertyTween's methods; start(), stop(), resume() and destroy(). If you'd like to find out more about about PropertyTween's methods, you can find them in the documentation.

[edit] start

Once your PT has instantiated you can call the start() method to begin the PT.

In the tutorial file: most of the PTs' start() methods are called from event observers. There is also one called from a timeout (line 102), and another called directly from the function configureAnimations on line 65.

Note: If you start() a PT, then tell it to stop(), then tell it to start() again it will restart the PT from beginning. If you'd rather have the PT resume from the position where it was stopped you'll want to use the resume() method described below.

[edit] stop

Stopping a PT will pause the progress of the PT, which can then be resumed with the resume() method.

In the tutorial file: the stop() method is only called from the associated buttons on stage (these buttons are enabled with the function configureButtons starting on line 70.

[edit] resume

Resuming a PT will begin the progress of the PT from the point in time where it was stopped.

In the tutorial file: the resume() method is only called from the associated buttons on stage (these buttons are enabled with the function configureButtons starting on line 70.

[edit] destroy

Destroying a PT removes internal variables, enterFrame callbacks, and event observers to allow the object have a smaller footprint and to be more easily garbage collected. For more information about garbage collection see Quick Tips:Garbage Collection.

In the tutorial file: Due to limitations of coding in Flash's timeline, we've had to create a series of functions named specifically for the PTs they will be garbage collecting for. The event observers for this are added at line 52 and the functions are declared between lines 110 and 131. You would ideally build a destroy method into your classes outside of the timeline.

[edit] Adding Event Observers

The two types of events covered in this tutorial are onProgress and onComplete; you can find documentation on PropertyTween's other events in the CASA docs.

this.circle1_pt.addEventObserver(this, PropertyTween.EVENT_PROGRESS, "monitorCircle1TweenProgress");

(Line 46)

Note: In the example above PropertyTween.EVENT_PROGRESS is used instead of "onProgress". The advantage in using PropertyTween.EVENT_PROGRESS is that it's a property of PropertyTween so if it's misspelled it'll return an error. However if you pass a non-valid string, it'll fail silently.

[edit] EVENT_PROGRESS

On each frame while the PT is tweening, the onProgress observer is triggered which then calls the function monitorCircle1TweenProgress.

Note: If you want to trigger another PT at a specific point of the onProgress you'll want to create the logic so it only fires the start() command once (otherwise onProgress will continually start(), and therefore restart it's timer and appear to make no progress). In the tutorial I wanted the animation to only fire once at the 50%+ point, you can find the logic in the function monitorCircle1TweenProgress (line 94).

[edit] EVENT_COMPLETE

On line 47 an event observer has been added to circle1_pt to monitor when the PT is finished. When circle1_pt has completed its tween, it will then tell circle3_pt to start().

this.circle1_pt.addEventObserver(this.circle3_pt, PropertyTween.EVENT_COMPLETE, "start");

[edit] Setting a Timeout

circle4_pt is triggered by setTimeout, which belongs to CASA's Interval class. A "timeout" is a request to call a specified method (only once) after a specified amount of time. The benefits of using CASA's Interval class (versus the _global.setInterval() method) are its added robustness, its efficiency, and the fact that it is managed and controlled in the same manner as the rest of CASA.

this.circle4_si = Interval.setTimeout(this, "startCircle4Tween", 6000);

this.circle4_si.start();

(Lines 59-62)

The code above creates a timeout named circle4_si. Its scope is set to this (the _root timeline), and it will fire the method startCircle4Tween (Line 101) 6 seconds after the Interval is started. We want to start the Interval immediately, so we call the start() method right after it is created.

[edit] Conclusion

PropertyTween, as shown in this tutorial, is a very useful, versatile tweening engine for tweening property values of MovieClips. However, this class can not only be used with MovieClips, but any class with numeric properties.

And because PropertyTween extends CASA's powerful EventDispatcher, you can easily watch numerous events associated with your PropertyTween. In the tutorial, we only demonstrated the EVENT_PROGRESS and EVENT_COMPLETE events. Here is the full list:

• EVENT_COMPLETE
• EVENT_POSITION
• EVENT_PROGRESS
• EVENT_RESUME
• EVENT_START
• EVENT_STOP

This gives you complete control over how your application responds to your PropertyTween.

By using the CASA Interval class, we also demonstrated how to delay the start of a tween (since instantiating a PropertyTween doesn't actually put it in motion). You can read some Quick Tips about the Interval class if you want to see other ways of using it.

Lastly we touched on how to make use of the EVENT_COMPLETE event dispatched by our PropertyTweens to trigger some garbage collection routines. By employing the common CASA destroy() method, the PropertyTween will clean up any resources within itself. You can read more about how CASA makes garbage collection easy by reading this Quick Tip about Garbage Collection.