Skip to content
Snippets Groups Projects

Qt UI Viewer

Qt UI Viewer

About

Launch Qt Design Studio projects in your Android device in seconds. Qt UI Viewer is a simple app that allows you to view your Qt Design Studio projects on your Android device. It's a great tool for designers and developers to preview their designs on a real device.

Qt UI Viewer is built with Qt for Android.

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

Code Map

  • cicd: GitLab pipeline files
  • resources: UI related files
  • android: Files needed for Android build system
  • src: All source files
  • 3rdparty: Required 3rd party libraries
    • qtquickdesigner-components: QML components
    • zxing-cpp: QR code decoding/encoding
  • assets: Play Store Assets
  • 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 or emulator and run. Then follow the instructions within the app.

Running on Android Emulator

For creating and running an Android emulator, follow the instructions on the avdmanager and emulator pages. Please also make sure that telnet is installed on your system for emulator console commands.

Android emulators run behind a virtual router and network address translation (NAT) so they can't be accessed directly from the host machine. There is one TCP port required to be forwarded in between that virtual router and the host machine so that Qt Design Studio can communicate with the application.

After creating and spinning up the emulator, you can forward the required ports to the emulator with the following command on terminal:

Note: This unfortunately needs to be repeated every time the emulator is started.

telnet localhost 5554 --> ( that will show you the file to get the auth code )
auth <auth-code>
redir add tcp:40000:40000

Then in the Qt Design Studio add a new device with the IP of 127.0.0.1

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