Text buffers
ui::text_buf in isolenui/ui/ui_text_buf.h is growable UTF-8 text. The text fields take it in place of a buffer and a capacity, so what you type has no length limit and your code never sizes a buffer.
The type
A text_buf holds data, len and cap, the bytes held including the terminator. The bytes live on the heap and are always terminated. It owns them: it frees them when it is destroyed, it moves but does not copy, and text_buf(utf8) makes one from a string.
c_str()is never null. An empty text reads as"".empty()is true whenlenis zero.- All zero memory is a valid empty text, so a zeroed struct or a store record can hold one as it is.
- The most one text holds is
k_text_buf_max, just under 2 GB.
Calls
| Call | Does |
|---|---|
text_buf_reserve(t, len) | Room for len bytes and the terminator. It grows to at least twice what it held, rounded to 64 bytes, so appends are amortised and a text that stops growing never allocates again. |
text_buf_set(t, utf8, len), text_buf_set(t, utf8) | Replaces the text. The source may point inside the text itself. |
text_buf_append(t, utf8, len), text_buf_append(t, utf8) | Adds to the end. The source may point inside the text itself. |
text_buf_format(t, fmt, ...) | Replaces the text, formatted as printf does. |
text_buf_clear(t) | Empties the text and keeps the memory. |
text_buf_free(t) | Frees the memory and leaves an empty text. |
text_buf_swap(a, b) | Swaps two texts without copying. |
text_buf_drop | A store drop for a record that starts with a text_buf. See the state store. |
The calls that can grow return false when the memory could not be had or the text would pass the most, and log it. The text keeps what it had, except text_buf_format, which leaves it empty. Growing past a megabyte logs the new size.
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"
#include "isolenui/ui/ui_text_buf.h"
#include <stdint.h>
// a text_buf owns its bytes on the heap and grows as it is written
struct note {
ui::text_buf title{ "untitled" };
ui::text_buf body;
uint32_t saves = 0;
};
static void build(note* n)
{
ui::text_buf_append(&n->body, "first line\n");
ui::text_buf_format(&n->title, "draft %u", n->saves + 1u);
// c_str never returns null, an empty text reads as ""
const char* shown = n->title.c_str();
(void)shown;
}
static void editor(ui::ctx* u, note* n)
{
// the growable overloads take the text itself, no capacity
if (ui::text_box(u, "title", &n->title)) {
++n->saves;
}
ui::search_box(u, "find in note", &n->body);
ui::textarea(u, "body", &n->body, ui::textarea_of().lines(6u, 20u));
}
// state kept in the store starts with the text, zeroed memory is an empty text
struct draft {
ui::text_buf text;
bool sent;
};
static void compose(ui::ctx* u)
{
const uint64_t id = ui::next_id(u);
bool fresh = false;
draft* d = static_cast<draft*>(
ui::store(u, id, sizeof(draft), ui::text_buf_drop, &fresh));
ui::field_ex(u, "message", &d->text, ui::field_live, nullptr);
}text_buf kept there must be freed by a drop. Pass text_buf_drop when the text is the first field, or free it in your own drop.Fields that take it
| Call | How it edits |
|---|---|
text_box(u, label, &text), search_box(u, label, &text) | A growable working copy, written back on Enter or when focus leaves, as the buffer versions do. There is no read only cut at UI_EDIT_MAX. |
field_ex(u, label, &text, flags, out) | The same, with the field flags. With field_live every edit reaches the text as it is typed. |
input_group(u, label, &text, lead, lead_count, trail, trail_count, flags, out) | The bare field inside the group frame. See forms. |
textarea(u, label, &text, spec), textarea_run(u, label, &text, spec) | The editor is bound to the text and edits it in place, so it grows as text is typed or pasted. |
A null text makes the field return false and draw nothing. While a single line field is not focused it paints only the first 4096 bytes of the text. The queries of comboboxes and command lists are text buffers too, so a query has no length limit either.
Binding the edit core
A custom host binds the edit core to a text with edit_bind(e, &text, flags). Inserts, pastes, undo and redo then grow it, and text.len follows every edit. The editor's buf and cap move with the text when it grows, so read them after an edit, not before.
If you write the text yourself, call edit_rebind(e). It points the editor at the text again and reloads it, dropping the history and any preedit, and returns true. It returns false and does nothing when the text still has the same address, capacity and length, so a same length rewrite in place needs edit_set_text instead.
#include "isolenui/ui/ui.h"
#include "isolenui/ui/ui_edit.h"
#include "isolenui/ui/ui_text_buf.h"
// a custom host binds the editor to a text_buf, so inserts grow it in place
struct log_view {
ui::edit ed;
ui::text_buf text;
bool bound;
};
static void open_view(log_view* v)
{
ui::text_buf_set(&v->text, "boot ok\n");
ui::edit_bind(&v->ed, &v->text, ui::edit_multiline);
v->bound = true;
}
static void on_input(log_view* v, const ui::input& in, double now)
{
// text.len and text.data follow every edit, the buffer may move as it grows
ui::edit_apply(&v->ed, in, now);
}
static void add_line(log_view* v, const char* line)
{
// the owner wrote the text itself, the editor points at it again and reloads
ui::text_buf_append(&v->text, line);
ui::edit_rebind(&v->ed);
}
static void close_view(log_view* v)
{
ui::edit_free(&v->ed);
ui::text_buf_free(&v->text);
}Long lines
The edit core keeps a pen stop about every kilobyte of every line: the byte, the pen position there and how far the line had reached. A key press, a click or a paint on a long line starts walking from the stop before the place it needs, and an edit lays out again only round itself. So typing into a line of megabytes costs about a kilobyte of work per key, and a paint asks the draw list only for the glyphs that can show.