Doc: Add info on Live Preview

The documentation was moved from the Qt Design Studio repository
and edited to make it applicable to Qt Creator, too.

Change-Id: I3072fc712b5ee002cd6e7486927de31f9117d7bc
Reviewed-by: Brook Cronin <brook.cronin@qt.io>
Reviewed-by: Tim Jenssen <tim.jenssen@qt.io>

10 files changed, 258 insertions, 3 deletions

diff --git a/doc/config/qtcreator-project.qdocconf b/doc/config/qtcreator-project.qdocconf
index 4ab5505f763..ba394e3b275 100644
--- a/doc/config/qtcreator-project.qdocconf
+++ b/doc/config/qtcreator-project.qdocconf
@@ -20,6 +20,7 @@ imagedirs = ../images \
             ../../src/plugins/qmldesigner/components/formeditor \
             ../../src/plugins/qmldesigner/components/navigator \
             ../../src/plugins/qmldesigner/components/timelineeditor/images \
+            ../../src/plugins/qmldesigner/qmlpreviewplugin/images \
             ../../src/plugins/scxmleditor/common/images \
             ../../src/plugins/texteditor/images \
             ../../src/plugins/valgrind/images
diff --git a/doc/images/qtcreator-live-preview-kit.png b/doc/images/qtcreator-live-preview-kit.png
new file mode 100644
index 00000000000..f76099ab829
--- /dev/null
+++ b/doc/images/qtcreator-live-preview-kit.png
diff --git a/doc/images/qtcreator-live-preview.png b/doc/images/qtcreator-live-preview.png
new file mode 100644
index 00000000000..91d505dce91
--- /dev/null
+++ b/doc/images/qtcreator-live-preview.png
diff --git a/doc/src/projects/creator-only/creator-projects-building-running.qdoc b/doc/src/projects/creator-only/creator-projects-building-running.qdoc
index 656be23bd55..0e1c2c581aa 100644
--- a/doc/src/projects/creator-only/creator-projects-building-running.qdoc
+++ b/doc/src/projects/creator-only/creator-projects-building-running.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2018 The Qt Company Ltd.
+** Copyright (C) 2019 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -33,7 +33,7 @@
     \contentspage index.html
     \previouspage creator-scxml.html
     \page creator-building-running.html
-    \nextpage creator-building-targets.html
+    \nextpage creator-live-preview.html
 
     \title Building and Running
 
@@ -46,6 +46,14 @@
     running your project.
 
     \list
+
+        \li \l {Previewing}
+
+            You can use the QML live preview to preview a QML file or an
+            entire Qt Quick application on the desktop, as well as on
+            Android and embedded Linux devices. The changes you make to
+            the UI are instantly visible to you in the preview.
+
         \li \l{Building for Multiple Platforms}
 
             \e {Build configurations} contain everything you need to compile
diff --git a/doc/src/qtcreator-toc.qdoc b/doc/src/qtcreator-toc.qdoc
index c2beb581b88..331a5a8091b 100644
--- a/doc/src/qtcreator-toc.qdoc
+++ b/doc/src/qtcreator-toc.qdoc
@@ -156,6 +156,11 @@
         \endlist
         \li \l{Building and Running}
         \list
+            \li \l{Previewing}
+            \list
+                \li \l{Previewing on Desktop}
+                \li \l{Previewing on Devices}
+            \endlist
             \li \l{Building for Multiple Platforms}
             \li \l{Running on Multiple Platforms}
             \li \l{Deploying to Devices}
diff --git a/doc/src/qtcreator.qdoc b/doc/src/qtcreator.qdoc
index 7c29421693a..4d814582ecc 100644
--- a/doc/src/qtcreator.qdoc
+++ b/doc/src/qtcreator.qdoc
@@ -94,6 +94,7 @@
         \row
             \li \b {\l{Building and Running}}
                 \list
+                    \li \l{Previewing}
                     \li \l{Building for Multiple Platforms}
                     \li \l{Running on Multiple Platforms}
                     \li \l{Deploying to Devices}
