On this page

Keyboard and input

ui::input is one frame of pointer, wheel, text and key input. ui::input_of returns the one the context was begun with.

What input carries

  • The pointer position, whether it is inside the window, and down, pressed, released and double click flags.
  • The wheel, wheel_x and wheel_y, already in logical units and signed the way the platform scrolls. wheel_precise means trackpad deltas rather than notches. The app shell sets it when a mac trackpad or smooth wheel sent any part of the frame's scroll, or on Windows when a wheel delta was not a whole notch, so lists and rollers can move by distance instead of by row. A trackpad moves one logical pixel per point everywhere: the shell turns its travel into wheel_x and wheel_y directly, and only mouse wheel notches are scaled by rows.
  • wheel_points_y, the same vertical trackpad travel as wheel_y in logical pixels, one per point under the fingers, and 0 when the platform only sends notches.
  • wheel_phase, what the trackpad gesture did this frame, as ui::pad bits: fingers 1 while the fingers move, lifted 2 when they lift, momentum 4 while the system coasts after a lift, and momentum_end 8 when that stops. It comes from the macOS event phases and from Windows Direct Manipulation, and stays 0 on a platform that cannot tell.
  • chars, the codepoints typed this frame, for text entry.
  • keys, the keys pressed this frame, as ui::vk numbers.
  • The ctrl, shift, alt and cmd modifiers.
  • context_pressed, a secondary click this frame: the right button, or control click on a mac.
  • right_down, the secondary button held, where a mac control click counts. A press or release of it asks for a frame, and on Windows the window keeps the pointer captured while it is down, so a right drag keeps reporting outside the window.
  • pinch, a trackpad pinch this frame as a scale step. Positive spreads the fingers. A pinch asks for a frame like the wheel does. It comes from a mac trackpad, and on Windows from a precision touchpad through Direct Manipulation. Under the shell a pinch zooms the page, so pinch stays 0 unless the element under it called take_pinch or the app set no_zoom. See pinch zoom.
  • key_mods, the modifiers held as each key landed, one byte per key: ctrl 1, shift 2, alt 4, cmd 8. Null applies the four flags above to every key.
  • now, monotonic wall seconds for the caret blink and click counting. Zero reads the clock.
  • commit and commit_len, IME text committed this frame, and preedit, preedit_len and preedit_caret, the live composition. Both are UTF-8. See text editing and IME.

The arrays are counted by char_count and key_count. UI_INPUT_QUEUE, 32, is how many keys focus routing reads in one frame, and how many keys ui::post_key can queue. Keys past it in one frame are dropped with a warning.

Sideways scrolling

wheel_x uses the same units and sign as wheel_y: a notch is the same distance, and a positive value moves toward the start. The app shell fills it from:

SourcePlatform
Trackpad swipes and sideways mouse scrolling, from the event's horizontal deltamacOS
Tilt wheels, from WM_MOUSEHWHEELWindows
Shift with the wheel, as every Windows app does. Shift with Ctrl stays a scale step.Windows

On a mac, a sideways delta with Ctrl held is ignored. Sideways input also sets wheel_precise the same way the vertical wheel does, and it wakes an idle app like any other input.

Who gets a key

A focused control takes the keys it claims before your app sees them. A slider takes the arrows, a text field takes typing and editing keys, and a button takes enter and space. What is left reaches ui::input as usual. While a blocking scope such as a modal is open, ui::captured is true, and app shortcuts should wait. See focus, scopes and modals.

ui::vk

The key numbers are the same on every platform, so one switch serves Windows and macOS. They follow the Windows virtual key values.

ConstantValueConstantValue
ui::vk::back0x08ui::vk::tab0x09
ui::vk::enter0x0dui::vk::escape0x1b
ui::vk::space0x20ui::vk::page_up0x21
ui::vk::page_down0x22ui::vk::end0x23
ui::vk::home0x24ui::vk::left0x25
ui::vk::up0x26ui::vk::right0x27
ui::vk::down0x28ui::vk::insert0x2d
ui::vk::del0x2eui::vk::f10x70
input_keys.cpp
#include "isolenui/ui/ui.h"

// input carries this frame's typed characters and key presses, the keys are
// the ui::vk numbers on every platform so one table serves windows and macos
struct slide_nav {
    uint32_t slide = 0;
    uint32_t count = 1;
    bool blank = false;
};

static void handle_keys(ui::ctx* u, slide_nav* nav)
{
    const ui::input* in = ui::input_of(u);
    for (uint32_t i = 0; i < in->key_count; ++i) {
        switch (in->keys[i]) {
        case ui::vk::right:
        case ui::vk::page_down:
        case ui::vk::space:
            nav->slide = nav->slide + 1 < nav->count ? nav->slide + 1 : nav->slide;
            break;
        case ui::vk::left:
        case ui::vk::page_up:
        case ui::vk::back:
            nav->slide = nav->slide ? nav->slide - 1 : 0;
            break;
        case ui::vk::home:
            nav->slide = 0;
            break;
        case ui::vk::end:
            nav->slide = nav->count - 1;
            break;
        case ui::vk::escape:
            nav->blank = !nav->blank;
            break;
        default:
            break;
        }
    }

    // ctrl on windows and cmd on macos arrive as separate flags
    const bool jump = (in->ctrl || in->cmd) && in->shift;
    ui::textf(u, ui::mono(u), "slide %u of %u%s, %u chars typed", nav->slide + 1,
              nav->count, jump ? ", jump held" : "", in->char_count);
}

// the wheel is already in logical pixels and signed the way the platform
// scrolls, precise means a trackpad rather than notches
static float wheel_zoom(const ui::input* in, float zoom)
{
    const float step = in->wheel_precise ? 0.002f : 0.1f / 40.0f;
    return (in->ctrl || in->cmd) ? zoom * (1.0f + in->wheel_y * step) : zoom;
}

Last updated 6 October 2026