Stay organized with collections Save and categorize content based on your preferences.

Android Game Development Kit 的「GameTextInput」部分

使用 GameTextInput 程式庫是編寫全螢幕 Android 應用程式更為簡單的方式,可使用螢幕鍵盤輸入文字。

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 活動。這項操作對使用 View binding 而言簡單明瞭:

    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_showImeGameTextInput_hideIme 函式來存取顯示及隱藏輸入法編輯器的功能。

參考資料

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

意見回饋

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