PhysicsMotion

@MainActor
public class PhysicsMotion : Moveable, Additive, TempoDriven, PropertyDataDelegate

PhysicsMotion handles a single motion operation on one or more properties, using a physics system to update values with decaying velocity.

Public Properties

  • The delay, in seconds, before a motion operation begins.

    Warning

    Setting this parameter after a motion operation has begun has no effect.

    Declaration

    Swift

    @MainActor
public var delay: TimeInterval

  • A Boolean which determines whether a motion operation should repeat. When set to true, the motion operation repeats for the number of times specified by the repeatCycles property. The default value is false.

    Note

    By design, setting this value to true without changing the repeatCycles property from its default value will cause the motion to repeat infinitely.

    Seealso

    repeatCycles

    Declaration

    Swift

    @MainActor
public var repeating: Bool

  • The number of motion cycle operations to repeat.

    Remark

    This property is only used when repeating is set to true. Assigning REPEAT_INFINITE to this property signals an infinite amount of motion cycle repetitions. The default value is REPEAT_INFINITE.

    Seealso

    repeating

    Declaration

    Swift

    @MainActor
public var repeatCycles: UInt

  • An object conforming to the ValueAssistant protocol which acts as an interface for retrieving and updating value types.

    Remark

    By default, PhysicsMotion will assign an instance of the ValueAssistantGroup class with value assistants for Core Foundation structs and UIKit colors. You may add your own custom type assistants to this group, or replace it with your own custom ValueAssistant implementation.

    Declaration

    Swift

    @MainActor
public var valueAssistant: ValueAssistant { get set }

Additive protocol properties

  • A Boolean which determines whether this Motion should change its object values additively. Additive animation allows multiple motions to produce a compound effect, creating smooth transitions and blends between different ending value targets. Additive animation is the default behavior for UIKit animations as of iOS 8 and is great for making user interface animations fluid and responsive. MotionMachine uses its own implementation of additive movement, so you can use additive motions on any supported object properties.

    By default, each PhysicsMotion will apply a strong influence on the movement of a property towards its ending value. This means that two Motion objects with the same duration and moving the same object property to different ending values will fight, and the “winning” value will be the last Motion to start its movement. If the durations or starting times are different, a transition between the values will occur. If you wish to create additive motions that apply weighted value updates, you can adjust the additiveWeighting property. Setting values to that property that are less than 1.0 will create compound additive motions that are blends of each Motion object’s ending values.

    Remark

    The start value of PropertyData objects are ignored for additive animations, and will instead combine with the current value of the properties being moved.

    Warning

    Please be aware that because of the composite nature of additive movements, values can temporarily move past a PropertyData‘s specified end value. This can have unintended consequences if the property value you are moving is clamped to a limited range. Also note that additive movements may not work well with compound motions that are comprised of sequences, reversing, or repeating, and will not behave correctly when other Motion objects moving the same properties are not using the additive mode. Because of these caveats, the default value is false.

    Seealso

    additiveWeighting

    Declaration

    Swift

    @MainActor
public var additive: Bool { get set }

  • A weighting between 0.0 and 1.0 which is applied to this PhysicsMotion’s object value updates when it is using an additive movement. The higher the weighting amount, the more its additive updates apply to the properties being moved. A value of 1.0 will mean the motion will reach the specific end value of each PropertyData being moved, while a value of 0.0 will not move towards the end value at all. When multiple PhysicsMotions in additive mode are moving the same object properties, adjusting this weighting on each PhysicsMotion can create complex composite motions.

    Note

    This value only has an effect when additive is set to true. The default value is 1.0.

    Seealso

    additive

    Declaration

    Swift

    @MainActor
public var additiveWeighting: Double { get set }

  • An operation ID is assigned to a PhysicsMotion instance when it is moving an object’s property (via initWithObject…) and its motion operation is currently in progress. (read-only)

    Remark

    This value returns 0 if no ID is currently assigned.

    Declaration

    Swift

    @MainActor
private(set) public var operationID: UInt { get }

