Class “TextInput”

Object > NativeObject > Widget > TextInput

A widget that allows to enter text.

Examples

JavaScript

import {TextInput, contentView} from 'tabris';

new TextInput({
  left: 16, right: 16,
  message: 'Name'
}).onInput(({text}) => console.log(`Text changed to ${text}`))
  .appendTo(contentView);

See also:

JSX Creating a simple TextInput
JS Handling selection on a TextInput
JSX Handling focus changes on a TextInput
JS Creating TextInputs with various enter key types
JS Creating TextInputs with various keyboards
JS Showing password in clear text on a TextInput
JSX A form using TextInput and other input controls
TSX textinput-focus.tsx
TS textinput-keyboard.ts
TSX textinput-style.tsx

Constructor

new TextInput(properties?)

Properties

alignment

The horizontal alignment of the text.

autoCapitalize

Control how text input is capitalized.

• none - Do not change any text input
• sentence - Capitalize the first word of a sentence
• word - Capitalize every word
• all - Capitalize every letter

The boolean value false maps to none whereas true is equal to all.

autoCorrect

Enables the spell checker and auto-correction feature.

borderColor

The color of the border of the TextInput. On iOS this is a rectangular border around the TextInput, on Android it is a single line below the TextInput.

cursorColor

iOS

The color of the cursor in the TextInput.

editable

Whether the text can be edited or not.

enterKeyType

Label or icon to display on the keyboard ‘confirmation’ key. The key press can be captured via the accept event. Setting an enterKeyType other than default will change the key behavior to not close the keyboard automatically. The developer is able close the keyboard by removing the focus from the TextInput.

See also:

JS textinput-enterkeytype.js

floatMessage

Android

Should the hint message float above the TextInput when focus is gained.

focused

Reflects whether this widget has the keyboard focus. Setting this property to true will focus the widget and open the virtual keyboard, setting it to false will remove the focus and hide the virtual keyboard.

font

The font used for the text.

keepFocus

When true the TextInput will keep its focus, even when tapped outside of the widget bounds.

keyboard

Selects the keyboard type to use for editing this widget. Has no effect when type is set to multiline.

See also:

JS textinput-keyboard.js
TS textinput-keyboard.ts

keyboardAppearanceMode

Android

Allows to control when to show the virtual keyboard.

• 'never' - The keyboard is never shown when focus is gained.

• 'ontouch' - The keyboard is not shown when the focused property is set to true programmatically. Only the blinking cursor will be shown. Touching the TextInput will show the keyboard.

• 'onfocus' - The keyboard is always shown when the TextInput gains focus.

maxChars

The maximum number of characters that can be entered into a TextInput.

message

A hint text that is displayed when the input field is empty. Does not apply on iOS when type is set to multiline.

messageColor

Color of the message text.

revealPassword

Makes the text visible when the TextInput has the type password.

See also:

JS textinput-revealpassword.js

selection

The selection is a two element number array representing the text selections start and end position. The native platform usually shows selection handles so that the selection can be changed by the user. A selection array where both numbers are the same represent a single cursor at the given position. The selection start is the index of the first character where as the end is the index of the last character + 1. E.g. to select the word “ok” the selection would be [0, 2].

To make a selection visible the TextInput has to be in focus. Consequently the selection is preserved when the focus is lost and regained. When the user gives the TextInput focus by tapping on it, the selection is changed to represent his touch position.

Getting the selection upon user interaction (e.g. a button press) the focus would be lost and possibly the selection altered due to user interaction. In such a scenario it is recommended to set the keepFocus property to true.

See also:

JS textinput-selection.js

style

Android

The visual appearance of the text widget.

With the style outline, fill or underline the message hint will float above the TextInput on Android. This behavior can be controlled with the property floatMessage. The style none will remove any background visualization, allowing to create a custom background.

This property can only be set via constructor or JSX. Once set, it cannot change anymore.

See also:

TSX textinput-style.tsx

text

The text in the input field.

When using TextInput as an JSX element the elements Text content is mapped to this property.

textColor

The color of the text.

type

The type of the text widget.

This property can only be set via constructor or JSX. Once set, it cannot change anymore.

Events

accept

Fired when a text input has been finished by pressing the keyboard’s Enter key. The label of this key may vary depending on the platform and locale.

EventObject Type: TextInputAcceptEvent<TextInput>

select

The select event is fired when the user alters the text selection. Either by dragging the selection handles of a text selection, by moving the cursor inside the text or by typing which also advances the cursor.

The event also fires when the user taps inside a TextInput since this involves to set the cursor to the tapped position.

EventObject Type: TextInputSelectEvent<TextInput>

blur

Fired when the widget lost focus.

EventObject Type: EventObject<TextInput>

This event has no additional parameter.

focus

Fired when the widget gains focus.

EventObject Type: EventObject<TextInput>

This event has no additional parameter. See also:

TSX textinput-focus.tsx

input

Fired when the text was changed by the user.

EventObject Type: TextInputInputEvent<TextInput>

Change Events

textChanged

Fired when the text property has changed.

EventObject Type: PropertyChangedEvent<TextInput, string>

textColorChanged

Fired when the textColor property has changed.

EventObject Type: PropertyChangedEvent<TextInput, ColorValue>

messageChanged

Fired when the message property has changed.

EventObject Type: PropertyChangedEvent<TextInput, string>

messageColorChanged

Fired when the messageColor property has changed.

EventObject Type: PropertyChangedEvent<TextInput, ColorValue>

editableChanged

Fired when the editable property has changed.

EventObject Type: PropertyChangedEvent<TextInput, boolean>

maxCharsChanged

Fired when the maxChars property has changed.

EventObject Type: PropertyChangedEvent<TextInput, number>

floatMessageChanged

Fired when the floatMessage property has changed.

EventObject Type: PropertyChangedEvent<TextInput, boolean>

alignmentChanged

Fired when the alignment property has changed.

EventObject Type: PropertyChangedEvent<TextInput, string>

autoCorrectChanged

Fired when the autoCorrect property has changed.

EventObject Type: PropertyChangedEvent<TextInput, boolean>

autoCapitalizeChanged

Fired when the autoCapitalize property has changed.

EventObject Type: PropertyChangedEvent<TextInput, any>

keyboardChanged

Fired when the keyboard property has changed.

EventObject Type: PropertyChangedEvent<TextInput, string>

enterKeyTypeChanged

Fired when the enterKeyType property has changed.

EventObject Type: PropertyChangedEvent<TextInput, string>

focusedChanged

Fired when the focused property has changed.

EventObject Type: PropertyChangedEvent<TextInput, boolean>

keepFocusChanged

Fired when the keepFocus property has changed.

EventObject Type: PropertyChangedEvent<TextInput, boolean>

borderColorChanged

Fired when the borderColor property has changed.

EventObject Type: PropertyChangedEvent<TextInput, ColorValue>

revealPasswordChanged

Fired when the revealPassword property has changed.

EventObject Type: PropertyChangedEvent<TextInput, boolean>

cursorColorChanged

Fired when the cursorColor property has changed.

EventObject Type: PropertyChangedEvent<TextInput, ColorValue>

selectionChanged

Fired when the selection property has changed.

EventObject Type: PropertyChangedEvent<TextInput, Array>

fontChanged

Fired when the font property has changed.

EventObject Type: PropertyChangedEvent<TextInput, FontValue>

keyboardAppearanceModeChanged

Fired when the keyboardAppearanceMode property has changed.

EventObject Type: PropertyChangedEvent<TextInput, 'never' | 'ontouch' | 'onfocus'>