pub struct SystemTheme {
pub name: Cow<'static, str>,
pub mode: ColorMode,
pub light: ResolvedTheme,
pub dark: ResolvedTheme,
pub preset: String,
pub icon_set: IconSet,
pub icon_theme: Cow<'static, str>,
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 (from reader or preset).
§Ownership type — principled deviation from doc 2 §J.2 / §K.3
This field uses Cow<'static, str>, not Arc<str>. Doc 2 §J.2
(“B3 refinement: use Arc<str> for ReaderOutput::name”) and
§K.3 recommend uniform Arc<str> across name, icon_theme,
ReaderOutput::name, and ResolvedFontSpec::family. The audit in
docs/todo_v0.5.7_gaps.md §G9 (lines 449-506) concluded that the
uniform recommendation should be adopted ONLY for
ResolvedFontSpec::family
(where 26 widgets × connectors genuinely share font families), and
should be REVERSED for name / icon_theme because:
- Each resolved theme carries exactly ONE
name— no dedup benefit. - Bundled preset names are
&'static strliterals;Cow::Borrowed(static_lit)is zero allocation, zero refcount.Arc<str>would require at least one allocation per unique string at construction time, paying allocation cost for a dedup benefit that is structurally absent.
The same reasoning applies symmetrically to
SystemTheme::icon_theme,
Theme::name, and
ThemeDefaults::icon_theme.
See docs/todo_v0.5.7_gaps.md §G9 for the full audit.
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-sonoma”).
icon_set: IconSetWhich icon loading mechanism to use for this theme.
icon_theme: Cow<'static, str>The name of the visual icon theme (e.g. "breeze", "Adwaita").
§Ownership type
Cow<'static, str> is used here per the same principled deviation
documented on SystemTheme::name — see docs/todo_v0.5.7_gaps.md
§G9. Each resolved theme carries a single icon-theme name (KDE has
exactly two across light/dark variants — "breeze" / "breeze-dark";
other platforms have one), so the Arc<str> dedup benefit does not apply.
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 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.
§Examples
let system = native_theme::SystemTheme::from_system()?;
let overlay = native_theme::theme::Theme::from_toml(r##"
[light.defaults]
accent_color = "#ff6600"
[dark.defaults]
accent_color = "#ff6600"
"##)?;
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.
§Platform Behavior
- macOS: Calls
from_macos()when themacosfeature is enabled. Reads both light and dark variants via NSAppearance, merges withmacos-sonomapreset. - Linux: Uses
pollster::block_onto drive the async inner implementation, which handles portal D-Bus calls when theportalfeature is enabled. - Windows: Calls
from_windows()when thewindowsfeature is enabled, merges withwindows-11preset. - Other platforms: Returns
Error::PlatformUnsupported.
§Errors
Error::FeatureDisabledif the platform has a reader but the required feature 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().
Trait Implementations§
Source§impl Clone for SystemTheme
impl Clone for SystemTheme
Source§fn clone(&self) -> SystemTheme
fn clone(&self) -> SystemTheme
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more