Game Text Input

The interface to use GameTextInput.

Summary

Enumerations
GameTextInputSpanFlag enum
Values with special meaning in a GameTextInputSpan.
HideImeFlags enum
Flags to be passed to GameTextInput_hideIme.
ShowImeFlags enum
Flags to be passed to GameTextInput_showIme.

Typedefs
GameTextInput typedef
struct GameTextInput
Opaque handle to the GameTextInput API.
GameTextInputEventCallback)(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.
GameTextInputGetStateCallback)(void *context, const struct GameTextInputState *state) typedef
void(*
A callback called by GameTextInput_getState.
GameTextInputSpan typedef
This struct holds a span within a region of text from start (inclusive) to end (exclusive).
GameTextInputState typedef
This struct holds the state of an editable section of text.

Functions
GameTextInputState_fromJava(const GameTextInput *input, jobject state, GameTextInputGetStateCallback callback, void *context)
void
Convert from a Java gametextinput.State object into a C GameTextInputState struct.
GameTextInputState_toJava(const GameTextInput *input, const GameTextInputState *state)
jobject
Convert a GameTextInputState struct to a Java gametextinput.State object.
GameTextInput_destroy(GameTextInput *input)
void
Free any resources owned by the GameTextInput library.
GameTextInput_getState(GameTextInput *input, GameTextInputGetStateCallback 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.
GameTextInput_hideIme(GameTextInput *input, uint32_t flags)
void
Show the IME.
GameTextInput_init(JNIEnv *env, uint32_t max_string_size)
Initialize the GameTextInput library.
GameTextInput_processEvent(GameTextInput *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.
GameTextInput_setEventCallback(GameTextInput *input, GameTextInputEventCallback callback, void *context)
void
Optionally set a callback to be called whenever the IME state changes.
GameTextInput_setInputConnection(GameTextInput *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.
GameTextInput_setState(GameTextInput *input, const GameTextInputState *state)
void
Set the current GameTextInput state.
GameTextInput_showIme(GameTextInput *input, uint32_t flags)
void
Show the IME.

Structs
GameTextInputSpan

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

GameTextInputState

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

Enumerations

GameTextInputSpanFlag

 GameTextInputSpanFlag

Values with special meaning in a GameTextInputSpan.

HideImeFlags

 HideImeFlags

Flags to be passed to GameTextInput_hideIme.

ShowImeFlags

 ShowImeFlags

Flags to be passed to GameTextInput_showIme.

Typedefs

GameTextInput

struct GameTextInput GameTextInput

Opaque handle to the GameTextInput API.

GameTextInputEventCallback

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.

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

void(* GameTextInputGetStateCallback)(void *context, const struct GameTextInputState *state)

A callback called by GameTextInput_getState.

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

GameTextInputSpan

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

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

void GameTextInputState_fromJava(
  const GameTextInput *input,
  jobject state,
  GameTextInputGetStateCallback callback,
  void *context
)

Convert from a Java gametextinput.State object into a C GameTextInputState struct.

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

jobject GameTextInputState_toJava(
  const GameTextInput *input,
  const GameTextInputState *state
)

Convert a GameTextInputState 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

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

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

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

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

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

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

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

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

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