Class “TextInput”

Object > NativeObject > Widget > TextInput

A widget that allows to enter text.

Type:	`TextInput extends Widget`
Constructor:	public
Singleton:	No
Namespace:	tabris
Direct subclasses:	None
JSX Support:	Element: `<TextInput/>` Parent Elements: `<Canvas/>`, `<Cell/>`, `<Composite/>`, `<Page/>`, `<RefreshComposite/>`, `<Row/>`, `<ScrollView/>`, `<Stack/>`, `<Tab/>` Child Elements: Not Supported Element content sets: `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);

Constructor

new TextInput(properties?)

Parameter	Type	Description
properties	`Properties<TextInput>`	Sets all key-value pairs in the properties object as widget properties. Optional.

Properties

alignment

The horizontal alignment of the text.

Type:	`'left' \| 'right' \| 'centerX'`
Default:	`'left'`
Settable:	Yes
Change Event:	`alignmentChanged`

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.

Type:	`true \| false \| none \| sentence \| word \| all`
Default:	`false`
Settable:	Yes
Change Event:	`autoCapitalizeChanged`

autoCorrect

Enables the spell checker and auto-correction feature.

Type:	`boolean`
Default:	`false`
Settable:	Yes
Change Event:	`autoCorrectChanged`

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.

Type:	`ColorValue`
Settable:	Yes
Change Event:	`borderColorChanged`

cursorColor

The color of the cursor in the TextInput.

Type:	`ColorValue`
Settable:	Yes
Change Event:	`cursorColorChanged`

editable

Whether the text can be edited or not.

Type:	`boolean`
Default:	`true`
Settable:	Yes
Change Event:	`editableChanged`

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.

Type:	`'default' \| 'done' \| 'next' \| 'send' \| 'search' \| 'go'`
Default:	`'default'`
Settable:	Yes
Change Event:	`enterKeyTypeChanged`

floatMessage

Android

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

Type:	`boolean`
Default:	`true`
Settable:	Yes
Change Event:	`floatMessageChanged`

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.

Type:	`boolean`
Default:	`false`
Settable:	Yes
Change Event:	`focusedChanged`

font

The font used for the text.

Type:	`FontValue`
Settable:	Yes
Change Event:	`fontChanged`

keepFocus

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

Type:	`boolean`
Default:	`false`
Settable:	Yes
Change Event:	`keepFocusChanged`

keyboard

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

Type:	`'ascii' \| 'decimal' \| 'email' \| 'number' \| 'numbersAndPunctuation' \| 'phone' \| 'url' \| 'default'`
Default:	`'default'`
Settable:	Yes
Change Event:	`keyboardChanged`

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.

Type:	`'never' \| 'ontouch' \| 'onfocus'`
Default:	`'onfocus'`
Settable:	Yes
Change Event:	`keyboardAppearanceModeChanged`

maxChars

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

Type:	`number`
Default:	`null`
Settable:	Yes
Change Event:	`maxCharsChanged`

message

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

Type:	`string`
Settable:	Yes
Change Event:	`messageChanged`

messageColor

Color of the message text.

Type:	`ColorValue`
Settable:	Yes
Change Event:	`messageColorChanged`

revealPassword

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

Type:	`boolean`
Settable:	Yes
Change Event:	`revealPasswordChanged`

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.

Type:	`number[]`
Settable:	Yes
Change Event:	`selectionChanged`

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.

Type:	`'default' \| 'outline' \| 'fill' \| 'underline' \| 'none'`
Default:	`'default'`
Settable:	By Constructor or JSX
Change Event:	Not supported

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

text

The text in the input field.

Type:	`string`
Settable:	Yes
Change Event:	`textChanged`
JSX Content Type:	Text

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

textColor

The color of the text.

Type:	`ColorValue`
Settable:	Yes
Change Event:	`textColorChanged`

type

The type of the text widget.

Type:	`'default' \| 'password' \| 'search' \| 'multiline'`
Default:	`'default'`
Settable:	By Constructor or JSX
Change Event:	Not supported

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>

Property	Type	Description
text	`string`	The current value of text.

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>

Property	Type	Description
selection	`number[]`	The current `selection` as a two element number array of start and end position.

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.

input

Fired when the text was changed by the user.

EventObject Type: TextInputInputEvent<TextInput>

Property	Type	Description
text	`string`	The new value of text.

beforeTextChange

Fired when the text value is about to change due to a user action.

EventObject Type: TextInputBeforeTextChangeEvent<TextInput>

Property	Type	Description
newValue	`string`	The text after the change, i.e. the future `text` value if `preventDefault` is not called.
oldValue	`string`	The text before the change, i.e. the current `text` value.
preventDefault	`Function`	Call to intercept the change.