GameActivity 中的 TextInput   Android Game Development Kit 的一部分。

GameActivity 通过以下方式集成 GameTextInput：

  • 提供封装容器
  • 创建一个标志用于指示是否有新的文本输入事件
  • 直接使用 GameTextInput 的状态缓冲区来处理文本内容

如下图所示，应用使用不同的内部逻辑组件来实现用户输入文本这一目的：

alt_text

如需使用内置 GameTextInput 库，需要完成三个主要步骤：

  • 控制界面上的软键盘
  • 有新文本时收到通知
  • 检索用户输入文本及其状态

本文档的其余部分将详细介绍这些步骤。如需查看集成了 GameActivity 的 GameTextInput 实际应用示例，请参阅 games-samples 代码库。

控制界面上的软键盘

GameActivity 提供了两个函数来控制界面上的软键盘：

如需其定义，请参阅 API 参考文档。显示键盘后，应用的界面可能如下所示：

alt_text

检查文字是否可用

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

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

检索用户输入文本

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

  • GameActivity 的封装容器 API（推荐）
  • GameTextInput API

使用 GameActivity API 获取 TextInput 状态

应用通过典型的回调机制获取当前文本输入：

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

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：

另请注意，应用不应直接初始化 GameTextInput；GameActivity 在其初始化过程中已执行此操作。

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

参考文档

开发者可能会发现以下资源有助于创建 GameActivity 应用：

反馈

GameActivity 和 GameTextInput 都是 Jetpack 游戏库的一部分。如有任何问题和疑问，请在 Google IssueTracker 上创建 bug。