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

GameActivity интегрирует GameTextInput с помощью:

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

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

alt_text

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

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

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

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

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

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

alt_text

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

События виртуальной клавиатуры передаются из 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_pollOnce(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 с помощью API GameActivity

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

  • Реализуйте функцию обратного вызова типа 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 с помощью API GameTextInput

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

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

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

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

Ссылки

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

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

GameActivity и GameTextInput входят в библиотеку игр Jetpack. Если у вас возникли проблемы или вопросы, создайте баг в Google IssueTracker .