Android 플랫폼 참고 사항

이 페이지에는 Android에서 Qt 애플리케이션을 빌드하고 실행하는 데 필요한 구체적인 정보가 포함되어 있습니다. 지원되는 Android 버전 및 API 레벨에 대해서는 ‘지원되는 Android 버전’을 참조하십시오.

플러그인 및 임포트 시 특별 고려 사항

애플리케이션이 다른 모듈에 의존하는 플러그인을 사용하는 경우, 해당 모듈은 애플리케이션의 종속성에 나열되어야 합니다. 자세한 내용은 ‘종속성 감지’를 참조하십시오.

Qt GUI 의존성

안드로이드 앱은 일반적으로 GUI 요소를 포함하므로, Qt for Android 플러그인은 주로 GUI를 제공하기 위해 구축되었으며, 이에 따라 다양한 QPA 추상화를 구현합니다. 결과적으로, Qt for Android 앱을 배포할 때는 Qt GUI에 대한 의존성이 예상됩니다. 또한, Qt Creator 은 Gradle 빌드 및 배포만 지원하므로, 명령줄이나 셸 실행은 기본적으로 지원되지 않는다는 점에 유의해야 합니다.

뒤로 가기 키 및 뒤로 가기 제스처

Android에서 뒤로 가기 제스처(Android 13 이상)와 시스템 뒤로 가기 키 누름은 창을 닫는 것이 아니라 탐색 요청입니다. 뒤로 가기 누름을 처리하는 항목이 없는 경우, 뒤로 가기 누름은 애플리케이션을 백그라운드로 보냅니다. 애플리케이션은 종료되지 않고 상태를 유지한 채 중단된 지점부터 다시 실행됩니다.

Qt 6.12부터는 뒤로 가기 키를 누르면 ` Activity.moveTaskToBack() `를 사용하여 애플리케이션이 백그라운드로 이동하며, 더 이상 닫기 이벤트를 전달하지 않습니다. 즉, 사용자가 뒤로 가기 키를 누를 때 ` QWidget::closeEvent() ` 및 ` Window.onClosing ` 시그널이 트리거되지 않습니다. 애플리케이션이 뒤로 가기 버튼 누름을 가로채기 위해 이러한 시그널에 의존하는 경우, 아래에 표시된 ` Shortcut ` 방식을 채택해야 합니다.

대신 애플리케이션 내에서 탐색(예: StackView 에서 페이지를 불러오는 경우)을 하려면, 뒤로 가기 키를 처리하고 이벤트를 수락하십시오. 이벤트를 수락하면 Qt가 애플리케이션을 백그라운드로 보내는 것을 막을 수 있습니다. 권장되는 방법은 Back 키 시퀀스에 바인딩된 창 수준의 단축키를 사용하는 것으로, 이는 어떤 항목에 포커스가 있든 상관없이 발동됩니다:

Shortcut {
    sequences: ["Back"]
    enabled: Qt.platform.os === "android" && stack.depth > 1
    onActivated: stack.pop()
}

Android에서는 StandardKey.Back 대신 "Back" 키 조합을 사용하십시오. 표준 키에는 Backspace 및 Alt+Left 도 바인딩되어 있으며, 이는 하드웨어 키보드에서 트리거됩니다.

스택의 최상위에서는 enabled 이 false 으로 변환되므로, 뒤로 가기 키가 정상적으로 처리되어 Qt가 애플리케이션을 백그라운드로 보냅니다. 저장되지 않은 변경 사항에 대해 먼저 경고하려면, 변경 사항이 대기 중인 동안 단축키를 활성화하고 onActivated 을 통해 확인 메시지를 표시하십시오. 변경 사항이 처리되면 단축키가 비활성화되며, 다음 뒤로 가기 키 누름 시 애플리케이션이 백그라운드로 이동합니다.

포커스가 설정된 항목도 Qt::Key_Back 를 통해 Keys.onBackPressed 를 처리할 수 있지만, 이는 해당 항목이 활성 포커스를 유지하는 동안에만 가능합니다. 터치 기반 인터페이스에서는 종종 포커스가 설정된 항목이 없기 때문에 뒤로 가기 버튼 누름 이벤트가 해당 항목에 도달하지 않습니다. 창 수준의 단축키는 포커스 여부와 관계없이 일치하므로 더 안전한 선택입니다.

OpenGL에 대한 특별 고려 사항

최신 기기들은 대개 OpenGL ES 2.0 외에도 3.0이나 3.1을 지원합니다. 적절한 OpenGL 컨텍스트를 얻으려면 QSurfaceFormat::setVersion()를 통해 요청할 버전을 설정하십시오.

알려진 문제

Qt Creator 디버깅 문제

자세한 내용은 Qt Creator 의 ‘알려진 문제’를 참조하십시오.

자동 완성

일부 기기에서 발생하는 버그로 인해, ImhNoPredictiveText 를 사용하여 예측 입력 기능을 끄면 이 속성이 무시되고 예측 입력 기능이 계속 활성화됩니다. 이 문제를 해결하려면 QT_ANDROID_ENABLE_WORKAROUND_TO_DISABLE_PREDICTIVE_TEXT 환경 변수를 1 로 설정하세요. 하지만 이 환경 변수는 Gboard와 같은 다른 키보드에 문제를 일으킬 수 있다는 부작용이 있습니다. 일본어와 같은 언어를 사용할 경우, Gboard에서는 QWERTY 키보드만 표시됩니다. 이 환경 변수는 키보드가 표시될 때마다 확인되므로, 필요에 따라 이 해결 방법을 켜고 끌 수 있습니다.

텍스트 글리프 캐싱

일부 OpenGL 드라이버의 버그로 인해, Qt가 텍스트 글리프를 캐싱하는 데 사용하는 메커니즘이 모든 Android 기기에서 예상대로 작동하지 않아 텍스트가 뒤섞여 표시될 수 있습니다. 이를 해결하기 위한 우회 방법이 마련되어 있지만, 이로 인해 메모리 소비가 증가할 수 있으며 텍스트 렌더링 성능에도 영향을 미칠 수 있습니다. 현재 이 우회 방법은 모든 기기에서 기본적으로 사용됩니다.

QT_ANDROID_DISABLE_GLYPH_CACHE_WORKAROUND 환경 변수를 1 또는 true로 설정하여 이 해결 방법을 비활성화할 수 있습니다. 단, 대상 기기 전체에서 텍스트가 올바르게 표시되는지 확인한 후에만 이 설정을 변경해야 합니다.

제한 사항

일부 Qt 모듈이나 도구에는 Android에서 지원되지 않거나 제한 사항이 있는 기능이 있을 수 있습니다. 플랫폼별 제한 사항에 대해서는 해당 모듈의 문서를 참조하십시오.