Doc: Turn QML preview topics in to how-to topics in Qt Creator docs

- Move qt-quick-live-preview.qdoc to QDS sources
- Copy qt-quick-live-preview-desktop.qdoc to QDS sources as
  how-to\qtdesignstudio-live-preview-desktop.qdoc and remove
  Qt Creator-specific information from it
- Remove the "Running on Devices" and "Using SCXML State Machines"
  topics, which are not used any more
- Edit for style

Task-number: QTCREATORBUG-29361
Change-Id: I1646505aff8659605b09735da515e5d21070d39e
Reviewed-by: Ulf Hermann <ulf.hermann@qt.io>
Reviewed-by: Thomas Hartmann <thomas.hartmann@qt.io>
Reviewed-by: Pranta Ghosh Dastider <pranta.dastider@qt.io>

14 files changed, 89 insertions, 245 deletions

diff --git a/doc/qtcreator/config/style/qt5-sidebar.html b/doc/qtcreator/config/style/qt5-sidebar.html
index 69e03db07d..577bd5de42 100644
--- a/doc/qtcreator/config/style/qt5-sidebar.html
+++ b/doc/qtcreator/config/style/qt5-sidebar.html
@@ -13,7 +13,6 @@
             <li><a href="creator-getting-started.html">Getting Started</a></li>
             <li><a href="creator-project-creating.html">Creating Projects</a></li>
             <li><a href="creator-configuring-projects.html">Configuring Projects</a></li>
-            <li><a href="creator-live-preview.html">Validating with Target Hardware</a></li>
             <li><a href="creator-connecting-mobile.html">Connecting Devices</a></li>
             <li><a href="creator-debugging.html">Debugging</a></li>
             <li><a href="creator-analyze-mode.html">Analyzing Code</a></li>
diff --git a/doc/qtcreator/src/editors/creator-only/creator-coding-edit-mode.qdoc b/doc/qtcreator/src/editors/creator-only/creator-coding-edit-mode.qdoc
index dbf8b219ed..c90a21f80e 100644
--- a/doc/qtcreator/src/editors/creator-only/creator-coding-edit-mode.qdoc
+++ b/doc/qtcreator/src/editors/creator-only/creator-coding-edit-mode.qdoc
@@ -111,7 +111,7 @@
     \row
         \li \inlineimage icons/live-preview.png
         \li Preview changes to QML code live in your application.
-        \li \l {Previewing on Desktop}
+        \li \l {Preview a QML file on desktop}
     \row
         \li \inlineimage icons/debugger_singleinstructionmode.png
         \li Run Clang-Tidy or Clazy to analyze the currently open file.
diff --git a/doc/qtcreator/src/howto/creator-external-tools.qdoc b/doc/qtcreator/src/howto/creator-external-tools.qdoc
index 13927f3d67..8aef1d66fa 100644
--- a/doc/qtcreator/src/howto/creator-external-tools.qdoc
+++ b/doc/qtcreator/src/howto/creator-external-tools.qdoc
@@ -209,6 +209,10 @@
     \uicontrol External > \uicontrol {Qt Quick} > \uicontrol {QML Runtime}.
 
     \sa {Use external tools}
+
+    \if defined(qtcreator)
+    \sa {Design UIs}{How To: Design UIs}, {UI Design}
+    \endif
 */
 
 /*!
diff --git a/doc/qtcreator/src/howto/creator-how-to-view-images.qdoc b/doc/qtcreator/src/howto/creator-how-to-view-images.qdoc
index c5cf673347..17d660c4d6 100644
--- a/doc/qtcreator/src/howto/creator-how-to-view-images.qdoc
+++ b/doc/qtcreator/src/howto/creator-how-to-view-images.qdoc
@@ -43,6 +43,10 @@
     Select \uicontrol {Set as Default} to use the current settings for the
     background and outline modes and fitting images to screen as default
     values for the image viewer.
+
+    \if defined(qtcreator)
+    \sa {Design UIs}{How To: Design UIs}, {UI Design}
+    \endif
 */
 
 /*!
@@ -67,4 +71,8 @@
 
     You can then use QIcon::addPixmap() to add the pixmaps to icons in
     different modes and states.
+
+    \if defined(qtcreator)
+    \sa {Design UIs}{How To: Design UIs}, {UI Design}
+    \endif
 */
