Skip to main content

SystemTheme

Struct SystemTheme 

Source
pub struct SystemTheme {
    pub name: Cow<'static, str>,
    pub mode: ColorMode,
    pub light: ResolvedTheme,
    pub dark: ResolvedTheme,
    pub preset: String,
    pub version_match: Option<VersionMatch>,
    pub icon_set: IconSet,
    pub icon_theme: Option<Cow<'static, str>>,
    pub layout: LayoutTheme,
    pub accessibility: AccessibilityPreferences,
    /* private fields */
}
Expand description

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: Cow<'static, str>

Theme name: the reader’s (the KDE colour scheme’s, such as "BreezeDark", or "GNOME", "macOS", "Windows"), or the preset’s where no reader ran.

§mode: ColorMode

The OS color mode preference (light or dark).

§light: ResolvedTheme

Resolved light variant (always populated).

§dark: ResolvedTheme

Resolved dark variant (always populated).

§preset: String

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

§version_match: Option<VersionMatch>

How the running OS version relates to the generation of preset: None where the platform has no generation table (Linux, whose readers read the installed style) or no reader ran. On macOS 27 under macos-tahoe, which no preset of its own covers yet, it is Some(VersionMatch::PresetOlder); on Windows 10 under windows-11, Some(VersionMatch::PresetNewer). Early macOS 26 betas reported version 16 to a binary built against the macOS 15 SDK; a major version 16 gets macos-monterey with Some(VersionMatch::PresetOlder) (sources in the macOS generation table, pipeline.rs).

§icon_set: IconSet

Which icon loading mechanism to use for this theme.

§icon_theme: Option<Cow<'static, str>>

The name of the visual icon theme (e.g. "breeze", "Adwaita"): the active variant’s, else the theme’s, else the detected system icon theme. None where the theme states none and detection fails; system_icon_theme() gives the reason.

§layout: LayoutTheme

Layout spacing shared by both variants: the platform reader’s values merged field-wise over the preset’s, the same precedence the pipeline uses for colours. None in a field means neither the platform nor the preset specifies it (platform-facts §2.20); nothing is invented.

§accessibility: AccessibilityPreferences

OS-detected accessibility preferences (shared across variants).

Implementations§

Source§

impl SystemTheme

Source

pub fn pick(&self, mode: ColorMode) -> &ResolvedTheme

Pick a resolved variant by color mode.

§Examples
use native_theme::theme::ColorMode;

let sys = native_theme::SystemTheme::from_system()?;
let dark = sys.pick(ColorMode::Dark);
let active = sys.pick(sys.mode);
Source

pub fn icon_theme_for(&self, mode: ColorMode) -> Option<&str>

The icon-theme name for one colour mode, resolved for that mode’s variant by the same three tiers as icon_theme (its defaults.icon_theme, then the theme’s, then the detected system theme); for the mode the theme was built in it equals icon_theme as built. KDE names one theme per variant (breeze, breeze-dark); a toolkit that keeps a style per colour scheme needs both. None where that variant states none and detection failed; nothing is invented.

Source

pub fn icon<'a>( &self, id: impl Into<IconId<'a>>, mode: ColorMode, color: Option<Rgba>, ) -> Option<IconData>

Load an icon from this theme’s icon_set, in color, for one colour mode’s variant: a freedesktop icon comes from that variant’s theme, icon_theme_for(mode) (breeze or breeze-dark under kde-breeze), so an application can draw the variant that is not the OS’s.

color is honoured as in load_custom_icon: an SF Symbol or a Segoe glyph loads in it, and a Material or Lucide SVG (or a provider’s own SVG) is coloured through colorize_monochrome_svg. A freedesktop icon takes it where it has a foreground left to the caller: a symbolic icon’s placeholders (FreedesktopLoader::color) and a currentColor the document sets no color for (fill_current_color). An icon whose own stylesheet sets the color its currentColor takes (Breeze’s current-color-scheme) keeps that colour, as it is not yet rewritten from the theme as KDE’s own icon loader does, and a full-colour icon keeps its palette. None leaves each icon in the colour it loads in. A system set’s icon loads at its loader’s default size (a freedesktop icon looked up at 24 pixels, an SF Symbol at 24 points, a Segoe glyph at 32 pixels); load_custom_icon takes a size.

None where the set has no such icon, or without the set’s feature (see the loaders in icons).

§Examples
use native_theme::icons::IconRole;

let sys = native_theme::SystemTheme::from_system()?;
let fg = sys.pick(sys.mode).defaults.text_color;
let _icon = sys.icon(IconRole::ActionCopy, sys.mode, Some(fg));
Source

pub fn icon_indicator(&self, mode: ColorMode) -> Option<AnimatedIcon>

Load this theme’s icon_set animated loading indicator for one colour mode’s variant: a freedesktop spinner comes from icon_theme_for(mode), as in icon. See load_icon_indicator.

Source

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

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

Merges the overlay onto the pre-resolve ThemeMode (not the already-resolved ResolvedTheme) so that changed source fields propagate correctly through resolve(). For example, changing defaults.accent_color in the overlay will cause button.primary_background, checkbox.checked_background, slider.fill, etc. to be re-derived from the new accent color where the theme does not state them: windows-11 states its accent fills, button.primary_background among them, and those keep their values.

