GameActivity 的 TextInput   Android Game Development Kit 提供的一項工具

GameActivity 透過以下方式整合 GameTextInput

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

如下圖所示,應用程式在處理使用者文字輸入時,會使用不同的內部邏輯元件:

alt_text

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

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

本文件其他地方會再詳細說明以上內容。若想檢視 GameActivity 實際運作下的 GameTextInput 範例,請參閱 games-samples 存放區

在 UI 上控制螢幕鍵盤

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

如要瞭解定義的定義,請參閱「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 狀態

應用程式會使用一般回呼機制,取得目前的文字輸入內容:

接續上一節中的程式碼片段,下列程式碼會取得文字輸入內容緩衝區的參照、處理 (未顯示) 並重設事件標記:

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

同樣,應用程式不得直接初始化 GameTextInputGameActivity 已在初始化程序中執行這項動作。

回呼機制與 GameActivity 的 GameActivity_getTextInputState() 函式所使用的機制相同。

參考資料

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

意見回饋

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