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
- Qt Design Studio 4.7 or newer
- CMake 3.16 or newer
- Qt 6.8.0 or newer
- OpenSSL (https://github.com/KDAB/android_openssl)
- Android (min API 34) 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: 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.