TextInput in GameActivity   Teil des Android Game Development Kit.

GameActivity bindet GameTextInput so ein:

  • und einen Wrapper bereitstellen,
  • Erstellen eines Flags für die Verfügbarkeit neuer Texteingabeereignisse
  • direkt den Statuspuffer von GameTextInput für den Textinhalt verwenden

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:

  • Bildschirmtastatur über die Benutzeroberfläche steuern
  • Wissen, wann neuer Text verfügbar ist
  • Abrufen des vom Nutzer eingegebenen Texts und seines Status

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

Bildschirmtastatur auf der Benutzeroberfläche steuern

GameActivity bietet zwei Funktionen zur Steuerung der Bildschirmtastatur auf der Benutzeroberfläche:

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

alt_text

Verfügbarkeit von Text prüfen

Ereignisse der Bildschirmtastatur werden von GameTextInput auf der Java-Seite über das JNI an die C/C++-Seite übergeben, dann an den Wrapper von GameActivity weitergeleitet und schließlich im Flag android_app::textInputState widergespiegelt, das in native_app_glue implementiert ist. Anwendungen sollten dieses Flag regelmäßig abfragen, um die gewünschte Verarbeitung durchzuführen:

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

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

Im folgenden Code wird beispielsweise das Flag textInputState abgefragt, nachdem App-Zyklusbefehle, Touch-Events und Tastenereignisse verarbeitet wurden:

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

Den vom Nutzer eingegebenen Text abrufen

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

  • 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 Callback-Funktion 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.

Ausgehend vom Snippet im vorherigen Abschnitt wird im folgenden Code ein Verweis auf den Texteingabepuffer abgerufen, verarbeitet (nicht dargestellt) und das Ereignis-Flag zurückgesetzt:

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

In der im vorherigen Abschnitt gezeigten Spielschleife können Sie Text mit dem vorherigen Texteingabe-Handler prüfen und verarbeiten:

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

Anwendungen können den Inhalt von GameTextInputState 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 dies bereits während des Initialisierungsprozesses.

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

Verweise

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. Wenn Sie Probleme oder Fragen haben, erstellen Sie einen Fehler in der Google-Problemverfolgung.