# Game Text Input

The interface to use GameTextInput.

## Summary

| ### Enumerations ||
|---|---|
| `https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1gac52268e192515543b3bb207e68b94007` | enumValues with special meaning in a [GameTextInputSpan](https://developer.android.com/reference/games/game-text-input/struct/game-text-input-span#struct_game_text_input_span). |
| `https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga9c2d607d2c8e7452c5a2bc0a9f086624` | enumFlags to be passed to GameTextInput_hideIme. |
| `https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga1c15a456b89b00ffd6e30dab2add4e6d` | enumFlags to be passed to GameTextInput_showIme. |

| ### Typedefs ||
|---|---|
| `https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga4c4dac50a32fb6364b56d094844b466b` | typedef `struct https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga4c4dac50a32fb6364b56d094844b466b` Opaque handle to the GameTextInput API. |
| `https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga3494e8ab87f3d6a28c58615b28119efb)(void *context, const GameTextInputState *current_state)` | typedef `void(*` Type of the callback needed by GameTextInput_setEventCallback that will be called every time the IME state changes. |
| `https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga3a15a232cd46111d61566760c61d5dbe)(void *context, const struct GameTextInputState *state)` | typedef `void(*` A callback called by GameTextInput_getState. |
| `https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga42cb9917eca518b4d5959f631c7df56d` | typedef `struct https://developer.android.com/reference/games/game-text-input/struct/game-text-input-span#struct_game_text_input_span` This struct holds a span within a region of text from start (inclusive) to end (exclusive). |
| `https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1gaffe26d221b828d07da8c011b6a0d7b5c` | typedef `struct https://developer.android.com/reference/games/game-text-input/struct/game-text-input-state#struct_game_text_input_state` This struct holds the state of an editable section of text. |

| ### Functions ||
|---|---|
| `https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga3f7b119ab27fe831e51c71b718ae2e88(const https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga4c4dac50a32fb6364b56d094844b466b *input, jobject state, https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga3a15a232cd46111d61566760c61d5dbe callback, void *context)` | `void` Convert from a Java gametextinput.State object into a C [GameTextInputState](https://developer.android.com/reference/games/game-text-input/struct/game-text-input-state#struct_game_text_input_state) struct. |
| `https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga5e787b9a37ec77af06833cf075c98e1a(const https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga4c4dac50a32fb6364b56d094844b466b *input, const https://developer.android.com/reference/games/game-text-input/struct/game-text-input-state#struct_game_text_input_state *state)` | `jobject` Convert a [GameTextInputState](https://developer.android.com/reference/games/game-text-input/struct/game-text-input-state#struct_game_text_input_state) struct to a Java gametextinput.State object. |
| `https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga67a1a6a9efd4d7b11f91f9654a230940(https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga4c4dac50a32fb6364b56d094844b466b *input)` | `void` Free any resources owned by the GameTextInput library. |
| `https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga52b16a4af73d0fe28397e304ca96f47d(https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga4c4dac50a32fb6364b56d094844b466b *input, https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga3a15a232cd46111d61566760c61d5dbe callback, void *context)` | `void` Call a callback with the current GameTextInput state, which may have been modified by changes in the IME and calls to GameTextInput_setState. |
| `https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga57d790e1664b0f0f5092ca31baec4cfe(https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga4c4dac50a32fb6364b56d094844b466b *input, uint32_t flags)` | `void` Show the IME. |
| `https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1gaceb67d2acf41e5d7219ce0ec5d3dbe30(JNIEnv *env, uint32_t max_string_size)` | `https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga4c4dac50a32fb6364b56d094844b466b *` Initialize the GameTextInput library. |
| `https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1gaea1284431aaa930689e6199fa1494201(https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga4c4dac50a32fb6364b56d094844b466b *input, jobject eventState)` | `void` Unless using GameActivity, it is required to call this function from your Java gametextinput.Listener.stateChanged method to convert eventState and trigger any event callbacks. |
| `https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga0e3b95cbcce0debd475027b48191739b(https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga4c4dac50a32fb6364b56d094844b466b *input, https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga3494e8ab87f3d6a28c58615b28119efb callback, void *context)` | `void` Optionally set a callback to be called whenever the IME state changes. |
| `https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1gaa2f7ab8be3475a014b7da6e88558c78e(https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga4c4dac50a32fb6364b56d094844b466b *input, jobject inputConnection)` | `void` When using GameTextInput, you need to create a gametextinput.InputConnection on the Java side and pass it using this function to the library, unless using GameActivity in which case this will be done for you. |
| `https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga0fcb537a9f26254d9dde6802ef13cf14(https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga4c4dac50a32fb6364b56d094844b466b *input, const https://developer.android.com/reference/games/game-text-input/struct/game-text-input-state#struct_game_text_input_state *state)` | `void` Set the current GameTextInput state. |
| `https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga9a33fcd040be4cd63cea50068a573cd4(https://developer.android.com/reference/games/game-text-input/group/game-text-input#group__game__text__input_1ga4c4dac50a32fb6364b56d094844b466b *input, uint32_t flags)` | `void` Show the IME. |

| ### Structs ||
|---|---|
| [GameTextInputSpan](https://developer.android.com/reference/games/game-text-input/struct/game-text-input-span) | This struct holds a span within a region of text from start (inclusive) to end (exclusive). |
| [GameTextInputState](https://developer.android.com/reference/games/game-text-input/struct/game-text-input-state) | This struct holds the state of an editable section of text. |

## Enumerations

### GameTextInputSpanFlag

```text
 GameTextInputSpanFlag
```
Values with special meaning in a [GameTextInputSpan](https://developer.android.com/reference/games/game-text-input/struct/game-text-input-span#struct_game_text_input_span).

### HideImeFlags

```text
 HideImeFlags
```
Flags to be passed to GameTextInput_hideIme.

### ShowImeFlags

```text
 ShowImeFlags
```
Flags to be passed to GameTextInput_showIme.

## Typedefs

### GameTextInput

```text
struct GameTextInput GameTextInput
```
Opaque handle to the GameTextInput API.

### GameTextInputEventCallback

```gdscript
void(* GameTextInputEventCallback)(void *context, const GameTextInputState *current_state)
```
Type of the callback needed by GameTextInput_setEventCallback that will be called every time the IME state changes.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `context` | User-defined context set in GameTextInput_setEventCallback. | | `current_state` | Current IME state, owned by the library and valid during the callback. | |

### GameTextInputGetStateCallback

```gdscript
void(* GameTextInputGetStateCallback)(void *context, const struct GameTextInputState *state)
```
A callback called by GameTextInput_getState.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `context` | User-defined context. | | `state` | State, owned by the library, that will be valid for the duration of the callback. | |

### GameTextInputSpan

```text
struct GameTextInputSpan GameTextInputSpan
```
This struct holds a span within a region of text from start (inclusive) to end (exclusive).

An empty span or cursor position is specified with start==end. An undefined span is specified with start = end = SPAN_UNDEFINED.

### GameTextInputState

```text
struct GameTextInputState GameTextInputState
```
This struct holds the state of an editable section of text.

The text can have a selection and a composing region defined on it. A composing region is used by IMEs that allow input using multiple steps to compose a glyph or word. Use functions GameTextInput_getState and GameTextInput_setState to read and modify the state that an IME is editing.

## Functions

### GameTextInputState_fromJava

```gdscript
void GameTextInputState_fromJava(
  const GameTextInput *input,
  jobject state,
  GameTextInputGetStateCallback callback,
  void *context
)
```
Convert from a Java gametextinput.State object into a C [GameTextInputState](https://developer.android.com/reference/games/game-text-input/struct/game-text-input-state#struct_game_text_input_state) struct.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `input` | A valid GameTextInput library handle. | | `state` | A Java gametextinput.State object. | | `callback` | A function called with the C struct, valid for the duration of the call. | | `context` | Context passed to the callback. | |

### GameTextInputState_toJava

```gdscript
jobject GameTextInputState_toJava(
  const GameTextInput *input,
  const GameTextInputState *state
)
```
Convert a [GameTextInputState](https://developer.android.com/reference/games/game-text-input/struct/game-text-input-state#struct_game_text_input_state) struct to a Java gametextinput.State object.

Don't forget to delete the returned Java local ref when you're done.

| Details ||
|---|---|
| Parameters | |---|---| | `input` | A valid GameTextInput library handle. | | `state` | Input state to convert. | |
| **Returns** | A Java object of class gametextinput.State. The caller is required to delete this local reference. |

### GameTextInput_destroy

```scdoc
void GameTextInput_destroy(
  GameTextInput *input
)
```
Free any resources owned by the GameTextInput library.

Any subsequent calls to the library will fail until GameTextInput_init is called again.

| Details ||
|---|---|
| Parameters | |---|---| | `input` | A valid GameTextInput library handle. | |

### GameTextInput_getState

```scdoc
void GameTextInput_getState(
  GameTextInput *input,
  GameTextInputGetStateCallback callback,
  void *context
)
```
Call a callback with the current GameTextInput state, which may have been modified by changes in the IME and calls to GameTextInput_setState.

We use a callback rather than returning the state in order to simplify ownership of text_UTF8 strings. These strings are only valid during the calling of the callback.

| Details ||
|---|---|
| Parameters | |---|---| | `input` | A valid GameTextInput library handle. | | `callback` | A function that will be called with valid state. | | `context` | Context used by the callback. | |

### GameTextInput_hideIme

```scdoc
void GameTextInput_hideIme(
  GameTextInput *input,
  uint32_t flags
)
```
Show the IME.

Calls InputMethodManager.hideSoftInputFromWindow().

| Details ||
|---|---|
| Parameters | |---|---| | `input` | A valid GameTextInput library handle. | | `flags` | Defined in HideImeFlags above. For more information see: <https://developer.android.com/reference/android/view/inputmethod/InputMethodManager> | |

### GameTextInput_init

```scdoc
GameTextInput * GameTextInput_init(
  JNIEnv *env,
  uint32_t max_string_size
)
```
Initialize the GameTextInput library.

If called twice without GameTextInput_destroy being called, the same pointer will be returned and a warning will be issued.

| Details ||
|---|---|
| Parameters | |---|---| | `env` | A JNI env valid on the calling thread. | | `max_string_size` | The maximum length of a string that can be edited. If zero, the maximum defaults to 65536 bytes. A buffer of this size is allocated at initialization. | |
| **Returns** | A handle to the library. |

### GameTextInput_processEvent

```scdoc
void GameTextInput_processEvent(
  GameTextInput *input,
  jobject eventState
)
```
Unless using GameActivity, it is required to call this function from your Java gametextinput.Listener.stateChanged method to convert eventState and trigger any event callbacks.

When using GameActivity, this does not need to be called as event processing is handled by the Activity.

| Details ||
|---|---|
| Parameters | |---|---| | `input` | A valid GameTextInput library handle. | | `eventState` | A Java gametextinput.State object. | |

### GameTextInput_setEventCallback

```scdoc
void GameTextInput_setEventCallback(
  GameTextInput *input,
  GameTextInputEventCallback callback,
  void *context
)
```
Optionally set a callback to be called whenever the IME state changes.

Not necessary if you are using GameActivity, which handles these callbacks for you.

| Details ||
|---|---|
| Parameters | |---|---| | `input` | A valid GameTextInput library handle. | | `callback` | Called by the library when the IME state changes. | | `context` | Context passed as first argument to the callback. | |

### GameTextInput_setInputConnection

```scdoc
void GameTextInput_setInputConnection(
  GameTextInput *input,
  jobject inputConnection
)
```
When using GameTextInput, you need to create a gametextinput.InputConnection on the Java side and pass it using this function to the library, unless using GameActivity in which case this will be done for you.

See the GameActivity source code or GameTextInput samples for examples of usage.

| Details ||
|---|---|
| Parameters | |---|---| | `input` | A valid GameTextInput library handle. | | `inputConnection` | A gametextinput.InputConnection object. | |

### GameTextInput_setState

```gdscript
void GameTextInput_setState(
  GameTextInput *input,
  const GameTextInputState *state
)
```
Set the current GameTextInput state.

This state is reflected to any active IME.

| Details ||
|---|---|
| Parameters | |---|---| | `input` | A valid GameTextInput library handle. | | `state` | The state to set. Ownership is maintained by the caller and must remain valid for the duration of the call. | |

### GameTextInput_showIme

```scdoc
void GameTextInput_showIme(
  GameTextInput *input,
  uint32_t flags
)
```
Show the IME.

Calls InputMethodManager.showSoftInput().

| Details ||
|---|---|
| Parameters | |---|---| | `input` | A valid GameTextInput library handle. | | `flags` | Defined in ShowImeFlags above. For more information see: <https://developer.android.com/reference/android/view/inputmethod/InputMethodManager> | |