Revision control
++ // 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.
++
++ */