이 페이지는 Cloud Translation API를 통해 번역되었습니다.

GameActivity의 TextInput Android Game Development Kit의 일부

GameActivity는 다음과 같은 방식으로 GameTextInput을 통합합니다.

래퍼를 제공합니다.
새 텍스트 입력 이벤트 가용성에 관한 플래그를 만듭니다.
텍스트 콘텐츠에 GameTextInput의 상태 버퍼를 직접 사용합니다.

다음 다이어그램과 같이 애플리케이션은 사용자 텍스트 입력 목적으로 다양한 내부 논리적 구성요소를 사용합니다.

alt_text

내장된 GameTextInput 라이브러리를 사용하는 단계는 일반적으로 세 가지입니다.

UI에서 소프트 키보드 제어
새 텍스트를 사용할 수 있는 경우 파악
사용자 입력 텍스트 및 상태 가져오기

이 문서의 나머지 부분에서는 이에 관해 자세히 설명합니다. GameActivity가 작동하는 GameTextInput의 예는 games-samples 저장소를 참고하세요.

UI에서 소프트 키보드 제어

GameActivity는 UI에서 소프트 키보드를 제어하는 두 가지 함수를 제공합니다.

GameActivity_showSoftInput()은 소프트 키보드를 표시합니다.
GameActivity_hideSoftInput()은 소프트 키보드를 숨깁니다.

함수 정의는 API 참조 문서를 참고하세요. 키보드가 표시된 후 애플리케이션의 UI는 다음과 같이 표시될 수 있습니다.

alt_text

텍스트 사용 가능 여부 확인

소프트 키보드 이벤트는 자바 측의 GameTextInput에서 JNI를 통해 C/C++ 측으로 전달된 후 GameActivity의 래퍼로 이동하여 마침내 native_app_glue에 구현된 android_app::textInputState 플래그에 반영됩니다. 애플리케이션은 의도된 처리를 실행하기 위해 이 플래그를 주기적으로 폴링해야 합니다.

GameActivity는 android_app::textInputState 플래그만 설정합니다.
애플리케이션은 이 플래그를 폴링하고 새 GameTextInput 이벤트(예: 입력 버퍼에 추가된 새 텍스트)를 처리합니다.
애플리케이션은 android_app::textInputState를 삭제합니다.

android_app::textInputState는 단일 텍스트 입력 이벤트와 여러 텍스트 입력 이벤트를 구별하지 않습니다.

간단한 예를 들면 다음 코드는 앱 주기 명령어, 터치 이벤트, 키 이벤트를 처리한 후 textInputState 플래그를 폴링합니다.

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

사용자 입력 텍스트 가져오기

입력 텍스트 및 기타 상태는 GameTextInput의 내부 버퍼 GameTextInput::currentState_에 누적됩니다. 애플리케이션은 다음 방법 중 하나를 사용하여 콘텐츠를 가져올 수 있습니다.

GameActivity의 래퍼 API(권장)
GameTextInput API

GameActivity API를 사용하여 TextInput 상태 가져오기

애플리케이션은 다음과 같은 일반적인 콜백 메커니즘을 사용하여 현재 텍스트 입력을 가져옵니다.

GameTextInputGetStateCallback 유형의 콜백 함수를 구현하여 텍스트 입력 이벤트를 처리합니다.
처리되지 않은 이벤트가 하나 이상 있으면 GameActivity_getInputState()를 호출합니다.
이벤트가 처리된 후 android_app::textInputState를 삭제합니다.

이전 섹션의 스니펫으로 계속 진행하면 다음 코드는 텍스트 입력 버퍼 참조를 가져와 처리하고(표시되지 않음) 이벤트 플래그를 재설정합니다.

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

이전 섹션에 표시된 게임 루프에서 위의 텍스트 입력 핸들러를 사용하여 텍스트를 확인하고 처리합니다.

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

애플리케이션은 GameActivity_setTextInputState()를 사용하여 GameTextInputState 콘텐츠를 선택적으로 초기화할 수 있습니다.

GameTextInput API를 사용하여 TextInput 상태 가져오기

애플리케이션은 다음과 같이 GameTextInput API를 직접 사용하여 현재 GameTextInputState를 가져올 수도 있습니다.

GameActivity_getTextInput()을 사용하여 GameActivity의 내부 GameTextInput 인스턴스를 가져옵니다.
GameTextInput 인스턴스를 가져왔으면 GameTextInput_getState()를 호출하여 동일한 GameTextInputState 콘텐츠를 가져옵니다.

애플리케이션은 GameTextInput을 직접 초기화해서는 안 됩니다. GameActivity가 초기화 프로세스 중에 이 작업을 이미 실행합니다.

콜백 메커니즘은 GameActivity의 GameActivity_getTextInputState() 함수에서 사용하는 것과 동일합니다.

참조

개발자는 GameActivity 애플리케이션을 만들 때 다음 리소스가 유용할 수 있습니다.

의견

GameActivity 및 GameTextInput은 모두 Jetpack 게임 라이브러리의 일부입니다. 문제나 질문이 있는 경우 Google Issue Tracker에서 버그를 작성하세요.