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 (junto com os estados relevantes) no buffer interno GameTextInput::currentState_ e notifica o app sobre qualquer mudança nele. Em seguida, o app executa o processamento de texto na função de callback registrada.

Disponibilidade

O GameTextInput pode ser usado das seguintes maneiras:

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

  • Como uma biblioteca independente: o restante do guia descreve as etapas de uso.

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

As versões formais do GameTextInput estão disponíveis na versão da biblioteca de jogos do Jetpack no [Google Maven][google-maven]{:.external}.

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 da GameTextInput. É necessário 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 CMake ou Build do NDK.

  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. Observe que, se os aplicativos estiverem usando a GameActivity, eles não poderão usar a biblioteca GameTextInput independente.

  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 principal:

    #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 à 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 abaixo 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. Extraia 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 ser notificado sobre eventos como estrutura 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 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 achar os seguintes recursos úteis ao criar apps com GameTextInput:

Feedback

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