GameTextInput Parte do Android Game Development Kit

Usar a biblioteca GameTextInput é uma alternativa mais simples na criação de um app Android em tela cheia que usa o teclado de software para entrada de texto.

A GameTextInput fornece uma API simples para mostrar ou ocultar o teclado de software, definir ou receber o texto editado no momento e receber notificações quando o texto for modificado. Ela não é destinada a apps completos de editor de texto, mas ainda oferece compatibilidade regional para seleção e composição em casos de uso típicos em jogos. Essa biblioteca também é compatível com recursos avançados de Editor de método de entrada (IME, na sigla em inglês), como verificação ortográfica, conclusões e caracteres de várias teclas.

Internamente, GameTextInput acumula o texto de entrada (com os estados relevantes) no buffer interno GameTextInput::currentState_ e notifica o app sobre quaisquer mudanças nele. Em seguida, o app executa o processamento de texto na função de callback registrada.

Disponibilidade

GameTextInput pode ser usado das seguintes maneiras:

  • Com a GameActivity: a GameActivity integra a GameTextInput. Os aplicativos que usam a GameActivity só podem usar o GameTextInput integrado. As instruções de uso estão totalmente documentadas na página da GameActivity . Para ver um exemplo de integração da GameActivity e GameTextInput, consulte o repositório games-samples. Esse modelo de uso não está no escopo deste guia.

  • Como uma biblioteca autônoma: o restante do guia descreve as etapas de uso.

Os dois métodos acima são mutuamente exclusivos.

Os lançamentos formais GameTextInput estão disponíveis nos seguintes canais:

Este guia aborda o primeiro caso de uso. Para usar a liberação de arquivos ZIP, consulte as instruções enviadas dentro do pacote.

Configurar o build

A GameTextInput é distribuída como um ARchive do Android (AAR). Esse AAR contém as classes Java e o código-fonte C, que implementa os recursos nativos de GameTextInput. Você precisa incluir esses arquivos de origem como parte do processo de build usando Prefab, que expõe bibliotecas nativas e código-fonte ao seu projeto do CMake ou build do NDK (links em inglês).

  1. Siga as instruções na página Jetpack Android Games para adicionar a dependência da biblioteca GameTextInput ao arquivo build.gradle do jogo. Se os aplicativos estiverem usando a GameActivity, eles não poderão usar a biblioteca independente GameTextInput.

  2. Verifique se gradle.properties contém as seguintes linhas:

    # 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. Importe o pacote game-text-input e adicione-o ao destino no arquivo CMakeLists.txt do projeto:

    find_package(game-text-input REQUIRED CONFIG)
    ...
    target_link_libraries(... game-text-input::game-text-input)
    
  4. Em um dos arquivos .cpp no jogo, adicione a seguinte linha para incluir a implementação de GameTextInput:

    #include <game-text-input/gametextinput.cpp>
    
  5. Nos arquivos de origem que usam a API C GameTextInput, inclua o arquivo de cabeçalho:

    #include <game-text-input/gametextinput.h>
    
  6. Compile e execute o aplicativo. Em caso de erros do CMake, verifique se o AAR e os arquivos build.gradle estão configurados corretamente. Se o arquivo #include não for encontrado, verifique seu arquivo de configuração CMakeLists.txt.

Integrar o build

  1. Na linha de execução C que já está anexada à JVM ou na linha de execução principal do app, chame GameTextInput_init com um ponteiro 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. Crie uma classe Java InputEnabledTextView com acesso 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. Adicione o InputEnabledTextView criado ao layout da interface. Por exemplo, o código a seguir em activity_main.xml pode posicioná-lo na parte de baixo da tela:

    <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. Recupere essa nova classe InputEnabledTextView para sua atividade Java. Isso é relativamente simples quando você usa a Vinculação de visualizações:

    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. Na biblioteca C, transmita inputConnection para GameTextInput_setInputConnection. Transmita um callback em GameTextInput_setEventCallback para receber notificações sobre eventos como struct de estado 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. Na biblioteca C, chame GameTextInput_processEvent, que chama internamente o callback registrado na etapa anterior para que o app processe os eventos quando o estado mudar.

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

Funções utilitárias

A biblioteca GameTextInput inclui funções utilitárias que permitem a conversão entre objetos de estado Java e estruturas de estado C. Acesse a funcionalidade para mostrar e ocultar o IME usando as funções GameTextInput_showIme e GameTextInput_hideIme.

Referências

Os desenvolvedores podem considerar as seguintes informações úteis ao criar apps com GameTextInput:

Feedback

Em caso de problemas e dúvidas sobre GameTextInput, crie um bug no Google IssueTracker.