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:
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:
GameActivity_showSoftInput()
muestra el teclado en pantalla.GameActivity_hideSoftInput()
oculta el teclado en pantalla.
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:
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:
- Usa
GameActivity_getTextInput()
para obtener la instancia internaGameTextInput
de GameActivity. - Con la instancia de
GameTextInput
a mano, llama aGameTextInput_getState()
para obtener el mismo contenido deGameTextInputState
.
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
:
- Cómo comenzar a usar GameActivity
- Documentación del usuario de GameTextInput
- Ejemplo de agdkTunnel
- Documentación de referencia de Jetpack para GameActivity
- Documentación de referencia de Jetpack para GameTextInput
- Código fuente de AGDK
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.