Read a value from an app
Reads one number or word an app shows right now (the red number on its Dock icon, a menu bar item, a window title, a script's answer, a file) and hands it to the next steps.
Read from of app
Details #
Reads once, with no kit. The value is the step's output, and into stores it in a variable. app is the app's name (Mail) or bundle id (com.apple.mail) and from says where to read:
| from | Reads |
|---|---|
dockBadge (default) | the red number on the app's Dock icon, through the Dock's accessibility tree. Works for nearly every app that counts something, hidden or not. |
menuBarExtra | the title of the app's menu bar item (item picks one by words in its title) |
windowTitle | the app's main window title |
appleScript, jxa | a script's result (script) |
intent | an App Intent that returns a value (intent, params) |
file | a file's text, or with sql the first column of a read-only query on a SQLite file (path) |
ocr | text on screen (area), the last resort: it needs Screen Recording |
as turns the text into a value: number (1.2k, 1,234 and 3 unread all read as numbers), date, boolean, list, or text (default). regex takes the first group of a pattern from the text first ((\d+) errors?). When there is nothing to read, or the text isn't one of those, the value is default.
The output is {value, at, stale}.
The same keys, in a kit's readings, make a value that stays current: a token, a condition and a trigger.
Parameters #
| Parameter | Type | Required | Values | What it does |
|---|---|---|---|---|
app | text | The app: its name or bundle id. | ||
area | record | |||
as | one of | number text date boolean list | , default, regex: What to make of the text. | |
default | any value | |||
every | any value | |||
from | one of | dockBadge menuBarExtra windowTitle anchor appleScript jxa intent file notification ocr | Where to read it. Default: dockBadge. | |
intent | text | |||
into | text | The variable that receives the value. | ||
item | text | , script, intent, params, path, sql, area: What the source needs. | ||
key | text | |||
name | text | |||
params | record | |||
path | text | |||
regex | text | |||
sample | any value | |||
script | text | |||
separator | text | |||
source | one of | screen window | ||
sql | text |
Every step also accepts label, onFailure, timeout and dryRunSafe.
Examples #
- Read the Dock badge of “Mail”
- Show “Mail has {{unread}} unread”
Gotchas #
The Dock needs Accessibility, which Switchboard's engine already has for its other steps.
An app in a Dock folder has no tile of its own, so no badge.
anchorandnotificationreadings belong to a kit: an anchor is a kit's, and a notification is gone after it is posted.Scripts take up to 20 seconds; the step fails after that.
A dash before a number reads as a minus, as it does everywhere: a title like “Inbox – 3 unread” reads as -3. Use
regex((\d+) unread) to take the number out of a title.