Physics properties

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

    Remark

    By default, PhysicsMotion will assign an instance of PhysicsSystem to this property, but you can override this with your own custom physics system.

    Declaration

    Swift

    @MainActor
public var physicsSystem: PhysicsSolving

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

    Remark

    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 motionProgress property won’t be accurate.

    Declaration

    Swift

    @MainActor
public var velocity: Double { get set }

  • The current friction coefficient used by the physics system.

    Remark

    A value range between 0.0 and 1.0, with 1.0 representing very high friction and 0.0 representing almost no friction (setting this property to 0.0 will actually set it a bit fractionally higher than 0.0 to avoid divide-by-zero errors during calculations).

    Declaration

    Swift

    @MainActor
public var friction: Double { get set }

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

    Remark

    The way in which PhysicsSystem applies friction means that as velocity approaches 0.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 constant DEFAULT_DECAY_LIMIT (set to 0.96), which is fine for display properties, but you may prefer other values.

    Declaration

    Swift

    @MainActor
public var velocityDecayLimit: Double

  • Specifies a time step for the physics solver, which is updated independently of motion 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.

    Declaration

    Swift

    @MainActor
public var physicsTimerInterval: TimeInterval

Property collection methods

  • The collection of PropertyData instances, representing the object’s properties being moved.

    Remark

    The path property of each PropertyData must be a valid KVC-compliant keyPath of targetObject.

    Seealso

    targetObject

    Declaration

    Swift

    @MainActor
private(set) public var properties: [PropertyData] { get }

Motion state properties

  • The target object whose property should be moved.

    Declaration

    Swift

    @MainActor
private(set) public var targetObject: NSObject? { get }

  • A MotionState enum which represents the current movement state of the motion operation. (read-only)

    Declaration

    Swift

    @MainActor
private(set) public var motionState: MotionState { get }

  • A MotionDirection enum which represents the current direction of the motion operation. (read-only)

    Declaration

    Swift

    @MainActor
private(set) public var motionDirection: MotionDirection { get }

  • A value between 0.0 and 1.0, which represents the current progress of a movement between two value destinations. (read-only)

    Remark

    Be aware that if this motion is reversing or repeating, this value will only represent one movement. For instance, if a PhysicsMotion has been set to repeat once, this value will move from 0.0 to 1.0, then reset to 0.0 again as the new repeat cycle starts. Similarly, if a PhysicsMotion is set to reverse, this progress will represent each movement; first in the forward direction, then again when reversing back to the starting values.

    Declaration

    Swift

    @MainActor
private(set) public var motionProgress: Double { get set }

  • A value between 0.0 and 1.0, which represents the current progress of a motion cycle. (read-only)

    Remark

    A cycle represents the total length of a one motion operation. If reversing is set to true, a cycle comprises two separate movements (the forward movement, which at completion will have a value of 0.5, and the movement in reverse which at completion will have a value of 1.0); otherwise a cycle is the length of one movement. Note that if repeating, each repetition will be a new cycle and thus the progress will reset to 0.0 for each repeat.

    Declaration

    Swift

    @MainActor
private(set) public var cycleProgress: Double { get set }

  • The amount of completed motion cycles. (read-only)

    Remark

    A cycle represents the total length of a one motion operation. If reversing is set to true, a cycle comprises two separate movements (the forward movement and the movement in reverse); otherwise a cycle is the length of one movement. Note that if repeating, each repetition will be a new cycle.

    Declaration

    Swift

    @MainActor
private(set) public var cyclesCompletedCount: UInt { get }

  • A value between 0.0 and 1.0, which represents the current overall progress of the PhysicsMotion. This value should include all reversing and repeat motion cycles. (read-only)

    Remark

    If a Motion is not repeating, this value will be equivalent to the value of cycleProgress.

    Seealso

    cycleProgress

    Declaration

    Swift

    @MainActor
public var totalProgress: Double { get }

Moveable protocol properties

  • A Boolean which determines whether a motion operation, when it has moved to the ending value, should move from the ending value back to the starting value.

    Declaration

    Swift

    @MainActor
