TextInput na GameActivity Parte do Android Game Development Kit

A GameActivity integra a GameTextInput, executando os processos abaixo:

• Fornece um wrapper.
• Cria uma sinalização para novos eventos de entrada de texto.
• Usa o buffer de estado da GameTextInput para o conteúdo do texto.

Como mostrado no diagrama abaixo, os aplicativos usam diferentes componentes de lógica interna para processar entradas de texto do usuário:

Para usar a biblioteca GameTextInput integrada, é necessário implementar três etapas gerais:

• Controlar o teclado de software na IU.
• Saber quando um novo texto está disponível.
• Extrair o texto de entrada do usuário e os estados dele.

No restante deste documento, essas etapas vão ser explicadas em detalhes. Para ver um exemplo da GameTextInput com a GameActivity em ação, consulte o repositório games-samples (link em inglês).

Controlar o teclado de software na IU

A GameActivity oferece duas funções para controlar o teclado de software na IU:

• GameActivity_showSoftInput() mostra o teclado de software.
• GameActivity_hideSoftInput() oculta o teclado de software.

Consulte a documentação de referência da API para conferir as definições de cada uma. Quando o teclado é mostrado, a IU do app pode ficar parecida com esta:

Verificar a disponibilidade de texto

Os eventos de teclado de software são transmitidos de GameTextInput em Java para C/C++ pelo JNI. Depois disso, eles são transmitidos para o wrapper da GameActivity e, finalmente, refletidos na sinalização android_app::textInputState implementada em native_app_glue. Os apps precisam consultar essa sinalização periodicamente para realizar o processamento pretendido:

• A GameActivity só define a sinalização android_app::textInputState.
• Os apps consultam a sinalização e processam os novos eventos GameTextInput, como o novo texto adicionado ao buffer de entrada.
• Os apps limpam o android_app::textInputState.

Observe que android_app::textInputState não diferencia eventos de entrada de texto com apenas uma ou com várias palavras.

Para um exemplo simples, o código abaixo consulta a sinalização textInputState depois de processar comandos de ciclo de funcionamento do app, eventos de toque e eventos de pressionamento de tecla:

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.
   }
}

Extrair o texto da entrada do usuário

Os textos de entrada e outros estados são acumulados no buffer interno da GameTextInput, GameTextInput::currentState_. Os apps podem usar um dos abaixo processos para extrair esse conteúdo:

• Wrapper da API GameActivity (recomendado)
• API GameTextInput

Extrair o estado de TextInput da API GameActivity

Os aplicativos recebem a entrada de texto atual usando um mecanismo de callback típico:

• Implemente uma função de callback do tipo GameTextInputGetStateCallback para processar eventos de entrada de texto.
• Chame GameActivity_getInputState() quando houver um ou vários eventos pendentes.
• Limpe android_app::textInputState depois de processar os eventos.

Continuando com o snippet da seção anterior, o código abaixo recebe uma referência ao buffer de entrada de texto, processa esse texto (não demonstrado) e redefine a sinalização do evento:

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

Use o gerenciador de entrada de texto acima para consultar e processar o texto no loop de jogo apresentado na seção anterior:

if (state->textInputState) {
    GameActivity_getTextInputState(
        app->activity,
        GameTextInputGetStateCB,  // App's event handler shown above.
        &engine // Context to the GameTextInputGetStateCB function.
    );
}

Os apps podem inicializar o conteúdo GameTextInputState com GameActivity_setTextInputState().

Extrair o estado de TextInput da API GameTextInput

Os aplicativos também podem usar diretamente a API GameTextInput para extrair o GameTextInputState atual:

• Use GameActivity_getTextInput() para extrair a instância GameTextInput interna da GameActivity.
• Com a instância GameTextInput em mãos, chame GameTextInput_getState() para extrair o mesmo conteúdo de GameTextInputState.

Observe novamente que os aplicativos não podem inicializar GameTextInput diretamente. A GameActivity já faz isso durante o processo de inicialização.

O mecanismo de callback é o mesmo usado pela função GameActivity_getTextInputState() da GameActivity.

Referências

Os recursos abaixo podem ser úteis para desenvolvedores ao criar aplicativos GameActivity:

• Guia de introdução à GameActivity
• Documentação do usuário da GameTextInput
• Exemplo de agdkTunnel (em inglês)
• Documentação de referência do Jetpack para a GameActivity
• Documentação de referência do Jetpack para a GameTextInput
• Código-fonte do AGDK

Feedback

A GameActivity e a GameTextInput fazem parte da biblioteca de jogos do Jetpack. Em caso de problemas ou dúvidas, crie um relatório de bug no IssueTracker do Google.