MotionSequence

@MainActor
public class MotionSequence : Moveable, MoveableCollection, TempoDriven, MotionUpdateDelegate, Identifiable

MotionSequence moves a collection of objects conforming to the Moveable protocol in sequential order. A single MotionSequence could hold Motion, PhysicsMotion, and PathMotion objects, and even other MoveableCollection objects. MotionSequence provides a powerful and easy way of chaining together individual motions to create complex animations.

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

    Declaration

    Swift

    public typealias SequenceUpdateClosure = (_ sequence: MotionSequence) -> Void

    Parameters

    sequence

    The MotionSequence object which published this update closure.

  • 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 SequenceStarted = SequenceUpdateClosure

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

    Declaration

    Swift

    public typealias SequenceStopped = SequenceUpdateClosure

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

    Declaration

    Swift

    public typealias SequenceUpdated = SequenceUpdateClosure

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

    Declaration

    Swift

    public typealias SequenceReversed = SequenceUpdateClosure

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

    Declaration

    Swift

    public typealias SequenceRepeated = SequenceUpdateClosure

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

    Declaration

    Swift

    public typealias SequencePaused = SequenceUpdateClosure

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

    Declaration

    Swift

    public typealias SequenceResumed = SequenceUpdateClosure

  • 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 SequenceCompleted = SequenceUpdateClosure

  • This notification closure should be called when a sequence’s movement has advanced to its next sequence step.

    Declaration

    Swift

    public typealias SequenceStepped = SequenceUpdateClosure

Public Properties

  • The delay, in seconds, before the sequence begins.

    Warning

    Setting this parameter after a sequence has begun has no effect.

    Declaration

    Swift

    @MainActor
public var delay: TimeInterval

Identifiable conformance

  • id

    A unique identifier.

    Declaration

    Swift

    @MainActor
public let id: UUID

Motion State

  • An array of Moveable objects controlled by this MotionSequence object, determining each step of the sequence. (read-only)

    Remark

    The order of objects in this array represents the sequence order in which each will be moved.

    Declaration

    Swift

    @MainActor
private(set) public var steps: [Moveable] { 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 class 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 sequence. This value should include all reversing and repeat motion cycles. (read-only)

    Remark

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

    Declaration

    Swift

    @MainActor
public var totalProgress: Double { get }

Moveable protocol properties

  • Specifies that the MotionSequence’s child motions should reverse their movements back to their starting values after completing their forward movements. When each child motion should reverse is determined by the MotionSequence’s reversingMode.

    Important

    The previous state of isReversing on any of this sequence’s Moveable objects will be overridden with the value you assign to this property!

    Declaration

    Swift

    @MainActor
public var isReversing: Bool { get set }

  • A Boolean which determines whether the sequence should repeat. When set to true, the sequence 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 (0) will cause the sequence to repeat infinitely.

    Declaration

    Swift

    @MainActor
public var isRepeating: Bool

  • The number of complete sequence 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

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

    Declaration

    Swift

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

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

    Declaration

    Swift

    @MainActor
public weak var updateDelegate: MotionUpdateDelegate?

  • Declaration

    Swift

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

MoveableCollection protocol properties

  • An enum which defines the behavior of a Moveable class when its isReversing property is set to true. In the standard MotionMachine classes only MotionSequence currently uses this property to alter its behavior.

    Note

    While including this property in custom classes which implement the MoveableCollection protocol is required, implementation of behavior based on the property’s value is optional.

    Remark

    The default value is sequential. Please see the documentation for CollectionReversingMode for more information on these modes.

    Declaration

    Swift

    @MainActor
public var reversingMode: CollectionReversingMode { get set }

TempoDriven protocol properties

Notification closures

  • This closure is called when a motion operation starts.

    Seealso

    start

    Declaration

    Swift

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

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

    Seealso

    stop

    Declaration

    Swift

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

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

    Seealso

    update(withTimeInterval:)

    Declaration

    Swift

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

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

    Seealso

    repeating, cyclesCompletedCount

    Declaration

    Swift

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

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

    Declaration

    Swift

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

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

    Seealso

    pause

    Declaration

    Swift

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

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

    Seealso

    resume

    Declaration

    Swift

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

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

    Declaration

    Swift

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

  • This notification closure is called when the sequence’s movement has advanced to its next sequence step.

    Declaration

    Swift

    @discardableResult
@MainActor
public func stepCompleted(_ closure: @escaping SequenceStepped) -> Self

Initialization

  • Initializer.

    Declaration

    Swift

    @MainActor
public init(steps: [Moveable] = [], options: MotionOptions? = MotionOptions.none)

    Parameters

    steps

    An array of Moveable objects the MotionSequence should control. The positions of the objects in the Array will determine the order in which the child motions should move.
    options

    An optional set of MotionsOptions.

Public methods

  • Adds a sequence step to the end of the current sequence.

    Warning

    warning:

    • A NSInternalInconsistencyException will be raised if the provided object does not adopt the Moveable protocol.
    • This method should not be called after a MotionSequence has started moving.

    Declaration

    Swift

    @discardableResult
@MainActor
public func add(_ sequenceStep: Moveable, useChildTempo: Bool = false) -> Self

    Parameters

    sequenceStep

    An object which adopts the Moveable protocol.
    useChildTempo

    When true, the child object should use its own tempo to update its motion progress, and thus the update method will not be called on the object by the MotionSequence instance. The default is false, meaning that the MotionSequence will use its own Tempo object to send updates to this child motion. This setting has no effect if the motion object does not conform to the TempoDriven protocol.

  • Adds an array of sequence steps to the current sequence.

    Note

    All objects added via this method which subscribe to the TempoDriven protocol will have their Tempo updates overriden. The MotionSequence will call the update method directly on all of them.

    Warning

    warning:

    • A NSInternalInconsistencyException will be raised if the provided object does not adopt the Moveable protocol.
    • This method should not be called after a MotionGroup has started moving.

    Declaration

    Swift

    @discardableResult
@MainActor
public func add(_ steps: [Moveable]) -> Self

    Parameters

    steps

    An array of ‘Moveable` objects.

  • Removes the specified motion object from the sequence.

    Declaration

    Swift

    @MainActor
public func remove(_ sequenceStep: Moveable)

    Parameters

    sequenceStep

    The sequence step to remove.

  • Adds a delay before the motion operation will begin.

    Declaration

    Swift

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

    Parameters

    amount

    The number of seconds to wait.

    Return Value

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

    Parameters

    numberOfCycles

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

    Return Value

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

  • Specifies that the MotionSequence’s child motions should reverse their movements back to their starting values after completing their forward movements.

    Remark

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

    Declaration

    Swift

    @discardableResult
@MainActor
public func reverses(_ mode: CollectionReversingMode = .sequential) -> MotionSequence

    Parameters

    mode

    Defines the CollectionReversingMode used when reversing.

    Return Value

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

  • Either the sequence step which is currently moving, or the first sequence step if this instance’s motionState is currently Stopped.

    Declaration

    Swift

    @MainActor
public func currentStep() -> Moveable?

    Return Value

    The current sequence step.

  • Declaration

    Swift

    @MainActor
public func cleanupResources()

Moveable 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 sequence and all child motions to its initial state.

    Declaration

    Swift

    @MainActor
public func reset()

MotionUpdateDelegate methods

TempoDriven methods

TempoDelegate methods

  • Declaration

    Swift

    @MainActor
public func tempoBeatUpdate(_ timestamp: TimeInterval)