Integrating C++ code with QML Entry point to Qt Quick Ultralite application

C

Building Qt Quick Ultralite application as a static library

This topic provides an instructions to build a Qt Quick Ultralite application as a static library and integrate it with an external project.

Building as a library

Qt Quick Ultralite lets you build an Qt Quick Ultralite application as a static library by using the qul_add_target CMake function. This function builds an excutable target by default, unless the STATIC_LIBRARY option is added to the arguments list. See the following example:

qul_add_target(example_app
               STATIC_LIBRARY
               source1.cpp
               source2.cpp)

Note: The static library setup cannot be compiled for Qt Quick Ultralite FreeRTOS platform configurations, but it can be built for a baremetal configuration and used with an external FreeRTOS setup. Although this approach works, it is not recommended as it may lead to unexpected behaviors.

If app_target_default_entrypoint is set up in the CMake project file, the qul_run.h header file is genearted and copied to the libraries output directory. The header contains the qul_run() function, which will be the Qt Quick Ultralite application's entrypoint.

app_target_default_entrypoint(<target> QML_PROJECT <item>)

Where, target is the target created by the qul_add_target CMake function and item is the name of QmlProject file, which will contain the Qt Quick Ultralite application's configuration.

Integrating the static library with an external project

To integrate the Qt Quick Ultralite application library with an external project, link the external project against it, along with all the used Qt Quick Ultralite libraries. Some of the library versions vary depending on the Qt Quick Ultralite configuration. The following table summarizes these library versions and their corresponding Qt Quick Ultralite configuration:

Font Engine
`MCU.Config.fontEngine == Static (default)`	`MCU.Config.fontEngine == Spark`
Qul::MonotypeUnicodeEngineShaperDisabled	CMake property/variable	`1`, `ON`, or `True`	`0`, `OFF`, or `False`
	MCU.Config.platformImageAlignment	(default) Qul::MonotypeFontEngine	Qul::MonotypeFontEngineAligned
	MCU.Config.complexTextRendering	(default) Qul::MonotypeShaperEngine Qul::MonotypeUnicodeEngine	Qul::MonotypeUnicodeEngineShaperDisabled

PNG decoder (library needed only when using PNG files)
CMake property/variable	`1`, `ON`, or `True`	`0`, `OFF`, or `False`
ImageFiles.MCU.resourceCompression	Qul::PNGDecoderLodePNG	Qul::PNGDecoderNull (default)

In addition, copy or add the Qt Quick Ultralite include path to the external project's include path. if the Qt Quick Ultralite application provides a default entrypoint, copy or add the generated qul_run.h header file path to the external project's include path.

Next, reuse the existing Qt Quick Ultralite platform abstraction code in external project, or create a new one for your target board. See Qt Quick Ultralite Platform Porting Guide for more information.

Finally, create an entrypoint function in the external project based on the Entry point to Qt Quick Ultralite application guide. When default entrypoint is used, include the qul_run.h header file and call the qul_run() function at the desired location to initialize and start the Qt Quick Ultralite engine.

Note: Qul::initHardware() won't get called if qul_run() is called with initializeHardware set to false.

After calling the qul_run() function, the control jumps to Qul::Platform::exec(), which is specific to each platform abstraction. All implementations of this function for the platform abstraction examples delivered with Qt for MCUs contain an infinite while loop. This means that the rest of the non-UI code must either be moved to the corresponding Qul::Platform::exec() implementation or it must be interrupt-based.

If external project is using RTOS, Qt Quick Ultralite could be run in separate thread. In such a case user need to provide a thread-safe interface with Qt Quick Ultralite, as the embedded event system cannot be updated directly from other threads.

See also MCU.Config.fontEngine.

Integrating C++ code with QML Entry point to Qt Quick Ultralite application

Available under certain Qt licenses.
Find out more.