TextInput in GameActivity   Teil des Android Game Development Kit.

GameActivity integriert GameTextInput durch:

  • Bereitstellung eines Wrappers
  • Erstellen eines Flags für die Verfügbarkeit neuer Texteingabeereignisse
  • direkt über den Statuspuffer von GameTextInput für den Textinhalt

Wie im folgenden Diagramm dargestellt, verwenden Anwendungen unterschiedliche interne logische Komponenten für die Eingabe von Nutzertext:

alt_text

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

  • Bildschirmtastatur in der Benutzeroberfläche steuern
  • Wissen, wann neuer Text verfügbar ist
  • Texteingabe des Nutzers und zugehörige Status abrufen

Im Rest dieses Dokuments werden sie detailliert beschrieben. Ein Beispiel für GameTextInput mit GameActivity in Aktion finden Sie im Repository mit Spielbeispielen.

Bildschirmtastatur in der Benutzeroberfläche steuern

GameActivity bietet zwei Funktionen zum Steuern der Bildschirmtastatur in 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

Verfügbarkeit von Text prüfen

Softkeyboard-Ereignisse werden von GameTextInput auf der Java-Seite über die JNI an die C/C++-Seite übergeben, dann an den Wrapper von GameActivity weitergeleitet und schließlich im Flag android_app::textInputState in native_app_glue wiedergegeben. Anwendungen sollten dieses Flag regelmäßig abfragen, um die beabsichtigte 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 Eingabepuffer hinzugefügt wurde.
  • Anwendungen löschen den android_app::textInputState.

Bei android_app::textInputState wird nicht zwischen einzelnen und mehreren Texteingabeereignissen unterschieden.

In einem einfachen Beispiel wird mit dem folgenden Code das Flag textInputState nach der Verarbeitung von App-Zyklus-Befehlen, Touch-Ereignissen und Tastaturereignissen abgefragt:

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

Text der Nutzereingabe abrufen

Die Eingabetexte und andere Status werden im internen Puffer von GameTextInput, GameTextInput::currentState_, angesammelt. Anwendungen können Inhalte auf eine der folgenden Arten abrufen:

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

TextInput-Status mit der GameActivity API abrufen

Anwendungen rufen die aktuelle Texteingabe mit dem typischen Callback-Mechanismus ab:

  • Implementieren Sie eine Rückruffunktion vom Typ GameTextInputGetStateCallback, um Texteingabeereignisse zu verarbeiten.
  • Rufen Sie GameActivity_getInputState() auf, wenn ein oder mehrere ausstehende Ereignisse vorhanden sind.
  • Löschen Sie android_app::textInputState, nachdem die Ereignisse verarbeitet wurden.

Der folgende Code setzt das Snippet aus dem vorherigen Abschnitt fort. Er ruft eine Referenz auf den Texteingabepuffer ab, verarbeitet ihn (nicht dargestellt) und setzt das Ereignisflag 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 im Spielloop aus dem vorherigen Abschnitt Text mit dem oben gezeigten Text-Input-Handler:

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

Anwendungen können den GameTextInputState-Inhalt optional mit GameActivity_setTextInputState() initialisieren.

TextInput-Status mit der GameTextInput API abrufen

Anwendungen können auch die GameTextInput API direkt verwenden, um die aktuelle GameTextInputState abzurufen:

Auch hier gilt: Anwendungen sollten GameTextInput nicht direkt initialisieren. GameActivity übernimmt das bereits während der Initialisierung.

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

Referenzen

Entwickler finden möglicherweise die folgenden Ressourcen hilfreich, wenn sie GameActivity-Anwendungen erstellen:

Feedback

GameActivity und GameTextInput sind beide Teil der Jetpack-Spielebibliothek. Bei Problemen und Fragen erstellen Sie einen Fehler in der Google-Problemverfolgung.