diff --git a/doc/qtcreator/src/overview/creator-only/creator-overview.qdoc b/doc/qtcreator/src/overview/creator-only/creator-overview.qdoc
index cacbb5c376..f06a9546ce 100644
--- a/doc/qtcreator/src/overview/creator-only/creator-overview.qdoc
+++ b/doc/qtcreator/src/overview/creator-only/creator-overview.qdoc
@@ -94,6 +94,11 @@
             Load C++ plugins for QML to simulate data.
     \endlist
 
+    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.
+
     If you need a traditional user interface that has a clear structure and
     enforces a platform look and feel, use \l{Qt Widgets} and the integrated
     \l{\QD}.
@@ -207,15 +212,6 @@
 
     For more information, see \l{Connecting Devices} and \l{Deploy Configurations}.
 
-    \section2 Previewing QML
-
-    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.
-
-    For more information, see \l{Validating with Target Hardware}.
-
     \section1 Debugging Applications
 
     A debugger lets you see what happens \e inside an application while it runs
diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-building-running.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-building-running.qdoc
deleted file mode 100644
index f926f9cd48..0000000000
--- a/doc/qtcreator/src/projects/creator-only/creator-projects-building-running.qdoc
+++ /dev/null
@@ -1,43 +0,0 @@
-// Copyright (C) 2019 The Qt Company Ltd.
-// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
-
-// **********************************************************************
-// NOTE: the sections are not ordered by their logical order to avoid
-// reshuffling the file each time the index order changes (i.e., often).
-// Run the fixnavi.pl script to adjust the links to the index order.
-// **********************************************************************
-
-/*!
-    \previouspage creator-scxml.html
-    \page creator-building-running.html
-    \nextpage creator-live-preview.html
-
-    \title Running on Devices
-
-    \QC supports running and deploying Qt applications that you build
-    for different target platforms or with different compilers, debuggers, or
-    Qt versions. \l{glossary-buildandrun-kit}{Kits} define the tools,
-    \l{glossary-device}{device} type and other settings to use when building and
-    running your project.
-
-    \list
-
-        \li \l {Validating with Target Hardware}
-
-            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{Connecting Devices}
-
-            When you install tool chains for device types as part of a Qt distribution,
-            the build and run settings for the devices might be set up
-            automatically. However, you might need to install and configure some
-            additional software on the devices to be able to connect to them
-            from the development PC.
-
-    \endlist
-
-    \sa {Build and Run}{How To: Build and Run}
-*/
diff --git a/doc/qtcreator/src/qtcreator-toc.qdoc b/doc/qtcreator/src/qtcreator-toc.qdoc
index 3d0278b31c..044ad36f45 100644
--- a/doc/qtcreator/src/qtcreator-toc.qdoc
+++ b/doc/qtcreator/src/qtcreator-toc.qdoc
@@ -22,12 +22,6 @@
                 \endlist
             \li \l{Creating Projects}
             \li \l{Configuring Projects}
-            \li \l{Validating with Target Hardware}
-            \list
-                \li \l{Previewing on Desktop}
-                \li \l{Previewing on Devices}
-                \li \l{Previewing in Browsers}
-            \endlist
             \li \l{Connecting Devices}
             \list
                 \li \l{Connecting Android Devices}
diff --git a/doc/qtcreator/src/qtcreator.qdoc b/doc/qtcreator/src/qtcreator.qdoc
index 0c90ce9c48..8f0020283e 100644
--- a/doc/qtcreator/src/qtcreator.qdoc
+++ b/doc/qtcreator/src/qtcreator.qdoc
@@ -39,7 +39,6 @@
                     \li \l{Getting Started}
                     \li \l{Creating Projects}
                     \li \l{Configuring Projects}
-                    \li \l{Validating with Target Hardware}
                     \li \l{Connecting Devices}
                     \li \l{Debugging}
                     \li \l{Analyzing Code}
