TextInput in GameActivity Teil des Android Game Development Kit.

GameActivity bindet GameTextInput folgendermaßen ein:

  • Bereitstellung eines Wrappers
  • Flag für die Verfügbarkeit eines neuen Texteingabeereignisses erstellen
  • direkt mit dem Statuspuffer von GameTextInput für den Textinhalt

Wie im folgenden Diagramm dargestellt, verwenden Anwendungen verschiedene interne logische Komponenten für die Texteingabe durch Nutzer:

Alt-Text

Die Verwendung der integrierten GameTextInput-Bibliothek umfasst drei grundlegende Schritte:

  • Softtastatur in der Benutzeroberfläche steuern
  • Benachrichtigung, wenn neuer Text verfügbar ist
  • Eingabetext und Status der Nutzereingabe abrufen

Im weiteren Verlauf dieses Dokuments werden diese ausführlich beschrieben. Ein Beispiel für GameTextInput mit GameActivity in Aktion findest du im games-sample-Repository.

Bildschirmtastatur für die Benutzeroberfläche steuern

GameActivity bietet zwei Funktionen zum Steuern der Bildschirmtastatur auf der Benutzeroberfläche:

Die Definitionen finden Sie in der API-Referenzdokumentation. Nachdem die Tastatur angezeigt wird, sieht die Benutzeroberfläche der Anwendung möglicherweise so aus:

Alt-Text

Textverfügbarkeit prüfen

Soft Keyboard-Ereignisse werden von GameTextInput auf der Java-Seite an die C/C++-Seite über die JNI übergeben und dann zum Wrapper von GameActivity weitergeleitet, was schließlich im Flag android_app::textInputState wiedergibt, das in native_app_glue implementiert ist. Dieses Flag sollte von Anwendungen regelmäßig abgefragt werden, um die vorgesehene Verarbeitung durchzuführen:

  • GameActivity legt nur das Flag android_app::textInputState fest.
  • Anwendungen fragen das Flag ab und verarbeiten die neuen GameTextInput-Ereignisse, z. B. den neuen Text, der dem Eingabezwischenspeicher hinzugefügt wurde.
  • Anwendungen löschen die android_app::textInputState.

Beachten Sie, dass android_app::textInputState nicht zwischen einzelnen und mehreren Texteingabeereignissen unterscheidet.

Für ein einfaches Beispiel wird mit dem folgenden Code das Flag textInputState abgefragt, nachdem App-Zyklusbefehle, Touch-Ereignisse und Schlüsselereignisse verarbeitet wurden:

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.
   }
}

Nutzereingabetext abrufen

Eingabetexte und andere Status werden im internen Zwischenspeicher GameTextInput::currentState_ von GameTextInput akkumuliert. Anwendungen können eine der folgenden Methoden verwenden, um ihren Inhalt abzurufen:

  • Wrapper API von GameActivity (empfohlen)
  • GameTextInput-API

TextInput-Status mit GameActivity API abrufen

Anwendungen erfassen die aktuelle Texteingabe mit dem typischen Callback-Mechanismus:

  • Implementieren Sie eine Callback-Funktion vom Typ GameTextInputGetStateCallback, um Texteingabeereignisse zu verarbeiten.
  • Rufen Sie GameActivity_getInputState() bei einem oder mehreren ausstehenden Ereignissen auf.
  • Löschen Sie den android_app::textInputState, nachdem die Ereignisse verarbeitet wurden.

Fahren wir fort mit dem Snippet im vorherigen Abschnitt. Im folgenden Code wird ein Verweis auf den Texteingabezwischenspeicher abgerufen, verarbeitet (nicht gezeigt) und setzt das Ereignis-Flag zurück:

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;
}

Prüfen und verarbeiten Sie in der im vorherigen Abschnitt gezeigten Spielschleife Text mit dem obigen Texteingabe-Handler:

if (state->textInputState) {
    GameActivity_getTextInputState(
        app->activity,
        GameTextInputGetStateCB,  // App's event handler shown above.
        &engine // Context to the GameTextInputGetStateCB function.
    );
}

Optional kann der GameTextInputState-Inhalt von Anwendungen mit GameActivity_setTextInputState() initialisiert werden.

TextInput-Status mit GameTextInput API abrufen

Anwendungen können die aktuelle GameTextInputState auch direkt über die GameTextInput API abrufen:

Anwendungen sollten GameTextInput nicht direkt initialisieren, da dies bei GameActivity bereits während des Initialisierungsvorgangs erfolgt.

Der Callback-Mechanismus ist derselbe, der von der GameActivity_getTextInputState()-Funktion der GameActivity verwendet wird.

Referenzen

Die folgenden Ressourcen können für Entwickler beim Erstellen von GameActivity-Anwendungen hilfreich sein:

Feedback

GameActivity und GameTextInput sind beide Teil der Jetpack-Spielebibliothek. Bei Problemen und Fragen können Sie Programmfehler im Google IssueTracker erstellen.