SPTween Class Reference
Inherits from | SPEventDispatcher : NSObject |
Conforms to | SPAnimatable |
Declared in | SPTween.h |
Overview
An SPTween animates numeric properties of objects. It uses different transition functions to give the animations various styles.
The primary use of this class is to do standard animations like movement, fading, rotation, etc.
But there are no limits on what to animate; as long as the property you want to animate is numeric
(int
, uint
, float
, double
), the tween can handle it. For a list of available Transition
types, see SPTransitions
.
Here is an example of a tween that moves an object, rotates it, and fades it out:
SPTween *tween = [SPTween tweenWithTarget:object time:2.0 transition:SP_TRANSITION_EASE_IN_OUT];
[tween moveToX:50.0f y:20.0f];
[tween animateProperty:@"rotation" targetValue:object.rotation + SP_D2R(45)];
[tween fadeTo:0.0f];
[Sparrow.juggler addObject:tween];
Note that the object is added to a juggler at the end. A tween will only be executed if its
advanceTime:
method is executed regularly - the juggler will do that for us, and will release
the tween when it is finished.
Tweens provide block-based callbacks that are executed in certain phases of their life time:
onStart
: Invoked once when the tween starts.onUpdate
: Invoked every time it is advanced.onComplete
: Invoked when it reaches its target value.onRepeat
: Invoked each time the tween finishes one repetition.
Use the repeatCount
property to repeat the tween several times. The reverse
property defines
the way in which the repetitions will be done (ping-pong
Tasks
Initialization
-
– initWithTarget:time:transition:
Initializes a tween with a target, duration (in seconds) and a transition function. Designated Initializer.
-
– initWithTarget:time:
Initializes a tween with a target, a time (in seconds) and a linear transition (
SPTransitionLinear
). -
+ tweenWithTarget:time:transition:
Factory method.
-
+ tweenWithTarget:time:
Factory method.
Methods
-
– animateProperty:targetValue:
Animates the property of an object to a target value. You can call this method multiple times on one tween.
-
– moveToX:y:
Animates the
x
andy
properties of an object simultaneously. -
– scaleTo:
Animates the
scaleX
andscaleY
properties of an object simultaneously. -
– fadeTo:
Animates the
alpha
property.
Properties
-
target
The target object that is animated.
property -
transition
The transition method used for the animation.
property -
totalTime
The total time the tween will take (in seconds).
property -
currentTime
The time that has passed since the tween was started (in seconds).
property -
isComplete
Indicates if the total time has passed and the tweened properties have finished.
property -
delay
The delay before the tween is started.
property -
repeatCount
The number of times the tween will be executed. Set to 0 to tween indefinitely. (Default: 1)
property -
repeatDelay
The number seconds to wait between repeat cycles. (Default: 0)
property -
reverse
Indicates if the tween should be reversed when it is repeating. If enabled, every second repetition will be reversed. (Default:
propertyNO
) -
onStart
A block that will be called when the tween starts (after a possible delay).
property -
onUpdate
A block that will be called each time the tween is advanced.
property -
onRepeat
A block that will be called each time the tween finishes one repetition (except the last, which will trigger ‘onComplete’).
property -
onComplete
A block that will be called when the tween is complete.
property
Properties
currentTime
The time that has passed since the tween was started (in seconds).
@property (nonatomic, readonly) double currentTime
Discussion
The time that has passed since the tween was started (in seconds).
Declared In
SPTween.h
delay
The delay before the tween is started.
@property (nonatomic, assign) double delay
Discussion
The delay before the tween is started.
Declared In
SPTween.h
isComplete
Indicates if the total time has passed and the tweened properties have finished.
@property (nonatomic, readonly) BOOL isComplete
Discussion
Indicates if the total time has passed and the tweened properties have finished.
Declared In
SPTween.h
onComplete
A block that will be called when the tween is complete.
@property (nonatomic, copy) SPCallbackBlock onComplete
Discussion
A block that will be called when the tween is complete.
Declared In
SPTween.h
onRepeat
A block that will be called each time the tween finishes one repetition (except the last, which will trigger ‘onComplete’).
@property (nonatomic, copy) SPCallbackBlock onRepeat
Discussion
A block that will be called each time the tween finishes one repetition (except the last, which will trigger ‘onComplete’).
Declared In
SPTween.h
onStart
A block that will be called when the tween starts (after a possible delay).
@property (nonatomic, copy) SPCallbackBlock onStart
Discussion
A block that will be called when the tween starts (after a possible delay).
Declared In
SPTween.h
onUpdate
A block that will be called each time the tween is advanced.
@property (nonatomic, copy) SPCallbackBlock onUpdate
Discussion
A block that will be called each time the tween is advanced.
Declared In
SPTween.h
repeatCount
The number of times the tween will be executed. Set to 0 to tween indefinitely. (Default: 1)
@property (nonatomic, assign) int repeatCount
Discussion
The number of times the tween will be executed. Set to 0 to tween indefinitely. (Default: 1)
Declared In
SPTween.h
repeatDelay
The number seconds to wait between repeat cycles. (Default: 0)
@property (nonatomic, assign) double repeatDelay
Discussion
The number seconds to wait between repeat cycles. (Default: 0)
Declared In
SPTween.h
reverse
Indicates if the tween should be reversed when it is repeating. If enabled,
every second repetition will be reversed. (Default: NO
)
@property (nonatomic, assign) BOOL reverse
Discussion
Indicates if the tween should be reversed when it is repeating. If enabled,
every second repetition will be reversed. (Default: NO
)
Declared In
SPTween.h
target
The target object that is animated.
@property (nonatomic, readonly) id target
Discussion
The target object that is animated.
Declared In
SPTween.h
Class Methods
Instance Methods
animateProperty:targetValue:
Animates the property of an object to a target value. You can call this method multiple times on one tween.
- (void)animateProperty:(NSString *)property targetValue:(float)value
Discussion
Animates the property of an object to a target value. You can call this method multiple times on one tween.
Declared In
SPTween.h
fadeTo:
Animates the alpha
property.
- (void)fadeTo:(float)alpha
Discussion
Animates the alpha
property.
Declared In
SPTween.h
initWithTarget:time:
Initializes a tween with a target, a time (in seconds) and a linear transition
(SPTransitionLinear
).
- (instancetype)initWithTarget:(id)target time:(double)time
Discussion
Initializes a tween with a target, a time (in seconds) and a linear transition
(SPTransitionLinear
).
Declared In
SPTween.h
initWithTarget:time:transition:
Initializes a tween with a target, duration (in seconds) and a transition function. Designated Initializer.
- (instancetype)initWithTarget:(id)target time:(double)time transition:(NSString *)transition
Discussion
Initializes a tween with a target, duration (in seconds) and a transition function. Designated Initializer.
Declared In
SPTween.h