Motion

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

Motion handles a single motion operation on one or more properties, interpolating between specified starting and ending values.

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

  • The duration of a motion operation, in seconds, as it moves from its starting property values to its ending values. (read-only)

    Remark

    If the Motion is reversing or repeating, the total duration will be increased by multiples of this duration. If reversing is set to true, the duration of a total motion cycle will be twice this amount as there will be two separate movements (forwards and back).

    Warning

    Do not set this parameter while a motion operation is in progress.

    Declaration

    Swift

    @MainActor
public var duration: 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, Motion will assign an instance of the ValueAssistantGroup class with value assistants for CoreFoundation structs and some color classes (CIColor, and UIColor for platforms which support it). 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 Motion 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. This transition occurs because the most recent additive Motion will assign the ending value of the last additive Motion as its starting position. 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 composite 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 Motion’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 Motions in additive mode are moving the same object properties, adjusting this weighting on each Motion 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 Motion instance when it is moving an object’s property 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 }

PropertyCollection 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 }

Easing update closures

  • A EasingUpdateClosure closure which performs easing calculations for the motion operation.

    Note

    By default, Motion will use EasingLinear.easeNone() for its easing equation if no easing closure is assigned.

    Seealso

    reverseEasingBlock

    Declaration

    Swift

    @MainActor
public var easing: EasingUpdateClosure

  • An optional EasingUpdateClosure closure which performs easing calculations for a motion operation that is reversing.

    Remark

    If not set, the easing closure defined by the easing property is used while reversing.

    Seealso

    easingBlock

    Declaration

    Swift

    @MainActor
public var reverseEasing: EasingUpdateClosure?

Motion state properties

  • The target object whose property should be moved.

    Declaration

    Swift

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

  • A MotionState enum which represents the current 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 Motion 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 Motion 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 Motion. 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 weak var updateDelegate: MotionUpdateDelegate?

TempoDriven protocol properties

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

    Remark

    By default, Motion 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 MotionStarted) -> 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 MotionStopped) -> 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 MotionUpdated) -> Self

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

    Remark

    This method can be chained when initializing the object.

    Seealso

    repeating, cyclesCompletedCount

    Declaration

    Swift

    @discardableResult
@MainActor
public func cycleRepeated(_ closure: @escaping MotionRepeated) -> 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 MotionReversed) -> 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 MotionPaused) -> 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 MotionResumed) -> 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 MotionCompleted) -> Self

Initialization

  • Initializer.

    Declaration

    Swift

    @MainActor
public convenience init(target targetObject: NSObject, properties: [PropertyData], duration: TimeInterval, easing: EasingUpdateClosure? = EasingLinear.easeNone(), 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.
    duration

    The length of the motion, in seconds.
    easing

    An optional EasingUpdateClosure easing equation to use when moving the values of the given properties. EasingLinear.easeNone() is the default equation if none is provided.
    options

    An optional set of MotionsOptions.

  • Initializer.

    Declaration

    Swift

    @MainActor
public convenience init(target targetObject: NSObject, duration: TimeInterval, easing: EasingUpdateClosure? = EasingLinear.easeNone(), options: MotionOptions? = MotionOptions.none)

    Parameters

    target

    The target object whose properties should be modified.
    duration

    The length of the motion, in seconds.
    easing

    An optional EasingUpdateClosure easing equation to use when moving the values of the given properties. EasingLinear.easeNone() is the default equation if none is provided.
    options

    An optional set of MotionsOptions.

  • Initializer. Using this convenience method, you can pass in objects of the value type you’re modifying without having to manually create PropertyData objects for each object property you wish to modify. For instance, if you’re modifying a CGRect object, you can provide CGRect objects that represent its starting and ending states and it will handle the setup for all the properties of the CGRect that have changed between the two states.

    Declaration

    Swift

    @MainActor
public convenience init(target targetObject: NSObject, statesForProperties templateObjects: [PropertyStates], duration: TimeInterval, easing: EasingUpdateClosure? = EasingLinear.easeNone(), options: MotionOptions? = MotionOptions.none)

    Parameters

    target

    The target object whose properties should be modified.
    statesForProperties

    An Array of PropertyStates objects which represent property keypaths (relative to the target object), and values that represent their starting and ending states. By using PropertyStates objects, you can pass in objects of the value type you’re modifying without having to manually create PropertyData objects for each object property you wish to modify. Please see the PropertyStates documentation for usage information.
    duration

    The length of the motion, in seconds.
    easing

    An optional EasingUpdateClosure easing equation to use when moving the values of the given properties. EasingLinear.easeNone() is the default equation if none is provided.
    options

    An optional set of MotionsOptions.

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) -> Motion

    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) -> Motion

    Parameters

    amount

    The number of seconds to wait.

    Return Value

    A reference to this Motion 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

    repeatCycles, repeating

    Declaration

    Swift

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

    Parameters

    numberOfCycles

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

    Return Value

    A reference to this Motion 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 reverses in the options parameter of the init method.

    Seealso

    reversing, reverseEasing

    Declaration

    Swift

    @discardableResult
@MainActor
public func reverses(withEasing easing: EasingUpdateClosure? = nil) -> Motion

    Parameters

    withEasing

    The easing equation to be used while reversing. When no equation is provided, the normal easing closure will be used in both movement directions.

    Return Value

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

  • Builds PropertyData objects for the supplied PropertyStates objects.

    Remark

    This method is used internally by the initializer when the statesForProperties convenience method is used, but you can also call it directly to build an array of PropertyData objects.

    Declaration

    Swift

    @MainActor
public func buildPropertyData(forObject targetObject: AnyObject, statesForProperties: [PropertyStates]) -> [PropertyData]

    Parameters

    forObject

    The object to be modified, and the base object for the paths of the PropertyStates objects.
    statesForProperties

    An Array of PropertyStates objects that define how the PropertyData objects are constructed.

    Return Value

    An Array of PropertyData objects.

  • 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)