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

GameActivity 整合 GameTextInput 指標:

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

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

alt_text

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

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

本文件其他地方會再詳細說明以上內容。如需 GameTextInputGameActivity 實際運作的範例,請前往 games-samples 存放區

在 UI 上控制螢幕鍵盤

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

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

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

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

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:

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

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

參考資料

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

意見回饋

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