Porting to Android

Most Qt applications should be portable to Android with ease unless they depend on a specific hardware or software feature not supported by Android.

The porting approach differs depending on whether the existing application is QML or Widget based, your intended build tool, and if you are porting from a mobile or desktop application.

QML-based applications built with CMake are considered the best approach for mobile applications.

Porting from Qt desktop applications

Most of your existing Qt code should work, but you must make some decisions around your UI scalability and layout for different orientations and screen sizes. Consider a responsive layouts approach to fully take advantage of Qt Qml Applications.

There are considerations that are not directly impacted by using Qt, such as app store guidelines, theme guidelines, and others that may impact the way you develop your application. These won't be discussed here.

Adding resources

Most applications need resources. Here, we discuss how that impacts porting your application to Android.

The Qt resource system

Like most UI applications, Qt applications also depend on resources such as images, icons, translation files, and so on. These resources must be made available on the device as they are required for the application to function correctly.

The most convenient option is to bundle the resources into a qrc file, which gets built into the application binary. This approach reduces the porting effort considerably and provides faster access to the resources. It is also a cross-platform approach, which makes porting to other platforms easier.

By default, all Qt applications can access the contents of a qrc file using the ":/" prefix or the URL scheme prefix, "qrc:". To know more about qrc files and how they are handled, see the Qt Resource System.

Adding resources using the asset approach

The asset approach is the best option for better interoperability with the Android APIs. You can access all resources in the directory using the "assets:" prefix. Unlike qrc, this approach is Android-specific, not a cross-platform solution.

The asset approach with CMake

If you are new to using CMake or CMake with Qt for the first time, see Build with CMake. Here, the focus is on the steps applicable for adding resources.

You will likely want to modify a few things that are controlled by the Android Manifest file. See Qt Android Manifest File Configuration for more information on that. So you likely have already set QT_ANDROID_PACKAGE_SOURCE_DIR like so:

set_property(TARGET target_name PROPERTY QT_ANDROID_PACKAGE_SOURCE_DIR
             "${CMAKE_CURRENT_SOURCE_DIR}/android")

Once that is done, you can access your assets in your application as detailed in Assets File System.

The asset approach with qmake

To use the "assets:" approach, for example, add the following lines into the .pro file:

android {
    assets.files = images/happy.png
    assets.path = /assets/images/
    INSTALLS += assets
}

Then, you can access that image asset from C++ as follows:

QImage image("assets:/images/happy.png");

The following step-by-step instructions guide you to port an existing Qt Quick application to Android using the qrc approach:

1. Open your project in Qt Creator and select an Android kit. For more information, see Configuring Projects in Qt Creator.
2. Identify all the resources used by your application and add them to one or more qrc files. Qt Creator updates your qmake project file with the "RESOURCES" variable listing the qrc files you added.
3. To load or refer to the resources in the qrc file from your C++ code, use the "qrc:" scheme followed by the absolute URL. For example, to load the main.qml file from resources.qrc, you can use the following C++ code:

   QQuickView viewer;
   viewer.setSource(QUrl("qrc:/qml/main.qml"));
   viewer.show();

   Note: QML documents can refer to the contents in qrc files using the relative path to the document. Such references do not require the "qrc:" or ":/" prefix.

4. Deploy your application to a device or AVD. For more information, see Qt Creator: Deploying Applications to Android Devices.