On this page

Text editing and IME

Every text field runs on one edit core, isolenui/ui/ui_edit.h. The kit fields wrap it for apps, and the app shell connects it to the platform input method on Windows and mac.

Input, a single line text field, drawn by isolenInput, a single line text field, drawn by isolen

Fields in the kit

text_box and search_box in isolenui/kit/controls.h edit a caller buffer of capacity bytes, terminator included. The label doubles as the hint drawn while the field is empty and unfocused. A focused field works on its own copy and writes it back when you press enter or when focus moves away, and the call returns true on that frame. Escape drops the copy and the focus, so the buffer keeps what it had. A field only writes back if you typed in it, so tabbing through never touches the buffer.

  • Focus from tab or from code selects the whole text, as native fields do. A press places the caret, a double click selects a word and a triple click a paragraph.
  • A field edits at most UI_EDIT_MAX (1023) bytes, or capacity less one when that is smaller. Text longer than that shows read only and is never cut.
  • text_box, search_box and field_ex also take a text_buf* in place of the buffer and capacity. That field has no limit: it edits a growable copy and writes it back on the same enter, blur or live edit. Unfocused, it paints the first 4096 bytes. See text buffers.
  • search_box adds a lens and, once it holds text, a clear mark. Pressing the mark empties the buffer and returns true.
  • The caret blinks while the field has focus. It asks for a frame at each blink edge with redraw_after, so an idle app wakes only when the caret flips instead of every frame.

field_ex and host lists

field_ex is the same field with flags and an optional field_out. It is how a combo style list keeps focus in the field while the list takes the arrows: keys named by the flags leave the editor's queue and land in out.keys in the order they arrived, each with its modifier bits in out.mods. While the input method is composing, every key stays with the field.

FlagEffect
field_up, field_downUp and down go to the host.
field_enter, field_escapeEnter and escape go to the host instead of submitting or cancelling.
field_home, field_endHome and end go to the host.
field_pagesPage up and page down go to the host.
field_hostedUp, down, enter, escape and the page keys together. Home and end stay with the editor.
field_searchDraws it as a search box.
field_liveEvery edit reaches the buffer as it is typed, not on enter or blur.
field_bareNo frame and no ring of its own. It keeps the ink and state steps of its look, for a group that paints the frame around it.
field_outMeaning
idThe field's element id.
focusedThe field holds the editor this frame.
ringFocused from the keyboard, when a group around a bare field shows its ring.
changedThe same value the call returns.
keys, mods, key_countThe keys handed to the host, up to UI_INPUT_QUEUE.
finder.cpp
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"

struct finder {
    char name[64] = "";
    char query[128] = "";
    uint32_t pick = 0;
    uint32_t count = 12;
};

static void form(ui::ctx* u, finder* s)
{
    // the label is also the hint shown while the field is empty
    if (ui::text_box(u, "project name", s->name, sizeof(s->name))) {
        // written back on enter or when focus moves away
    }

    // a host list keeps focus in the field and takes the arrows and enter
    ui::field_out out;
    ui::field_ex(u, "find a file", s->query, sizeof(s->query),
                 ui::field_hosted | ui::field_live | ui::field_search, &out);
    if (out.changed) {
        s->pick = 0; // the query changed as it was typed
    }
    for (uint32_t i = 0; i < out.key_count; ++i) {
        const uint32_t k = out.keys[i];
        if (k == ui::vk::down && s->pick + 1 < s->count) {
            ++s->pick;
        } else if (k == ui::vk::up && s->pick > 0) {
            --s->pick;
        } else if (k == ui::vk::enter) {
            // open the picked row here
        } else if (k == ui::vk::escape) {
            s->query[0] = '\0';
        }
    }
}

Keys

The core reads the platform's conventions. On mac the command key is the primary modifier, option moves by word and command moves by line or document. Elsewhere control is primary and moves by word.

