TextInput in GameActivity   Part of Android Game Development Kit.

GameActivity integrates GameTextInput by:

  • providing a wrapper
  • creating a flag for new text input event availability
  • directly using GameTextInput’s state buffer for the text content

As shown in the following diagram, applications use different internal logical components for user text input purpose:

alt_text

There are three broad steps to using the built-in GameTextInput library:

  • Controlling the soft keyboard on UI
  • Knowing when new text is available
  • Retrieving the user input text and its states

The rest of this document describes them in detail. For an example of GameTextInput with GameActivity in action, see the games-samples repository.

Control the soft keyboard on UI

GameActivity provides two functions to control the soft keyboard on the UI:

Refer to the API reference docs for their definitions. After the keyboard is displayed, the application’s UI may look similar to the following:

alt_text

Check for text availability

Soft keyboard events get passed from GameTextInput on the Java side to the C/C++ side through the JNI, then travel up to GameActivity’s wrapper, finally reflecting in the android_app::textInputState flag implemented in native_app_glue. Applications should poll this flag periodically to perform the intended processing:

  • GameActivity only sets the android_app::textInputState flag.
  • Applications poll the flag and handle the new GameTextInput events, such as the new text added to the input buffer.
  • Applications clear the android_app::textInputState.

Note that android_app::textInputState does not differentiate between single and multiple text input events.

For a simple example, the following code polls the textInputState flag after handling app cycle commands, touch events, and key events:

while (true) {
   // Read all pending events.
   int events;
   struct android_poll_source* source;

   while ((ALooper_pollAll(engine.animating ? 0 : -1, nullptr, &events,
                                 (void**)&source)) >= 0) {
       // Process this event, etc.
       ...
       // Check if we are exiting.
       if (app->destroyRequested != 0) {
           engine_term_display(&engine);
           return;
       }
   }
   engine_handle_input(app);

   // Process text input events if there is any outstanding.
   if (app->textInputState) {
       // process TextInput events.
          ...
       //reset the textInputState flag
       app->textInputState = 0;
   }
   if (engine.animating) {
         // draw frames.
   }
}

Retrieve the user input text

The input texts and other states are accumulated in GameTextInput’s internal buffer, GameTextInput::currentState_. Applications can use one of the following ways to retrieve its content:

  • GameActivity’s wrapper API (recommended)
  • GameTextInput API

Get TextInput state with GameActivity API

Applications acquire the current text input with the typical callback mechanism:

Continuing with the snippet in the previous section, the following code acquires a reference to the text input buffer, processes it (not shown), and resets the event flag:

extern "C" void GameTextInputGetStateCB(void *ctx, const struct GameTextInputState *state) {
    auto* engine = (struct engine*)ctx;
    if (!engine || !state) return;

    // Process the text event(s).
    LOGI("UserInputText: %s", state->text_UTF8);

    // Clear the text input flag.
    engine->app->textInputState = 0;
}

In the game loop shown in the previous section, check and process text with the above text input handler:

if (state->textInputState) {
    GameActivity_getTextInputState(
        app->activity,
        GameTextInputGetStateCB,  // App's event handler shown above.
        &engine // Context to the GameTextInputGetStateCB function.
    );
}

Applications can optionally initialize the GameTextInputState content with GameActivity_setTextInputState().

Get TextInput state with GameTextInput API

Applications can also directly use GameTextInput API to retrieve the current GameTextInputState:

Again, note that applications should not initialize GameTextInput directly; GameActivity already does that during its initialization process.

The callback mechanism is the same as that used by the GameActivity’s GameActivity_getTextInputState() function.

References

Developers might find the following resources helpful when creating GameActivity applications:

Feedback

GameActivity and GameTextInput are both part of Jetpack games library. For any issues and questions, create a bug on the Google IssueTracker.