Android Game Development Kit 的「GameTextInput」部分。

針對編寫使用螢幕鍵盤輸入文字的全螢幕應用程式而言，運用 GameTextInput 程式庫是更為簡單的替代方案。

GameTextInput 提供簡單明瞭的 API 來顯示或隱藏螢幕鍵盤、設定或取得目前編輯過的文字，並在文字變更時接收通知。這並不適用於發展成熟的文字編輯器應用程式，但依然可為遊戲中的典型用途提供選取和編寫區域方面的支援。此外，這個程式庫支援進階輸入法編輯器 (IME) 功能，例如拼字檢查、自動完成和多鍵字元等功能。

在系統內部，GameTextInput 會在內部緩衝區 GameTextInput::currentState_ 累積輸入內容文字 (以及相關狀態)，並在有任何變動時通知應用程式。然後，應用程式就會在其註冊的回呼函式中執行文字處理。

適用方式

您可以藉由以下方式使用 GameTextInput：

  • 和 GameActivity 搭配使用：GameActivity 會和 GameTextInput 整合。使用 GameActivity 的應用程式只能使用整合過的 GameTextInput。我們有提供完整的使用說明文件，請見 GameActivity 頁面。如需 GameActivity 和 GameTextInput 整合示例，請造訪 games-samples 存放區。這個使用方式模組不在本指南的說明範圍內。

  • 當做獨立程式庫使用：本指南其他地方有說明使用步驟。

注意，以上兩種方法可以互相搭配使用。

您可以藉由以下管道取得正式 GameTextInput 版本：

本指南會說明第一種使用方式。如果想使用 ZIP 檔案版本，請參見套件內附的操作說明。

設定版本

GameTextInput 會以 Android Archive (AAR) 的形式發布。這個 AAR 包含會執行 GameTextInput 原生功能的 Java 類別和 C 原始碼。您必須在建構程序中透過 Prefab 將這些來源檔案納入，如此一來系統便會將原生資料庫和原始碼提供給 CMake 專案或 NDK 建構系統。

  1. 按照 Jetpack Android Games 頁面提供的操作說明，將 GameTextInput 程式庫依附元件新增至遊戲的 build.gradle 檔案。請注意，如果您的應用程式使用 GameActivity，則「無法」使用獨立的 GameTextInput 程式庫。

  2. 確認 gradle.properties 包含下列幾行：

    # Tell Android Studio we are using AndroidX.
android.useAndroidX=true
# Use Prefab 1.1.2 or higher, which contains a fix for "header only" libs.
android.prefabVersion=1.1.2
# Required only if you're using Android Studio 4.0 (4.1 is recommended).
# android.enablePrefab=true

  3. 匯入 game-text-input 套件，然後加入專案 CMakeLists.txt 檔案的目標內：

    find_package(game-text-input REQUIRED CONFIG)
...
target_link_libraries(... game-text-input::game-text-input)

  4. 在遊戲的其中一個 .cpp 檔案中加入以下行，以納入 GameTextInput 實作項目：

    #include <game-text-input/gametextinput.cpp>

  5. 在使用 GameTextInput C API 的來源檔案內加入標頭檔案：

    #include <game-text-input/gametextinput.h>

  6. 編譯並執行應用程式。如果碰到 CMake 錯誤，請確認 AAR 和 build.gradle 檔案的設定正確無誤。如果找不到 #include 檔案，請檢查 CMakeLists.txt 設定檔。

整合版本

  1. 透過已連接到 JVM 的 C 執行緒或應用程式主執行緒，使用 JNIEnv 指標呼叫 GameTextInput_init。

    static GameTextInput* gameTextInput = nullptr;

