TextInputBuffer class
Manages text input state with cursor positioning.
Encapsulates the common pattern found in text-based terminal prompts:
- Text buffer with cursor position
- Character insertion at cursor
- Backspace/delete operations
- Cursor movement (left/right, home/end)
- Optional max length enforcement
Usage:
final input = TextInputBuffer();
// Handle key events
if (input.handleKey(event)) {
// Input was modified, re-render
}
// Or use individual operations
input.insert('a');
input.backspace();
input.moveCursor(-1);
// Access state
final text = input.text;
final cursor = input.cursorPosition;
Key features:
- Cursor-aware text editing
- Efficient StringBuffer-based storage
- Key event handling helper
- Selection support (future-ready)
- Zero boilerplate in prompts
- Available extensions
Constructors
- TextInputBuffer({String initialText = '', int? maxLength})
- Creates a new text input buffer.
Properties
- charAtCursor → String?
-
Whole grapheme at cursor position, or null if cursor is at end.
no setter
- cursorAtEnd → bool
-
Whether the cursor is at the end.
no setter
- cursorAtStart → bool
-
Whether the cursor is at the start.
no setter
- cursorPosition → int
-
Current cursor position in UTF-16 code units, always at a grapheme boundary.
no setter
- hashCode → int
-
The hash code for this object.
no setterinherited
- isEmpty → bool
-
Whether the buffer is empty.
no setter
- isNotEmpty → bool
-
Whether the buffer is not empty.
no setter
- length → int
-
Length of the current text in UTF-16 code units.
no setter
- maxLength → int?
-
Optional maximum UTF-16 length; truncation preserves whole graphemes.
final
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
- text → String
-
Current text content.
no setter
- textAfterCursor → String
-
Text after the cursor (including char at cursor).
no setter
- textBeforeCursor → String
-
Text before the cursor.
no setter
Methods
-
append(
String text) → void -
Available on TextInputBuffer, provided by the SimpleTextInput extension
Appends text to the end (ignoring cursor position). -
backspace(
) → bool - Deletes the complete grapheme before the cursor.
-
backspaceWord(
) → bool - Deletes the word before the cursor, including trailing spaces.
-
clear(
) → void - Clears all text and resets cursor to start.
-
delete(
) → bool - Deletes the complete grapheme at the cursor.
-
handleKey(
KeyEvent event) → bool - Handles a key event for text input.
-
handleKeyExtended(
KeyEvent event, {bool ctrl = false}) → bool - Handles a key event with extended controls (word movement, etc.).
-
insert(
String text) → bool - Inserts text, returning whether any text was inserted.
-
insertText(
String value) → int - Inserts the longest whole-grapheme prefix that fits maxLength. Returns the number of UTF-16 code units inserted.
-
moveCursor(
int delta) → void - Moves by grapheme positions (negative = left, positive = right). The public cursor offset remains measured in UTF-16 code units.
-
moveCursorToEnd(
) → void - Moves cursor to the end.
-
moveCursorToStart(
) → void - Moves cursor to the start.
-
moveCursorWordLeft(
) → void - Moves cursor to the start of the previous word.
-
moveCursorWordRight(
) → void - Moves cursor past the current word and following spaces.
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
removeLast(
) → bool -
Available on TextInputBuffer, provided by the SimpleTextInput extension
Removes the last character (ignoring cursor position). -
setCursorPosition(
int position) → void - Sets a UTF-16 offset, clamped and rounded down to a grapheme boundary.
-
setText(
String newText) → void - Sets the buffer to new text, cursor at end.
-
textWithBlockCursor(
) → TextWithBlockCursor - Returns text formatted for display with inverse-video cursor.
-
textWithCursor(
{String cursorChar = '▌', bool showCursor = true}) → String - Returns the text with a cursor indicator at the current position.
-
toString(
) → String -
A string representation of this object.
override
-
toTextInputBindings(
{void onInput()?, void onTextChanged()?}) → KeyBindings -
Available on TextInputBuffer, provided by the TextInputBindingsExtensions extension
Creates text input bindings that delegate to a TextInputBuffer.
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited