Skip to main content

TextInputSystem.KeyboardOptions

Class

The settings used for how the input keyboard should work.

  • Available on all platforms
Platform details: Snapchat, SPECS, Camera Kit Web, Camera Kit Mobile fully supported.

Platform details

  • Snapchat — Fully supported.

  • SPECS — Fully supported.

  • Camera Kit Web — Fully supported.

  • Camera Kit Mobile — Fully supported.

Index

Example

var options = new TextInputSystem.KeyboardOptions();
options.enablePreview = false;
options.keyboardType = TextInputSystem.KeyboardType.Text;
options.returnKeyType = TextInputSystem.ReturnKeyType.Done;

// Maintain the state of the keyboard
options.onTextChanged = function(text, range) {
currText = text;
};

// When the keyboard returns, print the current text
options.onKeyboardStateChanged = function(isOpen) {
if (!isOpen) {
print(currText);
}
};

script.createEvent("TapEvent").bind(function(){
global.textInputSystem.requestKeyboard(options);
})

Constructors

Constructor

new KeyboardOptions(): KeyboardOptions

Returns

KeyboardOptions

Properties

enablePreview

enablePreview: boolean

Sets whether a preview should be visible above the input keyboard.

Since

Lens Scripting Version 165

Default Value

false

initialSelectedRange

initialSelectedRange: vec2

Initial selected text range to set on the inivisible text view.

Since

Lens Scripting Version 165

Default Value

(0, 0)

initialText

initialText: string

Initial text to fill into the invisible text view.

Since

Lens Scripting Version 165

Default Value

""

keyboardType

keyboardType: KeyboardType

Requested keyboard type.

Since

Lens Scripting Version 165

Default Value

TextInputSystem.KeyboardType.Text

onBeginBatchEdit

onBeginBatchEdit: () => void

SPECS

Callback to be invoked when a batch edit session is started. Editors can't send any update to the keyboard during a batch edit session.

Returns

void

Since

Lens Scripting Version 365

Default Value

null
@snapOS

Example

var options = new TextInputSystem.KeyboardOptions();

options.onBeginBatchEdit = function() {
print("Begin batch edit");
};

global.textInputSystem.requestKeyboard(options);

onCommitText

onCommitText: (text, newCursorPosition) => void

SPECS

Callback to be invoked when text should be committed to the selection/composing region.

Parameters

ParameterType
textstring
newCursorPositionnumber

Returns

void

Since

Lens Scripting Version 365

Default Value

null
@snapOS

Example

var options = new TextInputSystem.KeyboardOptions();

options.onCommitText = function(text, newCursorPosition) {
print("Commit text:", text, newCursorPosition);
};

global.textInputSystem.requestKeyboard(options);

onEndBatchEdit

onEndBatchEdit: () => void

SPECS

Callback to be invoked when a batch edit session is ended. Editors can resume their updates after receiving this callback

Returns

void

Since

Lens Scripting Version 365

Default Value

null
@snapOS

Example

var options = new TextInputSystem.KeyboardOptions();

options.onEndBatchEdit = function() {
print("End batch edit");
};

global.textInputSystem.requestKeyboard(options);

onError

onError: (error, description) => void

Callback to be invoked when there is an error.

Parameters

ParameterType
errornumber
descriptionstring

Returns

void

Default Value

null

onKeyboardKindChanged

onKeyboardKindChanged: (keyboardKind) => void

SPECS

Callback to be invoked when the kind of keyboard serving your text input session changes. The current kind is delivered right after the keyboard request. If the current text input follows pose suggestions, the last suggestion must be discarded when this callback is fired until new suggestion arrives.

Parameters

ParameterType
keyboardKindKeyboardKind

Returns

void

Since

Lens Scripting Version 372

Default Value

null
@snapOS

onKeyboardStateChanged

onKeyboardStateChanged: (keyboardIsOpen) => void

Callback to be invoked when keyboard is shown or dismissed.

Parameters

ParameterType
keyboardIsOpenboolean

Returns

void

Default Value

null

onPerformEditorAction

onPerformEditorAction: (action) => void

SPECS

Callback to be invoked when an editor action should be performed. This is typically used to perform actions like "search", "go", "next", "send", "newline", "done".

Parameters

ParameterType
actionTextFieldAction

Returns

void

Since

Lens Scripting Version 365

