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:

testo_alt

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:

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:

testo_alt

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:

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:

Feedback

GameActivity e GameTextInput fanno entrambi parte della raccolta di giochi Jetpack. Per qualsiasi problema e domanda, crea un bug su Google IssueTracker.