KeyWindowsmac
Left, rightBy character, by word with ctrlBy character, by word with option, to the line end with cmd
Up, downBy row in a multiline fieldBy row in a multiline field, to either end otherwise, to the document end with cmd
Home, endLine start and end, document with ctrlScrolls to the top or bottom, selects to there with shift
Backspace, deleteBy character, by word with ctrl. Shift delete cuts.By character, by word with option, by line with cmd
A, C, X, Vctrl: select all, copy, cut, paste. Ctrl insert copies and shift insert pastes.cmd: the same
Z, Yctrl z undoes, ctrl y and ctrl shift z redocmd z undoes, cmd shift z redoes
EnterSubmits, or starts a new line in a multiline field. Primary enter always submits.
EscapeCancels.

Tab inside a field

A plain tab normally moves focus. Two pieces let a field keep it. ui::keep_tab, called right after the focused element is declared, makes the next frame hand a plain tab to that element instead of moving focus. Shift tab still leaves. The edit flag edit_tabs then types four spaces for a plain tab. A host that sets edit_tabs must also call keep_tab, otherwise the tab has already moved focus.

The edit core

ui::edit is one edit model over a caller buffer. Every text widget drives it and only it, and a component or a custom host can drive it directly. Over a caller buffer it uses no heap for the text or for undo. Its allocations are the line table, made once a second line exists, and the pen stops of long lines. A bound text_buf grows on the heap.

CallWhat it does
edit_init(e, buf, cap, flags)Binds the buffer. cap includes the terminator, and the buffer is kept terminated. The caret starts at the end.
edit_bind(e, text, flags)Binds a text_buf instead. Every insert, paste, undo and redo grows it, text.len follows each edit, and e.buf follows the text as it moves. See text buffers.
edit_rebind(e)The owner wrote the bound text itself. The editor points at it again and reloads it, dropping history, and returns true. It returns false when the text is unchanged in place, size and length.
edit_free(e)Frees the line table. The buffer and the history memory stay yours.
edit_history(e, mem, bytes)Undo lives in this memory only, from 4 to 1024 steps. The oldest steps fall off. Less than 256 bytes turns undo off.
edit_limit(e, max_bytes, max_chars)Caps on bytes and code points. Zero leaves one uncapped.
edit_filter(e, fn, user)Called per code point on every insert. False drops that code point.
edit_font, edit_viewThe face, size, tracking and line height to measure with, zero line height taking the font's, and the visible size. Lines are laid out again only when one of them changes.
edit_dir(e, d)The paragraph direction, a text_dir. Right to left lines sit against the right of the view. Left to right is the default, and the kit fields keep it.
edit_set_textReplaces everything, drops history and any preedit, caret at the end.
FlagEffect
edit_multilineEnter types a newline. Without it a pasted newline becomes a space.
edit_wrapLines wrap at the view width. Only with edit_multiline.
edit_read_onlySelection and copy still work, nothing changes the text.
edit_numericOnly digits, . , - + e E get in.
edit_tabsA plain tab types four spaces. See above.

Inserts replace the selection and apply the filter and both limits per code point. Control characters never get in, and a tab from a paste becomes a space. Typing of the same kind within a second of the last step merges into one undo step, and edit_seal ends the current step early.

Driving it

  • edit_apply(e, in, now) takes a whole ui::input frame: the input method commit, then chars and keys in queue order, then the preedit. This is what the kit fields call.
  • edit_feed takes chars and keys directly, with per key modifier bits or one held set for all of them. edit_key and edit_char take one of each. Feeding stops at a submit or cancel.
  • edit_press and edit_drag take the pointer in view space. Press counts clicks itself, and a drag past the edge scrolls.
  • edit_caret, edit_select, edit_select_all, edit_move, edit_insert, edit_erase, edit_undo and edit_redo do the same from code. Moves take an edit_unit: char, word, line, doc, row or page.

