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.


In the galleryInputinputTextareatextarea
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, orcapacityless one when that is smaller. Text longer than that shows read only and is never cut. text_box,search_boxandfield_exalso take atext_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_boxadds 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.
| Flag | Effect |
|---|---|
field_up, field_down | Up and down go to the host. |
field_enter, field_escape | Enter and escape go to the host instead of submitting or cancelling. |
field_home, field_end | Home and end go to the host. |
field_pages | Page up and page down go to the host. |
field_hosted | Up, down, enter, escape and the page keys together. Home and end stay with the editor. |
field_search | Draws it as a search box. |
field_live | Every edit reaches the buffer as it is typed, not on enter or blur. |
field_bare | No 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_out | Meaning |
|---|---|
id | The field's element id. |
focused | The field holds the editor this frame. |
ring | Focused from the keyboard, when a group around a bare field shows its ring. |
changed | The same value the call returns. |
keys, mods, key_count | The keys handed to the host, up to UI_INPUT_QUEUE. |
#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.
| Key | Windows | mac |
|---|---|---|
| Left, right | By character, by word with ctrl | By character, by word with option, to the line end with cmd |
| Up, down | By row in a multiline field | By row in a multiline field, to either end otherwise, to the document end with cmd |
| Home, end | Line start and end, document with ctrl | Scrolls to the top or bottom, selects to there with shift |
| Backspace, delete | By character, by word with ctrl. Shift delete cuts. | By character, by word with option, by line with cmd |
| A, C, X, V | ctrl: select all, copy, cut, paste. Ctrl insert copies and shift insert pastes. | cmd: the same |
| Z, Y | ctrl z undoes, ctrl y and ctrl shift z redo | cmd z undoes, cmd shift z redoes |
| Enter | Submits, or starts a new line in a multiline field. Primary enter always submits. | |
| Escape | Cancels. | |
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.
| Call | What 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_view | The 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_text | Replaces everything, drops history and any preedit, caret at the end. |
| Flag | Effect |
|---|---|
edit_multiline | Enter types a newline. Without it a pasted newline becomes a space. |
edit_wrap | Lines wrap at the view width. Only with edit_multiline. |
edit_read_only | Selection and copy still work, nothing changes the text. |
edit_numeric | Only digits, . , - + e E get in. |
edit_tabs | A 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 wholeui::inputframe: the input method commit, then chars and keys in queue order, then the preedit. This is what the kit fields call.edit_feedtakes chars and keys directly, with per key modifier bits or oneheldset for all of them.edit_keyandedit_chartake one of each. Feeding stops at a submit or cancel.edit_pressandedit_dragtake 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_undoandedit_redodo the same from code. Moves take anedit_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.
#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_hitmaps a content point to a byte.edit_pengives the 26.6 pen of a byte in its line, andedit_line_ofthe line holding a byte.edit_caret_boxgives 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 anedit_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_paintdraws the visible lines, the selection, the preedit underline and the caret with anedit_look: text, selection, caret and mark colours plus the caret width and height.edit_draw_runplaces a plain run on the same pens.
#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);
}
}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.
ime | Service |
|---|---|
| 0 | The 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. |
| 1 | IMM. The candidate window is only placed while composing, so an idle caret costs nothing. |
| 2 | TSF. 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.
#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.