GameTextInput Android 游戏开发套件的组成部分。
使用 GameTextInput
库是一种更简单的替代方法,无需编写使用软键盘进行文本输入的全屏 Android 应用。
GameTextInput
提供了一个简单的 API,可用于显示或隐藏软键盘、设置或获取当前编辑的文本,以及在文本更改时接收通知。此库并非用于功能完备的文本编辑器应用,但仍可为游戏的典型用例提供选择和组合区域支持。此外,此库还支持高级输入法编辑器 (IME) 功能,例如拼写检查、补全和多键字符。
在内部,GameTextInput
会将输入文本(以及相关状态)累积到内部缓冲区 GameTextInput::currentState_
,并在发生任何更改时通知应用。然后,应用会在其注册的回调函数中执行文本处理。
可用性
GameTextInput
可以通过以下方式使用
与 GameActivity 结合使用:GameActivity 集成了 GameTextInput。使用 GameActivity 的应用只能使用集成的 GameTextInput。完整的使用说明请参阅 GameActivity 页面 。有关 GameActivity 和 GameTextInput 集成的示例,请参阅 games-samples 代码库。本指南不涉及此使用模式。
作为独立库:本指南的其余部分介绍了使用步骤。
请注意,以上两种方法互斥。
正式版 GameTextInput
通过以下渠道发布
- Google Maven 中的 Jetpack 游戏库发布版本 Google Maven
- AGDK 下载页面上的 Zip 文件发布版本
本指南涵盖第一种使用情况。如需使用 Zip 文件发布版本,请参阅软件包中附带的说明。
设置您的构建
GameTextInput
以 Android Archive (AAR) 的形式分发。此 AAR 包含 Java 类和 C 源代码,可实现 GameTextInput
的原生功能。您需要通过 Prefab
将这些源文件作为构建过程的一部分包含在内,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
添加到界面布局中。例如,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 Activity 中。使用 视图绑定时,这相对简单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
函数访问显示和隐藏 IME 的功能。
参考资料
开发者在创建使用 GameTextInput
的应用时可能会发现以下内容很有帮助
反馈
对于 GameTextInput
的任何问题和疑问,请在 Google IssueTracker 上创建 Bug。