Qt UI Viewer

About

Launch Qt Design Studio projects in your Android device. The viewer that helps you do with Qt for Android.

Qt UI Viewer works with minimum Android 11 (API level 30).

Getting the App

You can get the pre-built app from either Google Play Store or Package Registry. Package registry provides the APK file for manual installation.

Prerequisites

• CMake 3.16 or newer
• Qt6.5.0 or newer
• OpenSSL (https://github.com/KDAB/android_openssl)
• Android SDK and NDK (https://developer.android.com/studio)

Code Map

• cicd: GitLab pipeline files
• resources: UI related files
• android: Files needed for Android build system
• src: Backend source files
• ui: UI source files
• 3rdparty: Required 3rd party libraries
  • qtquickdesigner-components: QML components
  • zxing-cpp: QR code decoding/encoding
• icons: App icons
• tests: Test files

Building

Build instructions are provided for Linux and macOS hosts. Windows should work as well but is not tested.

Note: If you're building in a Docker container and you've mounted the source directory into the container, you may need to change the build path pointing out somewhere out of the source directory. Otherwise you may get errors like the following; CMake Error at /opt/qt-v.6.5.0/android-arm64-v8a/lib/cmake/Qt6/QtSyncQtHelpers.cmake:235 (message): syncqt.cpp failed for module QtQuickStudioApplication: Unable to remove file ...

Note: Android build instructions can also be used on desktop (or host) for testing purposes. Just replace the CMAKE_TOOLCHAIN_FILE path with the path to your Qt host installation.

First build and install QtQuickDesigner Components for Android:

pushd 3rdparty/qtquickdesigner-components
cmake \
    -S . \
    -B build \
    -G Ninja \
    -DCMAKE_TOOLCHAIN_FILE=<qt-android-path>/lib/cmake/Qt6/qt.toolchain.cmake \
    -DCMAKE_INSTALL_PREFIX=<qt-android-path> \
    -DCMAKE_PREFIX_PATH=<qt-android-path> \
    -DANDROID_SDK_ROOT=<android-sdk-path> \
    -DANDROID_NDK_ROOT=<android-sdk-path>/ndk/<ndk-version> \
    -DANDROID_OPENSSL_PATH=<openssl-path> \
    -DFLOWVIEW_AUTO_QMLDIR=ON

cmake --build build
cmake --install build
popd

Then build the Qt UI Viewer:

cmake \
    -S . \
    -B build \
    -G Ninja \
    -DCMAKE_TOOLCHAIN_FILE=<qt-android-path>/lib/cmake/Qt6/qt.toolchain.cmake \
    -DANDROID_SDK_ROOT=<android-sdk-path> \
    -DANDROID_NDK_ROOT=<android-sdk-path>/ndk/<ndk-version> \
    -DANDROID_OPENSSL_PATH=<openssl-path> \
    -DGOOGLE_PLAY_APP_VERSION=30 \ ## see the 'Versioning' section
    -DBUILD_EXAMPLES=OFF

cmake --build build

Usage

Upload the final APK file to your Android device and run. Then follow the instructions within the app.

Testing

To run the tests a running emulator or a connected device is required. There's a helper script to run the tests under tests/scripts/run-tests.sh. To run the tests first copy the APK file to the device and then run the script. It'll extract the test results as output.junit.xml file.

Test results can be viewed with any JUnit compatible viewer. For example, you can use xunit-viewer to view the results:

npm i -g xunit-viewer
xunit-viewer -r output.junit.xml

It'll create a report.html file that can be opened in a web browser. For more information about xunit-viewer please visit the GitHub repo.

Versioning

android:versionCode is an integer value that should be incremented for each new release and it's required by Google Play Store. It's used to determine if the app should be updated or not.

During the development this value can be set to any arbitrary integer. But for the release it should be incremented. The value can be controlled by setting the CMake variable called GOOGLE_PLAY_APP_VERSION during the CMake configuration step.

It's easy for an individual developer to forget to increment it before the release. To prevent this, a GitLab pipeline is used to automatically increment this value for each new release. The pipeline is triggered by creating a new tag. The tag should be in the format of vX.Y.Z where X, Y, and Z are integers. Then the new value is determined by calculating the following formula:

android:versionCode = <total_number_of_tags> + 11

The value 11 is coming from the times where GOOGLE_PLAY_APP_VERSION was increased without creating a tag, so we have an offset in between the tag count and the actual value. From now on the value should be incremented by creating a new tag.

There's no AndroidManifest.xml file in the repository. AndroidManifest.xml.in file is used to generate the AndroidManifest.xml file during the configuration step. The versionCode value is set to the GOOGLE_PLAY_APP_VERSION and the versionName value is set to the output of the git describe --always --tags command.

Both values can be seen in the AndroidManifest.xml file after the CMake configuration step is completed.

3rd Party Libraries/Components

• zxing-cpp Apache License 2.0 ZXing C++ port for QR code decoding.

• QtQuickDesigner Components GNU GENERAL PUBLIC LICENSE QtQuickDesigner Components is a collection of QML components for Qt Quick Designer.