MotionGroup

public class MotionGroup: Moveable, MoveableCollection, TempoDriven, MotionUpdateDelegate

MotionGroup handles the movement of one or more objects which conform to the Moveable protocol, either being instances of Motion or other custom classes. The MotionGroup class is a good solution when you want to easily synchronize the movements of many Moveable objects.

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

    public var delay: TimeInterval = 0.0

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

    Seealso

    repeatCycles

    Declaration

    Swift

    public var repeating: Bool = false

  • 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

    public var repeatCycles: UInt = REPEAT_INFINITE

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

    Note

    This property only has an effect when reversing 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.

    The default value is false.

    Seealso

    reversing

    Declaration

    Swift

    public var syncMotionsWhenReversing: Bool = false

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

    Declaration

    Swift

    private(set) public var motions: [Moveable] = []

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

    Declaration

    Swift

    private(set) public var motionState: MotionState

  • A MotionDirection enum which represents the current direction of the motion operation. (read-only)

    Declaration

    Swift

    private(set) public var motionDirection: MotionDirection

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

    private(set) public var motionProgress: Double

  • 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

    private(set) public var cycleProgress: Double

  • 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

    private(set) public var cyclesCompletedCount: UInt = 0

  • 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 a group is not repeating, this value will be equivalent to the value of cycleProgress.

    Seealso

    cycleProgress

    Declaration

    Swift

    public var totalProgress: Double

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

    public var reversing: Bool

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

    Declaration

    Swift

    public var updateDelegate: MotionUpdateDelegate?

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

    public var reversingMode: CollectionReversingMode = .sequential

TempoBeating 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

    public var tempo: Tempo?

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 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 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 public func updated(_ closure: @escaping GroupUpdated) -> Self

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

    Seealso

    repeating, cyclesCompletedCount

    Declaration

    Swift

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

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

    Seealso

    motionDirection, reversing

    Declaration

    Swift

    @discardableResult 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 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 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 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 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 public func add(_ motions: [Moveable]) -> Self

    Parameters

    motions

    An array of ‘Moveable` objects.

  • Removes the specified motion object from the group.

    Declaration

    Swift

    public func remove(_ motion: Moveable)

    Parameters

    motion

    The motion object to remove.

  • Adds a delay before the motion operation will begin.

    Declaration

    Swift

    @discardableResult 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 .Repeat in the options parameter of the init method.

    Seealso

    repeatCycles, repeating

    Declaration

    Swift

    @discardableResult 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 .Reverse in the options parameter of the init method.

    Seealso

    reversing, syncMotionsWhenReversing

    Declaration

    Swift

    @discardableResult 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.

Moveable protocol methods

  • Declaration

    Swift

    public func update(withTimeInterval currentTime: TimeInterval)

  • Declaration

    Swift

    @discardableResult public func start() -> Self

  • Declaration

    Swift

    public func stop()

  • Declaration

    Swift

    public func pause()

  • Declaration

    Swift

    public func resume()

  • Resets the group and all child motions to its initial state.

    Declaration

    Swift

    public func reset()

MotionUpdateDelegate methods

TempoDriven methods

TempoDelegate methods