On this page

Interaction

The building blocks every widget is made of, available for your own boxes.

Tooltip, a hint that shows on hover, drawn by isolenTooltip, a hint that shows on hover, drawn by isolen

interact, tooltip, ease, focus and canvas

interact returns a ui::hit for the element just declared, always read against last frame's rectangle. It reports hovered, pressed, held, released, clicked and double clicked, plus the pointer position. tooltip attaches a tip to the same element, drawn over everything. It now lives in the kit's menus group, with tooltip_begin and tooltip_end for richer content. See overlays. focus and focused move and read keyboard focus by id.

ease(u, slot, target, rate) keeps a value per element and slot that moves toward the target each frame. While any value is still moving, ui::busy is true and the app keeps producing frames. canvas declares a box and calls your paint function during ui::end with the solved box and the list already clipped to it. That call comes after your view returns, so user must outlive the frame.

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

#include <math.h>

// a paint callback for canvas, drawn during end once the box is solved and
// clipped, well after this frame's function calls have returned, so user
// must point at state that outlives the frame, not a local
static void draw_wave(gfx_list* l, lay_box box, void* user)
{
    const float* phase = static_cast<const float*>(user);
    const float mid = box.y + box.h * 0.5f;
    float xy[64];
    for (uint32_t i = 0; i < 32; ++i) {
        const float t = float(i) / 31.0f;
        xy[i * 2 + 0] = box.x + t * box.w;
        xy[i * 2 + 1] = mid + 12.0f * sinf(t * 6.28f + *phase);
    }
    gfx_polyline(l, xy, 32u, 1.5f, 0.0f, 0xffe5648au, 0u);
}

// wave_phase is owned by the caller, a field on some state struct that
// already lives past this frame, never a local float passed by value
static void interactive_card(ui::ctx* u, float* wave_phase)
{
    ui_box(u, ui::col().pad(16.0f).round(10.0f).bg(0xff161616u))
    {
        // captured first, before interact, ease or tooltip might otherwise
        // read against whatever gets declared after them instead of this box
        const uint64_t card = ui::last_id(u);

        // interact and tooltip both read the element just declared, so
        // both come before textf declares a new one
        const ui::hit h = ui::interact(u);
        if (h.clicked) {
            ui::focus(u, card);
        }

        // ease, a value that eases toward a target, keyed by slot zero here
        const float lift = ui::ease(u, 0u, h.hovered ? 1.0f : 0.0f, 8.0f);
        ui::tooltip(u, "click to focus this card");
        ui::textf(u, ui::body(u), "lift %.2f", lift);

        // canvas, custom painting inside its own solved and clipped box
        ui::canvas(u, ui::col().grow().height(48.0f), draw_wave, wave_phase);
    }
}

shield

Anything you paint straight into isolen_frame::list is invisible to the tree. shield tells the tree that a rectangle is covered, so on the next frame the pointer and the wheel stop reaching whatever lies under it. Use it for popups and overlays drawn outside the tree. The draw list page covers the painting calls.

main.cpp
#include "isolenui/app/app.h"
#include "isolenui/kit/kit.h"

// a popup painted straight into the frame list is not part of the tree, so
// shield tells the tree it covers that rect and takes the pointer and the
// wheel from whatever lies under it on the next frame
static void draw(isolen_frame* f, void* user)
{
    bool* open = static_cast<bool*>(user);
    ui::ctx* u = f->ui;
    ui_box(u, ui::col().pad(24.0f).gap(12.0f))
    {
        if (ui::button(u, "show popup")) {
            *open = !*open;
        }
        ui::button(u, "covered by the popup");
    }

    if (*open) {
        const lay_box r = { 24.0f, 72.0f, 280.0f, 120.0f };
        gfx_list_layer(f->list, GFX_LAYERS - 1u);
        gfx_glass(f->list, r.x, r.y, r.w, r.h, 12.0f, 0.4f, 0xe0161616u);
        ui::shield(u, r);
    }
}

int main(int argc, char** argv)
{
    static bool open = false;
    isolen_app_desc d = isolen_app_defaults();
    d.view = draw;
    d.user = &open;
    return isolen_run(&d, argc, argv);
}

Last updated 6 October 2026