/****************************************************************************
**
** 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.
*/