Timer

class Timer : Equatable
extension Timer: Hashable
extension Timer: CustomDebugStringConvertible

This is used as a wrapper for each individual timer, and provides accessors.

We make it a class, so it can be easily referenced.

  • This is the structure of the callback for each “tick,” handed to the instance. It is called once a second. This will always be called in the main thread.

    Declaration

    Swift

    public typealias TickHandler = (_ timer: Timer) -> Void

    Parameters

    timer

    The timer wrapper instance calling it.

  • This is the structure of the callback for mode transitions, handed to the instance. It is called, once only, when the timer mode changes. This will always be called in the main thread.

    Declaration

    Swift

    public typealias TransitionHandler = (_ timer: Timer, _ fromMode: TimerEngine.Mode, _ toMode: TimerEngine.Mode) -> Void

    Parameters

    timer

    The timer wrapper instance calling it.
    fromMode

    The mode we have transitioned from.
    toMode

    The mode we have transitioned into.

  • Equatable Conformance

    Declaration

    Swift

    static func == (lhs: Timer, rhs: Timer) -> Bool

    Parameters

    lhs

    The left-hand side of the comparison.
    rhs

    The right-hand side of the comparison.

    Return Value

    True, if they are equal (same ID).

  • The actual timer engine.

    Declaration

    Swift

    private let _engine: TimerEngine

  • The group to which this container belongs.

    Declaration

    Swift

    var group: TimerGroup?

  • The callback for the tick handler. This can be called in any thread.

    Declaration

    Swift

    public var tickHandler: TickHandler?

  • The callback for the transition handler. This can be called in any thread. It may also be nil.

    Declaration

    Swift

    public var transitionHandler: TransitionHandler?

  • If true, then this timer is the selected timer. There can only be one.

    Declaration

    Swift

    public var isSelected: Bool { get set }

  • Default initializer.

    Declaration

    Swift

    init(group inGroup: TimerGroup,
     startingTimeInSeconds inStartingTimeInSeconds: Int = 0,
     warningTimeInSeconds inWarningTimeInSeconds: Int = 0,
     finalTimeInSeconds inFinalTimeInSeconds: Int = 0,
     transitionHandler inTransitionHandler: TransitionHandler? = nil,
     tickHandler inTickHandler: TickHandler? = nil
)

    Parameters

    inGroup

    The group to which this container belongs. This is required.
    inStartingTimeInSeconds

    This is the beginning (total) countdown time. If not supplied, is set to 0.
    inWarningTimeInSeconds

    This is the threshold, at which the clock switches into “warning” mode. If not supplied, is set to 0.
    inFinalTimeInSeconds

    This is the threshold, at which the clock switches into “final” mode. If not supplied, is set to 0.
    inTransitionHandler

    The callback for each transition. This is optional.
    inTickHandler

    The callback for each tick. This can be a tail completion, and is optional.

  • Initializer with group and preset dictionary.

    Declaration

    Swift

    init(group inGroup: TimerGroup? = nil,
     dictionary inDictionary: [String: any Hashable],
     transitionHandler inTransitionHandler: TransitionHandler? = nil,
     tickHandler inTickHandler: TickHandler? = nil
)

    Parameters

    inGroup

    The group to which this instance belongs.
    inDictionary

    The timer state, as a dictionary.
    inTransitionHandler

    The callback for each transition. This is optional.
    inTickHandler

    The callback for each tick. This can be a tail completion, and is optional.

Timer Extension for Display

  • This returns an “optimized” string, with the HH:mm:ss format of the starting time. Empty, if none.

    Declaration

    Swift

    var setTimeDisplay: String { get }

  • This returns an “optimized” string, with the HH:mm:ss format of the warning threshold time. Empty, if none.

    Declaration

    Swift

    var warnTimeDisplay: String { get }

  • This returns an “optimized” string, with the HH:mm:ss format of the final threshold time. Empty, if none.

    Declaration

    Swift

    var finalTimeDisplay: String { get }

Read-Only Computed Properties

  • id

    The timer’s unique ID.

    Declaration

    Swift

    var id: UUID { get }

  • The timer’s ultimate model.

    Declaration

    Swift

    var model: TimerModel? { get }

  • This is the 00:00:00 format of the time, as a string.

    Declaration

    Swift

    var timerDisplay: String { get }

  • The index path of this timer, in the model.

    Declaration

    Swift

    var indexPath: IndexPath? { get }