public var reversing: Bool

  • Provides a delegate for updates to a Moveable object’s status, used by Moveable collections.

    Declaration

    Swift

    @MainActor
public var updateDelegate: MotionUpdateDelegate?

TempoDriven protocol properties

  • A concrete Tempo subclass that provides an update “beat” while a motion operation occurs.

    Remark

    By default, PhysicsMotion will assign an instance of CATempo to this property, which uses CADisplayLink for interval updates.

    Declaration

    Swift

    @MainActor
public var tempo: Tempo? { get set }

Notification closures

  • This closure is called when a motion operation starts.

    Remark

    This method can be chained when initializing the object.

    Seealso

    start

    Declaration

    Swift

    @discardableResult
@MainActor
public func started(_ closure: @escaping PhysicsMotionStarted) -> Self

  • This closure is called when a motion operation is stopped by calling the stop method.

    Remark

    This method can be chained when initializing the object.

    Seealso

    stop

    Declaration

    Swift

    @discardableResult
@MainActor
public func stopped(_ closure: @escaping PhysicsMotionStopped) -> Self

  • This closure is called when a motion operation update occurs and this instance’s motionState is .Moving.

    Remark

    This method can be chained when initializing the object.

    Seealso

    update(withTimeInterval:)

    Declaration

    Swift

    @discardableResult
@MainActor
public func updated(_ closure: @escaping PhysicsMotionUpdated) -> Self

  • This closure is called when a motion cycle has completed.

    Remark

    This method can be chained when initializing the object.

    Seealso

    repeating, cyclesCompletedCount

    Declaration

    Swift

    @discardableResult
@MainActor
public func cycleRepeated(_ closure: @escaping PhysicsMotionRepeated) -> Self

  • This closure is called when the motionDirection property changes to reversing.

    Remark

    This method can be chained when initializing the object.

    Seealso

    motionDirection, reversing

    Declaration

    Swift

    @discardableResult
@MainActor
public func reversed(_ closure: @escaping PhysicsMotionReversed) -> Self

  • This closure is called when calling the pause method on this instance causes a motion operation to pause.

    Remark

    This method can be chained when initializing the object.

    Seealso

    pause

    Declaration

    Swift

    @discardableResult
@MainActor
public func paused(_ closure: @escaping PhysicsMotionPaused) -> Self

  • This closure is called when calling the resume method on this instance causes a motion operation to resume.

    Remark

    This method can be chained when initializing the object.

    Seealso

    resume

    Declaration

    Swift

    @discardableResult
@MainActor
public func resumed(_ closure: @escaping PhysicsMotionResumed) -> Self

  • This closure is called when a motion operation has completed (or when all motion cycles have completed, if repeating is set to true).

    Remark

    This method can be chained when initializing the object.

    Declaration

    Swift

    @discardableResult
@MainActor
public func completed(_ closure: @escaping PhysicsMotionCompleted) -> Self

  • This Boolean represents whether collision detections are active in the physics simulation. If true, collisions will be checked using the start and end properties of each PropertyData object passed in to the solve(forPositions:timestamp:) method. The default value is false.

    Declaration

    Swift

    @MainActor
public var useCollisionDetection: Bool { get set }

Initialization

  • Initializer method.

    Declaration

    Swift

    @MainActor
public convenience init(target targetObject: NSObject, properties: [PropertyData], velocity: Double, friction: Double, options: MotionOptions? = MotionOptions.none)

    Parameters

    target

    The target object whose properties should be modified.
    properties

    An array of PropertyData objects that provide instructions for which properties to modify and how.
    velocity

    The velocity used to calculate new values in the PhysicsSolving system. Any values are accepted due to the differing ranges of velocity magnitude required for various motion applications. Experiment to see what suits your needs best.
    friction

    The friction used to calculate new values in the PhysicsSolving system. Acceptable values are 0.0 (no friction) to 1.0 (no movement); values outside of this range will be clamped to the nearest edge.
    options

    An optional set of MotionsOptions.

  • Initializer.

    Declaration

    Swift

    @MainActor
