MotionGroup

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

MotionGroup handles the movement of one or more objects which conform to the Moveable protocol. A single MotionGroup could hold Motion, PhysicsMotion, and PathMotion objects, and even other MoveableCollection objects. The MotionGroup class is a good solution when you want to easily synchronize the movements of many Moveable objects.

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

    Declaration

    Swift

    public typealias GroupUpdateClosure = (_ group: MotionGroup) -> Void

    Parameters

    group

    The MotionGroup 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 GroupStarted = GroupUpdateClosure

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

    Declaration

    Swift

    public typealias GroupStopped = GroupUpdateClosure

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

    Declaration

    Swift

    public typealias GroupUpdated = GroupUpdateClosure

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

    Declaration

    Swift

    public typealias GroupReversed = GroupUpdateClosure

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

    Declaration

    Swift

    public typealias GroupRepeated = GroupUpdateClosure

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

    Declaration

    Swift

    public typealias GroupPaused = GroupUpdateClosure

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

    Declaration

    Swift

    public typealias GroupResumed = GroupUpdateClosure

  • 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 GroupCompleted = GroupUpdateClosure

Public Properties

  • The delay, in seconds, before the group’s 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 the MotionGroup should synchronize when its Moveable objects reverse direction during each movement cycle. This means that the MotionGroup’s fastest child motion will wait for the other children to finish their movements before reversing direction.

    When set to true, the MotionGroup will not tell its Moveable objects to reverse direction until all of them have completed their current movement cycle. This will occur both when the child motions have finished their foward movement, and when they’ve finished their movement in the opposite direction. When this property is set to false, the MotionGroup’s objects will move independently of each other.

    The default value is false.

    Note

    This property only has an effect when isReversing is set to true, in which case the MotionGroup will call the GroupReversed notification closure when all of its Moveable objects are ready to reverse.

    Declaration

    Swift

    @MainActor
public var syncMotionsWhenReversing: Bool

Identifiable conformance

  • id

    A unique identifier.

    Declaration

    Swift

    @MainActor
public let id: UUID

  • An array comprising the Moveable objects controlled by this MotionGroup object. (read-only)

    Declaration

    Swift

    @MainActor
private(set) public var motions: [Moveable] { get }

  • An enum which represents the current movement 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 MotionGroup 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 MotionGroup is reversing, this property’s value 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 group. This value should include all reversing and repeat motion cycles. (read-only)

    Remark

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

    Declaration

    Swift

    @MainActor
public var totalProgress: Double { get }

Moveable protocol properties

  • A Boolean which determines whether the MotionGroup’s child motions should reverse their movements back to their starting values after completing their forward movements.

    Declaration

    Swift

    @MainActor
public var isReversing: Bool { get set }

  • A Boolean which determines whether the group’s 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 (0) 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?

  • Declaration

    Swift

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

MoveableCollection protocol properties

  • A CollectionReversingMode enum which defines the behavior of a Moveable class when its reversing property is set to true. In the standard MotionMachine classes only MotionSequence currently uses this property to alter its behavior. This property should not be set directly on a MotionGroup object.

    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. If a delay has been specified, this closure is called after the delay is complete.

    Seealso

    start

    Declaration

    Swift

    @discardableResult
@MainActor
public func started(_ closure: @escaping GroupStarted) -> 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 GroupStopped) -> 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 GroupUpdated) -> Self

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

    Seealso

    repeating, cyclesCompletedCount

    Declaration

    Swift

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

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

    Declaration

    Swift

    @discardableResult
@MainActor
public func reversed(_ closure: @escaping GroupReversed) -> 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 GroupPaused) -> 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 GroupResumed) -> 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 GroupCompleted) -> Self

Initialization

Public methods

  • Adds an object which conforms to the Moveable protocol to the group of motion ‘children’ this object controls.

    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(_ motion: Moveable, useChildTempo: Bool = false) -> Self

    Parameters

    motion

    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 MotionGroup instance. The default is false, meaning that the MotionGroup 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 Moveable objects to the group of motion ‘children’ this object controls.

    Note

    All objects added via this method which subscribe to the TempoDriven protocol will have their Tempo updates overriden. The MotionGroup 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(_ motions: [Moveable]) -> Self

    Parameters

    motions

    An array of ‘Moveable` objects.

  • Removes the specified motion object from the group.

    Declaration

    Swift

    @MainActor
public func remove(_ motion: Moveable)

    Parameters

    motion

    The motion object to remove.

  • Adds a delay before the motion operation will begin.

    Declaration

    Swift

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

    Parameters

    amount

    The number of seconds to wait.

    Return Value

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

    Parameters

    numberOfCycles

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

    Return Value

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

  • Specifies that the MotionGroup’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.

    Seealso

    reversing, syncMotionsWhenReversing

    Declaration

    Swift

    @discardableResult
@MainActor
public func reverses(syncsChildMotions syncMotions: Bool) -> MotionGroup

    Parameters

    syncMotions

    Determines whether the MotionGroup should synchronize when its Moveable objects reverse direction during each movement cycle.

    Return Value

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