TextInput in GameActivity Parte del Android Game Development Kit.
GameActivity integra GameTextInput:
- fornendo un wrapper
- creazione di un flag per la disponibilità di un nuovo evento di input di testo
- direttamente usando il buffer di stato di GameTextInput per il contenuto testuale
Come mostrato nel seguente diagramma, le applicazioni utilizzano diversi componenti logici interni per l'inserimento di testo all'utente:
Per utilizzare la libreria GameTextInput
integrata sono previsti tre passaggi principali:
- 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 li descrive dettagliatamente. Per un esempio di
GameTextInput
con GameActivity
in azione, consulta il
repository dei giochi-samples.
Controlla la tastiera software nell'interfaccia utente
GameActivity
offre due funzioni per controllare la tastiera software nell'interfaccia utente:
GameActivity_showSoftInput()
mostra la tastiera software.GameActivity_hideSoftInput()
nasconde la tastiera software.
Per le relative definizioni, consulta la documentazione di riferimento dell'API. Dopo la visualizzazione della tastiera, l'interfaccia utente dell'applicazione potrebbe essere simile alla seguente:
Verificare la disponibilità del testo
Gli eventi della tastiera software vengono trasmessi da GameTextInput
sul lato Java al lato C/C++ tramite JNI, quindi passano al wrapper di GameActivity, per poi riflettersi nel flag android_app::textInputState
implementato in native_app_glue
. Le applicazioni
devono eseguire il polling di questo flag periodicamente 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 differenza tra eventi di input di testo
singoli e multipli.
Come semplice esempio, il codice seguente esegue il polling del flag textInputState
dopo aver gestito i comandi del ciclo dell'app, gli eventi di tocco e gli 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
Ottieni lo 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
android_app::textInputState
al termine dell'elaborazione degli eventi.
Continuando con lo snippet della 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 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 i contenuti GameTextInputState
con GameActivity_setTextInputState()
.
Ottieni lo 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 ottenere l'istanzaGameTextInput
interna di GameActivity. - Con l'istanza
GameTextInput
in mano, chiamaGameTextInput_getState()
per ricevere gli stessi contenuti diGameTextInputState
.
Anche in questo caso le applicazioni non devono inizializzare GameTextInput
direttamente, poiché 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 di applicazioni GameActivity
:
- Iniziare a utilizzare GameActivity
- Documentazione per l'utente di GameTextInput
- esempio di agdkTunnel
- Documentazione di riferimento del Jetpack per GameActivity
- Documentazione di riferimento 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 in Google IssueTracker.