Embedding QML: Why, Where, and How

Laurent Montel,

Andy Gryc

5 November 2015

Tags

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!

7 Comments

Just a silly question, but what is the advantage of packaging inside a plugin vs just simply putting the QML files into an application resource?

If you can put in your application is great. But during my project it was not. So I embedded qml in plugin directly

Hello respected engineers. I'd like to have a deep talk with you. Say, your article is quite inspiring that I could extend from your point of view. However, Something must be wrong that I've ran into what is so frustrating at embedding static plugins in my Qt program. Try to extend this program: Modify something to make the plugin as static Qt plugin, and import it using Q_IMPORT_PLUGIN macro. Suppose that I have two of them, and I have to link the static plugin sequentially. But something strange happened. How to say.... I've created a github repository to describe my problem, I'm looking for help. https://github.com/jiangcaiyang/multiple-static-qt-plugins-link-problem

Hi Laurent, hi Andy,

let me at first thank you for writing the very interesting article. QML is missing a technique like this to hide the implementation details. There is the QML compiler for the more expensive commercial QT versions, I guess, The QML compiler is not included in the MobileDeveloper license package though.

Unfortunately, I could not follow your example with the clocks. It seems I am missing a crucial step somewhere .. . (I am using a mac, so I do not get a .so, but a .dylib libary.) In the plugins dir, I did a qmake, make, make install and got a dylib called libqmlqtimeexampleplugin.dylib. The install step copied the lib to ./install/TimeExample

Then I did a qmake, make, make install in src and I do get an application file called extensionpluginsapps.app. The install step copied this file into ./install .

But unfortunately, when I start these apps, I just get a white screen, no clocks.

Do you know what I am doing wrong ? Is there a Mac difference ?

Thanks for your help, Thomas

Hi, I don't develop on Mac. So I can't add more info about it. But it uses standard QMake code so for me it will work. Really I don't know why it doesn't work for you.

Hi, so the compilation sequence I followed is correct then, right ?

I am going to try on a Linux box now. Thanks for your help, Thomas

Hi, on a Linux machine the example works straight out of the box.

The qml code is still very easily extracted from the plugin (or even a static plugin) with a simple hex viewer. Now I am missing the difference between this approach and using a .qrc resource file, where the listed files get 'compiled' into the binary. With both systems the qml files are quite easy to read, but not easy to tinker with.

Thomas