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:
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:
- Mit
GameActivity_showSoftInput()
wird die Bildschirmtastatur angezeigt. GameActivity_hideSoftInput()
blendet die Bildschirmtastatur aus.
Die Definitionen finden Sie in der API-Referenzdokumentation. Nachdem die Tastatur angezeigt wird, sieht die Benutzeroberfläche der Anwendung möglicherweise so aus:
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:
- Verwenden Sie
GameActivity_getTextInput()
, um die interneGameTextInput
-Instanz von GameActivity abzurufen. - Rufe mit der
GameTextInput
-InstanzGameTextInput_getState()
auf, um denselbenGameTextInputState
-Inhalt zu erhalten.
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:
- Einstieg in GameActivity
- GameTextInput-Nutzerdokumentation
- Beispiel für agdkTunnel
- Jetpack-Referenzdokumentation für GameActivity
- Jetpack-Referenzdokumentation für GameTextInput
- AGDK-Quellcode
Feedback
GameActivity und GameTextInput sind beide Teil der Jetpack-Spielebibliothek. Bei Problemen und Fragen können Sie Programmfehler im Google IssueTracker erstellen.