TextInput in GameActivity   Parte di Android Game Development Kit.

GameActivity integra GameTextInput:

• fornendo un wrapper
• creazione di un flag per la disponibilità di nuovi eventi di input di testo
• direttamente utilizzando 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:

Esistono tre passaggi generali per utilizzare la libreria GameTextInput integrata:

• Controllare la tastiera su schermo nell'interfaccia utente
• Sapere quando è disponibile un nuovo testo
• Recuperare il testo inserito dall'utente e i relativi stati

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

Controllare la tastiera su schermo nell'interfaccia utente

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

• GameActivity_showSoftInput() visualizza la tastiera virtuale.
• GameActivity_hideSoftInput() nasconde la tastiera su schermo.

Per le definizioni, consulta la documentazione di riferimento dell'API. Dopo la visualizzazione della tastiera, la UI dell'applicazione potrebbe avere un aspetto simile al seguente:

Verificare la disponibilità del testo

Gli eventi della tastiera virtuale vengono passati da GameTextInput sul lato Java al lato C/C++ tramite JNI, quindi vengono trasferiti 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 app cancellano android_app::textInputState.

Tieni presente che android_app::textInputState non fa distinzione tra eventi di input di testo singolo e multiplo.

Per un esempio semplice, il seguente codice esegue il polling del flag textInputState dopo la gestione dei comandi del ciclo di vita dell'app, degli eventi tocco 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.
   }
}

Recuperare 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 recuperare i contenuti:

• API wrapper di GameActivity (consigliata)
• API GameTextInput

Ottenere 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 input di testo.
• Chiama GameActivity_getInputState() quando sono presenti uno o più eventi in sospeso.
• Cancella 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 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 inizializzare facoltativamente i contenuti GameTextInputState con GameActivity_setTextInputState().

Ottenere lo stato di TextInput con l'API GameTextInput

Le applicazioni possono anche utilizzare direttamente l'API GameTextInput per recuperare l'GameTextInputState attuale:

• Utilizza GameActivity_getTextInput() per ottenere l'istanza GameTextInput interna di GameActivity.
• Con l'istanza GameTextInput a portata di mano, chiama GameTextInput_getState() per ottenere gli stessi contenuti di GameTextInputState.

Ancora una volta, tieni presente che le applicazioni non devono inizializzare GameTextInput direttamente; GameActivity lo fa già durante la procedura 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:

• Guida introduttiva a GameActivity
• Documentazione utente di GameTextInput
• agdkTunnel sample
• Documentazione di riferimento di Jetpack per GameActivity
• Documentazione di riferimento di Jetpack per GameTextInput
• Codice sorgente AGDK

Feedback

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