TextInput en GameActivity   Parte de Android Game Development Kit.

GameActivity integra GameTextInput de la siguiente manera:

  • Proporciona un wrapper.
  • Crea una marca para la disponibilidad de nuevos eventos de entrada de texto.
  • Usa de forma directa el búfer de estado de GameTextInput para el contenido de texto.

Como se muestra en el siguiente diagrama, las aplicaciones usan diferentes componentes lógicos internos para fines de entrada de texto del usuario:

alt_text

Hay tres pasos generales para usar la biblioteca integrada de GameTextInput:

  • Controlar el teclado en pantalla en la IU
  • Saber si hay texto nuevo disponible
  • Recuperar el texto de entrada del usuario y sus estados

En el resto de este documento, se describen en detalle. Para ver un ejemplo de GameTextInput con GameActivity en acción, consulta el repositorio games-samples.

Cómo controlar el teclado en pantalla en la IU

GameActivity proporciona dos funciones para controlar el teclado en pantalla en la IU:

Consulta los documentos de referencia de la API para conocer sus definiciones. Después de que se muestre el teclado, es posible que la IU de la aplicación se vea como la siguiente:

alt_text

Cómo comprobar la disponibilidad de texto

Los eventos de teclado en pantalla se pasan de GameTextInput en el lado de Java al lado de C/C++ a través de la JNI, luego viajan hasta el wrapper de GameActivity y, por último, se reflejan en la marca android_app::textInputState implementada en native_app_glue. Las aplicaciones deben sondear esta marca de forma periódica para realizar el procesamiento previsto:

  • GameActivity solo establece la marca android_app::textInputState.
  • Las aplicaciones sondean la marca y controlan los eventos GameTextInput nuevos, como el texto nuevo que se agregó al búfer de entrada.
  • Las aplicaciones borran el android_app::textInputState.

Ten en cuenta que android_app::textInputState no diferencia entre eventos de entrada de texto individuales y múltiples.

Para ver un ejemplo sencillo, el siguiente código sondea la marca textInputState después de controlar comandos de ciclo de la app, eventos táctiles y eventos clave:

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.
   }
}

Cómo recuperar el texto de entrada del usuario

Los textos de entrada y otros estados se acumulan en el búfer interno de GameTextInput, GameTextInput::currentState_. Las aplicaciones pueden usar uno de los siguientes métodos para recuperar su contenido:

  • API de wrapper de GameActivity (recomendada)
  • API de GameTextInput

Cómo obtener el estado de TextInput con la API de GameActivity

Las aplicaciones adquieren la entrada de texto actual con el mecanismo típico de devolución de llamada:

  • Implementa una función de devolución de llamada de tipo GameTextInputGetStateCallback para procesar eventos de entrada de texto.
  • Llama a GameActivity_getInputState() cuando haya uno o varios eventos pendientes.
  • Borra android_app::textInputState después de que se procesen los eventos.

Para continuar con el fragmento de la sección anterior, el siguiente código adquiere una referencia al búfer de entrada de texto, lo procesa (no se muestra) y restablece la marca del evento:

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;
}

En el bucle de juego que se muestra en la sección anterior, verifica y procesa el texto con el controlador de entrada de texto anterior:

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

De manera opcional, las aplicaciones pueden inicializar el contenido de GameTextInputState con GameActivity_setTextInputState().

Cómo obtener el estado de TextInput con la API de GameTextInput

Las aplicaciones también pueden usar directamente la API de GameTextInput para recuperar el objeto GameTextInputState actual:

Una vez más, ten en cuenta que las aplicaciones no deben inicializar GameTextInput directamente. GameActivity ya lo hace durante el proceso de inicialización.

El mecanismo de devolución de llamada es el mismo que usa la función GameActivity_getTextInputState() de GameActivity.

Referencias

Los siguientes recursos podrían ser útiles para los desarrolladores a la hora de crear aplicaciones de GameActivity:

Comentarios

GameActivity y GameTextInput son parte de la biblioteca de juegos de Jetpack. Si tienes problemas o preguntas, crea un error en la Herramienta de seguimiento de errores de Google.