- Qt 5.15
- Prototyping with qmlscene
- Qt 5.15.6 Reference Documentation

# Prototyping with qmlscene

Qt 5 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 2.3

     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 2.3

     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 2.3
     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 2.3
     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++.