Actin®  Version 5.1.0 Software for Robotics Simulation and Control
Actin QML Development Reference

# Introduction

QtQuick/QML technologies provide a new mechanism for developing UIs and are quite stable now. They have a number of features (advantageous and disadvantageous) that make QML based UIs quite different from QWidget based ones. Since it's a new technology, we've introduced some basic support for QtQuick/QML projects in Actin SDK's CMake-based build system. The current development is in early stages, with limited functionalities, just enough for the target projects. However, we expect that the framework will evolve further over time into a much better and larger ecosystem.

A QML GUI is declared in QML file(s). A root level QML file is loaded in a QML engine, which is hosted in an QGLScene. Qt provides some existing forms/widgets like QQuickView, QQmlApplicationEngine, QQuickWidgetItem, etc. that implement the full functionality required to render a QML file.

This document describes the features/enhancements added to date to our build system and SDK library. It should serve as a reference for new developers intending to develop a new project or components for existing projects using QtQuick/QML technologies.

Currently, the build system primarily supports three kinds of QML enabled projects using the capabilities in our SDK framework:

• Actin Plugin (with QML interface)
• QML Application
• QML Extension Module/Plugin.

These project types and current capabilities of the Actin SDK in context of these is explained in the following sections.

# QML Applications

A QML Application is a standard QGuiApplication, which hosts a QML file to render its GUI. In the main() of the application, a root QML file is loaded into the QML Engine of a QQuickView, QQmlApplicationEngine or a similar renderer. This QML file creates the top-level GUI interface by importing and instantiating various QML elements from:

• Qt's QML Component library (Qt's QML Plugins) - e.g. QtQuick.Controls
• Actin's QML Modules (Actin QML Plugins) - e.g. Ec_Qml_QmlViewer
• Third-party QML extension modules (Third-party QML plugins) - e.g. osgViewer
• Project-specific QML Modules (Project QML Plugins)
• Additional QML/JS files in the same project.

The CMake project for such an application is same as other general executable projects developed using Actin SDK. To create a QML executable application, Qt5Core, Qt5Gui, Qt5Quick and Qt5Qml should be linked as external link libraries. Any QML files used in the project should usually be added to a resource file compiled with the application. Those QML files may also be specified in ecSourceFiles macro so that they are also displayed in the project tree.

Note
A QML-enabled executable project should have all its QML files embedded in a resource file. Loose QML files aren't supported for an application project. In case a set of loose QML files are required, consider creating a QML Extension Module for that.

# Actin Plugin

The Actin Plugins are dynamically-linked runtime libraries usually loaded using the plugin interface in Actin SDK (used heavily by Actin Viewer and ActinRT applications). Such plugins derive from Ec::Plugin and implement necessary interface to support dynamic loading into an Actin application. Some plugins may derive from Ec::PluginGUI (a derivative of Ec::Plugin) which have additional GUI capabilities using QWidget GUI framework. These plugins can show a separate dialog or a dockable widget that can be docked in the existing Actin Viewer window.

QML rendering usually requires a rendering container like QQuickView or QQmlApplicationEngine, which initialize an OpenGL context in their own window. Certain widgets like QQuickWidget also allow QML rendering in a QWidget container using certain performance-intensive techniques, which make it possible to integrate QML in a QWidget application. However, due to certain technical reasons (some conflict between existing implementation of OSG and OpenGL in GUI components of Actin SDK), QQuickWidget cannot be displayed correctly in a dockable widget, limiting QQuickWidget usage only to GUI plugins with separate dialogs.

Another alternative to using a QQuickWidget is to embed a window like QQuickView inside a QWidget using QWidget::createWindowContainer(). This approach has its own strengths, caveats and quirks. In case a dockable interface isn't required, the plugin doesn't necessarily have to be derived from Ec::PluginGUI. However, it's useful since it forces the usage of the plugin to be limited to the platforms/build with GUI capabilities and the Ec::PluginGUI interface provides some additional capabilities available only to the GUI plugins.

Just like a QML application, an Actin plugin with QML is created in the same manner as a regular GUI plugin. The plugin should be linked to the same set of libraries as specified for a QML application. The QML files can be added to a resource library compiled with the plugin binary or loaded directly from disk using appropriate CMake macros as described in CMake Macros. Just like the QML application, any QML/JS files can also be added to the project source file via ecSourceFiles macro to display them in the project tree if they are being compiled via a resource file.

# QML Extension Module/Plugin

A QML Extension Module or plugin is a set of files (binary shared libraries, QML and JavaScript files) that can be imported and dynamically loaded by a QML script. It is different from an Actin Plugin as it is independent of the Actin Viewer application and can run without the Actin Viewer or ActinRT. We would mostly create QML extensions in/using Actin SDK to wrap existing legacy C++ types into QObjects and to be able to use them appropriately in QML. Another common use is to create reusable QML components in form of binary shared libraries and/or QML files.

A QML Extension can consist one or more components including C++ shared binary libraries, QML and JavaScript (JS) files. The extension module itself is defined using a qmldir file placed in a folder path same as the plugin's type namespace under the QML imports directory. The shared binary libraries can inter-operate with other legacy binary components in an application through regular linking mechanisms. The QML files in the module package can import other QML/JS files and/or components from other QML extension modules provided that the module dependencies are also correctly defined in the qmldir file.

A QML Extension Plugin also requires definition of a class that exports the types in the plugin appropriately such that they can be loaded by the Qt Plugin Loader easily as a QML plugin from the shared library and to register the QObject types with the QML type system. A base type named EcQmlPluginHelper has been provided in qmlCore library to allow easy registration of QObject types.

The above two requirements make the CMake definition of a QML Extension project slightly different from the conventional Actin plugins. While most of the CMake macros are the same, the binary component must be generated at a different output directory and requires generation of appropriate source files as well. The QML/JS files expected to be imported by other application QML files should be copied to the output folder whenever modified. Hence, we've added some new macros to the Actin's CMake build system scripts to allow specifying such details related to the QML extension plugin, including the helper class for registering the QObject types. Also, as part of the same process, such a project is built using ecQmlExtensionPlugin instead of ecPlugin macro. These CMake macros are described with detail in CMake Macros.

Note
The module path for a QML Extension Plugin built using Actin's build system is automatically generated and is in the format Ec.<SolutionName>.<ProjectName>. The deployed files are hence located in folder bin/qmlImports/Ec/<SolutionName>/<ProjectName>.

# Related Pages:

Created by Energid Technologies www.energid.com