Inherits from NSObject
Conforms to PMTweenTempoDelegate
PMTweening
Declared in PMTweenPhysicsUnit.h
PMTweenPhysicsUnit.m

Overview

PMTweenPhysicsUnit handles a single tween operation on an NSValue property, using a physics system to update a value with decaying velocity.

Tasks

Creating an Instance

Setting Up a Tween

Tween State

Notification Blocks

Controlling a Tween

Properties

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

PMTweenPhysicsUnit.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

Declared In

PMTweenPhysicsUnit.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

PMTweenPhysicsUnit.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

PMTweenPhysicsUnit.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

PMTweenPhysicsUnit.h

friction

The current friction coefficient used by the physics system.

@property (nonatomic, assign) double friction

Discussion

@remarks A value range between 0 and 1, with 1 representing very high friction and 0 representing almost no friction. Setting this property to 0.0 will actually set it a bit fractionally higher than 0 to avoid divide-by-zero errors during calculations.

Declared In

PMTweenPhysicsUnit.h

numberOfRepeats

The number of tween cycle operations to repeat. The default value is 0.

@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

PMTweenPhysicsUnit.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

PMTweenPhysicsUnit.h

physicsSystem

An object conforming to the PMTweenPhysicsSolving protocol which solves position calculation updates.

@property (nonatomic, strong) NSObject<PMTweenPhysicsSolving> *physicsSystem

Discussion

@remarks By default, PMTweenPhysicsUnit will assign an instance of PMTweenPhysicsSystem to this property, but you can override this with your own custom classes in order to supply a different physics model.

Declared In

PMTweenPhysicsUnit.h

physicsTimerInterval

Specifies a time step for the physics solver, which is updated independently of tween value updates. The default value calls the physics system 120 times a second, which provides double the precision if your app is rendering at 60 fps.

@property (nonatomic, assign) NSTimeInterval physicsTimerInterval

Declared In

PMTweenPhysicsUnit.h

repeatCycleBlock

This notification block is executed when a tween cycle has repeated.

@property (nonatomic, copy) PMTweenDidRepeatBlock repeatCycleBlock

See Also

Declared In

PMTweenPhysicsUnit.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

PMTweenPhysicsUnit.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

PMTweenPhysicsUnit.h

reverseBlock

This notification block is executed when this instance’s tweenDirection property changes to PMTweenDirectionReverse.

@property (nonatomic, copy) PMTweenDidReverseBlock reverseBlock

See Also

Declared In

PMTweenPhysicsUnit.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

PMTweenPhysicsUnit.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

Declared In

PMTweenPhysicsUnit.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

PMTweenPhysicsUnit.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, PMTweenPhysicsUnit 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

PMTweenPhysicsUnit.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

PMTweenPhysicsUnit.h

targetProperty

The property to be tweened.

@property (readonly, nonatomic, strong) NSObject *targetProperty

Declared In

PMTweenPhysicsUnit.h

tweenDirection

A PMTweenDirection enum which represents the current direction of the tween operation. (read-only)

@property (readonly, nonatomic, assign) PMTweenDirection tweenDirection

Declared In

PMTweenPhysicsUnit.h

tweenProgress

A float value between 0.0 and 1.0, which represents the current progress of a physics deceleration, calculated as the difference between the starting velocity and the current velocity. (read-only)

@property (readonly, nonatomic, assign) CGFloat tweenProgress

Declared In

PMTweenPhysicsUnit.h

tweenState

A PMTweenState enum which represents the current state of the tween operation. (read-only)

@property (readonly, nonatomic, assign) PMTweenState tweenState

Declared In

PMTweenPhysicsUnit.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

PMTweenPhysicsUnit.h

velocity

The current velocity used by the physics system to calculate tween values, measured in units per second.

@property (nonatomic, assign) double velocity

Discussion

@remarks If you wish to change the velocity after initially setting it via one of the init methods, use this setter. If you change the velocity directly on the physicsSystem object, the tweenProgress property won’t be accurate.

Declared In

PMTweenPhysicsUnit.h

velocityDecayLimit

This float value is used to determine whether the object modeled by the physics system has come to rest due to deceleration.

@property (nonatomic, assign) CGFloat velocityDecayLimit

Discussion

@remarks The way PMTweenPhysicsSystem applies friction means that as velocity approaches 0, it will be assigned smaller and smaller fractional numbers, so we need a reasonable cutoff that approximates the velocity coming to rest. The default value is the internal constant PMTWEEN_DECAY_LIMIT (set to 1.0), which is fine for display properties, but you may prefer other values.

Declared In

PMTweenPhysicsUnit.h

Instance Methods

initWithObject:propertyKeyPath:startingValue:velocity:friction:options:

Initalizes a new PMTweenPhysicsUnit object, passing in a target object, its property, and values for the tween operation.

- (instancetype)initWithObject:(NSObject *)object propertyKeyPath:(NSString *)propertyKeyPath startingValue:(double)startingValue velocity:(double)velocity friction:(double)friction options:(PMTweenOptions)options

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.

velocity

The velocity value to use in the physics calculations, measured in units per second.

friction

The friction value between 0 and 1 to use in the physics calculations, with 1 representing very high friction and 0 representing almost no friction.

options

A bitmask of PMTweenOptions configuration values. Defaults to PMTweenOptionNone.

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. PMTweenPhysicsUnit 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 PMTweenPhysicsUnit doesn’t support by default.

See Also

Declared In

PMTweenPhysicsUnit.h

initWithProperty:startingValue:velocity:friction:options:

Initializes a new PMTweenPhysicsUnit object, passing in a property and values for the tween operation.

- (instancetype)initWithProperty:(NSValue *)property startingValue:(double)startingValue velocity:(double)velocity friction:(double)friction options:(PMTweenOptions)options

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.

velocity

The velocity value to use in the physics calculations, measured in units per second.

friction

The friction value between 0 and 1 to use in the physics calculations, with 1 representing very high friction and 0 representing almost no friction.

options

A bitmask of PMTweenOptions configuration values. Defaults to PMTweenOptionNone.

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

PMTweenPhysicsUnit.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

updateWithTimeInterval:

This method is called to prompt a tweening class to update its current tween values.

- (void)updateWithTimeInterval:(NSTimeInterval)currentTime

Parameters

currentTime

A timestamp that can be used in easing calculations.

Declared In

PMTweening.h