Embedding QML: Why, Where, and How

05.11.2015 Laurent Montel and Andy Gryc 7 comments

If you’re already using QML in Qt, you know that it can help quickly create flexible user interfaces using little or no C++ programming. With a basic text file and some JavaScript logic, you can put together a pretty sophisticated interface like that shown in the Qt Quick Clock demo (below) with a minimum of fuss. But did you know you can compress your plainly readable QML and hide it away inside a binary?

Figure 1: Qt Quick Clock screen

If substantial portions of the application are in a plain text file, they could be examined or modified by the user. That’s a concern if your UX contains sensitive information. Perhaps you want to remove any temptation to “tinker” with the interface, ensuring there are no unnecessary support calls. Is there any opportunity to more tightly bundle those QML resources along with the executable? Thankfully, the answer is a resounding “yes”.

Standard Qt resources—icons, bitmaps, audio files, translation tables, etc—can be compressed and linked to the executable, allowing you to create a distribution with fewer external dependencies. Not only is this simpler to manage for versioning and installation, but it provides a measure of confidence that your application will always have the resources it depends on to run properly.

With just a bit of creativity, the Qt resource capability can also be used to insert QML files into an accompanying library, making the QML a bit more protected while retaining the interface definition separate from the executable. The trick is to subvert the QML plugin capability to bind your QML into the app. You still need a bit of a QML stub to get the process kicked off. However, the main logic and content gets pulled into the app through the QML plugin, turning it into an “invisible” resource.

Here’s a little example of this approach by merging the QMLExtensionPlugins and Qt Quick Clock examples so you can see this technique in action.

First of all, we insert a line in our Qt project files (src.pro) to add an “install” directory:

target.path = $$OUT_PWD/../install

Now we’ll be able to run “make install” to create our plugin. But what goes in the plugin? The plugins directory from the example contains the files needed to manage and install the Qt plugin process, so we copy those directly. Again, we need to adapt those to integrate our Clock example, so here are the files we need:

./plugins.qml
./extensionpluginsapps
./TimeExample/hour.png
./TimeExample/minute.png
./TimeExample/clock.png
./TimeExample/center.png
./TimeExample/Clock.qml
./TimeExample

Clock.qml is our QML file that we’ll incorporate into our plugin, and the png images are referenced in the QML for drawing the clock face.

We need to create a resource file that we’ll call qmlqtimeexampleplugin.qrc that pulls in our Clock.qml as well as the other resources referenced by our QML:

<RCC>
   <qresource prefix="/clock">
       <file>Clock.qml</file>
       <file>center.png</file>
       <file>clock.png</file>
       <file>hour.png</file>
       <file>minute.png</file>
   </qresource>
</RCC>

In this case, we don’t need a prefix when referring to the resource as they’re in the same directory as the QML. (If you do need to access something in a specific QtResource path, you can prepend “qrc:///<path>” to your resource name when you reference it.)

We also need to create a qmldir file in the TimeExample directory to define our module:

module TimeExample
Clock 1.0 qrc:///clock/Clock.qml
plugin qmlqtimeexampleplugin

We keep the qmldir module definition file separated from the Qt Resources so our application can find the plugin.

After handling all of the above details, and doing a build to create the plugin shared object, we’re left with the following files for the main application to use:

./extensionpluginsapps
 ./TimeExample/qmldir
 ./TimeExample/libqmlqtimeexampleplugin.so

We won’t step through the entire Qt plugin mechanism in this blog, but we will quickly review the other bits needed to take advantage of our new plugin:

• qrc lists the program resources; in this case it’s just the plugins.qml file below
• qml provides the interface to our QML resource. Of course the implementation is provided within the libqmlqtimeexampleplugin.so file that we’ve just created
• imports/plugin.cpp is the C++ implementation that ties things together

Now that we have all of the QML and plugin components in place, our main.cpp file puts the gears in motion like this:

view.setSource(QUrl(QStringLiteral("qrc:/plugins.qml")));
view.show();

We’ve now got our user interface safely encapsulated in a .so, safe from tampering, compressed for size, and bundled with all the resources it needs. No more excuses for not jumping on the QML bandwagon!