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 the reader uses (the font
DPI, dark mode, the icon theme, the accessibility preferences) stay cached
until the caches are cleared.
§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.