本頁面由 Cloud Translation API 翻譯而成。

GameActivity 的 TextInput 由 Android Game Development Kit 提供

GameActivity 透過以下方式整合 GameTextInput：

提供包裝函式
為新的文字輸入事件可用性建立旗標
直接使用 GameTextInput 進行文字內容的緩衝處理

如以下圖表所示，應用程式會使用不同的內部邏輯元件，以便處理使用者的文字輸入內容：

alt_text

以下是內建 GameTextInput 程式庫的三個主要步驟：

在 UI 上控制螢幕鍵盤
瞭解何時有新文字
擷取使用者輸入內容文字及其狀態

本文件其他地方會再詳細說明以上內容。如需 GameTextInput 與 GameActivity 實際運作的範例，請參閱「games-samples 存放區」。

在 UI 上控制螢幕鍵盤

GameActivity 提供兩種在 UI 上控制螢幕鍵盤的功能：

GameActivity_showSoftInput() 會顯示螢幕鍵盤。
GameActivity_hideSoftInput() 會隱藏螢幕鍵盤。

如要瞭解定義的定義，請參閱「API 參考說明文件」。顯示鍵盤後，應用程式的 UI 看起來可能類似以下內容：

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_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 遊戲庫的一部分。如有任何問題和疑問，請在 IssueTracker 上建立錯誤。