Add qml runtime tool documentation

qmlscene is deprecated.  Much of the same information has been
applicable to the qml runtime tool for a number of years already;
however that wasn't documented until now.

We remove the information about the --dummy-data argument because
it's a means of injecting context properties, which are deprecated.

Information about the -I imports option is temporarily omitted
because it was deemed somewhat confusing (although still applicable).

Task-number: QTBUG-53219
Task-number: QTBUG-96800
Change-Id: I12370d523d43f7ea6ca4ce3ff1ceb8431d87a889
Reviewed-by: Ulf Hermann <ulf.hermann@qt.io>
(cherry picked from commit eb630974940420a6e01e47cebadf343390e6759c)

7 files changed, 161 insertions, 8 deletions

diff --git a/doc/src/qmlapp/applicationdevelopers.qdoc b/doc/src/qmlapp/applicationdevelopers.qdoc
index 0e8ec352..a02ea0de 100644
--- a/doc/src/qmlapp/applicationdevelopers.qdoc
+++ b/doc/src/qmlapp/applicationdevelopers.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2021 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -188,7 +188,7 @@ QML code is used in applications.
 \li \l{qtquick-internationalization.html}{Internationalization and Localization}
 \li Testing and Debugging
     \list
-    \li \l{qtquick-qmlscene.html}{Prototyping with qmlscene}
+    \li \l{qtquick-qml-runtime.html}{Prototyping with the qml runtime tool}
     \li \l{qtquick-debugging.html}{Debugging QML Applications}
     \li \l{Qt Quick Test}{Qt Quick Test: QML Unit Testing Framework}
     \endlist
diff --git a/doc/src/qmlapp/debugging.qdoc b/doc/src/qmlapp/debugging.qdoc
index c44fe5e1..5b748b43 100644
--- a/doc/src/qmlapp/debugging.qdoc
+++ b/doc/src/qmlapp/debugging.qdoc
@@ -158,7 +158,7 @@ import QtQuick 2.3
 Rectangle { width: 100; height: 100 }
 \endqml
 
-If you set \c {QML_IMPORT_TRACE=1} before running the \l{qtquick-qmlscene.html}{QML Scene} or your
+If you set \c {QML_IMPORT_TRACE=1} before running the \l{qtquick-qml-runtime.html}{QML Runtime} or your
 QML C++ application, you will see output similar to:
 
 \code
diff --git a/doc/src/qmlapp/deployment.qdoc b/doc/src/qmlapp/deployment.qdoc
index 5bb66177..dafe62eb 100644
--- a/doc/src/qmlapp/deployment.qdoc
+++ b/doc/src/qmlapp/deployment.qdoc
@@ -36,7 +36,7 @@ to third-party QML types and modules.
 
 Applications that use QML must invoke the QML runtime to run QML documents. You can do this by
 creating a QQuickView or a QQmlEngine, as described below. In addition, the Declarative UI
-package includes the qmlscene tool, which loads \c .qml files. This tool is useful for developing
+package includes the \c qml tool, which loads \c .qml files. This tool is useful for developing
 and testing QML code without having to write a C++ application to load the QML runtime.
 
 \section1 Deploying Applications with Qt Creator
@@ -93,7 +93,7 @@ loaded.
 
 \section1 Prototyping with QML Scene
 
-The Declarative UI package includes a QML runtime tool, \l{qtquick-qmlscene.html}{qmlscene},
+The Declarative UI package includes a QML runtime tool, \l{qtquick-qml-runtime.html}{qml},
 which loads and displays QML documents. This is useful during the application development phase
 for prototyping QML-based applications without writing your own C++ applications to invoke
 the QML runtime.
diff --git a/doc/src/qmlapp/firststepsqml.qdoc b/doc/src/qmlapp/firststepsqml.qdoc
index e1ad1369..1b40028b 100644
--- a/doc/src/qmlapp/firststepsqml.qdoc
+++ b/doc/src/qmlapp/firststepsqml.qdoc
@@ -213,7 +213,8 @@ Rectangle {
 }
 \endqml
 
-This example can be saved as "ClickableHelloWorld.qml" and run with qmlscene.
+This example can be saved as "ClickableHelloWorld.qml" and run with the
+\l{qtquick-qml-runtime.html}{qml} runtime tool.
 Whenever the user clicks anywhere in the window, the rectangle will change
 from red to blue.
 
diff --git a/doc/src/qmlapp/porting.qdoc b/doc/src/qmlapp/porting.qdoc
index 98153578..5fc927fc 100644
--- a/doc/src/qmlapp/porting.qdoc
+++ b/doc/src/qmlapp/porting.qdoc
@@ -211,11 +211,12 @@ QGraphicsView. In contrast, QQuickView inherits from QQuickWindow and uses the Q
 infrastructure introduced in Qt 5; any QGraphicsView-specific functionality is no longer available.
 
 