public convenience init(target targetObject: NSObject, velocity: Double, friction: Double, options: MotionOptions? = MotionOptions.none)

    Parameters

    target

    The target object whose properties should be modified.
    velocity

    The velocity used to calculate new values in the PhysicsSolving system. Any values are accepted due to the differing ranges of velocity magnitude required for various motion applications. Experiment to see what suits your needs best.
    friction

    The friction used to calculate new values in the PhysicsSolving system. Acceptable values are 0.0 (no friction) to 1.0 (no movement); values outside of this range will be clamped to the nearest edge.
    options

    An optional set of MotionsOptions.

  • A convenience initializer.

    Declaration

    Swift

    @MainActor
public convenience init(target targetObject: NSObject, properties: [PropertyData], configuration: PhysicsConfiguration, options: MotionOptions? = MotionOptions.none)

    Parameters

    target

    The target object whose properties should be modified.
    properties

    An array of PropertyData objects that provide instructions for which properties to modify and how.
    configuration

    A configuration model containing data to set up this object’s PhysicsSystem for physics calculations.
    options

    An optional options model.

Public methods

  • Adds a PropertyData to control an object’s property. The PropertyData’s path must reflect a property keyPath of the Motion’s target object.

    Remark

    This method can be chained when initializing the object.

    Warning

    This method should not be called after the Motion has started.

    Declaration

    Swift

    @discardableResult
@MainActor
public func add(_ property: PropertyData) -> PhysicsMotion

    Parameters

    property

    A PropertyData instance.

    Return Value

    A reference to this Motion instance, for the purpose of chaining multiple calls to this method.

  • Adds a delay before the motion operation will begin.

    Declaration

    Swift

    @discardableResult
@MainActor
public func afterDelay(_ amount: TimeInterval) -> PhysicsMotion

    Parameters

    amount

    The number of seconds to wait.

    Return Value

    A reference to this PhysicsMotion instance, for the purpose of chaining multiple calls to this method.

  • Specifies that a motion cycle should repeat and the number of times it should do so. When no value is provided, the motion will repeat infinitely.

    Remark

    When this method is used there is no need to specify repeats in the options parameter of the init method.

    Seealso

    repeating, repeatCycles

    Declaration

    Swift

    @discardableResult
@MainActor
public func repeats(_ numberOfCycles: UInt = REPEAT_INFINITE) -> PhysicsMotion

    Parameters

    numberOfCycles

    The number of motion cycles to repeat. The default value is REPEAT_INFINITE.

    Return Value

    A reference to this PhysicsMotion instance, for the purpose of chaining multiple calls to this method.

  • Specifies that a motion, when it has moved to the ending value, should move from the ending value back to the starting value.

    Remark

    When this method is used there is no need to specify reverse in the options parameter of the init method.

    Seealso

    reversing, reverseEasing

    Declaration

    Swift

    @discardableResult
@MainActor
public func reverses() -> PhysicsMotion

    Return Value

    A reference to this PhysicsMotion instance, for the purpose of chaining multiple calls to this method.

  • Declaration

    Swift

    @MainActor
public func cleanupResources()

Moveable protocol methods

  • Declaration

    Swift

    @MainActor
public func update(withTimeInterval currentTime: TimeInterval)

  • Declaration

    Swift

    @discardableResult
@MainActor
public func start() -> Self

  • Declaration

    Swift

    @MainActor
public func stop()

  • Declaration

    Swift

    @MainActor
public func pause()

  • Declaration

    Swift

    @MainActor
public func resume()

  • Resets the motion to its initial state.

    Declaration

    Swift

    @MainActor
public func reset()

TempoDriven methods

TempoDelegate methods

  • Declaration

    Swift

    @MainActor
public func tempoBeatUpdate(_ timestamp: TimeInterval)

PropertyDataDelegate methods

  • Declaration

    Swift

    @MainActor
public func didUpdate(_ startValue: Double)