Signals
A signal runs a shell command when something happens: a window opens, the space changes, an app starts. A bar such as SketchyBar redraws its spaces this way.
Edit signals on Settings › Signals: under New Signal, choose the Event, type the Command, optionally limit
it to an app or a window title, and click Add Signal. Your Signals lists the signals you have. In the file each signal is a [[signal]] entry:
[[signal]]event = "space_changed"action = "sketchybar --trigger space_change"The command runs through your login shell, detached; its output is not kept.
Events
Section titled “Events”| Event | When |
|---|---|
window_created, window_destroyed |
A window opens or closes |
window_focused |
A window gets the focus |
window_moved, window_resized |
A window moves or changes size, also when the layout places it |
window_minimized, window_deminimized |
A window goes into the Dock or comes back |
space_changed |
Another space is shown |
space_created, space_destroyed |
A space is added or removed |
display_added, display_removed |
A display is connected or removed |
display_changed |
Another display has the focus |
app_launched, app_terminated |
An app starts or quits |
app_activated |
An app comes to the front |
app_hidden, app_shown |
An app is hidden or shown again |
mission_control_entered, mission_control_left |
Mission Control opens or closes |
system_woke |
The Mac wakes from sleep |
Each change is reported once. The windows and spaces that exist when TilingBud starts are not events.
Limiting a signal to apps and windows
Section titled “Limiting a signal to apps and windows”For window and app events, a signal can be limited as a window rule
is: app (a name or a program path), except_apps, and title or except_title as regular expressions on the window
title. Other events ignore them. label gives the signal a name, shown in Settings and in query --signals.
[[signal]]event = "window_focused"app = "iTerm2"except_title = "^vim"action = "~/bin/terminal-focused.sh"label = "terminal"Values for the command
Section titled “Values for the command”The command gets the event’s values as environment variables, each only where the event has it:
| Variable | Value |
|---|---|
TILINGBUD_EVENT |
The event’s name |
TILINGBUD_WINDOW_ID |
The window’s id |
TILINGBUD_PROCESS_ID |
The app’s process id |
TILINGBUD_SPACE_INDEX |
The space’s number over all displays (index in query --spaces) |
TILINGBUD_SPACE_ID |
The space’s id |
TILINGBUD_RECENT_SPACE_INDEX |
The space shown before, for space_changed |
TILINGBUD_DISPLAY_INDEX |
The display’s number |
TILINGBUD_DISPLAY_ID |
The display’s UUID |
[[signal]]event = "space_changed"action = "sketchybar --trigger space_change SPACE=$TILINGBUD_SPACE_INDEX"Listening instead
Section titled “Listening instead”A tool can keep tilingbud subscribe running and read one JSON line per event. Nothing is started per event and no
[[signal]] entry is needed:
tilingbud subscribe space_changed window_focused | while read -r line; do echo "$line" | jq .space_indexdoneWithout event names it reports every event. tilingbud subscribe nope fails and lists the event names. See the
command line for the fields of each line.
Typical uses
Section titled “Typical uses”- A bar redraws its spaces on
space_changed. - A script sets a chat status when a certain space opens, from
space_changedandTILINGBUD_SPACE_INDEX. - A layout script runs when a display is plugged in, on
display_added.
Every key is in the reference.