Android Game Development Kit 的「GameTextInput」部分。
針對編寫使用螢幕鍵盤輸入文字的全螢幕應用程式而言,運用 GameTextInput
程式庫是更為簡單的替代方案。
GameTextInput
提供簡單明瞭的 API 來顯示或隱藏螢幕鍵盤、設定或取得目前編輯過的文字,並在文字變更時接收通知。這並不適用於發展成熟的文字編輯器應用程式,但依然可為遊戲中的典型用途提供選取和編寫區域方面的支援。此外,這個程式庫支援進階輸入法編輯器 (IME) 功能,例如拼字檢查、自動完成和多鍵字元等功能。
在系統內部,GameTextInput
會在內部緩衝區 GameTextInput::currentState_
累積輸入內容文字 (以及相關狀態),並在有任何變動時通知應用程式。然後,應用程式就會在其註冊的回呼函式中執行文字處理。
適用方式
您可以藉由以下方式使用 GameTextInput
:
和 GameActivity 搭配使用:GameActivity 會和 GameTextInput 整合。使用 GameActivity 的應用程式只能使用整合過的 GameTextInput。我們有提供完整的使用說明文件,請見 GameActivity 頁面。如需 GameActivity 和 GameTextInput 整合示例,請造訪 games-samples 存放區。這個使用方式模組不在本指南的說明範圍內。
當做獨立程式庫使用:本指南其他地方有說明使用步驟。
注意,以上兩種方法可以互相搭配使用。
您可以藉由以下管道取得正式 GameTextInput
版本:
- Google Maven 有提供 Jetpack 遊戲程式庫版本
- AGDK 下載頁面有提供 ZIP 檔案版本
本指南會說明第一種使用方式。如果想使用 ZIP 檔案版本,請參見套件內附的操作說明。
設定版本
GameTextInput
會以 Android Archive (AAR) 的形式發布。這個 AAR 包含會執行 GameTextInput
原生功能的 Java 類別和 C 原始碼。您必須在建構程序中透過 Prefab
將這些來源檔案納入,如此一來系統便會將原生資料庫和原始碼提供給 CMake 專案或 NDK 建構系統。
按照 Jetpack Android Games 頁面提供的操作說明,將
GameTextInput
程式庫依附元件新增至遊戲的build.gradle
檔案。請注意,如果您的應用程式使用 GameActivity,則「無法」使用獨立的GameTextInput
程式庫。確認
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
匯入
game-text-input
套件,然後加入專案CMakeLists.txt
檔案的目標內:find_package(game-text-input REQUIRED CONFIG) ... target_link_libraries(... game-text-input::game-text-input)
在遊戲的其中一個
.cpp
檔案中加入以下行,以納入GameTextInput
實作項目:#include <game-text-input/gametextinput.cpp>
在使用
GameTextInput
C API 的來源檔案內加入標頭檔案:#include <game-text-input/gametextinput.h>
編譯並執行應用程式。如果碰到 CMake 錯誤,請確認 AAR 和
build.gradle
檔案的設定正確無誤。如果找不到#include
檔案,請檢查CMakeLists.txt
設定檔。
整合版本
透過已連接到 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); ... }
建立具有
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); }
將已建立的
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" />
將這個新的
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); }
在 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); }
在 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 建立錯誤。