GameTextInput   Teil des Android Game Development Kit.

Die Verwendung der Bibliothek GameTextInput ist eine einfachere Alternative zum Schreiben einer Android-App im Vollbildmodus, die die Bildschirmtastatur für die Texteingabe verwendet.

GameTextInput bietet eine einfache API, um die Bildschirmtastatur ein- oder auszublenden, den aktuell bearbeiteten Text festzulegen oder abzurufen und Benachrichtigungen zu erhalten, wenn der Text geändert wird. Sie ist nicht für vollwertige Texteditor-Apps gedacht, bietet aber Unterstützung für die Auswahl und das Verfassen von Texten für typische Anwendungsfälle in Spielen. Außerdem unterstützt diese Bibliothek erweiterte Funktionen des Eingabemethoden-Editors (IME), z. B. Rechtschreibprüfung, Vervollständigungen und Zeichen mit mehreren Tasten.

Intern akkumuliert GameTextInput den Eingabetext (zusammen mit den relevanten Status) im internen Zwischenspeicher GameTextInput::currentState_ und benachrichtigt die App über alle Änderungen darin. Die App führt dann die Textverarbeitung in ihrer registrierten Callback-Funktion aus.

Verfügbarkeit

GameTextInput kann auf folgende Weise verwendet werden:

  • Zusammen mit GameActivity: GameActivity integriert GameTextInput. Anwendungen, die GameActivity verwenden, können nur das integrierte GameTextInput verwenden. Eine vollständige Anleitung zur Verwendung finden Sie auf der GameActivity-Seite. Ein Beispiel für die Integration von GameActivity und GameTextInput finden Sie im games-samples-Repository. Dieses Nutzungsmodell wird in diesem Leitfaden nicht behandelt.

  • Als eigenständige Bibliothek: Die restlichen Schritte in diesem Leitfaden beschreiben die Verwendung.

Diese beiden Methoden schließen sich gegenseitig aus.

Formelle GameTextInput-Releases sind im Release der Jetpack-Spielebibliothek in Google Maven verfügbar.

Build einrichten

GameTextInput wird als Android-Archiv (AAR) bereitgestellt. Dieses AAR enthält die Java-Klassen und den C-Quellcode, der die nativen Funktionen von GameTextInput implementiert. Sie müssen diese Quelldateien als Teil Ihres Build-Prozesses mit Prefab einbinden, wodurch native Bibliotheken und Quellcode für Ihr CMake-Projekt oder Ihren NDK-Build verfügbar gemacht werden.

  1. Folgen Sie der Anleitung auf der Seite Jetpack Android Games, um die Bibliotheksabhängigkeit GameTextInput der Datei build.gradle Ihres Spiels hinzuzufügen. Wenn deine Anwendungen GameActivity verwenden, können sie die eigenständige GameTextInput-Bibliothek nicht verwenden.

  2. Prüfen Sie, ob gradle.properties die folgenden Zeilen enthält:

    # Tell Android Studio we are using AndroidX.
    android.useAndroidX=true
    # Use Prefab 1.1.2 or higher, which contains a fix for "header only" libs.
    android.prefabVersion=1.1.2
    # Required only if you're using Android Studio 4.0 (4.1 is recommended).
    # android.enablePrefab=true
    
  3. Importieren Sie das Paket game-text-input und fügen Sie es Ihrem Ziel in der Datei CMakeLists.txt Ihres Projekts hinzu:

    find_package(game-text-input REQUIRED CONFIG)
    ...
    target_link_libraries(... game-text-input::game-text-input)
    
  4. Fügen Sie in einer der .cpp-Dateien in Ihrem Spiel die folgende Zeile hinzu, um die GameTextInput-Implementierung einzubinden:

    #include <game-text-input/gametextinput.cpp>
    
  5. Fügen Sie in den Quelldateien, die die GameTextInput C API verwenden, die Header-Datei ein:

    #include <game-text-input/gametextinput.h>
    
  6. Kompilieren Sie die App und führen Sie sie aus. Wenn CMake-Fehler auftreten, prüfen Sie, ob die AAR- und die build.gradle-Dateien richtig eingerichtet sind. Wenn die Datei #include nicht gefunden wird, prüfen Sie die Konfigurationsdatei CMakeLists.txt.