diff --git a/doc/qtcreator/src/qtquick/creator-only/qt-design-viewer.qdoc b/doc/qtcreator/src/qtquick/creator-only/qt-design-viewer.qdoc
index 8ff40ec941..58e3e900ba 100644
--- a/doc/qtcreator/src/qtquick/creator-only/qt-design-viewer.qdoc
+++ b/doc/qtcreator/src/qtquick/creator-only/qt-design-viewer.qdoc
@@ -1,27 +1,25 @@
-// Copyright (C) 2019 The Qt Company Ltd.
+// Copyright (C) 2024 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*!
     \page qt-design-viewer.html
-    \previouspage creator-live-preview-devices.html
-    \nextpage creator-building-targets.html
+    \previouspage creator-how-tos.html
 
-    \title Previewing in Browsers
+    \ingroup creator-how-to-design
+
+    \title Preview UI prototypes in browsers
 
     \image qt-design-viewer.png
 
-    \QDV is a QML viewer that runs in your web browser. This means that you can
-    run applications in most widely-used web browsers, such as Apple Safari,
-    Google Chrome, Microsoft Edge, and Mozilla Firefox, on the desktop and on
-    mobile devices.
+    Run Qt Quick UI Prototype projects in web browsers, such as Apple Safari,
+    Google Chrome, Microsoft Edge, and Mozilla Firefox, with \QDV.
 
     The startup and compilation time depend on your browser and configuration.
-    However, the actual performance of the application once started is
-    indistinguishable from the same application running on the desktop.
+    Once started, the application performs the same as when running on the
+    desktop.
 
-    You can run Qt Quick UI Prototype projects, which
-    have a .qmlproject file that defines the main QML file and the import paths.
-    Compress the project folder into a ZIP file that you upload to \QDV.
+    The .qmlproject configuration file defines the main QML file and the import
+    paths. Compress the project folder into a ZIP file that you upload to \QDV.
 
     The loaded applications remain locally in your browser. No data is uploaded
     into the cloud.
