Struct SystemTheme 

pub struct SystemTheme {
    pub name: String,
    pub is_dark: bool,
    pub light: ResolvedThemeVariant,
    pub dark: ResolvedThemeVariant,
    pub preset: String,
    /* private fields */
}

Result of the OS-first pipeline. Holds both resolved variants.

Produced by SystemTheme::from_system() and SystemTheme::from_system_async(). Both light and dark are always populated: the OS-active variant comes from the reader + preset + resolve, the inactive variant comes from the preset + resolve.

Fields

name: String

Theme name (from reader or preset).

is_dark: bool

Whether the OS is currently in dark mode.

light: ResolvedThemeVariant

Resolved light variant (always populated).

dark: ResolvedThemeVariant

Resolved dark variant (always populated).

preset: String

The platform preset used (e.g., “kde-breeze”, “adwaita”, “macos-sonoma”).

Implementations

impl SystemTheme

pub fn active(&self) -> &ResolvedThemeVariant

Returns the OS-active resolved variant.

If is_dark is true, returns &self.dark; otherwise &self.light.

pub fn pick(&self, is_dark: bool) -> &ResolvedThemeVariant

Pick a resolved variant by explicit preference.

pick(true) returns &self.dark, pick(false) returns &self.light.

pub fn with_overlay(&self, overlay: &ThemeSpec) -> Result<Self>

Apply an app-level TOML overlay and re-resolve.

Merges the overlay onto the pre-resolve ThemeVariant (not the already-resolved ResolvedThemeVariant) so that changed source fields propagate correctly through resolve(). For example, changing defaults.accent in the overlay will cause button.primary_background, checkbox.checked_background, slider.fill, etc. to be re-derived from the new accent color.

Examples

let system = native_theme::SystemTheme::from_system().unwrap();
let overlay = native_theme::ThemeSpec::from_toml(r##"
    [light.defaults]
    accent = "#ff6600"
    [dark.defaults]
    accent = "#ff6600"
"##).unwrap();
let customized = system.with_overlay(&overlay).unwrap();
// customized.active().defaults.accent is now #ff6600
// and all accent-derived fields are updated

pub fn with_overlay_toml(&self, toml: &str) -> Result<Self>

Apply an app overlay from a TOML string.

Parses the TOML as a ThemeSpec and calls with_overlay.

pub fn from_system() -> Result<Self>

Load the OS theme synchronously.

Detects the platform and desktop environment, reads the current theme settings, merges with a platform preset, and returns a fully resolved SystemTheme with both light and dark variants.

The return value goes through the full pipeline: reader output → resolve → validate → SystemTheme with both light and dark ResolvedThemeVariant variants.

Platform Behavior

• macOS: Calls from_macos() when the macos feature is enabled. Reads both light and dark variants via NSAppearance, merges with macos-sonoma preset.
• Linux (KDE): Calls from_kde() when XDG_CURRENT_DESKTOP contains “KDE” and the kde feature is enabled, merges with kde-breeze preset.
• Linux (other): Uses the adwaita preset. For live GNOME portal data, use from_system_async() (requires portal-tokio or portal-async-io feature).
• Windows: Calls from_windows() when the windows feature is enabled, merges with windows-11 preset.
• Other platforms: Returns Error::Unsupported.

Errors

• Error::Unsupported if the platform has no reader or the required feature is not enabled.
• Error::Unavailable if the platform reader cannot access theme data.

Examples

let system = native_theme::SystemTheme::from_system().unwrap();
let active = system.active();

pub async fn from_system_async() -> Result<Self>

Async version of from_system() that uses D-Bus portal backend detection to improve desktop environment heuristics on Linux.

When XDG_CURRENT_DESKTOP is unset or unrecognized, queries the D-Bus session bus for portal backend activatable names to determine whether KDE or GNOME portal is running, then dispatches to the appropriate reader.

Returns a SystemTheme with both resolved light and dark variants, same as from_system().

On non-Linux platforms, behaves identically to from_system().

Trait Implementations

impl Clone for SystemTheme

fn clone(&self) -> SystemTheme

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SystemTheme

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.