-\section3 qmlscene Utility
+\section3 Utilities: qmlscene and qml
 
 The \c qmlviewer tool provided for prototyping and testing QML applications in Qt 4.x has been
 replaced with the \c qmlscene tool which integrates with the new scenegraph features in Qt 5.
-
+In Qt 5.2, the \l{qtquick-qml-runtime.html}{qml} tool was added, intended as the eventual
+replacement for \c qmlscene.
 
 \section2 QML plugins
 
diff --git a/doc/src/qmlapp/qml.qdoc b/doc/src/qmlapp/qml.qdoc
new file mode 100644
index 00000000..ff445170
--- /dev/null
+++ b/doc/src/qmlapp/qml.qdoc
@@ -0,0 +1,148 @@
+/****************************************************************************
+**
+** Copyright (C) 2021 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-qml-runtime.html
+    \ingroup qtquick-tools
+    \title Prototyping with the QML Runtime Tool
+    \ingroup qttools
+    \brief Utility to test and load QML files
+
+    Qt includes the \c qml executable, a utility that loads and displays QML
+    documents.
+
+    The \c 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 \l {Deploying QML applications} for more information. When
+    given a bare \l Item as root element, \c qml will automatically create a
+    window to show the scene. Notably, \l QQmlComponent::create() will not do
+    that. Therefore, when moving from a prototype developed with \c qml to a
+    C++ application, you need to either make sure the root element is a
+    \l Window, or create a \l QQuickView in C++ to hold the root \l Item.
+    But in the meantime, you can load and test parts of your prototype
+    separately with the \c qml tool.
+
+    To load a .qml file, provide the file path on the command prompt:
+
+    \code
+    $ qml myqmlfile.qml
+    \endcode
+
+    To see the configuration options, run \c qml with the \c --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 \c PartialScene object.  The \c 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 \c PartialScene.
+    The \c PartialScene.container property gives a URL pointing to QML source
+    code for the container component, which normally should declare a \l Window
+    in which to wrap the \l 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
+    \c --list-conf command:
+
+    \code
+    $ qml --list-conf
+    Built-in configurations:
+      default
+      resizeToItem
+    \endcode
+
+    The \c 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 \c resizeToItem configuration works the
+    other way around: the Item can programmatically set its own size (for
+    example by creating bindings to its own \c width and \c 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 -c or \c --config option:
+
+    \code
+    $ qml -c resizeToItem selfResizingItem.qml
+    \endcode
+
+    Additional configurations can be added by creating configuration
+    directories in \l QStandardPaths::AppConfigLocation, each with two QML
+    files inside: a configuration file named \c configuration.qml, and a QML
+    file that declares the Item wrapper, which can have any name.
+
+    Here is an example \c configuration.qml file:
+
+    \qml
+    import QmlRuntime.Config 1.0
+
+    Configuration {
+        PartialScene {
+            itemType: "QQuickItem"
+            container: Qt.resolvedUrl("ItemWrapper.qml")
+        }
+    }
+    \endqml
+
+    And here is the simplest-possible \c ItemWrapper.qml that the \c container
+    property could point to:
+
+    \qml
+    import QtQuick 2.0
+    import QtQuick.Window 2.0
+
+    Window {
+        property Item containedObject: null
+        onContainedObjectChanged: {
+            if (containedObject == undefined || containedObject == null) {
+                visible = false;
+            } else {
+                containedObject.parent = contentItem;
+                visible = true;
+            }
+        }
+    }
+    \endqml
+
+    When this has been done, you can use the \c {qml -c} option giving the
+    complete path to the \c configuration.qml file, which specifies the path to
+    the container object:
+
+    \code
+    $ qml -c ~/.config/QtProject/Qml\ Runtime/simplest/configuration.qml mycomponent.qml
+    \endcode
+
+    The \c qml runtime will directly set the \c containedObject property, which
+    is required to have that name; and when it is set, the \l Item will be
+    reparented to the \l 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.
+
+    In addition to the features that can be declared in the configuration files,
+    the \c qml tool also provides a few more features via command-line options.
+    Use the \c --help option to get an up-to-date list.
+*/
diff --git a/doc/src/qmlapp/qmlscene.qdoc b/doc/src/qmlapp/qmlscene.qdoc
index 02220774..6147d5c3 100644
--- a/doc/src/qmlapp/qmlscene.qdoc
+++ b/doc/src/qmlapp/qmlscene.qdoc
@@ -61,6 +61,9 @@
     side, the ability to automatically create a window gives you the option to
     load parts of your prototype separately with \c qmlscene.
 
+    \note The \l{qtquick-qml-runtime.html}{qml tool} is also included since
+    Qt 5.2, and has certain advantages over \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: