States and looks
Every element carries a set of interaction state bits, and any element can wear a look: a small table of colours per state. Once the frame is declared the core resolves each element's state, eases between the steps and paints the result, so a widget never works out its own hover or press colours.
State bits
ui::state has one bit per state, state_count (7) in all. A look applies its steps in this order, so a later bit wins where two steps set the same field.
| Bit | Set when |
|---|---|
state_hovered | The pointer is over an element that called interact. |
state_pressed | The pointer holds that element. |
state_focused | The element has keyboard focus. |
state_focus_visible | It is focused and was reached by the keyboard. Only then does a focus ring show. |
state_checked | The widget says so through set_state, for a ticked box or the chosen tab. |
state_open | The widget says so, for an open combo or disclosure. |
state_disabled | The element or any ancestor was declared with style::disable. |
A disabled element loses hovered, pressed, focused and focus visible. If it held focus the focus is dropped, interact returns an empty hit, and ui::focus refuses its id. Every element inside it is disabled too, and those without a look of their own fade through the plain look.
style::inert(on) does the same without the look: the element and everything inside it lose hover, press and focus and interact returns an empty hit, but no disabled step is blended in, so it paints as it was. state_of still reports state_disabled for it. Use it for a panel that is sliding away or covered by a fade, where a greyed look would flash. See styles for opacity, which pairs with it.
Looks
A look_step holds a fill, stroke, ink, stroke_w and opacity. Its sets field is a mask of look_field bits that says which of those it replaces; the others are left alone.
| look field | Meaning |
|---|---|
base | The step applied in full to every element wearing the look. |
on[state_count] | One step per state, indexed by bit number: hovered is 0, pressed 1, focused 2, focus visible 3, checked 4, open 5, disabled 6. |
ring, ring_w, ring_gap | The focus ring colour, width and gap. It fades in with the focus visible level and is drawn outside the box, even past a clipping edge. |
rate | How fast states ease in and out, per second. Zero snaps. |
Resolving starts from the element's own style fill, stroke and stroke width (and a text element's colour), applies base, then blends each state step in by how far that state has eased in. Levels run from 0 to 127. While any level is still moving the frame counts as busy, so the app keeps drawing until it settles. An element with a look keeps its levels in ease slots 1 and 2, so its own ui::ease calls should use slots 0 and 3.
Roles and the theme's looks
A ui::theme holds looks[role_count], one look per ui::role. theme_looks(t) builds them all from the palette in t, and ctx_create and set_theme call it for you unless own_looks is set. Every built look has a ring of the accent at 55 percent alpha, 2 px wide with a 2 px gap, a rate of 24 and a disabled step that drops opacity to 0.4.
| Group | Roles |
|---|---|
| Plain | role_none, only the ring and the disabled fade |
| Buttons | role_button, role_primary, role_flat, role_flat_danger, role_toggle |
| Choices | role_check, role_radio, role_switch, role_choice, role_tab, role_segment |
| Values | role_readout, role_slider, role_slider_fill, role_knob, role_drag, role_drag_fill, role_stepper |
| Text fields | role_field, role_lens, role_clear |
| Menus and lists | role_combo, role_menu_item, role_row, role_nav_item, role_header, role_disclosure |
| Pickers | role_day, role_swatch |
| Bubbles | role_bubble, role_bubble_muted, role_bubble_tint, role_bubble_outline, role_bubble_danger |
| Scrolling | role_scrollbar, role_grip |
| Links | role_link, ink between the accent and the dim text, the full accent on hover |
To change one role and keep the rest, call theme_looks on a copy, edit that look, set own_looks and pass the copy on. With own_looks set the context keeps every look exactly as given.
Wearing a look
style::as(role)wears the theme's look for that role.style::skinned(const look*)wears a look of your own. Only the pointer is kept, so the look must outlive the frame. A skin wins over a role.text_style::as(role)gives a text element the role's ink, and the text shows the state of its parent control.style::part()makes an element that is not interactive itself show the state of the nearest ancestor that calledinteract.mirror(u, id)makes the element just declared show the state of an element declared before it this frame.style::disable(on)disables the element and everything inside it.style::inert(on)takes input away from the element and everything inside it and keeps the look.
Hover and press only come from interact. A box with a role that never calls it shows focus, disabled and whatever set_state gives it.
#include "isolenui/ui/ui.h"
// a pickable row wearing the theme row look, the label follows the row
static bool pick_row(ui::ctx* u, const char* label, bool picked, bool locked)
{
bool clicked = false;
ui_box(u, ui::row().pad(12.0f, 8.0f).round(8.0f).as(ui::role_row).disable(locked))
{
// interact gives the row hover and press, set_state adds checked
clicked = ui::interact(u).clicked;
ui::set_state(u, ui::state_checked, picked);
ui::text(u, label, ui::body(u).as(ui::role_row));
}
return clicked;
}
// on is indexed by bit number, hovered is bit 0 and checked is bit 4
static ui::look g_pill;
static void build_pill(const ui::theme* t)
{
g_pill = t->looks[ui::role_button];
g_pill.base.fill = t->panel;
g_pill.on[4] = ui::look_step{ t->accent, 0u, t->bg, 0.0f, 1.0f,
ui::look_fill | ui::look_ink };
g_pill.rate = 12.0f;
}
static bool pill(ui::ctx* u, const char* label, bool on)
{
bool clicked = false;
ui_box(u, ui::row().pad(14.0f, 6.0f).round(14.0f).skinned(&g_pill))
{
clicked = ui::interact(u).clicked;
ui::focusable(u);
ui::set_state(u, ui::state_checked, on);
ui::text(u, label, ui::body(u).as(ui::role_button));
}
return clicked;
}Reading and setting state
state_of(u, id)gives the bits of the element just declared as they stand now, focus and disabled included. Any other id reads what it resolved to last frame, and 0 when it was not declared then.set_state(u, bits, on)turns bits on or off on the element just declared.set_state(u, id, bits, on)does it on one declared earlier this frame. Only hovered, pressed, checked and open can be set; focus and disabled belong to the core. A widget that hit tests painted parts itself uses this to take hover and press back off.shade_of_last(u)points at the resolved look of the element just declared. It is filled once the frame is solved, so keep the pointer and read it inside a canvas paint callback.resolve(look, state)resolves a look for a set of state bits with no easing.resolve(look, shade)uses the eased levels of a shade, so a painted part that is not an element moves in step with its control.
A shade holds the resolved fill, stroke, ink, ring, stroke_w, opacity, ring_w and ring_gap, plus the state bits and level[], how far each state has eased in out of 127.
#include "isolenui/ui/ui.h"
// paint runs inside end, so the payload lives past the frame
struct level_paint {
const ui::theme* t;
const ui::shade* sh;
float level;
};
static void paint_level(gfx_list* l, lay_box b, void* user)
{
const level_paint* p = static_cast<const level_paint*>(user);
// the bar eases with the same state levels as the box around it
const ui::shade bar = ui::resolve(p->t->looks[ui::role_slider_fill], *p->sh);
gfx_round(l, b.x + 4.0f, b.y + 4.0f, (b.w - 8.0f) * p->level, b.h - 8.0f, 4.0f, bar.ink);
}
static void level_meter(ui::ctx* u, level_paint* p, float level)
{
p->t = ui::theme_of(u);
p->level = level;
ui::canvas(u, ui::row().grow().height(24.0f).round(6.0f).as(ui::role_drag), paint_level, p);
ui::interact(u);
// filled once the frame is solved, read while the canvas paints
p->sh = ui::shade_of_last(u);
}Swapping the palette live
set_theme(u, t) copies the theme, rebuilds every look from the new palette unless own_looks is set, fills in scrim when it is zero, and asks for a frame. Nothing needs to be recreated. An app on the shell calls isolen_set_theme, which does the same for the app's context and repaints; see the app shell.
#include "isolenui/ui/ui.h"
// a light palette over the hud metrics, every look is rebuilt from it
static void use_light(ui::ctx* u)
{
ui::theme t = ui::theme_hud();
t.bg = ui::rgb("#f4f5f7");
t.panel = ui::rgb("#ffffff");
t.raised = ui::rgb("#e9ebef");
t.rule = ui::rgb("#d0d3d9");
t.track = ui::rgb("#dcdfe4");
t.text = ui::rgb("#191a1c");
t.text_soft = ui::rgb("#44464a");
t.text_dim = ui::rgb("#7d8085");
t.menu = ui::rgb("#ffffff");
ui::set_theme(u, &t);
}
// one role changed, the rest built from the palette
static void heavier_buttons(ui::ctx* u)
{
ui::theme t = *ui::theme_of(u);
ui::theme_looks(&t);
t.looks[ui::role_button].base.stroke_w = 2.0f;
t.own_looks = true;
ui::set_theme(u, &t);
}
// the state of another element as it resolved last frame
static bool menu_was_open(const ui::ctx* u, uint64_t trigger)
{
return (ui::state_of(u, trigger) & ui::state_open) != 0u;
}sunk, menu_hot and menu_pick that the built looks derive from, are on themes.