Default Value

null
@snapOS

Example

var options = new TextInputSystem.KeyboardOptions();

options.onPerformEditorAction = function(action) {
print("Perform editor action:", action);
};

global.textInputSystem.requestKeyboard(options);

onReturnKeyPressed

onReturnKeyPressed: () => void

Callback to be invoked when the user presses the return key.

Returns

void

Default Value

null

onSetComposingRegion

onSetComposingRegion: (start, end) => void

SPECS

Callback to be invoked when the composing region is changed.

Parameters

ParameterType
startnumber
endnumber

Returns

void

Since

Lens Scripting Version 365

Default Value

null
@snapOS

Example

var options = new TextInputSystem.KeyboardOptions();

options.onSetComposingRegion = function(start, end) {
print("Composing region:", start, end);
};

global.textInputSystem.requestKeyboard(options);

onSetComposingText

onSetComposingText: (text, newCursorPosition) => void

SPECS

Callback to be invoked when the composing text is changed.

Parameters

ParameterType
textstring
newCursorPositionnumber

Returns

void

Since

Lens Scripting Version 365

Default Value

null
@snapOS

Example

var options = new TextInputSystem.KeyboardOptions();

options.onSetComposingText = function(text, newCursorPosition) {
print("Composing text:", text, newCursorPosition);
};

global.textInputSystem.requestKeyboard(options);

onSetSelection

onSetSelection: (start, end) => void

SPECS

Callback to be invoked when there selection range is changed.

Parameters

ParameterType
startnumber
endnumber

Returns

void

Since

Lens Scripting Version 365

Default Value

null
@snapOS

Example

var options = new TextInputSystem.KeyboardOptions();

options.onSetSelection = function(start, end) {
print("Selection:", start, end);
};

global.textInputSystem.requestKeyboard(options);

onTextChanged

onTextChanged: (text, range) => void

Callback to be invoked every time the user presses a (non-return) key.

Parameters

ParameterType
textstring
rangevec2

Returns

void

Default Value

null

onTextInputPoseSuggestionChanged

onTextInputPoseSuggestionChanged: (position, rotation, size) => void

SPECS

Callback to be invoked with where the system suggests you place the edited content: position/rotation is the suggested bottom center of the text input UI element that currently has focus (just above the keyboard's top edge) in your Lens's world space (in centimeters). size (in centimeters), when non-zero, is the recommended (but not enforced) content size. Disregard the last suggestion after onKeyboardKindChanged.

Parameters

ParameterType
positionvec3
rotationquat
sizevec2

Returns

void

Since

Lens Scripting Version 372

Default Value

null
@snapOS

onUpdateText

onUpdateText: (updatedText) => void

SPECS

Callback to be invoked when there is a text update from the input method in the current cursor position.

Parameters

ParameterType
updatedTextTextUpdate

Returns

void

Since

Lens Scripting Version 365

Default Value

null
@snapOS

Example

var options = new TextInputSystem.KeyboardOptions();

options.onUpdateText = function(updatedText) {
print("Updated text:", updatedText.text);
};

global.textInputSystem.requestKeyboard(options);

onVirtualKeyboardMoveEnded

onVirtualKeyboardMoveEnded: () => void

SPECS

Callback to be invoked when the user releases the virtual keyboard after a drag. Always paired with a preceding onVirtualKeyboardMoveStarted.

Returns

void

Since

Lens Scripting Version 372

Default Value

null
@snapOS

onVirtualKeyboardMoveStarted

onVirtualKeyboardMoveStarted: () => void

SPECS

Callback to be invoked when the user grabs the virtual keyboard and starts dragging it. Apply transient drag effects, if any, to your content; pose suggestions may keep streaming during the move. Late joiners are notified if a keyboard move is in progress.

Returns

void

Since

Lens Scripting Version 372

Default Value

null
@snapOS

returnKeyType

returnKeyType: ReturnKeyType

Requested return key type.

Since

Lens Scripting Version 165

Default Value

TextInputSystem.ReturnKeyType.Done

Methods

getTypeName()

static getTypeName(): TypeName<KeyboardOptions>

Returns the fully-qualified JavaScript type name for this class (for example, "Component.Camera"). This is a static accessor (no instance required) and returns the same value as the instance getTypeName().

Returns

TypeName<KeyboardOptions>