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::easevalue that has not reached its target. - A look whose state levels are still easing, see states and looks.
- An animated
scroll_toor a scroll settling onto asnapstep. - 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 call | What the shell does |
|---|---|
ui::redraw | Sees ui::busy and runs the next frame, the same as isolen_redraw. |
ui::redraw_after | Reads redraw_in after ui::end and passes it to isolen_redraw_after. An idle app sleeps in the platform event wait until then. |
| none | isolen_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.
#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);
}
}
}ui::keep_focus on its row so a press on its buttons leaves focus on the field the chars are meant for.