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:

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:

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.
intevents;
structandroid_poll_source*source;
while((ALooper_pollOnce(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"voidGameTextInputGetStateCB(void*ctx,conststructGameTextInputState*state){
auto*engine=(structengine*)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:

Feedback

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