Expand description
Runtime theme change watching.
Requires the watch feature.
This module provides the public API for monitoring OS theme changes at
runtime. Call on_theme_change() with a callback to start watching;
the returned ThemeSubscription keeps the watcher alive via RAII semantics
– dropping it stops the watcher and joins the background thread (macOS has
no watcher thread: dropping it removes the notification observer).
§RAII ownership model
ThemeSubscription is an RAII guard. Dropping it stops the watcher and
joins the background thread. You must bind it to a variable – if
you discard the return value, the watcher is dropped immediately and
no events are ever delivered.
§Shutdown mechanism
When a ThemeSubscription is dropped, shutdown proceeds in three phases
(on macOS only the first, which removes the observer):
- Platform-specific wakeup – where the backend has one, it runs
first (GNOME closes its D-Bus connection, Windows posts
WM_QUIT). This wakes the background thread’s event loop so it can observe the disconnect. - Channel disconnect – the shutdown channel sender is dropped,
causing the receiver in the background thread to see
Disconnectedon its nextrecv()ortry_recv(). - Thread join –
JoinHandle::join()blocks until the background thread exits, ensuring clean shutdown before the guard is gone.
§Signal-only events
ThemeChangeEvent carries no theme data. When you receive an event,
call detect::invalidate_caches(),
then re-run SystemTheme::from_system()
to get the updated theme: the detection values (dark mode, reduced
motion, the accessibility preferences, the icon theme and, on Linux, the
desktop) stay cached until the caches are cleared, and the OS read takes
its icon theme and desktop from them.
§Example
use std::sync::mpsc;
let (tx, rx) = mpsc::channel();
let _watcher = native_theme::watch::on_theme_change(move |event| {
let _ = tx.send(event);
})?;
// On your UI thread:
// if let Ok(event) = rx.try_recv() {
// native_theme::detect::invalidate_caches();
// let theme = native_theme::SystemTheme::from_system()?;
// // re-apply theme ...
// }Structs§
- Theme
Subscription - RAII guard that keeps a theme watcher alive.
Enums§
- Theme
Change Event - A signal that the OS theme has changed.
Functions§
- on_
theme_ change - Start watching for OS theme changes.