Build einbinden

  1. Rufen Sie von Ihrem C-Thread, der bereits an die JVM angehängt ist, oder vom Hauptthread der App GameTextInput_init mit einem JNIEnv-Zeiger auf.

    static GameTextInput* gameTextInput = nullptr;
    
    extern "C"
    JNIEXPORT void JNICALL
    Java_com_gametextinput_testbed_MainActivity_onCreated(JNIEnv* env,
      jobject this) {
    {
        if(!gameTextInput)
          gameTextInput = GameTextInput_init(env);
        ...
    }
    
  2. Erstellen Sie eine InputEnabledTextView-Java-Klasse mit Zugriff auf InputConnection.

    public class InputEnabledTextView extends View implements Listener {
      public InputConnection mInputConnection;
      public InputEnabledTextView(Context context, AttributeSet attrs) {
        super(context, attrs);
      }
    
      public InputEnabledTextView(Context context) {
        super(context);
      }
      public void createInputConnection(int inputType) {
        EditorInfo editorInfo = new EditorInfo();
        editorInfo.inputType = inputType;
        editorInfo.actionId = IME_ACTION_NONE;
        editorInfo.imeOptions = IME_FLAG_NO_FULLSCREEN;
        mInputConnection = new InputConnection(this.getContext(), this,
                new Settings(editorInfo, true)
        ).setListener(this);
      }
    
      @Override
      public InputConnection onCreateInputConnection(EditorInfo outAttrs) {
        if (outAttrs != null) {
            GameTextInput.copyEditorInfo(mInputConnection.getEditorInfo(), outAttrs);
        }
        return mInputConnection;
      }
    
      // Called when the IME input changes.
      @Override
      public void stateChanged(State newState, boolean dismissed) {
        onTextInputEventNative(newState);
      }
      @Override
      public void onImeInsetsChanged(Insets insets) {
        // handle Inset changes here
      }
    
      private native void onTextInputEventNative(State softKeyboardEvent);
    }
    
  3. Fügen Sie das erstellte InputEnabledTextView zum UI-Layout hinzu. Mit dem folgenden Code in activity_main.xml kann sie beispielsweise am unteren Bildschirmrand platziert werden:

    <com.android.example.gametextinputjava.InputEnabledTextView
        android:id="@+id/input_enabled_text_view"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent" />
    
  4. Rufen Sie die InputEnabledTextView-Instanz in Ihrer Java-Aktivität ab. Das ist relativ einfach, wenn Sie View Binding verwenden:

    public class MainActivity extends AppCompatActivity {
      ...
      private ActivityMainBinding binding;
      private InputEnabledTextView inputEnabledTextView;
    
      private native void setInputConnectionNative(InputConnection c);
    
      @Override
      protected void onCreate(Bundle savedInstanceState) {
        ...
        binding = ActivityMainBinding.inflate(getLayoutInflater());
        inputEnabledTextView = binding.inputEnabledTextView;
        inputEnabledTextView.createInputConnection(InputType.TYPE_CLASS_TEXT);
        setInputConnectionNative(inputEnabledTextView.mInputConnection);
      }
    
  5. Übergeben Sie in Ihrer C-Bibliothek inputConnection an GameTextInput_setInputConnection. Übergeben Sie einen Callback in GameTextInput_setEventCallback, um über Ereignisse als C-Zustandsstruktur GameTextInputState benachrichtigt zu werden.

    extern "C"JNIEXPORT void JNICALL
    Java_com_gametextinput_testbed_MainActivity_setInputConnectionNative(
      JNIEnv *env, jobject this, jobject inputConnection) {
      GameTextInput_setInputConnection(gameTextInput, inputConnection);
      GameTextInput_setEventCallback(gameTextInput,[](void *ctx, const GameTexgtInputState *state) {
        if (!env || !state) return;
        // process the newly arrived text input from user.
        __android_log_print(ANDROID_LOG_INFO, "TheGreateGameTextInput", state->text_UTF8);
      }, env);
    }
    
  6. Rufe in deiner C-Bibliothek GameTextInput_processEvent auf. Dadurch wird intern der im vorherigen Schritt registrierte Callback aufgerufen, damit deine App Ereignisse verarbeiten kann, wenn sich der Status ändert.

    extern "C"
    JNIEXPORT void JNICALL
    Java_com_gametextinput_testbed_InputEnabledTextView_onTextInputEventNative(
      JNIEnv* env, jobject this, jobject soft_keyboard_event) {
      GameTextInput_processEvent(gameTextInput, soft_keyboard_event);
    }
    

Hilfsfunktionen

Die GameTextInput-Bibliothek enthält Dienstfunktionen, mit denen Sie zwischen Java-Zustandsobjekten und C-Zustandsstrukturen konvertieren können. Über die Funktionen GameTextInput_showIme und GameTextInput_hideIme kannst du auf die Funktionen zum Ein- und Ausblenden des IME zugreifen.

Verweise

Die folgenden Informationen können für Entwickler beim Erstellen von Apps mit GameTextInput hilfreich sein:

Feedback

Bei Problemen und Fragen zu GameTextInput können Sie einen Fehler in der Google-Problemverfolgung erstellen.