diff --git a/doc/src/qtquick/qtquick-live-preview-desktop.qdoc b/doc/src/qtquick/qtquick-live-preview-desktop.qdoc
new file mode 100644
index 00000000000..8d9f653b5e8
--- /dev/null
+++ b/doc/src/qtquick/qtquick-live-preview-desktop.qdoc
@@ -0,0 +1,70 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt Design Studio documentation.
+**
+** 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.
+**
+****************************************************************************/
+
+/*!
+    \contentspage {Qt Creator}
+    \previouspage creator-live-preview.html
+    \page creator-live-preview-desktop.html
+    \nextpage creator-live-preview-devices.html
+
+    \title Previewing on Desktop
+
+    To preview the currently active QML file on the desktop:
+
+    \list
+        \li Select \uicontrol Build > \uicontrol {QML Preview}.
+        \li Select the \inlineimage live_preview.png
+            (\uicontrol {Show Live Preview}) button.
+        \li Press \key {Alt+P}.
+    \endlist
+
+    \if defined(qtcreator)
+    \image qtcreator-live-preview.png
+    \else
+    \image studio-live-preview.png
+    \endif
+
+    To preview any QML file that belongs to the project, right-click the project
+    name in the \uicontrol Project tab in the \uicontrol Navigator, and select
+    \uicontrol {Preview file}.
+
+    To preview the whole UI, select \uicontrol {Show Live Preview}
+    when viewing the main QML UI file of the project.
+
+    To view the UI in different sizes, select the zooming level on the toolbar.
+
+    The frames-per-second (FPS) refresh rate of animations is displayed in the
+    \uicontrol FPS field.
+
+    \if defined(qtdesignstudio)
+    \section1 Selecting the Preview Tool
+
+    By default, the \c qmlscene utility is used for previewing. To use some
+    other tool, specify it in the \uicontrol {QML viewer} field in the run
+    settings of the project in the Projects mode.
+
+    \image studio-run-settings.png "Run settings"
+    \endif
+*/
diff --git a/doc/src/qtquick/qtquick-live-preview-devices.qdoc b/doc/src/qtquick/qtquick-live-preview-devices.qdoc
new file mode 100644
index 00000000000..d37b84075a1
--- /dev/null
+++ b/doc/src/qtquick/qtquick-live-preview-devices.qdoc
@@ -0,0 +1,104 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt Design Studio documentation.
+**
+** 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.
+**
+****************************************************************************/
+
+/*!
+    \contentspage {Qt Creator}
+    \previouspage creator-live-preview-desktop.html
+    \page creator-live-preview-devices.html
+    \if defined(qtdesignstudio)
+    \nextpage studio-advanced.html
+    \else
+    \nextpage creator-building-targets.html
+    \endif
+
+    \title Previewing on Devices
+
+    \omit
+    To preview UIs on Android devices, you need to enable USB debugging on them
+    and connect them to your system with a USB cable.
+    \endomit
+    To preview UIs on embedded devices, you need to connect the devices to your
+    system with a USB cable, or a wired or wireless connection, depending on
+    the device, and configure connections to them. The necessary kits have been
+    predefined and you only need to enable them for your current project.
+
+    \e {Deploy configurations} handle the packaging and copying of the
+    necessary files to a location in a device where you want to run the
+    executable at.
+
+    To preview a UI on a device:
+
+    \list 1
+        \li In \uicontrol Projects > \uicontrol {Build & Run}, enable the kit
+            predefined for the device type (1).
+        \li Select the kit for the device in the kit selector (2).
+            \if defined(qtcreator)
+            \image qtcreator-live-preview-kit.png
+            \else
+            \image studio-kit-selector.png "Kit selector"
+            \endif
+        \li Select \uicontrol Build > \uicontrol {QML Preview} or
+            press \key {Alt+P}.
+    \endlist
+
+    \omit
+    \section2 Previewing on Android Devices
+
+    The USB debugging feature on Android devices enables creating connections
+    to the devices from \QDS and running the live preview utility on them.
+
+    Debugging is enabled in different ways on different Android devices.
+    Look for \uicontrol {USB Debugging} under \uicontrol {Developer Options}.
+    On some devices \uicontrol {Developer Options} is hidden and becomes visible
+    when you tap the \uicontrol {Build number} field in \uicontrol Settings >
+    \uicontrol About several times.
+
+    After you have enabled debugging, connect the Android device to the system
+    with a USB cable.
+
+    The first time you preview a UI on devices, the preview utility
+    is copied to them. This might take some time. Thereafter, previewing will
+    get faster, because only the UI files need to be copied to the
+    device.
+    \endomit
+
+    \section2 Previewing on Embedded Devices
+
+    You can preview UIs on embedded devices that are supported by
+    \l{Qt for Device Creation}. For a list of supported devices, see
+    \l{https://doc.qt.io/QtForDeviceCreation/qtee-supported-platforms.html#reference-target-devices}
+    {Reference Target Devices}.
+
+    You must configure the device as instructed in the
+    \l{https://doc.qt.io/QtForDeviceCreation/b2qt-installation-guides.html}
+    {Installation Guides}.
+
+    \note At the time of this writing, \macos is not supported as a development
+    host for Qt for Device Creation. This means that you cannot preview UIs on
+    devices if you are using \QDS on \macos. For more information about
+    supported development hosts, see
+    \l {https://doc.qt.io/QtForDeviceCreation/qtdc-supported-platforms.html}
+    {Supported Development Hosts}.
+*/
diff --git a/doc/src/qtquick/qtquick-live-preview.qdoc b/doc/src/qtquick/qtquick-live-preview.qdoc
new file mode 100644
index 00000000000..95b01b9fe2a
--- /dev/null
+++ b/doc/src/qtquick/qtquick-live-preview.qdoc
@@ -0,0 +1,66 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt Design Studio documentation.
+**
+** 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.
+**
+****************************************************************************/
+
+/*!
+    \contentspage {Qt Creator}
+    \if defined(qtdesignstudio)
+    \previouspage creator-quick-ui-forms.html
+    \else
+    \previouspage creator-building-running.html
+    \endif
+    \page creator-live-preview.html
+    \nextpage creator-live-preview-desktop.html
+
+    \title Previewing
+
+    You can use the QML live preview to preview a QML file or the entire
+    UI on the desktop, as well as on Android and embedded Linux
+    devices. The changes you make to the UI are instantly visible
+    to you in the preview.
+
+    \if defined(qtcreator)
+    \image qtcreator-live-preview.png
+    \else
+    \image studio-live-preview.png
+    \endif
+
+    \list
+        \li \l{Previewing on Desktop}
+
+            You can preview individual QML files or the whole UI in the
+            Design mode.
+        \li \l{Previewing on Devices}
+
+            \if defined(qtcreator)
+            You can preview Qt Quick applications on devices that you have
+            connected to the development PC. For more information, see
+            \l {Connecting Devices}.
+            \else
+            When you install \QDS, everything you need for previewing on
+            devices is set up automatically. You only need to connect your
+            devices to your system.
+            \endif
+    \endlist
+*/
diff --git a/doc/src/qtquick/qtquick-ui-forms.qdoc b/doc/src/qtquick/qtquick-ui-forms.qdoc
index 6ec6313ccf3..b68fe32f10f 100644
--- a/doc/src/qtquick/qtquick-ui-forms.qdoc
+++ b/doc/src/qtquick/qtquick-ui-forms.qdoc
@@ -35,7 +35,7 @@
     \page creator-quick-ui-forms.html
     \if defined(qtdesignstudio)
     \previouspage qmldesigner-pathview-editor.html
-    \nextpage studio-live-preview.html
+    \nextpage creator-live-preview.html
     \else
     \previouspage qtquick-iso-icon-browser.html
     \nextpage quick-export-to-qml.html