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'istanza GameTextInput interna di GameActivity.
• Con l'istanza GameTextInput in mano, chiama GameTextInput_getState() per ricevere gli stessi contenuti di GameTextInputState.

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.