GameTextInput   Componente di Android Game Development Kit.

L'utilizzo della libreria GameTextInput è un'alternativa più semplice alla scrittura di un'app Android a schermo intero che utilizza la tastiera virtuale per l'inserimento di testo.

GameTextInput fornisce un'API semplice per mostrare o nascondere la tastiera virtuale, impostare o recuperare il testo attualmente modificato e ricevere notifiche quando il testo viene modificato. Non è pensato per app di editor di testo complete, ma fornisce comunque il supporto per la selezione e la composizione delle regioni per i casi d'uso tipici nei giochi. Inoltre, questa libreria supporta funzionalità avanzate dell'editor di metodi di inserimento (IME), come la verifica ortografica, le composizioni e i caratteri con più tasti.

All'interno, GameTextInput accumula il testo inserito (insieme agli stati pertinenti) nel buffer interno GameTextInput::currentState_ e comunica all'app eventuali modifiche. L'app esegue quindi l'elaborazione del testo nella sua funzione di callback registrata.

Disponibilità

GameTextInput può essere utilizzato nei seguenti modi:

  • Insieme a GameActivity: GameActivity integra GameTextInput. Le applicazioni che utilizzano GameActivity possono utilizzare solo GameTextInput integrato. Le istruzioni per l'utilizzo sono completamente documentate nella pagina GameActivity . Per un esempio di integrazione di GameActivity e GameTextInput, consulta il repository games-samples. Questo modello di utilizzo non rientra nell'ambito di questa guida.

  • Come libreria autonoma: il resto della guida descrive i passaggi per l'utilizzo.

Tieni presente che i due metodi sopra indicati sono mutuamente esclusivi.

Le release GameTextInput formali sono disponibili nella release della libreria Jetpack Games in [Google Maven][google-maven]{:.external}.

Configura la build

GameTextInput viene distribuito come archivio Android (AAR). Questo file AAR contiene le classi Java e il codice sorgente C, che implementa le funzionalità native di GameTextInput. Devi includere questi file sorgente durante il processo di compilazione tramite Prefab, che espone le librerie native e il codice sorgente al progetto CMake o alla compilazione NDK.

  1. Segui le istruzioni riportate nella pagina Jetpack Android Games per aggiungere la dipendenza della libreria GameTextInput al file build.gradle del tuo gioco. Tieni presente che se le tue applicazioni utilizzano GameActivity, non possono utilizzare la libreria GameTextInput autonoma.

  2. Assicurati che gradle.properties contenga le seguenti righe:

    # 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. Importa il pacchetto game-text-input e aggiungilo al target nel file CMakeLists.txt del progetto:

    find_package(game-text-input REQUIRED CONFIG)
...
target_link_libraries(... game-text-input::game-text-input)

  4. In uno dei file .cpp del tuo gioco, aggiungi la seguente riga per includere l'implementazione di GameTextInput:

    #include <game-text-input/gametextinput.cpp>

  5. Nei file di origine che utilizzano l'API C GameTextInput, includi il file di intestazione:

    #include <game-text-input/gametextinput.h>

  6. Compila ed esegui l'app. Se si verificano errori CMake, verifica che i file AAR e build.gradle siano configurati correttamente. Se il file #include non viene trovato, verifica il file di configurazione CMakeLists.txt.

Integra la build

  1. Dal thread C già collegato alla JVM o dal thread principale dell'app, chiama GameTextInput_init con un puntatore JNIEnv.

    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. Crea una classe Java InputEnabledTextView con accesso a 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. Aggiungi il InputEnabledTextView creato al layout dell'interfaccia utente. Ad esempio, il seguente codice in activity_main.xml può posizionarlo nella parte inferiore dello schermo:

    <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. Recupera questa nuova classe InputEnabledTextView nella tua attività Java. È relativamente semplice se utilizzi View Binding:

    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. Nella libreria C, passa inputConnection a GameTextInput_setInputConnection. Passa un callback in GameTextInput_setEventCallback per ricevere una notifica degli eventi come struttura dello stato C GameTextInputState.

    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. Nella libreria C, chiama GameTextInput_processEvent , che chiama internamente il tuo callback registrato nel passaggio precedente, per consentire alla tua app di gestire gli eventi quando cambia lo stato.

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

Funzioni di utilità

La libreria GameTextInput include funzioni di utilità che consentono di eseguire la conversione tra oggetti stato Java e strutture stato C. Accedi alla funzionalità per mostrare e nascondere l'IME tramite le funzioni GameTextInput_showIme e GameTextInput_hideIme.

Riferimenti

Gli sviluppatori potrebbero trovare utile quanto segue quando creano app con GameTextInput:

Feedback

Per eventuali problemi e domande relativi a GameTextInput, crea un bug su Google IssueTracker.