Read/Write Computed Properties

  • Returns the timer mode.

    Declaration

    Swift

    var timerMode: TimerEngine.Mode { get }

  • Returns true, if the timer is currently ticking

    Declaration

    Swift

    var isTimerRunning: Bool { get }

  • Returns true, if the timer is paused.

    Declaration

    Swift

    var isTimerPaused: Bool { get }

  • Returns true, if the timer has reached warning mode.

    Declaration

    Swift

    var isTimerInWarning: Bool { get }

  • Returns true, if the timer has reached final mode.

    Declaration

    Swift

    var isTimerInFinal: Bool { get }

  • Returns true, if the timer is in “alarm” state

    Declaration

    Swift

    var isTimerInAlarm: Bool { get }

  • Returns true, if the timer is at the final point

    Declaration

    Swift

    var isTimerAtEnd: Bool { get }

  • Returns true, if the timer is at the starting point

    Declaration

    Swift

    var isTimerAtStart: Bool { get }

  • This is the saved state of the timer. It may be extracted, or supplied.

    Declaration

    Swift

    var timerState: [String : any Hashable] { get set }

  • This is a direct accessor for the timer’s starting time.

    Declaration

    Swift

    var startingTimeInSeconds: Int { get set }

  • This is a direct accessor for the timer’s warning time.

    Declaration

    Swift

    var warningTimeInSeconds: Int { get set }

  • This is a direct accessor for the timer’s final time.

    Declaration

    Swift

    var finalTimeInSeconds: Int { get set }

  • This is a direct accessor for the timer’s current countdown time (integer).

    Declaration

    Swift

    var currentTime: Int { get set }

  • This is a direct accessor for the timer’s current countdown time (precise).

    Declaration

    Swift

    var currentPreciseTime: TimeInterval? { get set }

  • This returns the entire timer state as a simple dictionary, suitable for use in plists. The instance can be saved or restored from this. Restoring stops the timer.

    Note

    This does not affect the tickHandler or transitionHandler properties.

    Declaration

    Swift

    var asDictionary: [String : any Hashable] { get set }

Instance Methods

  • This simply sets the last paused time, to 0.

    Declaration

    Swift

    func resetLastPausedTime()

  • The callback for the individual second ticks. May be called in any thread.

    Declaration

    Swift

    private func _internalTickHandler(_ inTimerEngine: TimerEngine)

    Parameters

    inTimerEngine

    The timer engine.

  • Called when the timer experiences a state transition.

    Declaration

    Swift

    private func _internalTransitionHandler(_ inTimerEngine: TimerEngine, _ inFromMode: TimerEngine.Mode, _ inToMode: TimerEngine.Mode)

    Parameters

    inTimerEngine

    The timer engine.
    inFromMode

    The previous mode (state).
    inToMode

    The current (new) mode (state).

  • This removes the timer from the model.

    Declaration

    Swift

    @discardableResult
func delete() -> Bool

    Return Value

    True, if the deletion was successful. May be ignored.

  • Starts the timer from the beginning. It will do so, from any timer state.

    This will interrupt any current timer.

    Declaration

    Swift

    func start()

  • This stops the timer, and resets it to the starting point, with no alarm. It will do so, from any timer state.

    This will interrupt any current timer.

    Declaration

    Swift

    func stop()

  • This forces the timer into alarm mode. It will do so, from any timer state.

    This will interrupt any current timer.

    Declaration

    Swift

    func end()

  • This pauses a running timer. The timer must already be in .countdown, .warning, or .final state.

    Declaration

    Swift

    @discardableResult
func pause() -> [String : any Hashable]

    Return Value

    The state of the instance, just prior to pausing (empty, if failed). Can be ignored.

  • This resumes a paused timer. The timer must already be in .paused state, or a new state should be provided.

    You can use this method to set a timer to a saved state, and start it going immediately.

    Note

    This does not affect the tickHandler or transitionHandler properties, unless they are provided as method arguments. If the tickHandler or transitionHandler method arguments are supplied, and the resume fails, they will not be applied.

    Declaration

    Swift

    @discardableResult
func resume(_ inState: [String: any Hashable]? = nil,
            transitionHandler inTransitionHandler: TimerEngine.TimerTransitionHandler? = nil,
            tickHandler inTickHandler: TimerEngine.TimerTickHandler? = nil
) -> Bool

    Parameters

    inState

    The saved state of the timer. If provided, the timer is set to that state, and started immediately, as opposed to a regular resume.
    inTransitionHandler

    The callback for each transition. This is optional.
    inTickHandler

    The callback for each tick. This can be a tail completion, and is optional.

    Return Value

    True, if the resume was successful. Can be ignored.

  • This forces the timer to sync directly to the given seconds. The date is the time that corresponds to the exact second. The timer is started, if it was not already running.

    Note

    This directly sets the timer to a running state, but the tickHandler and transitionHandler callbacks may not be immediately executed. The timer must already be in .countdown, .warning, or .final state.

    Declaration

    Swift

    func sync(to inSeconds: Int, date inDate: Date = .now)

    Parameters

    inSeconds

    The actual integer second.
    inDate

    The date that corresponds to the given second. If not supplied, .now is used.

Hashable Conformance

  • Hash dealer.

    Declaration

    Swift

    func hash(into inOutHasher: inout Hasher)

    Parameters

    inOutHasher

    The hasher we’re loading up.

Instance Methods

  • Emits a formatted string, describing the model.

    Declaration

    Swift

    var debugDescription: String { get }