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: ColorModeThe OS color mode preference (light or dark).
light: ResolvedThemeResolved light variant (always populated).
dark: ResolvedThemeResolved dark variant (always populated).
preset: StringThe 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: IconSetWhich 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: LayoutThemeLayout 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: AccessibilityPreferencesOS-detected accessibility preferences (shared across variants).
Implementations§
Source§impl SystemTheme
impl SystemTheme
Sourcepub fn pick(&self, mode: ColorMode) -> &ResolvedTheme
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);Sourcepub fn icon_theme_for(&self, mode: ColorMode) -> Option<&str>
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.
Sourcepub fn icon<'a>(
&self,
id: impl Into<IconId<'a>>,
mode: ColorMode,
color: Option<Rgba>,
) -> Option<IconData>
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));Sourcepub fn icon_indicator(&self, mode: ColorMode) -> Option<AnimatedIcon>
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.
Sourcepub fn with_overlay(&self, overlay: &Theme) -> Result<Self>
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 updatedSourcepub fn from_system() -> Result<Self>
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
macosfeature, reads both light and dark variants via NSAppearance and merges them with the preset of the running version’s generation,macos-montereyon 12 to 15 andmacos-tahoeon 26 and later (version_matchreports macOS 27 asPresetOlder); the active mode comes fromdetect::detect_is_dark. - Linux: the async implementation handles portal D-Bus calls when
the
portalfeature 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-breezeon KDE,adwaitaelsewhere, aspipeline::platform_preset_namenames it), resolved in the light/dark modedetect::detect_is_darkreads. - Windows: with the
windowsfeature, reads the active variant and merges it with thewindows-11preset, the one Windows generation (version_matchreports Windows 10 asPresetNewer). - Other platforms: Returns
Error::PlatformUnsupported.
§Errors
Error::FeatureDisabledon macOS or Windows when themacos/windowsfeature is not enabled.Error::PlatformUnsupportedif the platform has no reader at all.Error::ReaderFailedif 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;Sourcepub async fn from_system_async() -> Result<Self>
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().
Sourcepub fn from_system_with_preset(preset: &str) -> Result<Self>
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::UnknownPresetfor a name that is not a generation of the running platform, and for any name on a platform without a generation table.Error::FeatureDisabledon macOS or Windows when themacos/windowsfeature is not enabled.Error::ReaderFailedif 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");Sourcepub async fn from_system_with_preset_async(preset: &str) -> Result<Self>
pub async fn from_system_with_preset_async(preset: &str) -> Result<Self>
Async version of
from_system_with_preset().