TextInputSession

Added in 1.0.0
Deprecated in 1.7.0-alpha04

Represents a input session for interactions between a soft keyboard and editable text.

This session may be closed at any time by TextInputService or by calling dispose, after which isOpen will return false and all further calls will have no effect.

Summary

Public constructors

TextInputSession(
    textInputService: TextInputService,
    platformTextInputService: PlatformTextInputService
)
Cmn

Public functions

Unit

Close this input session.

Cmn
Boolean

Hide onscreen keyboard for a specific TextInputSession.

Cmn
Boolean

Notify the focused rectangle to the system.

Cmn
Boolean

Request showing onscreen keyboard.

Cmn
Boolean
updateState(oldValue: TextFieldValue?, newValue: TextFieldValue)

Notify IME about the new TextFieldValue and latest state of the editing buffer.

Cmn
Boolean
updateTextLayoutResult(
    textFieldValue: TextFieldValue,
    offsetMapping: OffsetMapping,
    textLayoutResult: TextLayoutResult,
    textFieldToRootTransform: (Matrix) -> Unit,
    innerTextFieldBounds: Rect,
    decorationBoxBounds: Rect
)

Notify the input service of layout and position changes.

Cmn

Public properties

Boolean

If this session is currently open.

Cmn

Public constructors

TextInputSession

TextInputSession(
    textInputService: TextInputService,
    platformTextInputService: PlatformTextInputService
)

Public functions

dispose

fun dispose(): Unit

Close this input session.

All further calls to this object will have no effect, and isOpen will return false.

Note, TextInputService may also close this input session at any time without calling dispose. Calling dispose after this session has been closed has no effect.

hideSoftwareKeyboard

fun hideSoftwareKeyboard(): Boolean

Hide onscreen keyboard for a specific TextInputSession.

This call will have no effect if this session is not open.

This should be used instead of TextInputService.showSoftwareKeyboard when implementing a new editable text composable to hide the keyboard in response to events related to that composable.

Returns
Boolean

false if this session expired and no action was performed

notifyFocusedRect

fun notifyFocusedRect(rect: Rect): Boolean

Notify the focused rectangle to the system.

The system can ignore this information or use it to for additional functionality.

For example, desktop systems show a popup near the focused input area (for some languages).

If the session is not open, no action will be performed.

Parameters
rect: Rect

the rectangle that describes the boundaries on the screen that requires focus

Returns
Boolean

false if this session expired and no action was performed

showSoftwareKeyboard

fun showSoftwareKeyboard(): Boolean

Request showing onscreen keyboard.

This call will have no effect if this session is not open.

This should be used instead of TextInputService.showSoftwareKeyboard when implementing a new editable text composable to show the keyboard in response to events related to that composable.

There is no guarantee that the keyboard will be shown. The software keyboard or system service may silently ignore this request.

Returns
Boolean

false if this session expired and no action was performed

updateState

fun updateState(oldValue: TextFieldValue?, newValue: TextFieldValue): Boolean

Notify IME about the new TextFieldValue and latest state of the editing buffer. oldValue is the state of the buffer before the changes applied by the newValue.

oldValue represents the changes that was requested by IME on the buffer, and newValue is the final state of the editing buffer that was requested by the application. In cases where oldValue is not equal to newValue, it would mean the IME suggested value is rejected, and the IME connection will be restarted with the newValue.

If the session is not open, action will be performed.

Parameters
oldValue: TextFieldValue?

the value that was requested by IME on the buffer

newValue: TextFieldValue

final state of the editing buffer that was requested by the application

Returns
Boolean

false if this session expired and no action was performed

updateTextLayoutResult

fun updateTextLayoutResult(
    textFieldValue: TextFieldValue,
    offsetMapping: OffsetMapping,
    textLayoutResult: TextLayoutResult,
    textFieldToRootTransform: (Matrix) -> Unit,
    innerTextFieldBounds: Rect,
    decorationBoxBounds: Rect
): Boolean

Notify the input service of layout and position changes.

Parameters
textFieldValue: TextFieldValue

the text field's TextFieldValue

offsetMapping: OffsetMapping

the offset mapping for the visual transformation

textLayoutResult: TextLayoutResult

the text field's TextLayoutResult

textFieldToRootTransform: (Matrix) -> Unit

function that modifies a matrix to be a transformation matrix from local coordinates to the root composable coordinates

innerTextFieldBounds: Rect

visible bounds of the text field in local coordinates, or an empty rectangle if the text field is not visible

decorationBoxBounds: Rect

visible bounds of the decoration box in local coordinates, or an empty rectangle if the decoration box is not visible

Public properties

isOpen

val isOpenBoolean

If this session is currently open.

A session may be closed at any time by TextInputService or by calling dispose.