qt-everywhere-src-5.15.1/qtdoc/doc/src/qmlapp/qmlscene.qdoc

/****************************************************************************
**
** 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++}.

*/