Skip to main content

Module watch

Module watch 

Source
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):

  1. 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.
  2. Channel disconnect – the shutdown channel sender is dropped, causing the receiver in the background thread to see Disconnected on its next recv() or try_recv().
  3. 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§

ThemeSubscription
RAII guard that keeps a theme watcher alive.

Enums§

ThemeChangeEvent
A signal that the OS theme has changed.

Functions§

on_theme_change
Start watching for OS theme changes.