本頁面由 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

檢查文字可用性

螢幕鍵盤事件會從 Java 端的 GameTextInput 傳遞至 C/C++ 端透過 JNI 執行，然後跳至 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.
    );
}

應用程式可選擇使用GameTextInputState GameActivity_setTextInputState()。

透過 GameTextInput API 取得 TextInput 狀態

應用程式也可以直接使用 GameTextInput API 擷取目前的 GameTextInputState:

使用 GameActivity_getTextInput() 來取得 GameActivity 的內部 GameTextInput 執行個體。
備妥 GameTextInput 例項後，呼叫 GameTextInput_getState() 即可取得相同的 GameTextInputState 內容。

同樣，應用程式不得初始化 GameTextInput ；GameActivity 已在初始化過程中執行這項動作。

回呼機制與 GameActivity 的 GameActivity_getTextInputState() 函式。

參考資料

建立下列資源時，開發人員可能會覺得下列資源有幫助： GameActivity 個應用程式：

意見回饋

GameActivity 和 GameTextInput 都是 Jetpack 遊戲程式庫的一部分。對於任何如有任何問題和疑問，請在 IssueTracker 建立錯誤。