dymokomi/luce-ui
Source of release 0.19.0
0.19.0 / docs / TEXT-EDITOR.md
# Text controls
`TextEditor(text)` is an editable monospace widget. It owns Unicode scalar storage,
a selection, bounded undo/redo history, viewport offsets and optional colored
ranges. `read_only = true` provides a selectable output or document viewer.
`Highlight(start, end, color)` uses half-open scalar offsets. Supply ordered,
non-overlapping ranges to `set_highlights`; language analysis belongs to the app.
`on_change` fires after a document edit. Applications register Save, Build and
Run with `Application.set_commands`; the editor never opens files or launches
processes. `version()` changes when its content changes.
Native committed Unicode enters through standard `window`/`input`; keyboard
shortcuts stay physical key events. Editing supports selection, dragging,
clipboard, undo/redo, word and line navigation, indentation, auto-indented newlines
and scrolling. Control-Tab moves focus out; ordinary Tab indents. `line()` and
`column()` are one-based. Selection and highlight offsets are zero-based.
`ListView(items)` supplies scrollable single selection with keyboard navigation,
`select`, `set_items` and an `on_activate(index)` signal. Entries are
`ListItem(text, icon=IconKind.blank)` values; labels are copied when assigned,
and their icons do not alter indices or activation. It paints visible rows.
Applications choose symbols; filesystem and file-type policy stay outside UI.
`Application.focus(layout)` applies focus after the next arrangement, allowing
callbacks to replace a pane then focus its new child. `set_close_handler` installs
a Boolean callback that can keep unsaved work open. `set_error_handler` reports
recoverable input failures inside the app. These retained callbacks participate
in the same cycle collection as other native and Luce objects.
`Font` renders native antialiased text. Columns count monospace cells: a wide
East Asian scalar takes two, a combining mark none, a tab runs to the next stop of
four. `column()` reports cells, clicks land on the nearest scalar boundary, and soft
wrap moves a wide scalar that would cross the edge to the next row. Shaping, bidirectional layout,
grapheme-aware caret movement, accessibility, inline IME preedit and candidate
positioning need separate work. History is limited to 128 edits and 16 MiB of
changed ranges; documents support up to 1,048,576 scalars.
## Incremental decorations
`change()` returns `TextChange(start, old_end, new_end, version)` for the last
committed replacement. All offsets count Unicode scalars. `old_end` belongs to
the preceding version and `new_end` to the new one. Load, insert, undo, redo and
native input follow the same contract. Empty insertions do not advance version
or emit a change. Selection changes do neither.
The widget transforms existing highlights into the new coordinate space before
emitting `on_change`. Unaffected colors remain available even if a language
service delays or fails. `text_range(start, end)` reads only a needed interval;
`line_start(offset)` and `line_end(offset)` find the surrounding line boundaries.
The latter excludes the newline. `highlight_at(offset)` inspects a decoration.
`update_highlights(start, end, spans, version)` replaces one interval atomically,
retaining outside decorations. Spans use absolute scalar offsets and must be
ordered and disjoint inside that interval. An obsolete version returns false
without changing the set. Invalid ranges and allocation failure leave the
previous set intact. `set_highlights` replaces the entire set at the current
version. Both APIs allow at most 131072 spans.
A language service should cache outgoing line state, begin at the changed line,
and continue until its state agrees with an unchanged suffix. luced demonstrates
this for Luce's multiline strings, keeping token categories separate from their
colors. Revision checks make the same publication API usable by a future worker.
The current document and decoration arrays still move suffix storage after edits;
incremental tokenization is not a rope or an asynchronous language server.
## Folding and viewport bounds
`set_folds(ranges, version)` accepts up to 65536 language-neutral
`FoldRange(start, end)` values in zero-based Unicode scalar offsets. The start
names a header line; its following lines are hidden when collapsed. The end is
the start of the first line outside the fold, or the document's length. Headers
must be distinct and increasing; ranges may nest or be disjoint, but cannot
cross or end halfway through a line. Every range must hide at least one line.
Obsolete versions return false before validation. Invalid ranges and allocation
failure preserve the previous range set.
`set_folded(line, collapsed)` and `toggle_fold(line)` use one-based physical line
numbers. They return false when that line has no fold. `is_folded(line)` reports
the state. `fold_all()` and `unfold_all()` operate on the full set, including
nested folds; `visible_line_count()` reports the resulting rows. Click `−` or `+`
in the gutter to toggle a header. A collapsed header also displays an ellipsis.
The application supplies menu actions and shortcuts.
Folding changes neither source text, document revision, nor undo history. Nested
collapse state survives toggling its parent. Edits transform fold coordinates;
editing a header invalidates that fold until analysis publishes another set.
Unrelated edits preserve collapse state. A caret inside newly hidden text moves
to its visible header. Navigation skips hidden rows, while explicitly selecting
a hidden caret offset reveals its enclosing folds. Delete/Backspace at a folded
boundary expands it first. Explicit selections spanning folded text still include
that text for copying and replacement.
Painting, hit testing, navigation and scroll limits use one shared line
projection. Line metadata is updated from the changed text interval; unchanged
suffix entries move with the edit. Folding rebuilds visible row indices without
rereading source. Metadata arrays still take linear time to copy or traverse.
Scroll events describe content displacement, so viewport offsets subtract both
axes. Both offsets clamp to visible content after edits, folding and resizing.
Horizontal extent includes tab expansion, the longest visible line and room for
the caret; vertical extent uses visible rows. `scroll_offset()` returns the
clamped offsets as `Size(width=x, height=y)`. The output viewer uses this same
behavior through `read_only=true`.
## Soft wrap
`set_wrap(enabled)` toggles soft wrap; `wrapping()` reports it. `TextEditor(…,
wrap=true)` starts wrapped. When on, each physical line becomes one or more visual
rows split to the viewport width, and horizontal scrolling is disabled. The
projection layers wrap over folding: a wrapped row keeps its physical line's tab
stops and carries the line number and fold marker only on its first segment.
Wrapping breaks at the last space that fits, falling back to a hard break for a
word wider than the pane, so it always advances. `visible_line_count()` counts
visual rows, and vertical navigation, hit testing and the caret follow them.
## Change bars
`set_baseline(text)` records a saved version to diff against; `clear_baseline()`
removes it, and `has_changes()` reports whether the buffer currently differs. A
Myers line diff classifies each current line as unchanged, added or modified and
marks where baseline lines were deleted, drawn as gutter bars in
`EditorTheme.diff_added`, `diff_modified` and `diff_deleted`. The diff recomputes
only when the document revision changes, and its cost scales with the number of
changed lines, so a few edits in a large file stay cheap; a very divergent file
falls back to a coarse whole-region mark. Pass the current text (as after a save)
to clear the bars. luced sets the baseline to the file on disk and re-baselines on
save.
## Editing commands and context menus
`copy`, `cut`, `paste`, `select_all`, `undo` and `redo` expose the same operations
used by keyboard editing. `has_selection`, `is_read_only`, `can_undo` and
`can_redo` let menus update availability. Cut and paste leave read-only content
unchanged. The application owns Command instances and may wrap the editor in a
ContextMenu; clipboard and document logic remain inside the text control.
The gutter marks the caret's visible row with `EditorTheme.gutter_active` and
`active_line_number`, even while a menu temporarily owns keyboard focus. Hovering
a different gutter row uses `gutter_hover` and brightens its number/fold marker.
Both rows use the same projection and scroll position as text, including folded
content. Passive pointer movement changes no document, decoration or measured
geometry.
The inherited theme has a separate gutter color, so the folding/line-number
area remains distinct from document content when the application changes theme.