text_input (cellium v0.1.0)

View Source

Text input widget module for editable text fields.

This module provides an interactive text input widget that handles keyboard events and supports optional word wrapping with vertical scrolling.

Usage

Basic text input:

text_input:new(my_input)

Text input with wrapping (requires expand or size to get width/height from layout):

(text_input:new(my_input))#{wrap => true, expand => true}

Properties

  • wrap (boolean): Enable word wrapping. When true, text wraps at the widget's width and shows only the last N lines that fit in height. Default: false
  • expand (boolean): Request the layout system to assign width and height. Required when using wrap. Default: false
  • width (integer): Set by the layout system when expand is true. Determines wrap width.
  • height (integer): Set by the layout system when expand is true. Determines how many wrapped lines to show (shows last N lines).
  • state (map): Text input state containing text and cursor position

Wrapping Behavior

When wrap is enabled:

  • Text wraps horizontally at word boundaries (using greedy wrap algorithm)
  • Only the last N lines (fitting in height) are displayed
  • Earlier lines are hidden but not discarded
  • Cursor follows correctly across wrapped lines

Summary

Functions

handle_event/2

Handles keyboard events for the text input.

new(Id)

Creates a new text input widget.

render(Widget, Buffer)

Renders the text input widget (unfocused state).

render_focused(Widget, Buffer)

Renders the text input widget (focused state) with cursor.

state(Text)

Creates a text input state with the given text.

Functions

handle_event/2

-spec handle_event(term(), string() | map()) -> string() | map().

Handles keyboard events for the text input.

Processes keyboard input including character insertion, backspace, and cursor movement (left/right arrow keys).

new(Id)

-spec new(term()) -> map().

Creates a new text input widget.

To enable word wrapping, set the wrap property to true and add expand so the layout system assigns width and height:

(text_input:new(my_id))#{wrap => true, expand => true}

render(Widget, Buffer)

-spec render(map(), map()) -> map().

Renders the text input widget (unfocused state).

If wrap is enabled and width/height are set by layout:

  • Text wraps at word boundaries at the widget's width
  • Only the last N lines (fitting in height) are displayed

render_focused(Widget, Buffer)

-spec render_focused(map(), map()) -> map().

Renders the text input widget (focused state) with cursor.

If wrap is enabled and width/height are set by layout:

  • Text wraps at word boundaries at the widget's width
  • Only the last N lines (fitting in height) are displayed
  • Cursor position is calculated correctly across wrapped lines

state(Text)

-spec state(string()) -> map().

Creates a text input state with the given text.