| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** Alternatively, this file may be used under the terms of the GNU Free |
| ** Documentation License version 1.3 as published by the Free Software |
| ** Foundation and appearing in the file included in the packaging of |
| ** this file. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| |
| /*! |
| \page android-platform-notes.html |
| \title Platform and Compiler Notes - Android |
| \contentspage Platform and Compiler Notes |
| |
| This page contains information particular to building Qt applications for |
| and running them on the \l{Qt for Android}{Android} platform. Qt supports |
| Android versions 4.1 (API level 16) or later. |
| |
| \tableofcontents |
| |
| \section1 Android Development in Qt Creator |
| |
| The easiest way to develop with Qt for Android is to use |
| \l{http://doc.qt.io/qtcreator/creator-developing-android.html}{Qt Creator}. When you apply |
| a \b{Qt for Android Kit} to a Qt Creator project, it will create and maintain a set of files which |
| are required to make your application run on Android. |
| |
| The files added to your project are: |
| \list |
| \li \e .java files will serve as the entry point into your application and |
| automatically load Qt to execute the native code in your application |
| \li \e AndroidManifest.xml which provides meta-information about your |
| application |
| \li Other XML files detailing the dependencies of your application |
| \li Resource files |
| \li Depending on the deployment method selected in Qt Creator, additional |
| files like libraries and QML files can be included in the project. |
| \endlist |
| |
| Qt Creator adds these files in a subdirectory of your project called \b android. The contents of |
| the \b android folder is used as basis for your app's distributable application package. |
| |
| \section1 Application Package |
| |
| On Android, apps are distributed to devices in packages called \e APK. |
| |
| For distributing apps in Google Play, a different format called AAB is used |
| instead. |
| |
| Although Qt Creator supports building both these package formats for you, you could |
| also build them manually when needed. To do so, ensure that the necessary packages |
| and build files are in place. For more detailed information about how the packaging |
| is done, see \l{Deploying an Application on Android}. |
| |
| \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. This is because Qt Creator does not know ahead |
| of time which plugins your application will end up loading. |
| |
| For example, if a plugin depends on \l{Qt Multimedia}, then the Qt Multimedia module |
| must explicitly be made a dependency of the application, otherwise the plugin cannot be |
| loaded. You can do this by adding it to the application's \c .pro file: |
| |
| \code |
| QT += multimedia |
| \endcode |
| |
| The automatic deployment tool detects any dependencies on QML modules that are imported |
| from the application's code, but in special case (for instance when QML code is generated |
| by the C++ code), this is not possible. If this generated code imports any special |
| QML modules, they are not detected by the deployment tool and therefore will |
| not be included in the application bundle. |
| |
| In these cases, you must add "dummy" QML code importing the same modules as the generated |
| code, so that the automated tool detects the dependencies. |
| |
| \section1 Text Special Considerations |
| |
| 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, which increases memory consumption and can also affect text rendering |
| performance. Before Qt 5.3.2, the workaround was enabled only for a particular set of devices. |
| It 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 \c 1. You should do so only after verifying that text appears correctly |
| on all targeted devices. |
| |
| \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 QSurfaceFormat::setVersion(). Note however that the |
| header files are only available in recent API levels, for example to include gl31.h, you need to |
| target API level 21. Keep in mind also that using OpenGL ES 3.x features will result in the |
| application breaking on older devices that only support 2.0. |
| |
| \section1 Multimedia Special Considerations |
| The \l{Qt Multimedia Widgets} module is not supported on Android, which means |
| video display is only available using the VideoOutput and the \l [QML]{QtMultimedia::}{Video} |
| QML Type. |
| |
| |
| \section1 Assets File System |
| |
| Qt for Android provides a special, virtual file system which is based on the \e assets mechanism |
| in Android. Files that are put under \e assets in the \e android folder created by Qt Creator, will |
| be packaged as part of your application package. These can be accessed in Qt by prefixing the paths |
| with \c{assets:/}. For instance, to access the image \e logo.png in the folder \e{assets/images}, |
| you can use \c QPixmap("assets:/images/logo.png"). |
| |
| If using the assets mechanism is not required for your app, the recommended way of distributing |
| resources with your Qt app is to use \l{The Qt Resource System}, which is a cross-platform mechanism |
| for distributing resources with your app. |
| |
| \section1 Supported Architectures |
| |
| Qt for Android currently has binaries for armv7a, arm64-v8a, x86 and x86-64. |
| |
| If you want to support several different ABIs in your application, the recommendation is |
| to build an Application App Bundle (AAB) containing binaries for each of the ABIs. Based on this, |
| Google Play generates optimized Application Packages (APK) for the device issuing the download |
| request. |
| |
| The Application App Bundle is generated by Qt Creator, if the corresponding checkbox for this |
| is selected in the project settings. It can also be built from the command line by using the |
| "aab" Makefile target. |
| |
| \code |
| % make aab |
| \endcode |
| |
| \section1 Known Issues |
| |
| Due to a bug on some devices, when you turn off predictive text with \c ImhNoPredictiveText, |
| this property will be ignored and predictive text will still be 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. |
| */ |