GameTextInput Часть пакета разработки игр для Android .

Использование библиотеки GameTextInput — это более простая альтернатива написанию полноэкранного приложения для Android, использующего программную клавиатуру для ввода текста.

GameTextInput предоставляет простой API для отображения или скрытия программной клавиатуры, установки или получения редактируемого в данный момент текста и получения уведомлений при изменении текста. Это не предназначено для полноценных приложений текстового редактора, но по-прежнему обеспечивает поддержку выбора и создания регионов для типичных случаев использования в играх. Кроме того, эта библиотека поддерживает функции расширенного редактора методов ввода (IME) , такие как проверка орфографии, завершение и использование нескольких клавишных символов.

Внутри GameTextInput накапливает входной текст (вместе с соответствующими состояниями) во внутреннем буфере GameTextInput::currentState_ и уведомляет приложение о любых изменениях в нем. Затем приложение выполняет обработку текста в своей зарегистрированной функции обратного вызова.

Доступность

GameTextInput можно использовать следующими способами:

• Вместе с GameActivity: GameActivity интегрирует GameTextInput. Приложения, использующие GameActivity, могут использовать только встроенный GameTextInput. Инструкции по использованию полностью документированы на странице GameActivity . Пример интеграции GameActivity и GameTextInput смотрите в репозитории games-samples . Эта модель использования выходит за рамки данного руководства.

• Как автономная библиотека: остальная часть руководства описывает этапы использования.

Обратите внимание, что два вышеуказанных метода являются взаимоисключающими.

Официальные выпуски GameTextInput доступны на следующих каналах:

• Выпуск библиотеки игр Jetpack в Google Maven
• Выпуски ZIP-файлов на странице загрузки AGDK.

В этом руководстве рассматривается первый вариант использования. Чтобы использовать выпуски zip-файлов, обратитесь к инструкциям, входящим в комплект поставки.

Настройте свою сборку

GameTextInput распространяется в виде Android Archive (AAR) . Этот AAR содержит классы Java и исходный код C, который реализует собственные функции GameTextInput . Вам необходимо включить эти исходные файлы как часть процесса сборки через 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. В исходные файлы, использующие API GameTextInput C, включите файл заголовка:

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

6. Скомпилируйте и запустите приложение. Если у вас есть ошибки CMake, убедитесь, что файлы AAR и build.gradle настроены правильно. Если файл #include не найден, проверьте файл конфигурации CMakeLists.txt .

Интегрируйте свою сборку

1. Из потока C, который уже подключен к JVM, или основного потока приложения, вызовите GameTextInput_init с указателем JNIEnv .

   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. Создайте Java-класс InputEnabledTextView с доступом к InputConnection .

   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 в макет пользовательского интерфейса. Например, следующий код в 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. Доступ к функциям отображения и скрытия IME с помощью функций GameTextInput_showIme и GameTextInput_hideIme .

Ссылки

Разработчикам может быть полезно следующее при создании приложений с помощью GameTextInput :

• Тестовое приложение GameTextInput
• Используйте GameTextInput с GameActivity
• Справочный документ GameTextInput
• Исходный код GameTextInput

Обратная связь

По любым проблемам и вопросам по GameTextInput создайте ошибку в Google IssueTracker .