A reading from an app changes
Runs the macro when a number or word an app shows (unread count, a label, a script's answer) changes, goes up or down, appears, disappears or crosses a limit.
name in kit changes
Details #
An App Kit declares readings in its kit.json: named values it reads from the app, like unread from the Dock badge. This trigger runs a macro when one of them changes. kit is the kit's id (kit.mail) and name is the reading's name.
when says which change counts:
| when | Runs when |
|---|---|
changed | the value is different (numbers: by says how much) |
increased | a number went up (by: at least that much; threshold: it reached or passed the limit) |
decreased | a number went down (by: at least that much; threshold: it fell to or below the limit) |
appeared | nothing became something (0, empty text and false are nothing) |
disappeared | something became nothing |
crossed | the value went to the other side of threshold, either way (at or above is one side) |
by is a number or a percent (10%). So "Xcode's error count dropped to 0" is decreased with threshold 0, and "Slack's unread went up" is increased.
The run starts with before, after and at. A reading is read only while something uses it, and this macro is one of those uses.
A reading is never read as soon as it moves. Every source waits one second, reads again, and only a value that is still there counts, so a badge caught mid-update doesn't fire the macro. The first read after Switchboard starts, or after the kit is turned on, only records where the reading stands.
Parameters #
| Parameter | Type | Required | Values | What it does |
|---|---|---|---|---|
by | any value | The least change that counts: a number or a percent. | ||
kit | text | The kit's id, like kit.mail. | ||
name | text | The reading's name in that kit. | ||
threshold | number | The limit to reach (increased, decreased) or cross (crossed). | ||
when | one of | changed increased decreased appeared disappeared crossed | The kind of change. Default: changed. |
Every trigger also takes Limits: a cooldown, the first time each day, every nth time, twice within seconds, a chance, only while you are at the Mac, on one Mac, or in a State. See Limits on any trigger.
Examples #
- “unread” in “mail” goes up
- Show “Mail: {{after}} unread (was {{before}})”
Gotchas #
A macro in a group that is limited to the app only runs while that app is in front, like any macro in that group. Put it in a group for everywhere if the app is in the background when the reading changes.
A reading that can't be read (the window is closed, the app isn't running) keeps its last value and is marked stale; that is not a change.
A reading that nothing else uses is read only for this trigger, so turning the macro off stops it.