TextInput w GameActivity   Część Android Game Development Kit.

GameActivity integruje GameTextInput w ten sposób:

• zapewnienie otoki,
• utworzenie flagi dostępności nowego zdarzenia wprowadzania tekstu,
• bezpośrednio za pomocą bufora stanu GameTextInput dla treści tekstowej;

Jak widać na poniższym diagramie, aplikacje używają różnych wewnętrznych komponentów logicznych do wprowadzania tekstu przez użytkownika:

Korzystanie z wbudowanej biblioteki GameTextInput obejmuje 3 główne kroki:

• Sterowanie klawiaturą ekranową w interfejsie
• wiedzieć, kiedy dostępny jest nowy tekst;
• Pobieranie tekstu wprowadzonego przez użytkownika i jego stanów

Szczegółowo opisujemy je w dalszej części tego dokumentu. Przykład użycia funkcji GameTextInput z GameActivity znajdziesz w repozytorium games-samples.

Sterowanie klawiaturą ekranową w interfejsie

GameActivity udostępnia 2 funkcje sterowania klawiaturą ekranową w interfejsie:

• GameActivity_showSoftInput() – wyświetla klawiaturę ekranową.
• GameActivity_hideSoftInput() ukrywa klawiaturę ekranową.

Definicje znajdziesz w dokumentacji referencyjnej interfejsu API. Po wyświetleniu klawiatury interfejs aplikacji może wyglądać podobnie do tego:

Sprawdzanie dostępności tekstu

Zdarzenia klawiatury ekranowej są przekazywane z GameTextInput po stronie Javy na stronę C/C++ za pomocą JNI, a następnie trafiają do otoki GameActivity, co ostatecznie znajduje odzwierciedlenie we fladze android_app::textInputState zaimplementowanej w native_app_glue. Aplikacje powinny okresowo sprawdzać ten flag, aby wykonać zamierzone przetwarzanie:

• Interfejs GameActivity ustawia tylko flagę android_app::textInputState.
• Aplikacje sprawdzają stan flagi i obsługują nowe zdarzenia GameTextInput, takie jak nowy tekst dodany do bufora wejściowego.
• Aplikacje czyszczą android_app::textInputState.

Pamiętaj, że android_app::textInputState nie rozróżnia pojedynczych i wielokrotnych zdarzeń wprowadzania tekstu.

Prosty przykład: ten kod odpytuje flagę textInputState po obsłużeniu poleceń cyklu aplikacji, zdarzeń dotykowych i zdarzeń klawiatury:

while (true) {
   // Read all pending events.
   int events;
   struct android_poll_source* source;

   while ((ALooper_pollOnce(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.
   }
}

Pobieranie tekstu wprowadzonego przez użytkownika

Teksty wejściowe i inne stany są gromadzone w wewnętrznym buforze GameTextInput, GameTextInput::currentState_. Aplikacje mogą pobierać treści na jeden z tych sposobów:

• API otoki GameActivity (zalecane)
• GameTextInput API

Pobieranie stanu TextInput za pomocą interfejsu GameActivity API

Aplikacje uzyskują bieżące dane wejściowe za pomocą typowego mechanizmu wywołania zwrotnego:

• Zaimplementuj funkcję wywołania zwrotnego typu GameTextInputGetStateCallback, aby przetwarzać zdarzenia wprowadzania tekstu.
• Wywołaj funkcję GameActivity_getInputState(), gdy występuje co najmniej 1 oczekujące zdarzenie.
• Wyczyść android_app::textInputState po przetworzeniu zdarzeń.

Kontynuując pracę z fragmentem kodu z poprzedniej sekcji, poniższy kod uzyskuje odniesienie do bufora wprowadzania tekstu, przetwarza go (nie jest to pokazane) i resetuje flagę zdarzenia:

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

W pętli gry pokazanej w poprzedniej sekcji sprawdź i przetwórz tekst za pomocą powyższego modułu obsługi wprowadzania tekstu:

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

Aplikacje mogą opcjonalnie zainicjować treść GameTextInputState za pomocą funkcji GameActivity_setTextInputState().

Pobieranie stanu TextInput za pomocą interfejsu GameTextInput API

Aplikacje mogą też bezpośrednio używać interfejsu GameTextInput API do pobierania bieżącychGameTextInputState:

• Użyj GameActivity_getTextInput(), aby uzyskać wewnętrzną instancję GameTextInput GameActivity.
• Mając instancję GameTextInput, wywołaj GameTextInput_getState(), aby uzyskać tę samą treść GameTextInputState.

Pamiętaj, że aplikacje nie powinny inicjować kodu GameTextInput bezpośrednio. GameActivity robi to już podczas procesu inicjowania.

Mechanizm wywołania zwrotnego jest taki sam jak w przypadku funkcji GameActivity_getTextInputState() w klasie GameActivity.

Pliki referencyjne

Podczas tworzenia aplikacji deweloperom mogą się przydać te materiały:GameActivity

• Pierwsze kroki z GameActivity
• Dokumentacja użytkownika GameTextInput
• Przykładowy kod agdkTunnel
• Dokumentacja referencyjna Jetpack dla GameActivity
• Dokumentacja referencyjna Jetpack dla GameTextInput
• Kod źródłowy AGDK

Opinia

GameActivity i GameTextInput są częścią biblioteki gier Jetpack. W przypadku problemów i pytań utwórz zgłoszenie błędu w Google IssueTracker.