TextInput in GameActivity Parte del Kit di sviluppo dei giochi Android.
GameActivity integra GameTextInput tramite:
- fornendo un wrapper
- la creazione di un flag per la disponibilità di un nuovo evento di input di testo
- utilizzando direttamente il buffer di stato di GameTextInput per i contenuti testuali
Come mostrato nel seguente diagramma, le applicazioni utilizzano diversi componenti logici interni per l'input di testo dell'utente:
L'utilizzo della libreria GameTextInput
integrata prevede tre passaggi generali:
- Controllo della tastiera software nell'interfaccia utente
- Sapere quando è disponibile nuovo testo
- Recupero del testo di input dell'utente e dei relativi stati
Il resto del documento le descrive in dettaglio. Per un esempio di GameTextInput
con GameActivity
in azione, consulta il repository game-samples.
Controlla la tastiera temporanea nell'interfaccia utente
GameActivity
offre due funzioni per controllare la tastiera software nell'interfaccia utente:
GameActivity_showSoftInput()
visualizza la tastiera software.GameActivity_hideSoftInput()
nasconde la tastiera software.
Fai riferimento alla documentazione di riferimento dell'API per conoscere le relative definizioni. Dopo la visualizzazione della tastiera, l'interfaccia utente dell'applicazione potrebbe essere simile alla seguente:
Verifica la disponibilità del testo
Gli eventi della tastiera soft vengono trasferiti da GameTextInput
sul lato Java al lato C/C++ attraverso il JNI, quindi si spostano fino al wrapper di GameActivity, riflettendo infine nel flag android_app::textInputState
implementato in native_app_glue
. Le applicazioni
devono eseguire periodicamente il polling di questo flag per eseguire l'elaborazione prevista:
- GameActivity imposta solo il flag
android_app::textInputState
. - Le applicazioni eseguono il polling del flag e gestiscono i nuovi eventi
GameTextInput
, come il nuovo testo aggiunto al buffer di input. - Le applicazioni cancellano
android_app::textInputState
.
Tieni presente che android_app::textInputState
non fa distinzione tra eventi di immissione
di testo singoli e multipli.
Come semplice esempio, il seguente codice esegue il polling del flag textInputState
dopo
la gestione dei comandi del ciclo dell'app, degli eventi di tocco e degli eventi chiave:
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.
}
}
Recupera il testo inserito dall'utente
I testi di input e altri stati vengono accumulati nel buffer interno di GameTextInput, GameTextInput::currentState_
. Le applicazioni
possono utilizzare uno dei seguenti modi per recuperarne i contenuti:
- API wrapper di GameActivity (consigliata)
- API GameTextInput
Recupero dello stato di TextInput con l'API GameActivity
Le applicazioni acquisiscono l'input di testo corrente con il tipico meccanismo di callback:
- Implementa una funzione di callback di tipo
GameTextInputGetStateCallback
per elaborare gli eventi di immissione testo. - Chiama
GameActivity_getInputState()
quando sono presenti uno o più eventi in sospeso. - Cancella il segno
android_app::textInputState
al termine dell'elaborazione degli eventi.
Proseguendo con lo snippet nella sezione precedente, il seguente codice acquisisce un riferimento al buffer di input di testo, lo elabora (non mostrato) e reimposta il flag 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;
}
Nel ciclo di gioco mostrato nella sezione precedente, controlla ed elabora il testo con il gestore di input di testo riportato sopra:
if (state->textInputState) {
GameActivity_getTextInputState(
app->activity,
GameTextInputGetStateCB, // App's event handler shown above.
&engine // Context to the GameTextInputGetStateCB function.
);
}
Le applicazioni possono facoltativamente inizializzare il contenuto GameTextInputState
con
GameActivity_setTextInputState()
.
Recupero dello stato di TextInput con l'API GameTextInput
Le applicazioni possono anche utilizzare direttamente l'API GameTextInput
per recuperare l'attuale GameTextInputState
:
- Utilizza
GameActivity_getTextInput()
per recuperare l'istanzaGameTextInput
interna di GameActivity. - Con l'istanza
GameTextInput
in mano, chiamaGameTextInput_getState()
per ricevere gli stessi contenuti diGameTextInputState
.
Anche in questo caso, tieni presente che le applicazioni non devono inizializzare GameTextInput
direttamente; GameActivity
lo fa già durante il processo di inizializzazione.
Il meccanismo di callback è lo stesso utilizzato dalla funzione GameActivity_getTextInputState()
di GameActivity.
Riferimenti
Gli sviluppatori potrebbero trovare utili le seguenti risorse durante la creazione delle applicazioni GameActivity
:
- Iniziare a usare GameActivity
- Documentazione per gli utenti di GameTextInput
- Esempio di agdkTunnel
- Documentazione di riferimento per Jetpack per GameActivity
- Documentazione di riferimento per Jetpack per GameTextInput
- Codice sorgente AGDK
Feedback
GameActivity e GameTextInput fanno entrambi parte della raccolta di giochi Jetpack. Per qualsiasi problema e domanda, crea un bug su Google IssueTracker.