Prototyping with qmlscene

Qt includes qmlscene, a utility that loads and displays QML documents even before the application is complete. This utility also provides the following additional features that are useful while developing QML applications:

• View the QML document in a maximized window.
• View the QML document in full-screen mode.
• Make the window transparent.
• Disable multi-sampling (anti-aliasing).
• Do not detect the version of the .qml file.
• Run all animations in slow motion.
• Resize the window to the size of the root item.
• Add the list of import paths.
• Add a named bundle.
• Use a translation file to set the language.

The qmlscene utility is meant to be used for testing your QML applications, and not as a launcher in a production environment. To launch a QML application in a production environment, 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, qmlscene will automatically create a window to show the scene. Notably, QQmlComponent::create() will not do such a thing. Therefore, when moving from a prototype developed with qmlscene to a C++ application, you need to either make sure the root element is a Window or manually create a window using QtQuick's C++ API. On the flip side, the ability to automatically create a window gives you the option to load parts of your prototype separately with qmlscene.

To load a .qml file, run the tool and select the file to be opened, or provide the file path on the command prompt:

qmlscene myqmlfile.qml

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

Adding Module Import Paths

Additional module import paths can be provided using the -I flag. For example, the QML plugin example creates a C++ plugin identified with the namespace, TimeExample. To load the plugin, you must run qmlscene with the -I flag from the example's base directory:

qmlscene -I imports plugins.qml

This adds the current directory to the import path so that qmlscene will find the plugin in the imports directory.

Note: By default, the current directory is included in the import search path, but modules in a namespace such as TimeExample are not found unless the path is explicitly added.

Loading Test Data

Often, QML applications are prototyped with test data that is later replaced by real data sources from C++ plugins. The qmlscene utility assists in this aspect by loading test data into the application context. It looks for a directory named dummydata in the same directory as the target QML file, and loads the .qml files in that directory as QML objects and bind them to the root context as properties named after the files.

For example, the following QML document refers to a lottoNumbers property which does not exist within the document:

import QtQuick

ListView {
    width: 200; height: 300
    model: lottoNumbers
    delegate: Text { text: number }
}

If, within the document's directory, there is a dummydata directory which contains a lottoNumbers.qml file like this:

import QtQuick

ListModel {
    ListElement { number: 23 }
    ListElement { number: 44 }
    ListElement { number: 78 }
}

Then this model would be automatically loaded into the ListView in the previous document.

Child properties are included when loaded from dummydata. The following document refers to a clock.time property:

import QtQuick
Text { text: clock.time }

The text value could be filled by a dummydata/clock.qml file with a time property in the root context:

import QtQuick
QtObject { property int time: 54321 }

To replace this with real data, bind the real data object to the root context in C++ using QQmlContext::setContextProperty(). This is detailed in Integrating QML and C++.