| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** Alternatively, this file may be used under the terms of the GNU Free |
| ** Documentation License version 1.3 as published by the Free Software |
| ** Foundation and appearing in the file included in the packaging of |
| ** this file. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \page qtquick-qmlscene.html |
| \ingroup qtquick-tools |
| \title Prototyping with qmlscene |
| \ingroup qttools |
| \brief Utility to test and load QML files |
| |
| Qt 5 includes \c 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: |
| \list |
| \li View the QML document in a maximized window. |
| \li View the QML document in full-screen mode. |
| \li Make the window transparent. |
| \li Disable multi-sampling (anti-aliasing). |
| \li Do not detect the version of the .qml file. |
| \li Run all animations in slow motion. |
| \li Resize the window to the size of the root item. |
| \li Add the list of import paths. |
| \li Add a named bundle. |
| \li Use a translation file to set the language. |
| \endlist |
| |
| The \c 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 \l {Deploying QML |
| applications} for more information. When given a bare \l Item as root |
| element, \c qmlscene will automatically create a window to show the scene. |
| Notably, \l QQmlComponent::create() will not do such a thing. Therefore, |
| when moving from a prototype developed with \c qmlscene to a C++ |
| application, you need to either make sure the root element is a |
| \l 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 \c 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: |
| |
| \code |
| qmlscene myqmlfile.qml |
| \endcode |
| |
| To see the configuration options, run \c qmlscene with the \c -help |
| argument. |
| |
| \section1 Adding Module Import Paths |
| |
| Additional module import paths can be provided using the \c -I flag. |
| For example, the \l{QML Plugin Example}{QML plugin example} |
| creates a C++ plugin identified with the namespace, \c TimeExample. |
| To load the plugin, you must run \c qmlscene with the \c{-I} flag from the |
| example's base directory: |
| |
| \code |
| qmlscene -I imports plugins.qml |
| \endcode |
| |
| This adds the current directory to the import path so that \c qmlscene will |
| find the plugin in the \c imports directory. |
| |
| \note By default, the current directory is included in the import search |
| path, but modules in a namespace such as \c TimeExample are not found |
| unless the path is explicitly added. |
| |
| \section1 Loading Test Data |
| |
| Often, QML applications are prototyped with test data that is later |
| replaced by real data sources from C++ plugins. The \c qmlscene utility |
| assists in this aspect by loading test data into the application context. |
| It looks for a directory named \c {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 \c lottoNumbers |
| property which does not exist within the document: |
| |
| \qml |
| import QtQuick 2.3 |
| |
| ListView { |
| width: 200; height: 300 |
| model: lottoNumbers |
| delegate: Text { text: number } |
| } |
| \endqml |
| |
| If, within the document's directory, there is a \c{dummydata} directory |
| which contains a \c lottoNumbers.qml file like this: |
| |
| \qml |
| import QtQuick 2.3 |
| |
| ListModel { |
| ListElement { number: 23 } |
| ListElement { number: 44 } |
| ListElement { number: 78 } |
| } |
| \endqml |
| |
| Then this model would be automatically loaded into the ListView in the |
| previous document. |
| |
| Child properties are included when loaded from \c dummydata. The following |
| document refers to a \c clock.time property: |
| |
| \qml |
| import QtQuick 2.3 |
| Text { text: clock.time } |
| \endqml |
| |
| The text value could be filled by a \c dummydata/clock.qml file with a |
| \c time property in the root context: |
| |
| \qml |
| import QtQuick 2.3 |
| QtObject { property int time: 54321 } |
| \endqml |
| |
| To replace this with real data, bind the real data object to |
| the root context in C++ using QQmlContext::setContextProperty(). This is |
| detailed in \l{Integrating QML and C++}. |
| |
| */ |
| |