On this page

Cursors

Each frame settles on one pointer shape, and the app shell hands it to the window. Most elements never ask: a field gets the text beam and a link the hand on their own. A part that needs another shape asks for it with ui::cursor.

Choosing a shape

  • cursor(u, shape) asks for a shape this frame. The last call in the frame wins.
  • With no call, the element under the pointer, or the one held, picks by its role when it calls interact: role_field gives the text beam, role_link the hand, and everything else the arrow. See states and looks for roles.
  • cursor_of(u) returns what the frame settled on. Read it after end.
editor.cpp
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"

struct sketch {
    float split;
    bool locked;
};

static void paint_board(gfx_list* l, lay_box b, void* user)
{
    (void)user;
    gfx_fill(l, b.x, b.y, b.w, b.h, 0xff1a1a1au);
}

static void editor(ui::ctx* u, sketch* s)
{
    ui_box(u, ui::row().width(lay_pct(1.0f)).height(lay_pct(1.0f)))
    {
        // a drawing surface shows the crosshair while the pointer is over it
        ui::canvas(u, ui::row().width(lay_px(s->split)).height(lay_pct(1.0f)), paint_board, s);
        if (ui::interact(u).hovered) {
            ui::cursor(u, ui::cursor_crosshair);
        }

        // a hand made grip, the last cursor call in the frame wins
        ui_box(u, ui::row().width(lay_px(6.0f)).height(lay_pct(1.0f)).bg("#333333")) {}
        const ui::hit h = ui::interact(u);
        if (h.hovered || h.held) {
            ui::cursor(u, s->locked ? ui::cursor_not_allowed : ui::cursor_resize_x);
        }
        if (h.held && !s->locked) {
            s->split = ui::input_of(u)->mouse_x;
        }

        // a text box needs no call, a field under the pointer picks the text beam
        static char name[64];
        ui::text_box(u, "name", name, sizeof(name));
    }
}

The shapes

cursor_shapeWindowsmacOS
cursor_arrowIDC_ARROWarrow
cursor_textIDC_IBEAMI beam
cursor_handIDC_HANDpointing hand
cursor_resize_xIDC_SIZEWEresize left right
cursor_resize_yIDC_SIZENSresize up down
cursor_moveIDC_SIZEALLopen hand, since macOS has no public four way cursor
cursor_crosshairIDC_CROSScrosshair
cursor_not_allowedIDC_NOoperation not allowed

cursor_count ends the list. A value past it is taken as the arrow.

What the kit sets

  • Text boxes, search boxes, field_ex, text areas, spin boxes, one time code cells and the roller are styled as fields, so they show the text beam.
  • A split grip asks for cursor_resize_x while hovered or held, or cursor_resize_y when the panes are stacked.
  • A data table asks for cursor_resize_x over a column edge it can resize, and while one is dragged.

Reaching the window

The shell calls window_set_cursor(win, window_cursor(cursor_of(u))) after every frame. The window side lives in isolenui/platform/window_cursor.h: window_cursor has the same values as cursor_shape, and window_cursor_name gives each one a name for the log.

  • The shape applies only over the app's own content. The frame edges keep the system's resize cursors, and another window over the same spot keeps its own.
  • A change is applied at once, so a pointer that has not moved still sees the new shape.
  • Windows loads each system cursor once and falls back to the arrow, with a warning, if one will not load. Both platforms log a change at trace level.
A host that drives ui::begin and ui::end itself reads cursor_of after end and sets its own window's cursor the same way.

Last updated 23 October 2026