PMTweenUnit Class Reference
Inherits from | NSObject |
Conforms to | PMTweenTempoDelegate PMTweening |
Declared in | PMTweenUnit.h PMTweenUnit.m |
Overview
PMTweenUnit handles a single tween operation on an NSValue property, interpolating between specified starting and ending values.
Tasks
Creating an Instance
-
– initWithProperty:startingValue:endingValue:duration:options:easingBlock:
-
– initWithObject:propertyKeyPath:startingValue:endingValue:duration:options:easingBlock:
Setting Up a Tween
-
delay
property -
duration
property -
repeating
property -
numberOfRepeats
property -
additive
property -
structValueUpdater
property
Easing Blocks
-
easingBlock
property -
reverseEasingBlock
property
Tween State
-
targetProperty
property -
targetObject
property -
propertyKeyPath
property -
operationID
property -
tweenState
property -
tweenDirection
property -
startingValue
property -
currentValue
property -
endingValue
property -
tweenProgress
property -
cycleProgress
property -
cyclesCompletedCount
property
Notification Blocks
-
startBlock
property -
stopBlock
property -
updateBlock
property -
repeatCycleBlock
property -
reverseBlock
property -
pauseBlock
property -
resumeBlock
property -
completeBlock
property
Controlling a Tween
Properties
additive
A Boolean which determines whether this tween should change its property value additively. Additive animation allows multiple tweens to produce a compound effect, instead of overwriting each other as they update the same property. Additive animation is now the default behavior for tweening animations in iOS 8, and is great for making user interface animations fluid and responsive.
@property (nonatomic, assign) BOOL additive
Discussion
@remarks The startingValue
property is ignored for additive animations, and will instead combine with the current value of the property being tweened. Please be aware that because of the composite nature of additive animations, values can temporarily tween past the specified endingValue. This can have unintended consequences if the property you are tweening is clamped to a limited range of values. Also note that additive animations may not work well with complex tweens using sequences, reversing, or repeating, and will not work with other tweens that are not using the additive mode. Because of these caveats, the default value is NO.
Declared In
PMTweenUnit.h
completeBlock
This notification block is executed when a tween operation has completed (or when all tween cycles have completed, if repeating
is set to YES
).
@property (nonatomic, copy) PMTweenDidCompleteBlock completeBlock
Declared In
PMTweenUnit.h
currentValue
The current value of the tween operation. (read-only)
@property (readonly, nonatomic, assign) double currentValue
Discussion
@remarks Note that for non-numeric properties like structs this may affect multiple values, such as the x and y properties of CGPoint.
See Also
@property startingValue, endingvalue
Declared In
PMTweenUnit.h
cycleProgress
A float value between 0.0 and 1.0, which represents the current progress of a tween cycle. (read-only)
@property (readonly, nonatomic, assign) CGFloat cycleProgress
Discussion
@remarks This progress could represent one tween or two, depending on whether reversing
is set to YES
.
Declared In
PMTweenUnit.h
cyclesCompletedCount
The amount of completed tween cycles. (read-only)
@property (readonly, nonatomic, assign) NSUInteger cyclesCompletedCount
Discussion
@remarks A cycle represents the total length of tweening operation. If reversing
is set to YES
, a cycle comprises two separate tweens; otherwise a cycle is the length of one tween.
Declared In
PMTweenUnit.h
delay
The delay, in seconds, before a tween operation begins.
@property (nonatomic, assign) NSTimeInterval delay
Discussion
Warning: Setting this parameter after a tween operation has begun has no effect.
Declared In
PMTweenUnit.h
duration
The duration of a tween operation, in seconds. (read-only)
@property (nonatomic, assign) NSTimeInterval duration
Discussion
@remarks If reversing
is set to YES
, the duration of a total tween cycle will be twice this amount as there will be two separate tween operations (forwards and back).
Warning: Do not set this parameter while a tween operation is in progress.
Declared In
PMTweenUnit.h
easingBlock
A PMTweenEasingBlock
block which performs easing calculations for the tweening operation.
@property (nonatomic, copy) PMTweenEasingBlock easingBlock
See Also
Declared In
PMTweenUnit.h
endingValue
The ending value of the tween operation.
@property (nonatomic, assign) double endingValue
Discussion
@remarks Note that for non-numeric properties like structs this may affect multiple values, such as the x and y properties of CGPoint.
Declared In
PMTweenUnit.h
numberOfRepeats
The number of tween cycle operations to repeat.
@property (nonatomic, assign) NSUInteger numberOfRepeats
Discussion
@remarks This property is only used when repeating
is set to YES
. The default value is 0.
See Also
Declared In
PMTweenUnit.h
operationID
An operation ID is assigned to a PMTweenUnit when it is tweening an object’s property (via initWithObject…) and its tween operation is currently in progress. (read-only)
@property (readonly, nonatomic, assign) NSUInteger operationID
Discussion
@remarks This value returns 0 if no ID is currently assigned.
Declared In
PMTweenUnit.h
pauseBlock
This notification block is executed when calling the pauseTween
method on this instance causes a tween operation to pause.
@property (nonatomic, copy) PMTweenDidPauseBlock pauseBlock
See Also
Declared In
PMTweenUnit.h
propertyKeyPath
Key path for property on target. Only used when class is created with initWithObject.
@property (readonly, nonatomic, copy) NSString *propertyKeyPath
Declared In
PMTweenUnit.h
repeatCycleBlock
This notification block is executed when a tween cycle has repeated.
@property (nonatomic, copy) PMTweenDidRepeatBlock repeatCycleBlock
Declared In
PMTweenUnit.h
repeating
A Boolean which determines whether a tween operation should repeat.
@property (nonatomic, assign) BOOL repeating
Discussion
@remarks When set to YES
, the tween operation repeats for the number of times specified by the numberOfRepeats
property. The default value is NO
.
See Also
Declared In
PMTweenUnit.h
resumeBlock
This notification block is executed when calling the resumeTween
method on this instance causes a tween operation to resume.
@property (nonatomic, copy) PMTweenDidResumeBlock resumeBlock
See Also
Declared In
PMTweenUnit.h
reverseBlock
This notification block is executed when this instance’s tweenDirection
property changes to PMTweenDirectionReverse
.
@property (nonatomic, copy) PMTweenDidReverseBlock reverseBlock
See Also
@property tweenDirection, reversing
Declared In
PMTweenUnit.h
reverseEasingBlock
An optional PMTweenEasingBlock
block which performs easing calculations for the tweening operation while reversing.
@property (nonatomic, copy) PMTweenEasingBlock reverseEasingBlock
Discussion
@remarks If not defined, the easing block defined by the easingBlock
property is used during reversing tweens.
See Also
Declared In
PMTweenUnit.h
startBlock
This notification block is executed when calling the startTween
method on this instance causes a tween operation to start.
@property (nonatomic, copy) PMTweenDidStartBlock startBlock
See Also
Declared In
PMTweenUnit.h
startingValue
The starting value of the tween operation.
@property (nonatomic, assign) double startingValue
Discussion
@remarks Note that for non-numeric properties like structs this may affect multiple values, such as the x and y properties of CGPoint.
See Also
@property currentValue, endingvalue
Declared In
PMTweenUnit.h
stopBlock
This notification block is executed when calling the stopTween
method on this instance causes a tween operation to stop.
@property (nonatomic, copy) PMTweenDidStopBlock stopBlock
See Also
Declared In
PMTweenUnit.h
structValueUpdater
An object conforming to the PMTweenObjectUpdating
protocol which handles the updating of properties on objects and structs.
@property (nonatomic, strong) NSObject<PMTweenObjectUpdating> *structValueUpdater
Discussion
@remarks By default, PMTweenUnit will assign an instance of PMTweenObjectUpdater
to this property, but you can override this with your own custom classes if, for instance, you need to tween a value in an object or struct which PMTweenObjectUpdater
doesn’t handle.
Declared In
PMTweenUnit.h
targetObject
The target object whose property should be tweened, applicable if this instance was initiated with the initWithProperty:… method.
@property (readonly, nonatomic, strong) NSObject *targetObject
Declared In
PMTweenUnit.h
targetProperty
The property to be tweened.
@property (readonly, nonatomic, strong) NSObject *targetProperty
Declared In
PMTweenUnit.h
tweenDirection
A PMTweenDirection
enum which represents the current direction of the tween operation. (read-only)
@property (readonly, nonatomic, assign) PMTweenDirection tweenDirection
Declared In
PMTweenUnit.h
tweenProgress
A float value between 0.0 and 1.0, which represents the current progress of a tween operation between two values. (read-only)
@property (readonly, nonatomic, assign) CGFloat tweenProgress
Declared In
PMTweenUnit.h
tweenState
A PMTweenState
enum which represents the current state of the tween operation. (read-only)
@property (readonly, nonatomic, assign) PMTweenState tweenState
Declared In
PMTweenUnit.h
updateBlock
This notification block is executed when the updateWithTimeInterval:currentTime:
method is called on this instance while this instance’s tweenState
is PMTweenStateTweening
.
@property (nonatomic, copy) PMTweenDidUpdateBlock updateBlock
Declared In
PMTweenUnit.h
Instance Methods
initWithObject:propertyKeyPath:startingValue:endingValue:duration:options:easingBlock:
Initalizes a new PMTweenUnit object, passing in a target object, its property, and values for the tween operation.
- (instancetype)initWithObject:(NSObject *)object propertyKeyPath:(NSString *)propertyKeyPath startingValue:(double)startingValue endingValue:(double)endingValue duration:(NSTimeInterval)duration options:(PMTweenOptions)options easingBlock:(PMTweenEasingBlock)easingBlock
Parameters
- object
An object whose property should be tweened.
- propertyKeyPath
A string keyPath that points to a NSValue property of the target object to be tweened. Supported properties include several NSValue-encoded structs such as NSNumber, CGPoint, CGSize, CGRect, CGAffineTransform, and CATransform3D.
- startingValue
The property’s starting value for the tween operation.
- endingValue
The property’s ending value for the tween operation.
- duration
The duration of the tween.
- options
A bitmask of
PMTweenOptions
configuration values. Defaults toPMTweenOptionNone
.
- easingBlock
An optional
PMTweenEasingBlock
block which performs easing calculations.
Return Value
A new instance of this class.
@remarks If you need to update the property of an object such as a UIView, use this method. PMTweenUnit will handle updating the object’s property automatically if you have provided a valid keyPath to the property. For a keyPath to be valid, all objects or NSValue types must be supported. By supplying a custom class to structValueUpdater
, you can handle structs that PMTweenUnit doesn’t support by default.
See Also
Declared In
PMTweenUnit.h
initWithProperty:startingValue:endingValue:duration:options:easingBlock:
Initializes a new PMTweenUnit object, passing in a property and values for the tween operation.
- (instancetype)initWithProperty:(NSValue *)property startingValue:(double)startingValue endingValue:(double)endingValue duration:(NSTimeInterval)duration options:(PMTweenOptions)options easingBlock:(PMTweenEasingBlock)easingBlock
Parameters
- property
An NSValue property to be tweened. Supported properties include several NSValue-encoded structs such as NSNumber, CGPoint, CGSize, CGRect, CGAffineTransform, and CATransform3D.
- startingValue
The property’s starting value for the tween operation.
- endingValue
The property’s ending value for the tween operation.
- duration
The duration of the tween.
- options
A bitmask of
PMTweenOptions
configuration values. Defaults toPMTweenOptionNone
.
- easingBlock
An optional
PMTweenEasingBlock
block which performs easing calculations.
Return Value
A new instance of this class.
@remarks If you need to tween an NSValue directly, without needing to update an object such as a UIView instance, using this method is adequate.
Declared In
PMTweenUnit.h
isReversing
A Boolean which determines whether a tween operation, when it has tweened to the ending value, should tween from the ending value back to the starting value.
- (BOOL)isReversing
Discussion
@remarks When set to YES
, the tween plays in reverse after completing a forward tween. In this state, a tween cycle represents the combination of the forward and back tweens. The default value is NO
.
Declared In
PMTweening.h
pauseTween
Pauses a tween that is currently tweening. (required)
- (void)pauseTween
Discussion
@remarks When this method is called, a tween should only enter a paused state if it is currently tweening.
Declared In
PMTweening.h
resumeTween
Resumes a tween that is currently paused. (required)
- (void)resumeTween
Discussion
@remarks When this method is called, a tween should only resume tweening if it is currently paused.
Declared In
PMTweening.h
setReversing:
A Boolean which determines whether a tween operation, when it has tweened to the ending value, should tween from the ending value back to the starting value.
- (void)setReversing:(BOOL)reversing
Discussion
@remarks When set to YES
, the tween plays in reverse after completing a forward tween. In this state, a tween cycle represents the combination of the forward and back tweens. The default value is NO
.
Declared In
PMTweening.h
setTempo:
A concrete PMTweenTempo
subclass that provides an update “beat” while a tween operation occurs.
- (void)setTempo:(PMTweenTempo *)tempo
Discussion
@remarks While you don’t have to implement PMTweenTempo for your own class updating, other tween collection classes like PMTweenGroup
will try to remove any tempos of tween objects added to them.
Declared In
PMTweening.h
startTween
Starts a tween that is currently stopped. (required)
- (void)startTween
Discussion
@remarks When this method is called, a tween should only start tweening if it is stopped.
Declared In
PMTweening.h
stopTween
Stops a tween that is currently tweening. (required)
- (void)stopTween
Discussion
@remarks When this method is called, a tween should only enter a stopped state if it currently tweening.
Declared In
PMTweening.h
tempo
A concrete PMTweenTempo
subclass that provides an update “beat” while a tween operation occurs.
- (PMTweenTempo *)tempo
Discussion
@remarks While you don’t have to implement PMTweenTempo for your own class updating, other tween collection classes like PMTweenGroup
will try to remove any tempos of tween objects added to them.
Declared In
PMTweening.h
tempoBeatWithTimestamp:
Sends an update beat that should prompt tweening classes to recalculate tween values.
- (void)tempoBeatWithTimestamp:(NSTimeInterval)timestamp
Parameters
- timestamp
A timestamp with the current time, by which tween classes can calculate new tween values.
Declared In
PMTweenTempo.h