Every driving call returns edit_result bits: edit_changed when the text changed, edit_moved when the caret or selection moved, edit_submit for enter and edit_cancel for escape. The core never commits or leaves focus on its own. That is the host's call.

Clipboard

edit_copy, edit_cut and edit_paste go through isolenui/platform/clipboard.h. clipboard_set(utf8, len) puts UTF-8 text on the system clipboard. clipboard_get(out, cap) copies at most cap bytes and returns the full length, so a call with a null buffer sizes it first. Both run on the main thread only. Cut in a read only field copies.

share.cpp
#include "isolenui/platform/clipboard.h"
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"

#include <string.h>

// copy a readout, and paste a short code into a buffer the app owns
static void share_row(ui::ctx* u, const char* link, char* code, uint32_t cap)
{
    if (ui::button(u, "copy link")) {
        clipboard_set(link, uint32_t(strlen(link)));
    }
    if (ui::button(u, "paste code")) {
        // the full length comes back even when it did not fit
        const uint32_t n = clipboard_get(code, cap - 1u);
        code[n < cap - 1u ? n : cap - 1u] = '\0';
    }
}

Geometry and paint

All geometry is 26.6 fixed point, walked by edit_pen_walk, so the caret, hit tests and the painted glyphs land on the same bits. The model has no draw list dependency, and painting lives in its own unit.

  • edit_hit maps a content point to a byte. edit_pen gives the 26.6 pen of a byte in its line, and edit_line_of the line holding a byte.
  • edit_caret_box gives the caret in view space, which is what the candidate window hangs off.
  • edit_blink(e, now, &next) says whether the caret shows and how long until it flips.
  • Bidi text: once the direction is right to left, or the text holds anything that reorders, each line is walked in visual order, and the lines of one paragraph share a single bidi analysis. edit_visual(e, line) returns that walk as an edit_vis: per code point its left and right edges and level, the glyphs in visual order, the width, the right to left inset and the paragraph level. It is null while the text reads plain left to right, and valid until the next call. Left and right arrows then move the caret visually one character at a time, and a caret at a direction boundary remembers which side it belongs to, so it draws where the arrow or the click left it. Word and line moves stay logical, flipped in a right to left paragraph.
  • edit_paint draws the visible lines, the selection, the preedit underline and the caret with an edit_look: text, selection, caret and mark colours plus the caret width and height. edit_draw_run places a plain run on the same pens.
notes.cpp
#include "isolenui/ui/ui.h"
#include "isolenui/ui/ui_edit.h"

// a notes pane that drives the edit core itself
struct notes {
    char text[4096] = "";
    alignas(8) unsigned char history[16384];
    ui::edit ed{};
    bool ready = false;
    const ui::ctx* u = nullptr;
};

static bool no_digits(uint32_t cp, void* user)
{
    (void)user;
    return cp < '0' || cp > '9';
}

static void paint_notes(gfx_list* l, lay_box box, void* user)
{
    notes* n = static_cast<notes*>(user);
    const ui::theme* t = ui::theme_of(n->u);
    const ui::edit_look look = { t->text, t->accent_dim, t->accent, t->text, 1.6f, t->text_px };
    float next = -1.0f;
    const bool caret = ui::edit_blink(&n->ed, ui::input_of(n->u)->now, &next);
    const float base = box.y + text_font_ascent(ui::font_of(n->u), t->text_px);
    ui::edit_paint(&n->ed, l, ui::font_handle(n->u), box.x, box.y, base, look, caret);
}