Overlays stack: each call applies its overlay over the ones applied before it, so sys.with_overlay(&a)?.with_overlay(&b)? keeps what a states unless b states it too.

The overlay’s icon_set, icon_theme and [layout] apply too, by the precedence from_system() uses: a variant’s defaults.icon_theme, then the theme’s icon_theme, then the detected one. So an overlay’s top-level icon_theme loses to a variant’s own, such as the KDE reader’s breeze and breeze-dark; to replace those, state [light.defaults] icon_theme and [dark.defaults] icon_theme.

The result’s light, dark, layout, icon_set and icon_theme (with icon_theme_for’s per-variant names) are rebuilt from the theme’s sources and the overlays, not copied from self, so a change the caller made to one of those public fields is lost. name, mode, preset, version_match and accessibility are kept from self.

§Errors

Returns Error::ResolutionInvalid when a value the overlay states, or one that inherits it, is out of range. Each path is the TOML key, as Error::ResolutionIncomplete describes: a variant’s value under its variant table (light.button.min_height_px), a [layout] value with no variant (layout.widget_gap_px).

§Examples

An overlay is a theme file that states only what it changes; it needs no name:

let overlay = native_theme::Theme::from_toml(r##"
    [light.defaults]
    accent_color = "#ff6600"
    [dark.defaults]
    accent_color = "#ff6600"
"##)?;

Then apply it to the live OS theme:

let system = native_theme::SystemTheme::from_system()?;
let customized = system.with_overlay(&overlay)?;
// customized.pick(customized.mode).defaults.accent_color is now #ff6600
// and all accent-derived fields are updated
Source

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 ResolvedTheme variants.

On every platform pollster::block_on drives the async implementation that from_system_async awaits.

§Platform Behavior
  • macOS: with the macos feature, reads both light and dark variants via NSAppearance and merges them with the preset of the running version’s generation, macos-monterey on 12 to 15 and macos-tahoe on 26 and later (version_match reports macOS 27 as PresetOlder); the active mode comes from detect::detect_is_dark.
  • Linux: the async implementation handles portal D-Bus calls when the portal feature is enabled. Without a reader for the detected desktop (feature disabled, or a desktop with no reader), returns the desktop’s platform preset with no live reading (kde-breeze on KDE, adwaita elsewhere, as pipeline::platform_preset_name names it), resolved in the light/dark mode detect::detect_is_dark reads.
  • Windows: with the windows feature, reads the active variant and merges it with the windows-11 preset, the one Windows generation (version_match reports Windows 10 as PresetNewer).
  • Other platforms: Returns Error::PlatformUnsupported.
§Errors
  • Error::FeatureDisabled on macOS or Windows when the macos / windows feature is not enabled.
  • Error::PlatformUnsupported if the platform has no reader at all.
  • Error::ReaderFailed if the platform reader cannot access theme data.
§Examples
let sys = native_theme::SystemTheme::from_system()?;
let theme = sys.pick(sys.mode);
// Icon set and theme are on SystemTheme, shared across variants
let _icon_set = sys.icon_set;
let _icon_theme = &sys.icon_theme;
Source

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

Async version of from_system().

On Linux, this enables portal D-Bus calls (e.g. GNOME settings portal, KDE portal backend detection) via .await. On macOS and Windows, the future completes immediately – no actual async operations occur.

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

Source

pub fn from_system_with_preset(preset: &str) -> Result<Self>

Load the OS theme over a chosen generation’s preset: the platform reader runs as in from_system(), and its values merge over preset instead of the running version’s generation.

preset must be a generation of the running platform: macos-monterey or macos-tahoe on macOS, windows-11 on Windows. Any other name, and any name on a platform without a generation table (Linux, whose readers read the installed style, BSD and other platforms), is Error::UnknownPreset, where from_system() may return Error::PlatformUnsupported (BSD and other platforms).

The result is a hybrid, not the older OS’s look: the chosen generation’s geometry and design colours under the running OS’s colours, fonts and accessibility settings, which the reader reads live (on macOS 26 with macos-monterey, NSColor gives macOS 26’s colours). version_match reports the chosen generation against the running OS: PresetOlder for an older one, PresetNewer for a newer one.

§Errors
  • Error::UnknownPreset for a name that is not a generation of the running platform, and for any name on a platform without a generation table.
  • Error::FeatureDisabled on macOS or Windows when the macos / windows feature is not enabled.
  • Error::ReaderFailed if the platform reader cannot access theme data.
§Examples
// Keep the Monterey-to-Sequoia look on a Mac running macOS 26.
let sys = native_theme::SystemTheme::from_system_with_preset("macos-monterey")?;
assert_eq!(sys.preset, "macos-monterey");
Source

pub async fn from_system_with_preset_async(preset: &str) -> Result<Self>

Async version of from_system_with_preset().

Trait Implementations§

Source§

impl Clone for SystemTheme

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for SystemTheme

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more