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 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§

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.