- Qt 6.8
- Prototyping with the QML Runtime Tool
- Qt 6.8.0 Reference Documentation

# 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.