Using Animation
Apple provides a JavaScript class that functions as an animation timer, useful for animating fading elements or a series of images. The classes that provide this, AppleAnimator
and AppleAnimation
, are part of the Apple Classes included in OS X v10.4.3 and later.
For more on using all of the Apple Classes, including AppleAnimator
and AppleAnimation
, read Introduction to the Apple Classes.
Working with Animation
Providing an animation in your widget can be achieved using the AppleAnimator
and AppleAnimation
classes. AppleAnimator
is a timer that fires at designated intervals for a defined duration. The AppleAnimation
contains a set of values and a handler. As AppleAnimations
are added to AppleAnimators
, values in the animation's range are provided to the handler each time the animator fires. To use animators and animations, you need to:
Include the
AppleAnimator
class in your HTML fileConstruct an animator timer
Construct an animation
Provide a handler used to act when the timer fires
Apple Animator and Animation, in HTML
In order to declare AppleAnimator
and AppleAnimation
objects and use them in JavaScript, you need to include the class in your widget's HTML file. If you're planning backward compatibility with pre-OS X v.10.4.3 versions, follow the directions in Backwards Compatible Usage and include this path:
<script type='text/javascript' src='AppleClasses/AppleAnimator.js' charset='utf-8'/> |
If you plan on requiring OS X v.10.4.3 or newer for your widget, include the AppleAnimation
class in its location in /System/Library/WidgetResources/
:
<script type='text/javascript' src='/System/Library/WidgetResources/AppleClasses/AppleAnimator.js' charset='utf-8'/> |
Apple Animator and Animation, in JavaScript
There are two ways to set up the animation timers and associated animation ranges within your widget's JavaScript:
Full setup, allowing you to associate multiple ranges of values with one timer
Quick setup, allowing you to easily create a timer and an associated range of values
Full Setup and Usage
The AppleAnimator
and AppleAnimation
classes have no default appearance and provide no actual animations; instead, they provide numerical values that can be useful when animating elements in your widget's user interface. For instance, if you have elements that fade, resize, or change over time, these classes can provide you with relevant values over time.
The AppleAnimator
class provides an object that functions as a timer. Its constructor takes in two parameters, the length of time that the timer should fire over, and the interval at which the timer should fire, both in milliseconds:
currentAnimator = new AppleAnimator(500, 13); |
In this instance, the timer, when activated, lasts for 500 milliseconds and fires every 13 milliseconds.
Now that the timer has been created, the animation range needs to be as well. The constructor for the AppleAnimation
class takes three values: a starting value, a finishing value, and a handler:
currentAnimation = new AppleAnimation(0.0, 1.0, animationHandler); |
This animation provides values between 0.0
and 1.0
and, whenever its timer fires, calls a handler function called animationHandler
. The handler for the animation needs to accept four arguments: the animator that is processing the animation, the current value of the animation, the animation's starting value, and its finishing value.
function animationHandler(currentAnimator, current, start, finish) |
{ |
... // do something with a current value |
} |
Now that the animation is set up, it needs to be associated with a timer:
currentAnimator.addAnimation(currentAnimation); |
By adding, or associating, the animation with the timer, the timer calls the animation's handler whenever it fires. When the timer fires and provides the appropriate value for the interval, based on the animation's range mapped to the duration of the timer. Each animator can be associated with multiple animations, allowing you to track multiple sets of values with one timer.
At this point, the timer and the animation are ready to be run. To begin the timer, send it the start message:
currentAnimator.start(); |
Additionally, you can stop a time at any point by calling stop()
on the animator:
currentAnimator.stop(); |
Quick Setup
The previous section described how to perform a full setup of an AppleAnimator
timer and an AppleAnimation
. This allows you to include multiple animations with one animator and is appropriate for circumstances where one animation is associated with one animator.
The AppleAnimator
constructor, however, allows you to specify animation specifications in addition to its usual parameters. This allows you to bypass having a separate AppleAnimation
object, useful for when you only need one animation:
AppleAnimator(duration, interval, start, finish, handler) |
The first two values, duration
and interval
, are the duration of the timer and how often it fires. The next two values, start
and finish
, are the starting and finishing values of the range of numbers that are calculated as the timer runs. Finally, handler
is the name of the function that you provide; it is called whenever the timer fires:
function handler(currentAnimator, current, start, finish) |
{ |
... // do something with a current value |
} |
As with the animation handler above, this handler needs to accept four arguments: the animator that is processing the animation, the current value of the animation, the animation's starting value, and its finishing value.
To start the animation and the animator's timer, call start()
on the animator:
currentAnimator.start(); |
After starting the animator's timer, the handler
function is called every interval until the end of the animator's duration is finished. The current
value passed to handler
reflects an increasing value between start
and finish
. To stop the animator's timer before it has run out, call stop()
:
currentAnimator.stop(); |
Properties of Apple Animator and Animation
These properties are available to an AppleAnimator
object:
Property | Description |
---|---|
| The duration of the animator's timer |
| The interval at which the animation's handler is called |
| An array of the Apple Animation objects associated with an animator |
| The current value of the timer |
| A handler called when the timer is complete |
These properties are available to an AppleAnimation
object:
Property | Description |
---|---|
| The animation's starting value |
| The animation's finishing value |
| The animation's current value |
| The handler for the animation |
The Apple Rectangle Animation Subclass
The AppleRectangleAnimation
subclass provides values useful when transitioning between two rectangles (the subclass has no default appearance). An AppleRectangleAnimation
uses the AppleAnimator
timer to trigger its handlers, but require that starting and finishing rectangles be specified as Apple Rectangles, using the AppleRect
subclass.
An AppleRect
is defined as:
AppleRect(left, top, right, bottom) |
The rectangle is specified by its top left and bottom right coordinates. To create a new AppleRect
object, call its constructor and assign the resulting object into a variable:
startingRect = new AppleRect( 0, 0, 100, 100 ); |
Once you have created a starting and finishing rectangle, create an AppleRectAnimation
object, passing in the two AppleRect
objects and the name of a handler that's to be called when the rectangle animation's animator timer fires:
currentRectAnimation = new AppleRectAnimation( startingRect, finishingRect, rectHandler ); |
The rectangle animation handler you provide needs to accept four arguments: the rectangle animation that triggered the handler, an AppleRect
object with the current rectangle values, the starting AppleRect
object, and the finishing AppleRect
object:
function rectHandler( rectAnimation, currentRect, startingRect, finishingRect ); |
Once the AppleRectangleAnimation
object is created, construct a new AppleAnimator
object, associate it with your rectangle animation, and start the animator's timer:
currentAnimator = new AppleAnimator (500, 13); |
currentAnimator.addAnimation(currentRectAnimation); |
currentAnimator.start(); |
Properties of Apple Rectangle Animation and Apple Rectangle
These properties are available to an AppleRectangleAnimator
object:
Property | Description |
---|---|
| The animation's starting rectangle |
| The animation's finishing rectangle |
| The animation's current rectangle |
| The handler for the animation |
These properties are available to an AppleRect
object:
Property | Description |
---|---|
| The rectangle's left value, of the top left corner of the rectangle |
| The rectangle's top value, of the top left corner of the rectangle |
| The rectangle's right value, of the bottom right corner of the rectangle |
| The rectangle's bottom value, of the bottom right corner of the rectangle |
Copyright © 2010 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2010-02-01