Alarm

Alarms are a modification of the standard dart Timer class. They can be used like timers, waiting a certain duration until firing a callback, however with a few differences.

There are 2 variants of Alarms, Duration alarms and DateTime alarms.

Duration Alarms

Duration Alarms work more or less the same as the standard dart Timer. They take in a Duration, and after Alarm.start() is called, they wait for the given Duration and then run their callback.

Log log = Log("Alarm");

Alarm alarm = Alarm.duration(const Duration(seconds:10), () {
  log.info("Alarm went off!");
});

alarm.start();

This alarm will not start its' countdown until you call Alarm.start(). The alarm will then log "Alarm went off!" to the console after 10 seconds.

DateTime Alarms

DateTime Alarms are somewhat different. Rather than taking in a Duration, they take in a DateTime.

Log log = Log("Alarm");

Alarm alarm = Alarm.at(const DateTime.utc(2022, 3, 28), () {
  log.info("Alarm went off!");
});

This alarm will now fire at the given DateTime. Unlike Duration alarms, you do not need to call Alarm.start(). If the DateTime is in the past, then the alarm will fire immediately.

---

Tips and Tricks

Restarting an Alarm

When using a Duration alarm, calling Alarm.start() before the alarm has gone off will cause its' timer to restart.

Firing an Alarm again

When using a DateTime alarm, calling Alarm.start() after the DateTime has passed will make it fire its' callback again.

---

API

Static Methods

static void disableColors()

Disables the colors for the static Alarm Log object.

static Alarm at(DateTime at, void Function() callback)

Creates a new Alarm that will run callback at at. If at has already passed, it will fire callback immediately.

static Alarm after(Duration after, void Function() callback)

Creates a new Alarm that will run callback after Duration after has passed from Alarm.start() being called.

Methods

void cancel()

Cancels the Alarm, stopping it from firing its' callback. This is the equivalent of calling Timer.cancel()

Alarm start()

Starts the Alarm's internal Timer. If the Alarm is a DateTime alarm, and at has already passed, it will fire immediately. Returns itself so you can use it with a pseudo-builder pattern:

Alarm alarm = Alarm.after(duration,callback).start();

Getters

bool get isActive

If the Alarm's internal Timer is active, this will return true. This is the equivalent of calling Timer.isActive;

int get tick

Equivalent of Timer.tick for the internal Timer in the Alarm.

bool get onDateTime

Returns true if this Alarm was created using Alarm.at, or false otherwise

Duration get triggerAfter

Regardless of how the Alarm was created, returns the Duration between the Alarm starting and the DateTime that it will go off at.

DateTime get triggerAt

Regardless of how the Alarm was created, returns the DateTime that the Alarm will go off at. Note that when using a Duration Alarm, the DateTime returned will be relative to the current DateTime, even if the Alarm is always running.