ui::BackgroundBrush¶

Header: winui/ui/BackgroundBrush.hpp.

A control's Background: either a fixed color, a theme resource (ThemeColor), or nothing, plus the optional BrushTransition that animates every change of what is drawn.

The building block behind set_background() on Border, Grid, Panel, ForEach and the list views: the owning control stores one, calls resolve() from its render pass and advance() from its animation tick. A change is noticed in resolve(), the one place the theme is known, whether it came from set(), a new resource, or the same resource under a new theme, and the blend starts from the color on screen at that moment.

Example:

class Swatch final : public ui::Element
{
public:
    Swatch()
    {
        background_.set(ui::theme_colors::Background);
        background_.set_transition(ui::BrushTransition{.duration = 150ms});
    }
    void set_color(ui::Color color)
    {
        background_.set(color); // blends from the old color at the next render
        mark_dirty(ui::DirtyFlags::Visual);
    }

protected:
    ui::Size measure_override(ui::Size, const ui::MeasureContext&) const override
    {
        return ui::Size{40.0f, 40.0f};
    }
    void render_override(ui::Renderer& renderer, const ui::RenderContext& context) const override
    {
        if (const std::optional<ui::Color> fill = background_.resolve(context.theme))
        {
            renderer.fill_rounded_rect(bounds(), 0.0f, *fill);
        }
    }
    void tick_override(ui::Duration delta) override
    {
        if (background_.advance(delta)) // true while the blend runs
        {
            mark_dirty(ui::DirtyFlags::Visual);
        }
    }

private:
    ui::BackgroundBrush background_;
};

color¶

const std::optional<Color>& color() const

The fixed color; nullopt (a null brush) when there is none or a resource is set.

resource¶

ThemeColor resource() const

The theme resource, or nullptr when a fixed color (or nothing) is set.

set¶

void set(std::optional<Color> color)

Switches to a fixed color (nullopt: draw nothing) and clears any theme resource. The transition, if any, starts at the next resolve().

set¶

void set(Color color)

Switches to a fixed color and clears any theme resource.

set¶

void set(ThemeColor theme_color)

Switches to a theme resource, re-read on every resolve(), and clears any fixed color.

set¶

void set(const Paint& paint)

Switches to what paint holds: its color (a brush's flat color, see Paint), its resource, or nothing.

transition¶

const std::optional<BrushTransition>& transition() const

The blend between colors; nullopt (the default) makes every change immediate.

set_transition¶

void set_transition(std::optional<BrushTransition> transition)

Takes effect from the next change; a blend already running keeps going.

resolve¶

std::optional<Color> resolve(const Theme& theme) const

What to draw under theme now; nullopt draws nothing. A change since the last call starts the transition from the color that was on screen. Only color-to-color changes animate: a background appearing or disappearing is immediate.

advance¶

bool advance(Duration delta)

Advances a running transition by delta; true while it runs, so the owner keeps marking itself DirtyFlags::Visual. Call from the owner's tick_override().