On this page

Redraw and wake ups

A frame only runs when something could have changed. These calls are how a widget or a view says that something will change with no input the core can see. The shell side is described in frames on demand.

busy

ui::busy(u) is true when this frame or the one before asked for more, or while the pointer holds an element. The app shell checks it when it decides whether to run a frame. These all ask:

  • ui::redraw.
  • A ui::ease value that has not reached its target.
  • A look whose state levels are still easing, see states and looks.
  • An animated scroll_to or a scroll settling onto a snap step.
  • Posted input and a set_theme.

The clock and dt

ui::clock(u) and ui::dt(u) return the time and step the frame was begun with. Under the app shell the clock is wall seconds since the app opened, so it keeps real time across idle gaps: a timer that compares against it still fires on time after the app slept. dt is the seconds since the last frame, held to at most a quarter second so eased values never leap after a gap.isolen_frame::time is the same clock.

redraw and redraw_after

redraw(u) asks for one more frame. Anything that animates on its own, such as a canvas driven by the clock, calls it every frame it moves.

redraw_after(u, seconds) asks for a frame once that much time has passed, even if nothing else asks. The earliest ask in a frame wins, and the ask is cleared at every begin, so ask again in each frame that still needs it. redraw_in(u) returns the earliest ask, or a value below zero when there is none. The caret blink and a trackpad scroll settling onto its snap step both use it, which is why a focused field does not keep the app drawing between blinks.

ui callWhat the shell does
ui::redrawSees ui::busy and runs the next frame, the same as isolen_redraw.
ui::redraw_afterReads redraw_in after ui::end and passes it to isolen_redraw_after. An idle app sleeps in the platform event wait until then.
noneisolen_wake is the one call that is safe from another thread. The ui calls are main thread only.

A host that drives ui::ctx without the shell reads ui::busy and redraw_in after ui::end and schedules its next frame from them.

Text input for the IME

text_input(u, caret) is what a focused text field calls each frame, with its caret box in logical units. text_input_of(u, &caret) says whether any field asked this frame and where its caret is. The ask is cleared at every begin. The shell turns the platform text input on while a field asks, places the candidate window at the caret, and ends a composition quietly when focus moves to another field. The kit's text fields already call it; only a field of your own needs to.

Posting input

post_chars(u, chars, n) and post_key(u, vk, mods) queue typed input that is merged ahead of the next frame's real input, so the focused field takes it through the same key path as the keyboard. mods uses the same bits as ui::input::key_mods: ctrl 1, shift 2, alt 4 and cmd 8. The queue holds 64 chars and UI_INPUT_QUEUE (32) keys; anything past that is dropped with a warning. Posting also asks for a frame.

core_redraw.cpp
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"

// a countdown that ticks once a second without keeping the app awake
static void countdown(ui::ctx* u, double ends_at)
{
    const double left = ends_at - double(ui::clock(u));
    if (left > 0.0) {
        const double whole = double(int64_t(left));
        ui::redraw_after(u, float(left - whole) + 0.001f);
        ui::textf(u, ui::head(u), "%d", int(whole) + 1);
    } else {
        ui::text(u, "go", ui::head(u));
    }
}

// a canvas that animates on its own has to ask for every frame
static void spinner(ui::ctx* u, ui::paint_fn paint, void* user)
{
    ui::canvas(u, ui::row().width(24.0f).height(24.0f), paint, user);
    ui::redraw(u);
}

// an on screen keypad types into whichever field has focus
static void keypad(ui::ctx* u)
{
    ui_box(u, ui::row().gap(4.0f))
    {
        // a press in here leaves focus on the field
        ui::keep_focus(u);
        static const char* const digits[] = { "1", "2", "3" };
        for (uint32_t i = 0; i < 3u; ++i) {
            ui::key(u, uint64_t(i + 1u));
            if (ui::button(u, digits[i])) {
                const uint32_t cp = uint32_t('1' + i);
                ui::post_chars(u, &cp, 1u);
            }
        }
        if (ui::button(u, "del")) {
            ui::post_key(u, ui::vk::back);
        }
    }
}
The keypad calls ui::keep_focus on its row so a press on its buttons leaves focus on the field the chars are meant for.

Last updated 6 October 2026