extern "C"
JNIEXPORT void JNICALL
Java_com_gametextinput_testbed_MainActivity_onCreated(JNIEnv* env,
  jobject this) {
{
    if(!gameTextInput)
      gameTextInput = GameTextInput_init(env);
    ...
}

  2. 建立具有 InputConnection 存取權的 InputEnabledTextView Java 類別。

    public class InputEnabledTextView extends View implements Listener {
  public InputConnection mInputConnection;
  public InputEnabledTextView(Context context, AttributeSet attrs) {
    super(context, attrs);
  }

  public InputEnabledTextView(Context context) {
    super(context);
  }
  public void createInputConnection(int inputType) {
    EditorInfo editorInfo = new EditorInfo();
    editorInfo.inputType = inputType;
    editorInfo.actionId = IME_ACTION_NONE;
    editorInfo.imeOptions = IME_FLAG_NO_FULLSCREEN;
    mInputConnection = new InputConnection(this.getContext(), this,
            new Settings(editorInfo, true)
    ).setListener(this);
  }

  @Override
  public InputConnection onCreateInputConnection(EditorInfo outAttrs) {
    if (outAttrs != null) {
        GameTextInput.copyEditorInfo(mInputConnection.getEditorInfo(), outAttrs);
    }
    return mInputConnection;
  }

  // Called when the IME input changes.
  @Override
  public void stateChanged(State newState, boolean dismissed) {
    onTextInputEventNative(newState);
  }
  @Override
  public void onImeInsetsChanged(Insets insets) {
    // handle Inset changes here
  }

  private native void onTextInputEventNative(State softKeyboardEvent);
}

  3. 將已建立的 InputEnabledTextView 新增至 UI 版面配置。舉例來說，以下 activity_main.xml 中的程式碼可將其置於畫面底部：

    <com.android.example.gametextinputjava.InputEnabledTextView
    android:id="@+id/input_enabled_text_view"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    app:layout_constraintBottom_toBottomOf="parent"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintStart_toStartOf="parent" />

  4. 將這個新的 InputEnabledTextView 類別擷取至 Java 活動。如果您會使用檢視區塊繫結，則這項作業十分簡單。

    public class MainActivity extends AppCompatActivity {
  ...
  private ActivityMainBinding binding;
  private InputEnabledTextView inputEnabledTextView;

  private native void setInputConnectionNative(InputConnection c);

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    ...
    binding = ActivityMainBinding.inflate(getLayoutInflater());
    inputEnabledTextView = binding.inputEnabledTextView;
    inputEnabledTextView.createInputConnection(InputType.TYPE_CLASS_TEXT);
    setInputConnectionNative(inputEnabledTextView.mInputConnection);
  }

  5. 在 C 程式庫中，將 inputConnection 傳遞至 GameTextInput_setInputConnection。將回呼傳入 GameTextInput_setEventCallback，以接收 C 狀態結構GameTextInputState 的事件通知。

    extern "C"JNIEXPORT void JNICALL
Java_com_gametextinput_testbed_MainActivity_setInputConnectionNative(
  JNIEnv *env, jobject this, jobject inputConnection) {
  GameTextInput_setInputConnection(gameTextInput, inputConnection);
  GameTextInput_setEventCallback(gameTextInput,[](void *ctx, const GameTexgtInputState *state) {
    if (!env || !state) return;
    // process the newly arrived text input from user.
    __android_log_print(ANDROID_LOG_INFO, "TheGreateGameTextInput", state->text_UTF8);
  }, env);
}

  6. 在 C 資料庫中呼叫 GameTextInput_processEvent，令其在內部呼叫之前步驟中註冊的回呼，以便應用程式在狀態變更時處理事件。

    extern "C"
JNIEXPORT void JNICALL
Java_com_gametextinput_testbed_InputEnabledTextView_onTextInputEventNative(
  JNIEnv* env, jobject this, jobject soft_keyboard_event) {
  GameTextInput_processEvent(gameTextInput, soft_keyboard_event);
}

公用函式

GameTextInput 程式庫包含了公用函式，可讓您在 Java 狀態物件和 C 狀態結構之間進行轉換。透過 GameTextInput_showIme 和 GameTextInput_hideIme 函式來存取顯示及隱藏輸入法編輯器的功能。

參考資料

以下資源可以協助使用 GameTextInput 建立應用程式的開發人員：

意見回饋

若對 GameTextInput 有任何問題和疑問，請到 Google IssueTracker 建立錯誤。