@@ -30,11 +28,12 @@
 
     \list 1
         \li In the browser, open \l{ https://designviewer.qt.io/}{\QDV}.
-        \li Drag and drop your application package to \QDV, or click the load
+        \li Drag your application package to \QDV, or select the load
             icon to browse for your file.
     \endlist
 
     Your application is compiled and run on \QDV.
 
-    \sa {Create Qt Quick UI Prototypes}
+    \sa {Create Qt Quick UI Prototypes}, {Design UIs}{How To: Design UIs},
+    {UI Design}
 */
diff --git a/doc/qtcreator/src/qtquick/creator-only/qtquick-live-preview-desktop.qdoc b/doc/qtcreator/src/qtquick/creator-only/qtquick-live-preview-desktop.qdoc
new file mode 100644
index 0000000000..75a64831c0
--- /dev/null
+++ b/doc/qtcreator/src/qtquick/creator-only/qtquick-live-preview-desktop.qdoc
@@ -0,0 +1,22 @@
+// Copyright (C) 2024 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+    \page creator-live-preview-desktop.html
+    \previouspage creator-how-tos.html
+
+    \ingroup creator-how-to-design
+
+    \title Preview a QML file on desktop
+
+    To preview the currently active QML file on the desktop:
+
+    \list
+        \li Select \inlineimage icons/live-preview.png (\uicontrol {Live Preview})
+            on the \l{Edit Mode}{editor} toolbar.
+            \image qtcreator-live-preview.webp {Application running on top of the editor view}
+        \li Go to \uicontrol Build > \uicontrol {QML Preview}.
+    \endlist
+
+    \sa {Design UIs}{How To: Design UIs}, {UI Design}
+*/
diff --git a/doc/qtcreator/src/qtquick/creator-only/qtquick-states-scxml.qdocinc b/doc/qtcreator/src/qtquick/creator-only/qtquick-states-scxml.qdocinc
deleted file mode 100644
index 1f0fd5a8e0..0000000000
--- a/doc/qtcreator/src/qtquick/creator-only/qtquick-states-scxml.qdocinc
+++ /dev/null
@@ -1,26 +0,0 @@
-// Copyright (C) 2020 The Qt Company Ltd.
-// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
-
-/*!
-//! [scxml state machines]
-
-    \section1 Using SCXML State Machines
-
-    To use QML together with an SCXML state machine, add states and
-    bind them to the state machine in \l {Connection View} >
-    \uicontrol Backends, as described in \l {Managing C++ Backend Objects}.
-
-    In the \uicontrol States view, you can select \uicontrol Actions >
-    \uicontrol {Set when Condition} to edit the \c when condition of states
-    to map QML states to the states of the SCXML state machine. For an example,
-    see \l {Qt SCXML Traffic Light QML Example (Dynamic)}.
-
-    \image qmldesigner-states-when-condition.png
-
-    If you add animation to the states, you can
-    \l{Validating with Target Hardware}{preview}
-    or \l{Run on many platforms}{run}
-    the application to test the animation.
-
-//! [scxml state machines]
-*/
diff --git a/doc/qtcreator/src/qtquick/qtquick-live-preview-desktop.qdoc b/doc/qtcreator/src/qtquick/qtquick-live-preview-desktop.qdoc
deleted file mode 100644
index 2f939c69cb..0000000000
--- a/doc/qtcreator/src/qtquick/qtquick-live-preview-desktop.qdoc
+++ /dev/null
@@ -1,51 +0,0 @@
-// Copyright (C) 2024 The Qt Company Ltd.
-// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
-
-/*!
-    \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
-        \if defined(qtcreator)
-        \li Select \inlineimage icons/live-preview.png (\uicontrol {Live Preview})
-            on the \l{Edit Mode}{editor} toolbar.
-            \image qtcreator-live-preview.webp {Application running on top of the editor view}
-        \li Select \uicontrol Build > \uicontrol {QML Preview}.
-    \endlist
-        \else
-        \li Select the \uicontrol {Live Preview} button on the top toolbar.
-        \li Press \key {Alt+P}.
-        \image studio-live-preview.webp
-    \endlist
-
-    To preview any QML file in the project:
-
-    \list
-        \li Select the \uicontrol {Live Preview} button on the top toolbar.
-        \li Right-click the filename in the \l Projects view, and select
-            \uicontrol {Preview File}.
-    \endlist
-
-    To preview the whole UI, select \uicontrol {Live Preview}
-    when viewing the main QML file of the project.
-
-    \section1 Overriding the Preview Tool
-
-    By default, the QML runtime is used for previewing.
-
-    To use some other tool:
-
-    \list 1
-        \li Select \inlineimage icons/settings.png to go to
-            \uicontrol {Run Settings}.
-            \image studio-run-settings.webp {Run Settings}
-        \li In \uicontrol {Override device QML viewer}, select the folder where
-            the preview tool executable is located.
-    \endlist
-    \endif
-*/
diff --git a/doc/qtcreator/src/qtquick/qtquick-live-preview-devices.qdoc b/doc/qtcreator/src/qtquick/qtquick-live-preview-devices.qdoc
index 7fc12b690f..740b237eae 100644
--- a/doc/qtcreator/src/qtquick/qtquick-live-preview-devices.qdoc
+++ b/doc/qtcreator/src/qtquick/qtquick-live-preview-devices.qdoc
@@ -1,20 +1,30 @@
-// Copyright (C) 2020 The Qt Company Ltd.
+// Copyright (C) 2024 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*!
-    \previouspage creator-live-preview-desktop.html
     \page creator-live-preview-devices.html
+    \if defined (qtdesignstudio)
+    \previouspage studio-live-preview-desktop.html
     \nextpage qt-design-viewer.html
 
     \title Previewing on Devices
 
-    To preview UIs on Android devices, enable USB debugging on them
-    and connect them to your system with a USB cable.
+    \else
+    \previouspage creator-how-tos.html
+
+    \ingroup creator-how-to-design
+
+    \title Preview Qt Quick UIs on devices
+    \endif
+
+    To preview a UI on an Android device, turn on USB debugging on the device
+    and connect it to the computer with a USB cable.
 
-    To preview UIs on Boot2Qt devices, 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.
+    To preview a UI on a Boot2Qt device, connect the device to the computer
+    with a USB cable, or a wired or wireless connection, depending on
+    the device, and configure a connection to it. The necessary kits have been
+    predefined, but you need to select the one appropriate 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
@@ -27,8 +37,8 @@
 
     \list 1
         \if defined(qtcreator)
-        \li In \uicontrol Projects > \uicontrol {Build & Run}, enable the kit
-            predefined for the device type (1).
+        \li Go to \uicontrol Projects > \uicontrol {Build & Run}.
+        \li Activate the kit predefined for the device type (1).
         \li Select the kit for the device in the kit selector (2).
             \image qtcreator-kit-selector-devices.webp {Kit selector}
         \else
@@ -42,36 +52,36 @@
             press \key {Alt+P}.
     \endlist
 
-    \section2 Previewing on Android Devices
+    \section2 On Android
 
     \if defined(qtcreator)
-    With the USB debugging feature on Android devices, you can create connections
-    to the devices from \QC and run the preview utility on them.
+    Use the USB debugging feature on an Android device to create a connection
+    to the device from \QC and run the preview utility on it.
 
     Debugging is turned on 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.
+    Tap \uicontrol {Build number} in \uicontrol Settings > \uicontrol About
+    several times to show \uicontrol {Developer Options}.
 
     After you turn on 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.
+    The first time you preview a UI on a device, the preview utility
+    is copied to it, which might take some time. Thereafter, previewing
+    gets faster because only the UI files need to be copied to the device.
     \else
-    Preview your \QDS projects with \QUV. It is an application
-    that runs on your Android device.
+    Preview \QDS projects with \QUV on an Android device.
     Learn more about \l{Viewing Applications on Android}.
     \endif
 
+    \section2 On Boot2Qt
 
-    \section2 Previewing on Boot2Qt Devices
-
-    You can preview UIs on supported Boot2Qt devices that you configure as
+    Preview a UI on a supported Boot2Qt device that you configure as
     instructed in the Boot2Qt documentation.
 
     \sa {Boot2Qt: Documentation}, {Support Levels for Target Hardware}
+
+    \if defined(qtcreator)
+    \sa {Design UIs}{How To: Design UIs}, {UI Design}
+    \endif
 */
diff --git a/doc/qtcreator/src/qtquick/qtquick-live-preview.qdoc b/doc/qtcreator/src/qtquick/qtquick-live-preview.qdoc
deleted file mode 100644
index 2d2ac0b36b..0000000000
--- a/doc/qtcreator/src/qtquick/qtquick-live-preview.qdoc
+++ /dev/null
@@ -1,67 +0,0 @@
-// Copyright (C) 2024 The Qt Company Ltd.
-// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
-
-/*!
-    \page creator-live-preview.html
-    \if defined(qtdesignstudio)
-    \previouspage quick-states.html
-    \else
-    \previouspage creator-building-running.html
-    \endif
-    \nextpage creator-live-preview-desktop.html
-
-    \title Validating with Target Hardware
-
-    Preview a UI file or the entire UI on the desktop, as well as on embedded
-    Linux devices to instantly view the changes you make to the UI. On Android
-    devices, the preview shows the snapshot of your project from the moment
-    you start the preview on the device, not your changes.
-
-    \if defined(qtcreator)
-    \image qtcreator-live-preview.webp {Application running on top of the editor}
-    \else
-    \image studio-live-preview.webp
-    \endif
-
-    Or, use \QDV to run
-    \if defined(qtcreator)
-    \l{Create Qt Quick UI Prototypes}{Qt Quick UI projects}
-    \else
-    applications
-    \endif
-    in most widely-used web browsers on the desktop and in mobile devices and
-    share your designs with reviewers who don't have \QC.
-
-    \list
-        \li \l{Previewing on Desktop}
-
-            Preview individual QML files or the whole UI.
-        \li \l{Previewing on Devices}
-
-            \if defined(qtcreator)
-            Preview Qt Quick applications on devices that you
-            connect 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
-
-        \if defined(qtdesignstudio)
-        \li \l{Sharing Applications Online}
-
-            Share applications online and view them in a web browser.
-
-        \li \l{Viewing Applications on Android}
-
-           Preview your \QDS projects with \QUV. It is an application
-           that runs on your Android device.
-        \else
-        \li \l{Previewing in Browsers}
-
-            Open \l{https://designviewer.qt.io/}{\QDV}
-            in a browser and load applications to it.
-        \endif
-    \endlist
-*/