Prototyping with the QML Runtime Tool

Qt includes the qml executable, a utility that loads and displays QML documents.

The qml utility is meant mainly for testing your QML applications and components. To launch a QML application in a production environment, often you need to develop a custom C++ application, or bundle the QML file in a module. See Deploying QML applications for more information. When given a bare Item as root element, qml will automatically create a window to show the scene. Notably, QQmlComponent::create() will not do that. Therefore, when moving from a prototype developed with qml to a C++ application, you need to either make sure the root element is a Window, or create a QQuickView in C++ to hold the root Item. But in the meantime, you can load and test parts of your prototype separately with the qml tool.

To load a .qml file, provide the file path on the command prompt:

$ qml myqmlfile.qml

To see the configuration options, run qml with the --help argument.

When the root object in the QML file that you are loading is an Item rather than a Window, it needs to be wrapped in a Window to be shown. While this work is pending, the top-level object that is already loaded is represented by a PartialScene object. The qml tool then loads additional QML files to decide what to do next: one is a configuration file that specifies in what sort of container to wrap the PartialScene. The PartialScene.container property gives a URL pointing to QML source code for the container component, which normally should declare a Window in which to wrap the Item that was loaded first. Thus, the process of wrapping an Item into a Window is programmable; and by default, these two additional QML files are loaded from resources inside the qml executable. You can list the available configurations with the --list-conf command:

$ qml --list-conf
Built-in configurations:
  default
  resizeToItem

The default configuration provides default behavior: the root Item will be resized to fill the wrapper Window at startup, and also when the user resizes the window. The alternative resizeToItem configuration works the other way around: the Item can programmatically set its own size (for example by creating bindings to its own width and height properties), and the wrapper Window will be resized to fit (subject to any limits that may be imposed by the window system). You can choose either of these using the -c or --config option:

$ qml -c resizeToItem selfResizingItem.qml

Additional configurations can be added by creating configuration directories in QStandardPaths::AppConfigLocation, each with two QML files inside: a configuration file named configuration.qml, and a QML file that declares the Item wrapper, which can have any name. If this has been done, the qml --list-conf command will also list those extra configurations, while the --verbose option will expand those to give the complete paths to those configurations, and the additional locations that were searched:

$ qml --list-conf --verbose
Built-in configurations:
  default
  resizeToItem
Other configurations:
  /home/myuser/.config/QtProject/Qml Runtime/simplest
Checked in:
  /home/myuser/.config/QtProject/Qml Runtime
  /etc/xdg/QtProject/Qml Runtime

Here is an example configuration.qml file:

import QmlRuntime.Config

Configuration {
    PartialScene {
        itemType: "QQuickItem"
        container: Qt.resolvedUrl("ItemWrapper.qml")
    }
}

And here is the simplest-possible ItemWrapper.qml that the container property could point to:

import QtQuick

Window {
    required property Item containedObject: null
    onContainedObjectChanged: {
        if (containedObject == undefined || containedObject == null) {
            visible = false;
        } else {
            containedObject.parent = contentItem;
            visible = true;
        }
    }
}

When these files have been created, you can use the qml -c option giving the name of the directory containing the configuration.qml file, which specifies the path to the container object:

$ qml -c simplest mycomponent.qml

The qml runtime will directly set the containedObject property, which is required to have that name; and when it is set, the Item will be reparented to the Window and shown. Since this Window is declared in QML, when you write your own wrapper window, you are free to add whatever additional features you would like: to handle resizing in a customized way, or to add capabilities that you may find useful during prototyping.

Regardless of what was found in AppConfigLocation, you can alternatively use the qml -c option giving the complete path to the configuration.qml file, and it can in turn specify the complete path to the container object; so these files can be located anywhere.

In addition to the features that can be declared in the configuration files, the qml tool also provides a few more features via command-line options. Use the --help option to get an up-to-date list.