Module theme

Theming for ltk-based applications.

A theme is a directory on disk holding a theme.json and any supporting assets (wallpapers, fonts, …). The JSON declares light and dark modes — each with its own slot table plus wallpaper, lockscreen, launcher and window-controls blocks — plus a shared fonts registry. The shell picks which mode is active via ThemeMode.

On-disk layout

/usr/share/ltk/themes/<id>/             (system overlay, lower priority)
~/.local/share/ltk/themes/<id>/         (user overlay,   higher priority)
    theme.json
    background-light.png
    background-dark.png
    fonts/
        Sora-Regular.ttf

Paths inside theme.json are interpreted relative to the theme’s directory and are eagerly resolved to absolute paths at load time.

Process-wide active state

The active theme is published process-wide so widgets can consult their colours without every caller threading the palette through their own state. Use set_active_document / set_active_mode to change it, and active_document / active_mode / active_theme_id to read it back. Per-slot shorthand accessors (color, paint(), surface(), palette(), …) cover the common patterns without going through the full document.

There is no in-code fallback: if ensure_active cannot locate the default theme in any search path, the process aborts with a message pointing at the ltk-theme-default Debian package (it Provides: ltk-theme) or at the LTK_THEMES_DIR environment variable for development installations.

Re-exports

• pub use paint::ColorStop;
• pub use paint::GradientSpace;
• pub use paint::LinearGradient;
• pub use paint::Paint;
• pub use paint::RadialGradient;
• pub use shadow::BlendMode;
• pub use shadow::InsetShadow;
• pub use shadow::Shadow;
• pub use shadow::ShadowsRef;
• pub use surface::Surface;
• pub use text_style::FontRef;
• pub use text_style::FontStyle;
• pub use text_style::LineHeight;
• pub use text_style::TextDecoration;
• pub use text_style::TextStyle;
• pub use text_style::TextTransform;
• pub use fonts::FontFamilyDef;
• pub use fonts::FontSource;
• pub use font_registry::FontKey;
• pub use font_registry::FontLoadError;
• pub use font_registry::FontRegistry;
• pub use slots::Metadata;
• pub use slots::Slot;
• pub use slots::SlotStore;
• pub use document::Mode;
• pub use document::ThemeDocument;
• pub use accessors::color;
• pub use accessors::color_or;
• pub use accessors::paint;
• pub use accessors::palette;
• pub use accessors::resolve_surface;
• pub use accessors::shadows;
• pub use accessors::surface;
• pub use accessors::text_style;
• pub use accessors::window_controls;
• pub use active::active_document;
• pub use active::active_mode;
• pub use active::active_theme_id;
• pub use active::is_fallback_active;
• pub use active::set_active_document;
• pub use active::set_active_mode;
• pub use assets::app_default_icon;
• pub use assets::app_icon;
• pub use assets::branding_asset;
• pub use assets::branding_image;
• pub use assets::branding_raster;
• pub use assets::decode_svg_bytes;
• pub use assets::icon_path;
• pub use assets::icon_rgba;
• pub use assets::launcher_icon;
• pub use assets::lockscreen;
• pub use assets::logo;
• pub use assets::logo_horizontal;
• pub use assets::logo_square;
• pub use assets::tint_symbolic;
• pub use assets::wallpaper;
• pub use error::ThemeError;
• pub use palette::Palette;
• pub use prefs::LauncherSpec;
• pub use prefs::ThemeMode;
• pub use prefs::ThemePreference;
• pub use prefs::WallpaperFit;
• pub use prefs::WallpaperSpec;
• pub use prefs::WindowControlsSpec;
• pub use search::build_font_registry;
• pub use search::search_paths;

Modules

• accessors
  Slot-typed shorthand accessors against the active theme document.
• active
  Process-wide active theme state.
• assets
  Theme asset resolution: wallpapers, lockscreens, branding logos, app icons, launcher icon, and the SVG rasterisation pipeline (with process-wide cache) that the canvas consumes.
• document
  The top-level theme document: metadata, fonts block and per-mode slots.
• error
  Error type returned by theme loading and parsing.
• font_registry
  Runtime font registry: families → (weight, style) → fontdue::Font.
• fonts
  Font family definitions as declared by the theme document.
• gradient_lut
  CPU-side gradient sampling and LUT baking.
• paint
  Paint primitives: the “what do we fill a shape with” side of theming.
• palette
  The eight-slot semantic Palette every widget speaks in terms of, plus the derived WindowControlsSpec fallback used when a theme document omits the explicit window_controls block.
• prefs
  Theme preference / mode types and per-asset specification structs.
• search
  Theme directory search paths and the font-registry builder that walks the active document’s font block.
• shadow
  Shadow primitives: outer drop shadows, inner inset shadows, and the blend modes used to composite them.
• slots
  The slot-typed lookup table that backs the new theme API.
• surface
  Composite surfaces: fill + outer shadows + inset shadows.
• text_style
  Typography tokens: a resolved text style (family + weight + size + …) as the theme knows it.
• typography
  Typography scale used by the default theme.