static void notes_view(ui::ctx* u, notes* n)
{
    const ui::theme* t = ui::theme_of(u);
    if (!n->ready) {
        ui::edit_init(&n->ed, n->text, sizeof(n->text), ui::edit_multiline | ui::edit_wrap);
        ui::edit_history(&n->ed, n->history, sizeof(n->history));
        ui::edit_limit(&n->ed, 0u, 2000u);
        ui::edit_filter(&n->ed, no_digits, nullptr);
        n->ready = true;
    }
    n->u = u;

    const lay_box last = ui::rect_of(u, ui::next_id(u));
    ui::canvas(u, ui::col().width(lay_grow(1.0f)).height(240.0f), paint_notes, n);
    const ui::hit h = ui::interact(u);
    ui::focusable(u);

    const ui::input* in = ui::input_of(u);
    ui::edit_font(&n->ed, ui::font_of(u), t->face_ui, t->text_px, 0.0f, 0.0f);
    ui::edit_view(&n->ed, last.w, last.h);
    if (h.pressed) {
        ui::edit_press(&n->ed, in->mouse_x - last.x, in->mouse_y - last.y, in->now,
                       in->double_clicked, in->shift);
    } else if (h.held) {
        ui::edit_drag(&n->ed, in->mouse_x - last.x, in->mouse_y - last.y, ui::dt(u));
    }
    if (ui::focused(u, ui::last_id(u))) {
        const uint32_t r = ui::edit_apply(&n->ed, *in, in->now);
        if (r & ui::edit_cancel) {
            ui::focus(u, 0u);
        }
        // tell the host where the caret is so the ime hangs its window there
        float cx = 0.0f, cy = 0.0f, ch = 0.0f;
        ui::edit_caret_box(&n->ed, &cx, &cy, &ch);
        ui::text_input(u, lay_box{ last.x + cx, last.y + cy, 1.0f, ch });
        float next = -1.0f;
        ui::edit_blink(&n->ed, in->now, &next);
        ui::redraw_after(u, next);
    }
}
A host that drives the core must call ui::text_input each frame it holds focus, with the caret box. That is what turns the platform input method on and places its window. See the next section.

Input methods

The input method writes into the same frame input every field reads: commit is text committed this frame and preedit, with preedit_caret, is the live composition, all UTF-8. The preedit sits in the buffer marked and outside history until it commits. edit_preedit, edit_commit, edit_end_preedit and edit_drop_preedit are the core side.

Each frame the app shell reads ui::text_input_of. While a field wants typing it turns the platform text input on and passes the caret box in pixels. When focus moves to another field, the shell ends the old composition quietly first. A field that loses focus keeps its preedit as typed, and a cancel drops it.

Windows

Two text services sit behind one table and land in the same queues, so the edit core sees one preedit and one commit either way. The service starts the first time a field wants typing, not at boot.

imeService
0The measured default, which is TSF. Both cost about ten ms and one MB by the first composition, and TSF is several times cheaper per key and per focus change.
1IMM. The candidate window is only placed while composing, so an idle caret costs nothing.
2TSF. It only runs in a single threaded apartment. On a thread that is already multi threaded it logs and falls back to IMM.

Set it with isolen_app_desc::ime, or from the command line with --ime imm or --ime tsf. isolen_set_ime(app, mode) switches the service live. If a field is typing at that moment, the new service takes over with the caret where it was. The log names the service and how long it took to start.

mac

The view is an NSTextInputClient, and there is only one service, so ime and isolen_set_ime are ignored there. While a field has focus, keys go through the input method, and command and control chords skip it. Plain typing still arrives as chars. Anything the input method commits arrives as commit. A key it swallowed while composing never reaches the key queue.

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

static void view(isolen_frame* f, void* user)
{
    (void)user;
    static char name[64] = "";
    ui::text_box(f->ui, "name", name, sizeof(name));
    // switch the windows text service live, mac ignores it
    if (ui::button(f->ui, "use imm")) {
        isolen_set_ime(f->app, 1u);
    }
}

int main(int argc, char** argv)
{
    isolen_app_desc d = isolen_app_defaults();
    d.title = "ime";
    // 0 picks the measured default, 1 imm, 2 tsf, and --ime imm or tsf overrides it
    d.ime = 2u;
    d.view = view;
    return isolen_run(&d, argc, argv);
}

The frame loop is covered in the app shell and the widget list in text input.

Last updated 6 October 2026