GameActivity 中的 TextInput 属于 Android 游戏开发套件的一部分。

GameActivity 通过以下方式集成 GameTextInput

提供包装器
创建用于新文本输入事件可用性的标志
直接使用 GameTextInput 的状态缓冲区作为文本内容

如下图所示，应用程序使用不同的内部逻辑组件来完成用户文本输入目的

alt_text

使用内置 GameTextInput 库主要包括三个步骤

控制 UI 上的软键盘
了解何时有新文本可用
检索用户输入文本及其状态

本文档的其余部分将详细介绍它们。有关 GameTextInput 与 GameActivity 协同工作的示例，请参阅 games-samples 代码库。

控制 UI 上的软键盘

GameActivity 提供两个函数来控制 UI 上的软键盘

GameActivity_showSoftInput() 显示软键盘。
GameActivity_hideSoftInput() 隐藏软键盘。

请参阅 API 参考文档以了解它们的定义。键盘显示后，应用程序的 UI 可能类似于以下内容

alt_text

检查文本可用性

软键盘事件从 Java 端的 GameTextInput 通过 JNI 传递到 C/C++ 端，然后传递到 GameActivity 的包装器，最后反映在 android_app::textInputState 标志中，该标志在 native_app_glue 中实现。应用程序应定期轮询此标志以执行预期处理

GameActivity 仅设置 android_app::textInputState 标志。
应用程序轮询标志并处理新 GameTextInput 事件，例如添加到输入缓冲区的新文本。
应用程序清除 android_app::textInputState。

请注意，android_app::textInputState 不会区分单个文本输入事件和多个文本输入事件。

例如，以下代码在处理应用程序周期命令、触摸事件和按键事件后轮询 textInputState 标志

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.
   }
}

检索用户输入文本

输入文本和其他状态会累积在 GameTextInput 的内部缓冲区 GameTextInput::currentState_ 中。应用程序可以使用以下方法之一来检索其内容

GameActivity 的包装器 API（推荐）
GameTextInput API

使用 GameActivity API 获取 TextInput 状态

应用程序使用典型的回调机制获取当前文本输入

实现类型为 GameTextInputGetStateCallback 的回调函数来处理文本输入事件。
如果存在一个或多个未决事件，则调用 GameActivity_getInputState()。
在处理完事件后清除 android_app::textInputState。

继续上一节中的代码片段，以下代码获取对文本输入缓冲区的引用，对其进行处理（未显示），并重置事件标志

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;
}

在上一节中显示的游戏循环中，使用上述文本输入处理程序检查并处理文本

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

应用程序可以选择使用 GameActivity_setTextInputState() 初始化 GameTextInputState 内容。

使用 GameTextInput API 获取 TextInput 状态

应用程序也可以直接使用 GameTextInput API 来检索当前 GameTextInputState

使用 GameActivity_getTextInput() 获取 GameActivity 的内部 GameTextInput 实例。
获取到 GameTextInput 实例后，调用 GameTextInput_getState() 获取相同的 GameTextInputState 内容。

再次注意，应用程序不应直接初始化 GameTextInput；GameActivity 在其初始化过程中已经执行了此操作。

回调机制与 GameActivity 的 GameActivity_getTextInputState() 函数使用的机制相同。

参考资料

在创建 GameActivity 应用程序时，开发人员可能会发现以下资源很有用

反馈

GameActivity 和 GameTextInput 都是 Jetpack 游戏库的一部分。对于任何问题，请在 Google IssueTracker 上创建一个错误报告。