Cette page a été traduite par l'API Cloud Translation.

TextInput dans GameActivity Composant d'Android Game Development Kit.

fournissant un wrapper ;
créant un indicateur de disponibilité de nouvel événement d'entrée de texte ;
utilisant directement le tampon d'état de GameTextInput pour le contenu textuel.

Comme l'illustre le diagramme suivant, les applications utilisent différents composants logiques internes pour l'entrée de texte utilisateur :

alt_text

L'utilisation de la bibliothèque GameTextInput intégrée se décompose en trois grandes étapes :

Contrôler le clavier virtuel dans l'interface utilisateur
Déterminer quand un nouveau texte est disponible
Récupérer le texte de l'entrée utilisateur et ses états

Ces étapes sont décrites en détail ci-dessous. Pour obtenir un exemple de GameTextInput avec GameActivity en action, reportez-vous au dépôt games-samples.

Contrôler le clavier virtuel dans l'interface utilisateur

GameActivity fournit deux fonctions pour contrôler le clavier virtuel dans l'interface utilisateur :

GameActivity_showSoftInput() affiche le clavier virtuel.
GameActivity_hideSoftInput() masque le clavier virtuel.

Reportez-vous à la documentation de référence de l'API pour connaître leur définition. Une fois le clavier affiché, l'UI de l'application peut se présenter comme suit :

alt_text

Vérifier la disponibilité du texte

Les événements du clavier virtuel sont transmis de GameTextInput du côté Java au côté C/C++ par le biais de la JNI, puis remontent jusqu'au wrapper de GameActivity, pour enfin se refléter dans l'indicateur android_app::textInputState implémenté dans native_app_glue. Les applications doivent interroger régulièrement cet indicateur pour effectuer le traitement souhaité :

GameActivity définit uniquement l'indicateur android_app::textInputState.
Les applications interrogent l'indicateur et traitent les nouveaux événements GameTextInput, comme le nouveau texte ajouté au tampon d'entrée.
Les applications effacent android_app::textInputState.

Notez que android_app::textInputState ne fait pas la différence entre les événements d'entrée de texte simples et multiples.

Voici un exemple simple dans lequel le code interroge l'indicateur textInputState après avoir traité des commandes de cycle d'application, des événements tactiles et des événements clés :

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

Récupérer le texte de l'entrée utilisateur

Les textes d'entrée et autres états sont accumulés dans le tampon interne de GameTextInput, GameTextInput::currentState_. Les applications peuvent utiliser l'une des méthodes suivantes pour récupérer le contenu :

API Wrapper de GameActivity (recommandé)
API GameTextInput

Obtenir l'état de TextInput avec l'API GameActivity

Les applications acquièrent l'entrée de texte actuelle via le mécanisme de rappel classique :

Implémentez une fonction de rappel de type GameTextInputGetStateCallback pour traiter des événements d'entrée de texte.
Appelez GameActivity_getInputState() lorsqu'un ou plusieurs événements sont en attente.
Une fois les événements traités, effacez android_app::textInputState.

Dans la continuité de l'extrait de la section précédente, le code suivant acquiert une référence au tampon d'entrée de texte, le traite (non illustré) et réinitialise l'indicateur d'événement :

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

Dans la boucle de jeu présentée dans la section précédente, vérifiez et traitez le texte à l'aide du gestionnaire d'entrée de texte ci-dessus :

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

Les applications peuvent aussi initialiser le contenu de GameTextInputState avec GameActivity_setTextInputState() (facultatif).

Obtenir l'état de TextInput avec l'API GameTextInput

Les applications peuvent également utiliser directement l'API GameTextInput pour récupérer l'état GameTextInputState actuel :

Utilisez GameActivity_getTextInput() pour obtenir l'instance GameTextInput interne de GameActivity.
Avec l'instance GameTextInput en main, appelez GameTextInput_getState() pour obtenir le même contenu GameTextInputState.

Encore une fois, notez que les applications ne doivent pas initialiser directement GameTextInput. GameActivity le fait déjà lors de son initialisation.

Le mécanisme de rappel est le même que celui utilisé par la fonction GameActivity_getTextInputState() de GameActivity.

Références

Les ressources suivantes peuvent être utiles aux développeurs lorsqu'ils créent des applications GameActivity :

Commentaires

GameActivity et GameTextInput font tous deux partie de la bibliothèque de jeux Jetpack. Pour tout problème ou toute question, créez un bug sur l'outil IssueTracker de Google.