PathMotion

@MainActor
public class PathMotion : Moveable, TempoDriven, PropertyCollection, PropertyDataDelegate, Identifiable

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.

  • Undocumented

    Declaration

    Swift

    public typealias TargetType = PathState

  • A closure used to provide status updates for a PathMotion object.

    Declaration

    Swift

    public typealias PathMotionUpdateClosure = (_ motion: PathMotion, _ currentPoint: CGPoint) -> Void

    Parameters

    motion

    The PathMotion object which published this update closure.
    currentPoint

    The current position of a point being animated along a path.

  • This notification closure should be called when the start() method starts a motion operation. If a delay has been specified, this closure is called after the delay is complete.

    Declaration

    Swift

    public typealias PathMotionStarted = PathMotionUpdateClosure

  • This notification closure should be called when the stop() method starts a motion operation.

    Declaration

    Swift

    public typealias PathMotionStopped = PathMotionUpdateClosure

  • This notification closure should be called when the update(withTimeInterval:) method is called while a Moveable object is currently moving.

    Declaration

    Swift

    public typealias PathMotionUpdated = PathMotionUpdateClosure

  • This notification closure should be called when a motion operation reverses its movement direction.

    Declaration

    Swift

    public typealias PathMotionReversed = PathMotionUpdateClosure

  • This notification closure should be called when a motion has started a new motion cycle.

    Declaration

    Swift

    public typealias PathMotionRepeated = PathMotionUpdateClosure

  • This notification closure should be called when calling the pause() method pauses a motion operation.

    Declaration

    Swift

    public typealias PathMotionPaused = PathMotionUpdateClosure

  • This notification closure should be called when calling the resume() method resumes a motion operation.

    Declaration

    Swift

    public typealias PathMotionResumed = PathMotionUpdateClosure

  • This notification closure should be called when a motion operation has fully completed.

    Note

    This closure should only be executed when all activity related to the motion has ceased. For instance, if a Moveable class allows a motion to be repeated multiple times, this closure should be called when all repetitions have finished.

    Declaration

    Swift

    public typealias PathMotionCompleted = PathMotionUpdateClosure

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 isReversing or isRepeating, the total duration will be increased by multiples of this duration. If isReversing 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

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

    Remark

    Because PathMotion handles its own value interpolation along a path, it only uses the NumericAssistant.

    Declaration

    Swift

    @MainActor
public var valueAssistant: any ValueAssistant<TargetType>

  • An operation identifer 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 identifer is currently assigned.

    Declaration

    Swift

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

Identifiable conformance

  • id

    A unique identifier.

    Declaration

    Swift

    @MainActor
public let id: UUID

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.

    Declaration

    Swift

    @MainActor
private(set) public var properties: [PropertyData<TargetType>] { 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: TargetType? { get }

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

    Declaration

    Swift

    @MainActor
private(set) public var motionState: MoveableState { 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 isReversing or isRepeating, 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 isReversing 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 isRepeating is true, 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 isReversing 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 isRepeating is true, 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 the motion is not repeating, this value will be equivalent to the value of 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 isReversing: Bool

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

    Declaration

    Swift

    @MainActor
public var isRepeating: Bool

  • The number of motion cycle operations to repeat.

    Remark

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

    Declaration

    Swift

    @MainActor
public var repeatCycles: UInt

  • 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

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)