Brighterscript Game Engine

TextInput

Extends: UiWidget

A focusable single-line text entry widget. Characters arrive via onECPKeyboard() (Roku's mobile-app on-screen keyboard sends individual characters this way - see Game.bs's existing onECPKeyboard dispatch, which already reaches every UiContainer child unconditionally, same as onInput()). Left/Right (while focused) move the caret; OK fires onSubmit. No on-screen virtual keyboard is drawn by this widget - it relies entirely on the platform's own text-entry mechanism delivering onECPKeyboard() characters.

Properties

  • text (string) — Current text content.
  • cursorIndex (integer) — Caret position, 0..Len(text). Moved by Left/Right while focused, and ' advances/retreats as characters are inserted/deleted.
  • maxLength (integer) — Maximum text length, 0 = unlimited. A character typed once text.Len() ' already equals maxLength is silently dropped.
  • placeholder (string) — Text shown (dimmed) when text is empty and this widget isn't focused.
  • onChanged (dynamic) — Called after any edit (insert/delete) - function(input as TextInput) as void
  • onSubmit (dynamic) — Called on OK-press while focused - function(input as TextInput) as void
  • lastChangedValue (dynamic) — Test accessor: last value an onChanged callback stashed here. Not part ' of the public API - exists purely because a plain local var captured by ' an anonymous sub assigned to onChanged doesn't reliably update under ' brs-cli, so tests need a field on the widget itself to observe.
  • drawableText (BGE.DrawableText)
  • repeatThrottle (BGE.UI.RepeatThrottle) — Throttles repeat-while-held Left/Right to one step per ' WIDGET_REPEAT_DELAY_MS - see handleInput().

Constructor

new TextInput(game: BGE.Game): TextInput

Parameters

Instance Methods

getValue(): dynamic

Gets the current text content.

Returns

  • dynamic

onECPKeyboard(char: integer): void

Inserts/deletes a character at the caret. Called by the engine when the platform's own text-entry mechanism (e.g. Roku's mobile-app on-screen keyboard) sends a character - see the class doc comment above. char 8 (ASCII backspace) deletes the character before the caret; any other char is inserted as text, subject to maxLength.

Parameters

  • char (integer)

Returns

  • void

handleInput(input: BGE.GameInput): boolean

Left/Right (while focused) move the caret and consume the event. Called only while focused - see UiWidget.handleInput()/ BGE.UI.FocusManager.update(). A held Left/Right event is always consumed too - Game.bs synthesizes one alongside every press, and it has to be consumed rather than leaking through to GameEntity.onInput() - but it only MOVES once WIDGET_REPEAT_DELAY_MS has passed since the last step, so a single tap's press+held pair moves exactly once while a sustained hold still repeats.

Parameters

Returns

  • boolean

onClick(): void

Fires onSubmit on OK press.

Returns

  • void

draw(parent?: UiWidget): void

Draws the background/border (matching Select's pattern), the current text - or, when empty and unfocused, the dimmed placeholder - and a caret at cursorIndex while focused.

Parameters

  • parent (UiWidget, optional, default: "invalid")

Returns

  • void