TextInput in GameActivity   Parte di Android Game Development Kit.

GameActivity integra GameTextInput:

  • fornendo un wrapper
  • creazione di un flag per la disponibilità di un nuovo evento di immissione di testo
  • utilizzando direttamente il buffer di stato di GameTextInput per i contenuti di testo

Come mostrato nel seguente diagramma, le applicazioni utilizzano diversi componenti logici interni per l'inserimento di testo da parte dell'utente:

alt_text

L'utilizzo della libreria GameTextInput integrata prevede tre passaggi generali:

  • Controllo della tastiera su schermo nell'UI
  • Sapere quando è disponibile un nuovo testo
  • Recupero del testo di input dell'utente e dei relativi stati

Il resto del documento li descrive in dettaglio. Per un esempio di GameTextInput con GameActivity in azione, consulta il repository games-samples.

Controlla la tastiera su schermo nell'UI

GameActivity fornisce due funzioni per controllare la tastiera su schermo nell'interfaccia utente:

Per le definizioni, consulta la documentazione di riferimento dell'API. Dopo la visualizzazione della tastiera, la UI dell'applicazione potrebbe essere simile alla seguente:

alt_text

Verifica la disponibilità del testo

Gli eventi della tastiera su schermo vengono passati da GameTextInput sul lato Java al lato C/C++ tramite JNI, quindi passano al wrapper di GameActivity, riflettendosi 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, ad esempio il nuovo testo aggiunto al buffer di input.
  • Le applicazioni cancellano il android_app::textInputState.

Tieni presente che android_app::textInputState non distingue tra eventi di immissione di testo singoli e multipli.

Ad esempio, il codice seguente esegue il polling del flag textInputState dopo la gestione dei comandi del ciclo dell'app, degli eventi touch e degli eventi chiave:

while (true) {
   // Read all pending events.
   int events;
   struct android_poll_source* source;

   while ((ALooper_pollOnce(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 di input dell'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 recuperare 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 di testo.
  • Chiama GameActivity_getInputState() quando sono presenti uno o più eventi in sospeso.
  • Cancella la android_app::textInputState dopo l'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 dell'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 loop di gioco mostrato nella sezione precedente, controlla ed elabora il testo con il gestore di input di testo precedente:

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 il valore corrente di GameTextInputState:

Ancora una volta, 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 per la creazione di applicazioni GameActivity:

Feedback

GameActivity e GameTextInput fanno entrambi parte della libreria di giochi Jetpack. Per eventuali problemi e domande, crea un bug su Google IssueTracker.