When widgets update
Atsurae redraws a widget only when something it shows has changed. Knowing what triggers an update helps you build widgets that are both up to date and cheap to run.
Data sources
Section titled “Data sources”Atsurae looks at the tokens in your elements and starts only the data sources they need. If no enabled widget uses {track}, Atsurae doesn’t listen for music at all.
| Source | Tokens | Refreshes |
|---|---|---|
| Clock | dates, times, *.progress |
Exactly on each new minute, or each second if a widget shows seconds |
| Battery | {battery}, {batteryState}, {battery.level} |
Whenever macOS reports a change |
| CPU and memory | {cpu}, {memory}, *.level |
Every 5 seconds |
| Now playing | {track}, {artist}, {lastTrack}, {lastArtist} |
Whenever Music or Spotify changes track or pauses |
| Weather | {weather.*} |
Every 30 minutes |
| Script | {script.*} |
See below |
The clock switches to once a second only while an enabled widget actually shows seconds ({second}, {time} with Show seconds on, or a {date:…} pattern containing s).
When a widget redraws
Section titled “When a widget redraws”When a source changes, Atsurae works out each element’s new text or value and redraws only the elements whose content changed. If your clock shows {hour}:{minute}, it redraws once a minute; the date beneath it redraws once a day.
When scripts run
Section titled “When scripts run”A script’s update(context) runs:
- When the widget appears: it’s turned on, Atsurae starts, or the widget’s files change
- On its schedule, set by
updateEvery:"minute"(the default): just after each new minute"second": every second- a number: every that many seconds, e.g.
300for every five minutes (at least1)
- When the battery, the playing song or the weather changes, so scripts can react to them right away
A script doesn’t run every time the CPU or memory figures refresh. Those are read on the script’s own schedule.
Choose the slowest schedule that looks right. A countdown in days only needs "minute", or even 3600. A seconds counter needs "second".
When nothing updates
Section titled “When nothing updates”To save energy, Atsurae pauses all data sources and scripts:
- while the displays are asleep
- while no widget is turned on (there’s no widget window at all then)
- when Atsurae’s wallpaper is turned off, e.g. after signing out
When the displays wake, everything refreshes at once, so widgets are correct immediately.
In Atsurae’s own window
Section titled “In Atsurae’s own window”While the Library or Customize Widgets is open, Atsurae runs the scripts of every widget, even ones that are turned off, so their previews are live. Previews also fill in example values for data that’s missing, like “Song Title” when nothing is playing, so you can see the whole layout. Those example values never appear on the desktop.
Changing files
Section titled “Changing files”Atsurae watches your widgets folder. When you save a file:
- The widget’s files are read and checked again (within about 0.3 seconds).
- Its fonts and images are reloaded.
- Its script starts fresh: global variables are reset, and
updateruns right away. - The desktop and every preview redraw.
