Revision control
Copy as Markdown
// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page android-platform-notes.html
\title Android Platform Notes
\ingroup android-platform-extra-topics
\previouspage Supporting Google Emoji Font Policy
\nextpage Android GNU C++ Run-time Licensing
\brief Information particular to building and running Qt applications on Android.
This page contains information particular to building and running Qt
applications on Android. See \l{android_support}{Supported Android Versions}
for what Android versions and API levels are supported.
\section1 Plugins and Imports Special Considerations
If an application uses plugins that depend on other modules, these modules
must be listed in the application's dependencies. For more information, see
\l{Dependencies Detection}.
\section2 Qt GUI Dependency
Given that Android apps typically include GUI elements, the Qt for Android
plugin is built mainly to provide a GUI, so it implements the various QPA
abstractions. As a result, deploying a Qt for Android app is expected to
involve a dependency on \l [QtGui]{Qt GUI}. Moreover, it's worth noting that Qt
Creator only supports Gradle builds and deployments, meaning that command
line or shell executions are not supported out of the box.
\section1 Back Key and Back Gesture
On Android, the back gesture (Android 13+) and the system back key
press are a navigation request, not a window close. If there is no
item that handles a back press, the back press sends the application
to the background. The application keeps its state and resumes where
it left off, instead of exiting.
Since Qt 6.12, a back press sends the application to the background using
\c{Activity.moveTaskToBack()} and no longer delivers a close event. That
means that \c{QWidget::closeEvent()} and \c{Window.onClosing} signals
do not trigger when a user presses the back key. If your application
relies on these signals to intercept back button press, the application
should adopt the \l Shortcut approach shown below.
To navigate within the application instead, such as popping a page from a
\l StackView, handle the back key and accept the event. Accepting the event
stops Qt from sending the application to the background. The recommended way
is a window-level Shortcut bound to the \c Back key sequence, which fires no
matter which item has active focus:
\qml
Shortcut {
sequences: ["Back"]
enabled: Qt.platform.os === "android" && stack.depth > 1
onActivated: stack.pop()
}
\endqml
On Android, use the \c "Back" sequence rather than \c{StandardKey.Back}. The
standard key also binds \c Backspace and \c{Alt+Left}, which a hardware
keyboard would trigger.
At the root of the stack, \c enabled becomes \c false, so the back press
falls through and Qt sends the application to the background. To warn about
unsaved changes first, enable the shortcut while changes are pending and
show a prompt from \c onActivated. Once the changes are handled, the
shortcut is disabled and the next back press sends the application to the
background.
A focused item can also handle \l{Qt::Key_Back} through
\c{Keys.onBackPressed}, but only while it holds active focus. A touch-driven
interface often leaves no item focused, so the back press never reaches it.
The window-level shortcut matches regardless of focus, so it is the safer
choice.
\section1 OpenGL Special Considerations
Modern devices often support OpenGL ES 3.0 or 3.1 in addition to 2.0. To get
a suitable OpenGL context, set the requested version via
\l{QSurfaceFormat::setVersion()}.
\note Using OpenGL ES 3.x features will result in the application breaking on older
devices that only support 2.0.
\section1 Known Issues
\section2 Qt Creator Debugging Issues
See \l{\QC: Known Issues}{Qt Creator Known Issues}
for more information.
\section2 Predictive Text
Due to a bug on some devices, when you turn off predictive text with
\c{ImhNoPredictiveText}, this property is ignored and predictive text is
still enabled. To work around this, set the
\c{QT_ANDROID_ENABLE_WORKAROUND_TO_DISABLE_PREDICTIVE_TEXT} environment
variable to \c 1. However, one side effect is that this environment variable
can cause a problem with other keyboards such as Gboard. If you use a
language like Japanese, with Gboard, only a QWERTY keyboard is displayed.
This environment variable is queried each time the keyboard is displayed,
so it's possible to toggle the workaround on and off, as necessary.
\section2 Text Glyph Caching
Because of a bug in some OpenGL drivers, the mechanism used by Qt to cache
text glyphs does not work as expected on all Android devices, causing text
to appear scrambled. To remedy this, a workaround is in place, but it can
increase memory consumption and can also affect text rendering performance.
The workaround is now used by default on all devices.
You can disable the workaround by setting the
\c QT_ANDROID_DISABLE_GLYPH_CACHE_WORKAROUND environment variable to \e 1 or
\e true. However, you should do so only after verifying that text appears
correctly on all targeted devices.
\section1 Limitations
Some of the Qt modules or tools might have features that are not supported on Android
or have limitations. See a specific module's \l{All Modules}{documentation} for any platform
limitations.
*/