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

GameActivity интегрирует GameTextInput посредством:

• предоставление обертки
• создание флага доступности нового события ввода текста
• напрямую используя буфер состояния GameTextInput для текстового содержимого

Как показано на следующей диаграмме, приложения используют различные внутренние логические компоненты для ввода пользовательского текста:

Есть три основных шага к использованию встроенной библиотеки GameTextInput :

• Управление программной клавиатурой в пользовательском интерфейсе
• Знать, когда доступен новый текст
• Получение введенного пользователем текста и его состояний

В остальной части документа они описаны подробно. Пример GameTextInput с GameActivity в действии смотрите в репозитории games-samples .

Управление программной клавиатурой в пользовательском интерфейсе

GameActivity предоставляет две функции для управления программной клавиатурой в пользовательском интерфейсе:

• GameActivity_showSoftInput() отображает программную клавиатуру.
• GameActivity_hideSoftInput() скрывает программную клавиатуру.

Их определения см. в справочной документации API. После отображения клавиатуры пользовательский интерфейс приложения может выглядеть примерно так:

Проверить наличие текста

События программной клавиатуры передаются из GameTextInput на стороне Java на сторону C/C++ через JNI, затем передаются в оболочку GameActivity и, наконец, отражаются в флаге android_app::textInputState реализованном в native_app_glue . Приложения должны периодически опрашивать этот флаг для выполнения запланированной обработки:

• GameActivity устанавливает только флаг android_app::textInputState .
• Приложения опрашивают флаг и обрабатывают новые события GameTextInput , такие как новый текст, добавляемый во входной буфер.
• Приложения очищают android_app::textInputState .

Обратите внимание, что android_app::textInputState не различает одиночные и множественные события ввода текста.

В качестве простого примера следующий код опрашивает флаг textInputState после обработки команд цикла приложения, событий касания и событий клавиш:

while (true) {
   // Read all pending events.
   int events;
   struct android_poll_source* source;

   while ((ALooper_pollAll(engine.animating ? 0 : -1, nullptr, &events,
                                 (void**)&source)) >= 0) {
       // Process this event, etc.
       ...
       // Check if we are exiting.
       if (app->destroyRequested != 0) {
           engine_term_display(&engine);
           return;
       }
   }
   engine_handle_input(app);

   // Process text input events if there is any outstanding.
   if (app->textInputState) {
       // process TextInput events.
          ...
       //reset the textInputState flag
       app->textInputState = 0;
   }
   if (engine.animating) {
         // draw frames.
   }
}

Получить введенный пользователем текст

Входные тексты и другие состояния накапливаются во внутреннем буфере GameTextInput, GameTextInput::currentState_ . Приложения могут использовать один из следующих способов получения содержимого:

• API-оболочка GameActivity (рекомендуется)
• API GameTextInput

Получить состояние TextInput с помощью GameActivity API

Приложения получают текущий текстовый ввод с помощью типичного механизма обратного вызова:

• Реализуйте функцию обратного вызова типа GameTextInputGetStateCallback для обработки событий ввода текста.
• Вызовите GameActivity_getInputState() при наличии одного или нескольких невыполненных событий.
• Очистите android_app::textInputState после обработки событий.

Продолжая фрагмент из предыдущего раздела, следующий код получает ссылку на буфер ввода текста, обрабатывает ее (не показано) и сбрасывает флаг события:

extern "C" void GameTextInputGetStateCB(void *ctx, const struct GameTextInputState *state) {
    auto* engine = (struct engine*)ctx;
    if (!engine || !state) return;

    // Process the text event(s).
    LOGI("UserInputText: %s", state->text_UTF8);

    // Clear the text input flag.
    engine->app->textInputState = 0;
}

В игровом цикле, показанном в предыдущем разделе, проверьте и обработайте текст с помощью приведенного выше обработчика ввода текста:

if (state->textInputState) {
    GameActivity_getTextInputState(
        app->activity,
        GameTextInputGetStateCB,  // App's event handler shown above.
        &engine // Context to the GameTextInputGetStateCB function.
    );
}

Приложения могут дополнительно инициализировать содержимое GameTextInputState с помощью GameActivity_setTextInputState() .

Получить состояние TextInput с помощью GameTextInput API

Приложения также могут напрямую использовать GameTextInput API для получения текущего GameTextInputState :

• Используйте GameActivity_getTextInput() чтобы получить внутренний экземпляр GameTextInput GameActivity.
• Имея в наличии экземпляр GameTextInput , вызовите GameTextInput_getState() чтобы получить то же содержимое GameTextInputState .

Опять же, обратите внимание, что приложения не должны инициализировать GameTextInput напрямую; GameActivity уже делает это во время процесса инициализации.

Механизм обратного вызова тот же, что и используемый функцией GameActivity_getTextInputState() класса GameActivity.

Ссылки

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

• GameActivity, начало работы
• Пользовательская документация GameTextInput
• пример agdkTunnel
• Справочная документация Jetpack для GameActivity
• Справочная документация Jetpack для GameTextInput
• Исходный код АГДК

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

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