PathMotion

@MainActor
public class PathMotion : Moveable, TempoDriven, PropertyDataDelegate

PathMotion handles a single motion operation of a coordinate point along a CGPath. It does not directly accept PropertyData objects, but instead transforms a value between 0.0 and 1.0, representing the length of the associated path. Using this value, it updates the current point on the path.

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

  • 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. In a PathMotion the only PropertyData instance stored represents the internal progress along the path. To obtain the motion’s current point along the path, subscribe to one of its update methods.

    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 }

  • The object maintaining state on the path.

    Declaration

    Swift

    @MainActor
public private(set) var pathState: PathState { get }

  • Determines how path edges are handled during a motion when the motion attempts to travel past the path’s edges. This is rare, but can occur in some cases such as the EasingBack and EasingElastic easing equations. The default value is stopAtEdges.

    Declaration

    Swift

    @MainActor
public var edgeBehavior: PathEdgeBehavior { get set }

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 PathMotionStarted) -> 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 PathMotionStopped) -> 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 PathMotionUpdated) -> 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 PathMotionRepeated) -> 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 PathMotionReversed) -> 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 PathMotionPaused) -> 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 PathMotionResumed) -> 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 PathMotionCompleted) -> Self

Initialization

  • A convenience initializer.

    Declaration

    Swift

    @MainActor
public convenience init(path: CGPath, duration: TimeInterval, startPosition: Double? = nil, endPosition: Double? = nil, easing: EasingUpdateClosure? = EasingLinear.easeNone(), edgeBehavior: PathEdgeBehavior? = nil, options: MotionOptions? = MotionOptions.none)

    Parameters

    path

    A CGPath object to use as a motion guide.
    duration

    The duration of the motion.
    startPosition

    An optional starting value, corresponding to a percentage along the path’s length where the motion should begin. The range must be between 0.0 and 1.0; values outside that range will be clamped to the minimum or maximum value. The default value is 0.0.
    endPosition

    An optional ending value, corresponding to a percentage along the path’s length where the motion should end. The range must be between 0.0 and 1.0; values outside that range will be clamped to the minimum or maximum value. The default value is 1.0.
    easing

    An optional easing equation.
    edgeBehavior

    Determines how path edges are handled during a motion when the motion attempts to travel past the path’s edges. This is rare, but can occur in some cases such as the EasingBack and EasingElastic easing equations. The default value is stopAtEdges.
    options

    An optional options model.

  • The initializer.

    Declaration

    Swift

    @MainActor
public init(pathState: PathState, duration: TimeInterval, startPosition: Double? = nil, endPosition: Double? = nil, easing: EasingUpdateClosure? = EasingLinear.easeNone(), edgeBehavior: PathEdgeBehavior? = nil, options: MotionOptions? = MotionOptions.none)

    Parameters

    pathState

    A state object containing information about the path to use as a motion guide.
    duration

    The duration of the motion.
    startPosition

    An optional starting value, corresponding to a percentage along the path’s length where the motion should begin. The range must be between 0.0 and 1.0; values outside that range will be clamped to the minimum or maximum value. The default value is 0.0.
    endPosition

    An optional ending value, corresponding to a percentage along the path’s length where the motion should end. The range must be between 0.0 and 1.0; values outside that range will be clamped to the minimum or maximum value. The default value is 1.0.
    easing

    An optional easing equation.
    edgeBehavior

    Determines how path edges are handled during a motion when the motion attempts to travel past the path’s edges. This is rare, but can occur in some cases such as the EasingBack and EasingElastic easing equations. The default value is stopAtEdges.
    options

    An optional options model.

Public methods

  • Adds a delay before the motion operation will begin.

    Declaration

    Swift

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

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

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

    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.

  • setupPerformanceMode() Asynchronous

    Sets up performance mode, generating an internal lookup table for faster position calculations. To use the performance mode, this method must be used before calling start().

    Note

    With large paths, the lookup table generation could take a second or longer to complete. Be aware that the lookup table generation runs synchronously on another dispatch queue, blocking the return of this async call until the generation has completed. Be sure to call this method as early as possible to give the operation time to complete before your PathMotion needs to begin.

    Declaration

    Swift

    @MainActor
public func setupPerformanceMode() async

    Parameters

    lookupCapacity

    An optional capacity that caps the maximum lookup table amount.

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