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:

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:

• GameActivity_showSoftInput() displays the soft keyboard.
• GameActivity_hideSoftInput() hides the soft keyboard.

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

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:

• Implement a callback function of type GameTextInputGetStateCallback to process text input events.
• Call GameActivity_getInputState() when there is one or multiple outstanding events.
• Clear the android_app::textInputState after the events are processed.

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:

• Use GameActivity_getTextInput() to get GameActivity’s internal GameTextInput instance.
• With the GameTextInput instance in hand, call GameTextInput_getState() to get the same GameTextInputState content.

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:

• GameActivity get started
• GameTextInput user documentation
• agdkTunnel sample
• Jetpack reference documentation for GameActivity
• Jetpack reference documentation for GameTextInput
• AGDK source code

Feedback

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