Kit theme

use crownui::{
    kit::{provide_theme, use_theme, Theme},
    prelude::*,
};
 
fn main() -> Result<(), crownui::RunError> {
    crownui::run(
        component(|cx| {
            provide_theme(cx, Theme::light());
            component(|cx| {
                let theme = use_theme(cx);
                text("Hello")
                    .p(16.0)
                    .bg(bind(move |runtime| theme.with(runtime, |theme| theme.surface.raised)))
            })
        }),
        AppConfig::new("Hello").size(320, 200),
    )
}

pub fn provide_theme(cx: &mut Cx, theme: Theme) -> Signal<Theme>
pub fn provide_configured_theme(cx: &mut Cx) -> Signal<Theme>
pub fn use_theme(cx: &mut Cx) -> Signal<Theme>
pub fn panel_fill(theme: &Theme, opacity: f32) -> Color
pub fn panel_rim(theme: &Theme, opacity: f32) -> Color

Every kit widget reads its colors from the nearest provided Theme. These functions live in crownui::kit. provide_theme and provide_configured_theme put a theme in scope, use_theme reads it, and panel_fill and panel_rim derive the colors of a quick panel from it.

All three scope functions return a Signal<Theme>. Setting it restyles every kit widget that reads it, on the next frame.

provide_theme#

Provides theme to the current scope and everything built inside it.

let theme = provide_theme(cx, Theme::dark());
button("Light").on_click(move |cx, _| theme.set(cx, Theme::light()))

provide_configured_theme#

Provides the theme that ~/.config/crownos/appearance.ron and theme.ron describe, and keeps it following edits to either file while the calling component is mounted. The appearance picks the mode and the named accent. Then theme.ron replaces the accent if it sets one and edits individual slots for the current mode.

The first load happens on the calling thread. It reads both files and writes their defaults if they are missing. After that, the theme follows edits through one cx.spawn task per change.

use_theme#

Returns the nearest provided theme. When no theme is provided, it provides Theme::DEFAULT on the current scope and returns that.

let theme = use_theme(cx);
let border = bind(move |runtime| theme.with(runtime, |theme| theme.surface.border));

Theme#

Theme is the kit's complete palette, one Copy struct with every color a kit widget paints. Each field is a group of slots.

To change a few slots, spread a stock palette:

let base = Theme::dark();
provide_theme(
    cx,
    Theme {
        sidebar: SidebarColors { bg: rgb(0x16161c), ..base.sidebar },
        ..base
    },
);

Constructors and methods#

for_mode, with_stops, dark and light are const fn, so a theme can be a const.

use std::collections::BTreeMap;
 
const BLUE: GradientStops = GradientStops::new(rgb(0x5aa2ff), rgb(0x2563eb));
let overrides = BTreeMap::from([(String::from("surface.bg"), String::from("#101014"))]);
let theme = Theme::with_stops(ThemeMode::Dark, BLUE).with_overrides(&overrides);

ThemeMode#

GradientStops#

GradientStops holds the two stops of every accent surface as the public fields start (the lighter stop, toward the top or left) and end (the deeper stop).

Use vertical or horizontal to paint the accent in your own canvas:

let theme = use_theme(cx);
canvas(move |runtime, size, list| {
    let accent = theme.with(runtime, |theme| theme.accent);
    let bounds = Rect::new(Point::ZERO, size);
    list.fill(bounds, CornerRadii::uniform(12.0), accent.vertical(0.0, size.height));
})

Panel colors#

panel_fill(theme, opacity) returns the quick panel body, the theme's popover.bg at opacity. The compositor's blur shows through it. opacity is clamped to 0..=1.

panel_rim(theme, opacity) returns the hairline that keeps a translucent panel's edge off the wallpaper in both modes. It mixes the fill at opacity toward text.primary at a fixed alpha.

let theme = use_theme(cx);
vstack(rows)
    .rounded(16.0)
    .border(1.0)
    .bg(bind(move |runtime| theme.with(runtime, |theme| panel_fill(theme, 0.8))))
    .border_color(bind(move |runtime| theme.with(runtime, |theme| panel_rim(theme, 0.8))))

Why one theme value#

The kit keeps every color in one Copy struct behind one signal. A widget never holds its own color, so there is exactly one place to change the look of a window, and the desktop's settings reach every widget through it. The kit overview covers the tradeoffs in full.

Two details follow from that design. Each read through theme.with(..) subscribes the reader to the whole theme, not to one slot. Changing any slot wakes every reader, which is fine because themes change rarely. And Theme is plain data with PartialEq, so the kit's own tests build one with Theme::for_mode(..) for every accent and both modes and compare the rendered frames.