Files
kryon/docs/COMPOSITION_INPUT.md
waozi 216c190c43 Document only current Kryon APIs and website pages
Remove raylib paths, obsolete import and preview guidance, migration prose,
and orphaned documents/pages. Align widget imports, native ZX windows and
host contracts with the current implementation, and enforce current site routes.
2026-11-16 21:43:18 -03:00

2.6 KiB

Composition input

Kryon's checked TextField and TextArea accept raw composition events in props.input.composition_event. They return the next CompositionState and, for a commit, a normal byte-range edit. The caller owns the committed text and applies that edit before the next frame.

composition_input.zi exposes SampleComposition() as an ordinary Ziran library function. It calls the platform's PollComposition capability and returns a CompositionSample. Convert an available sample with CompositionEventForSample(sample) and pass it to the focused text widget. An unavailable sample converts to a no-op event. Events have the same phase numbers as the platform input phases: start 1, update 2, commit 3, cancel 4.

src/backend/composition_queue.zi implements a single-threaded queue for up to 16 pending events. BeginCompositionFrame, SubmitComposition, and TakeComposition manage ordering, owned byte copies, and UTF-8 truncation. The queue is tested from source and saved .zir on C and Go targets.

Portable applications bind composition_input:PollComposition to an ordinary Ziran provider with ziran bundle --bind; the checked test uses this route for source and saved .zx execution. A native platform host may implement the same PollComposition() -> CompositionSample function directly. The returned text must stay alive while the caller uses it. A caller that retains CompositionState.text must copy the bytes into its own storage before the provider releases them. Kryon owns composition decisions, preedit paint, and commit ranges; platform adapters own event delivery.

Graphemes and native shaping

TextField and TextArea cursor movement, deletion, selection boundaries and wrapping use the standard library's Unicode 17 grapheme segmentation. This keeps combining accents, family emoji, modifiers, regional-indicator flags and Indic joins intact, including joins across preedit segments. Existing max_codepoints limits continue to count Unicode scalars.

The native Cairo host uses Pango for shaping, bidirectional placement and font fallback. Caret measurement uses the full shaped line rather than a separately shaped prefix. tests/native_text_test.sh checks combining marks, Arabic joining, Hebrew caret/hit positions and long text through source/saved IR and C.

Logical Left/Right movement is still by grapheme order. Mixed bidirectional selection uses a single highlight rectangle, and separately styled preedit runs are not shaped as one joined run. Pixmap and other hosts retain their own font/rendering capabilities; Cairo shaping does not imply all-host bidirectional support.