diff options
Diffstat (limited to 'doc')
404 files changed, 5539 insertions, 5161 deletions
diff --git a/doc/config/macros.qdocconf b/doc/config/macros.qdocconf index b93baa5867..751bc80ab7 100644 --- a/doc/config/macros.qdocconf +++ b/doc/config/macros.qdocconf @@ -16,8 +16,10 @@ macro.macos = "macOS" macro.note = "\\b{Note:}" macro.oslash.HTML = "ø" macro.ouml.HTML = "ö" +macro.B2Q = "Boot to Qt" macro.Q3DS = "Qt 3D Studio" macro.QA = "Qt Assistant" +macro.QAC = "Qt Academy" macro.QB = "Qt Bridge" macro.QBPS = "Qt Bridge for Adobe Photoshop" macro.QBXD = "Qt Bridge for Adobe XD" @@ -25,13 +27,14 @@ macro.QBSK = "Qt Bridge for Sketch" macro.QBF = "Qt Bridge for Figma" macro.QC = "$IDE_DISPLAY_NAME" macro.QCE = "$IDE_DISPLAY_NAME Enterprise" -macro.QD = "Qt Designer" +macro.QD = "Qt Widgets Designer" macro.QDS = "Qt Design Studio" macro.QQEM = "Qt Quick Effect Maker" macro.QDV = "Qt Design Viewer" macro.QL = "Qt Linguist" macro.QMCU = "Qt for MCUs" macro.QMLD = "Qt Quick Designer" +macro.QMLLS = "QML Language Server" macro.QQV = "Qt QML Viewer" macro.QSDK = "Qt" macro.QUL = "Qt Quick Ultralite" diff --git a/doc/qtcreator/config/style/qt5-sidebar.html b/doc/qtcreator/config/style/qt5-sidebar.html index 509808af11..e7671b2b25 100644 --- a/doc/qtcreator/config/style/qt5-sidebar.html +++ b/doc/qtcreator/config/style/qt5-sidebar.html @@ -13,12 +13,8 @@ <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-deployment.html">Deploying to Devices</a></li> <li><a href="creator-debugging.html">Debugging</a></li> <li><a href="creator-analyze-mode.html">Analyzing Code</a></li> - <li><a href="creator-squish.html">Using Squish</a></li> </ul> </div> </div> @@ -51,6 +47,7 @@ <li><a href="creator-how-tos.html#create-models-and-diagrams">Create Models and Diagrams</a></li> <li><a href="creator-how-tos.html#debug">Debug</a></li> <li><a href="creator-how-tos.html#design-uis">Design UIs</a></li> + <li><a href="creator-how-tos.html#develop-for-devices">Develop for Devices</a></li> <li><a href="creator-how-tos.html#edit-code">Edit Code</a></li> <li><a href="creator-how-tos.html#manage-kits">Manage Kits</a></li> <li><a href="creator-how-tos.html#manage-projects">Manage Projects</a></li> @@ -74,12 +71,15 @@ <li><a href="creator-keyboard-shortcuts.html">Keyboard Shortcuts</a></li> <li><a href="creator-known-issues.html">Known Issues</a></li> <li><a href="technical-support.html">Technical Support</a></li> + <li><a href="creator-version-control.html">Version Control Systems</a></li> + <li><a href="creator-reference.html#analyzers">Analyzers</a></li> <li><a href="creator-reference.html#build-systems">Build Systems</a></li> - <li><a href="creator-reference.html#Editors">Editors</a></li> + <li><a href="creator-reference.html#debuggers">Debuggers</a></li> + <li><a href="creator-reference.html#devices">Devices</a></li> + <li><a href="creator-reference.html#editors">Editors</a></li> <li><a href="creator-reference.html#platforms">Platforms</a></li> <li><a href="creator-reference.html#preferences">Preferences</a></li> <li><a href="creator-reference.html#ui-design">UI Design</a></li> - <li><a href="creator-version-control.html">Version Control Systems</a></li> <li><a href="creator-reference.html#views">Views</a></li> <li><a href="creator-reference.html">See All</a></li> </ul> diff --git a/doc/qtcreator/images/numbers/01.png b/doc/qtcreator/images/numbers/01.png Binary files differindex 4c8b10b26c..1190a99cc6 100644 --- a/doc/qtcreator/images/numbers/01.png +++ b/doc/qtcreator/images/numbers/01.png diff --git a/doc/qtcreator/images/numbers/02.png b/doc/qtcreator/images/numbers/02.png Binary files differindex df24ef459e..9ae3bae02c 100644 --- a/doc/qtcreator/images/numbers/02.png +++ b/doc/qtcreator/images/numbers/02.png diff --git a/doc/qtcreator/images/numbers/03.png b/doc/qtcreator/images/numbers/03.png Binary files differindex 525bd92699..9d29cb93ff 100644 --- a/doc/qtcreator/images/numbers/03.png +++ b/doc/qtcreator/images/numbers/03.png diff --git a/doc/qtcreator/images/numbers/04.png b/doc/qtcreator/images/numbers/04.png Binary files differindex 6c6b489d5c..206e929462 100644 --- a/doc/qtcreator/images/numbers/04.png +++ b/doc/qtcreator/images/numbers/04.png diff --git a/doc/qtcreator/images/numbers/05.png b/doc/qtcreator/images/numbers/05.png Binary files differindex 6d831b204d..6baa13123d 100644 --- a/doc/qtcreator/images/numbers/05.png +++ b/doc/qtcreator/images/numbers/05.png diff --git a/doc/qtcreator/images/numbers/06.png b/doc/qtcreator/images/numbers/06.png Binary files differindex b7adb30f96..4f398dc263 100644 --- a/doc/qtcreator/images/numbers/06.png +++ b/doc/qtcreator/images/numbers/06.png diff --git a/doc/qtcreator/images/numbers/07.png b/doc/qtcreator/images/numbers/07.png Binary files differindex a160038f0e..c71842702f 100644 --- a/doc/qtcreator/images/numbers/07.png +++ b/doc/qtcreator/images/numbers/07.png diff --git a/doc/qtcreator/images/numbers/08.png b/doc/qtcreator/images/numbers/08.png Binary files differindex 6ccf88b7eb..f0d894c106 100644 --- a/doc/qtcreator/images/numbers/08.png +++ b/doc/qtcreator/images/numbers/08.png diff --git a/doc/qtcreator/images/numbers/09.png b/doc/qtcreator/images/numbers/09.png Binary files differindex 0ed195b154..0bf3bc7fb1 100644 --- a/doc/qtcreator/images/numbers/09.png +++ b/doc/qtcreator/images/numbers/09.png diff --git a/doc/qtcreator/images/numbers/10.png b/doc/qtcreator/images/numbers/10.png Binary files differindex 8c468d9998..bec47399a8 100644 --- a/doc/qtcreator/images/numbers/10.png +++ b/doc/qtcreator/images/numbers/10.png diff --git a/doc/qtcreator/images/qtcreator-configure-project.webp b/doc/qtcreator/images/qtcreator-configure-project.webp Binary files differnew file mode 100644 index 0000000000..6f77d3a2a9 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-configure-project.webp diff --git a/doc/qtcreator/images/qtcreator-custom-wizard.png b/doc/qtcreator/images/qtcreator-custom-wizard.png Binary files differdeleted file mode 100644 index 73d3b417b8..0000000000 --- a/doc/qtcreator/images/qtcreator-custom-wizard.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-custom-wizard.webp b/doc/qtcreator/images/qtcreator-custom-wizard.webp Binary files differnew file mode 100644 index 0000000000..6e0f5ddc71 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-custom-wizard.webp diff --git a/doc/qtcreator/images/qtcreator-debugger-threads.webp b/doc/qtcreator/images/qtcreator-debugger-threads.webp Binary files differindex 1a84d6ae2b..155c178155 100644 --- a/doc/qtcreator/images/qtcreator-debugger-threads.webp +++ b/doc/qtcreator/images/qtcreator-debugger-threads.webp diff --git a/doc/qtcreator/images/qtcreator-devices-qnx.webp b/doc/qtcreator/images/qtcreator-devices-qnx.webp Binary files differnew file mode 100644 index 0000000000..a431e883b2 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-devices-qnx.webp diff --git a/doc/qtcreator/images/qtcreator-edit-cmake-configuration-self-built-qt.webp b/doc/qtcreator/images/qtcreator-edit-cmake-configuration-self-built-qt.webp Binary files differnew file mode 100644 index 0000000000..820461039e --- /dev/null +++ b/doc/qtcreator/images/qtcreator-edit-cmake-configuration-self-built-qt.webp diff --git a/doc/qtcreator/images/qtcreator-editor-open-files.webp b/doc/qtcreator/images/qtcreator-editor-open-files.webp Binary files differindex 3ec7e58ae9..f01cf7c52d 100644 --- a/doc/qtcreator/images/qtcreator-editor-open-files.webp +++ b/doc/qtcreator/images/qtcreator-editor-open-files.webp diff --git a/doc/qtcreator/images/qtcreator-editor-symbols.webp b/doc/qtcreator/images/qtcreator-editor-symbols.webp Binary files differindex 70bcc2b442..a42455aab8 100644 --- a/doc/qtcreator/images/qtcreator-editor-symbols.webp +++ b/doc/qtcreator/images/qtcreator-editor-symbols.webp diff --git a/doc/qtcreator/images/qtcreator-filesystem-view-design.png b/doc/qtcreator/images/qtcreator-filesystem-view-design.png Binary files differdeleted file mode 100644 index da8766a9c2..0000000000 --- a/doc/qtcreator/images/qtcreator-filesystem-view-design.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-filesystem-view-design.webp b/doc/qtcreator/images/qtcreator-filesystem-view-design.webp Binary files differnew file mode 100644 index 0000000000..9d5995e416 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-filesystem-view-design.webp diff --git a/doc/qtcreator/images/qtcreator-filesystem-view.webp b/doc/qtcreator/images/qtcreator-filesystem-view.webp Binary files differindex 957a0e4b1b..f16a8060c4 100644 --- a/doc/qtcreator/images/qtcreator-filesystem-view.webp +++ b/doc/qtcreator/images/qtcreator-filesystem-view.webp diff --git a/doc/qtcreator/images/qtcreator-heob-in-terminal.webp b/doc/qtcreator/images/qtcreator-heob-in-terminal.webp Binary files differnew file mode 100644 index 0000000000..f36ac70144 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-heob-in-terminal.webp diff --git a/doc/qtcreator/images/qtcreator-heob.png b/doc/qtcreator/images/qtcreator-heob.png Binary files differdeleted file mode 100644 index c3b75ec847..0000000000 --- a/doc/qtcreator/images/qtcreator-heob.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-ios-preferences.png b/doc/qtcreator/images/qtcreator-ios-preferences.png Binary files differdeleted file mode 100644 index 935a528d6c..0000000000 --- a/doc/qtcreator/images/qtcreator-ios-preferences.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-kit-selector-devices.webp b/doc/qtcreator/images/qtcreator-kit-selector-devices.webp Binary files differnew file mode 100644 index 0000000000..7cb2b74e82 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-kit-selector-devices.webp diff --git a/doc/qtcreator/images/qtcreator-live-preview-kit.png b/doc/qtcreator/images/qtcreator-live-preview-kit.png Binary files differdeleted file mode 100644 index f76099ab82..0000000000 --- a/doc/qtcreator/images/qtcreator-live-preview-kit.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-locator-customize.webp b/doc/qtcreator/images/qtcreator-locator-customize.webp Binary files differindex 5a6d4e90d3..34b96a8d6f 100644 --- a/doc/qtcreator/images/qtcreator-locator-customize.webp +++ b/doc/qtcreator/images/qtcreator-locator-customize.webp diff --git a/doc/qtcreator/images/qtcreator-mcu-kit.png b/doc/qtcreator/images/qtcreator-mcu-kit.png Binary files differdeleted file mode 100644 index c218ad647e..0000000000 --- a/doc/qtcreator/images/qtcreator-mcu-kit.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-mcu-new-project.webp b/doc/qtcreator/images/qtcreator-mcu-new-project.webp Binary files differnew file mode 100644 index 0000000000..270907c08b --- /dev/null +++ b/doc/qtcreator/images/qtcreator-mcu-new-project.webp diff --git a/doc/qtcreator/images/qtcreator-mcu-options.png b/doc/qtcreator/images/qtcreator-mcu-options.png Binary files differdeleted file mode 100644 index a7234466e4..0000000000 --- a/doc/qtcreator/images/qtcreator-mcu-options.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-new-project.webp b/doc/qtcreator/images/qtcreator-new-project.webp Binary files differindex 1c0570b8b6..d073622419 100644 --- a/doc/qtcreator/images/qtcreator-new-project.webp +++ b/doc/qtcreator/images/qtcreator-new-project.webp diff --git a/doc/qtcreator/images/qtcreator-open-project-kits.png b/doc/qtcreator/images/qtcreator-open-project-kits.png Binary files differdeleted file mode 100644 index 8434389fa1..0000000000 --- a/doc/qtcreator/images/qtcreator-open-project-kits.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-options-android-main.png b/doc/qtcreator/images/qtcreator-options-android-main.png Binary files differdeleted file mode 100644 index 5ecea57d99..0000000000 --- a/doc/qtcreator/images/qtcreator-options-android-main.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-options-android-sdk-tools.png b/doc/qtcreator/images/qtcreator-options-android-sdk-tools.png Binary files differdeleted file mode 100644 index f3057ce0bc..0000000000 --- a/doc/qtcreator/images/qtcreator-options-android-sdk-tools.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-preferences-android.webp b/doc/qtcreator/images/qtcreator-preferences-android.webp Binary files differnew file mode 100644 index 0000000000..3c6e909df2 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-preferences-android.webp diff --git a/doc/qtcreator/images/qtcreator-preferences-build-run-general.webp b/doc/qtcreator/images/qtcreator-preferences-build-run-general.webp Binary files differindex c763689496..4826e22fc6 100644 --- a/doc/qtcreator/images/qtcreator-preferences-build-run-general.webp +++ b/doc/qtcreator/images/qtcreator-preferences-build-run-general.webp diff --git a/doc/qtcreator/images/qtcreator-preferences-debugger-gdb.webp b/doc/qtcreator/images/qtcreator-preferences-debugger-gdb.webp Binary files differindex 9ac81bce22..c3c4798c55 100644 --- a/doc/qtcreator/images/qtcreator-preferences-debugger-gdb.webp +++ b/doc/qtcreator/images/qtcreator-preferences-debugger-gdb.webp diff --git a/doc/qtcreator/images/qtcreator-preferences-kits-mcu.webp b/doc/qtcreator/images/qtcreator-preferences-kits-mcu.webp Binary files differnew file mode 100644 index 0000000000..cf61f131ec --- /dev/null +++ b/doc/qtcreator/images/qtcreator-preferences-kits-mcu.webp diff --git a/doc/qtcreator/images/qtcreator-preferences-mcu.webp b/doc/qtcreator/images/qtcreator-preferences-mcu.webp Binary files differnew file mode 100644 index 0000000000..83d6fd17e0 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-preferences-mcu.webp diff --git a/doc/qtcreator/images/qtcreator-preferences-qnx.webp b/doc/qtcreator/images/qtcreator-preferences-qnx.webp Binary files differnew file mode 100644 index 0000000000..435ce04034 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-preferences-qnx.webp diff --git a/doc/qtcreator/images/qtcreator-projects-cpp-code-model.webp b/doc/qtcreator/images/qtcreator-projects-cpp-code-model.webp Binary files differnew file mode 100644 index 0000000000..259d8092f3 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-projects-cpp-code-model.webp diff --git a/doc/qtcreator/images/qtcreator-qml-performance-monitor.png b/doc/qtcreator/images/qtcreator-qml-performance-monitor.png Binary files differdeleted file mode 100644 index 2f256ce3d6..0000000000 --- a/doc/qtcreator/images/qtcreator-qml-performance-monitor.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-qml-profiler-toolbar.webp b/doc/qtcreator/images/qtcreator-qml-profiler-toolbar.webp Binary files differnew file mode 100644 index 0000000000..b0b7ba4d7c --- /dev/null +++ b/doc/qtcreator/images/qtcreator-qml-profiler-toolbar.webp diff --git a/doc/qtcreator/images/qtcreator-qml-profiler.webp b/doc/qtcreator/images/qtcreator-qml-profiler.webp Binary files differnew file mode 100644 index 0000000000..281c7c94e6 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-qml-profiler.webp diff --git a/doc/qtcreator/images/qtcreator-scxml-editor.webp b/doc/qtcreator/images/qtcreator-scxml-editor.webp Binary files differindex d57a50dfb7..f78f7ff3d3 100644 --- a/doc/qtcreator/images/qtcreator-scxml-editor.webp +++ b/doc/qtcreator/images/qtcreator-scxml-editor.webp diff --git a/doc/qtcreator/images/qtcreator-sidebar.png b/doc/qtcreator/images/qtcreator-sidebar.png Binary files differdeleted file mode 100644 index 47d4e5e1f8..0000000000 --- a/doc/qtcreator/images/qtcreator-sidebar.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-sidebar.webp b/doc/qtcreator/images/qtcreator-sidebar.webp Binary files differnew file mode 100644 index 0000000000..fdf8640025 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-sidebar.webp diff --git a/doc/qtcreator/images/qtcreator-toggle-progress-bar.webp b/doc/qtcreator/images/qtcreator-toggle-progress-bar.webp Binary files differindex c8438ae002..d4170d4bc1 100644 --- a/doc/qtcreator/images/qtcreator-toggle-progress-bar.webp +++ b/doc/qtcreator/images/qtcreator-toggle-progress-bar.webp diff --git a/doc/qtcreator/images/qtcreator-valgrind-memcheck.png b/doc/qtcreator/images/qtcreator-valgrind-memcheck.png Binary files differdeleted file mode 100644 index 8131846ef5..0000000000 --- a/doc/qtcreator/images/qtcreator-valgrind-memcheck.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-valgrind-memcheck.webp b/doc/qtcreator/images/qtcreator-valgrind-memcheck.webp Binary files differnew file mode 100644 index 0000000000..c60fdbb72d --- /dev/null +++ b/doc/qtcreator/images/qtcreator-valgrind-memcheck.webp diff --git a/doc/qtcreator/images/qtcreator-welcome-open-projects.webp b/doc/qtcreator/images/qtcreator-welcome-open-projects.webp Binary files differindex 5281669b40..05af411f2d 100644 --- a/doc/qtcreator/images/qtcreator-welcome-open-projects.webp +++ b/doc/qtcreator/images/qtcreator-welcome-open-projects.webp diff --git a/doc/qtcreator/images/qtcreator-welcome-session.png b/doc/qtcreator/images/qtcreator-welcome-session.png Binary files differdeleted file mode 100644 index 669ec91423..0000000000 --- a/doc/qtcreator/images/qtcreator-welcome-session.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-welcome-session.webp b/doc/qtcreator/images/qtcreator-welcome-session.webp Binary files differnew file mode 100644 index 0000000000..7a67042f1c --- /dev/null +++ b/doc/qtcreator/images/qtcreator-welcome-session.webp diff --git a/doc/qtcreator/images/qtquick-example-setting-breakpoint1.png b/doc/qtcreator/images/qtquick-example-setting-breakpoint1.png Binary files differdeleted file mode 100644 index 67da2556c7..0000000000 --- a/doc/qtcreator/images/qtquick-example-setting-breakpoint1.png +++ /dev/null diff --git a/doc/qtcreator/images/qtquick-example-setting-breakpoint1.webp b/doc/qtcreator/images/qtquick-example-setting-breakpoint1.webp Binary files differnew file mode 100644 index 0000000000..0962179a6e --- /dev/null +++ b/doc/qtcreator/images/qtquick-example-setting-breakpoint1.webp diff --git a/doc/qtcreator/images/qtquick-example-setting-breakpoint2.png b/doc/qtcreator/images/qtquick-example-setting-breakpoint2.png Binary files differdeleted file mode 100644 index 788cacaf65..0000000000 --- a/doc/qtcreator/images/qtquick-example-setting-breakpoint2.png +++ /dev/null diff --git a/doc/qtcreator/images/qtquick-example-setting-breakpoint2.webp b/doc/qtcreator/images/qtquick-example-setting-breakpoint2.webp Binary files differnew file mode 100644 index 0000000000..ab4b1c3cdf --- /dev/null +++ b/doc/qtcreator/images/qtquick-example-setting-breakpoint2.webp diff --git a/doc/qtcreator/images/qtquick-example-setting-breakpoint3.png b/doc/qtcreator/images/qtquick-example-setting-breakpoint3.png Binary files differdeleted file mode 100644 index 5d197ff92c..0000000000 --- a/doc/qtcreator/images/qtquick-example-setting-breakpoint3.png +++ /dev/null diff --git a/doc/qtcreator/images/qtquick-example-setting-breakpoint3.webp b/doc/qtcreator/images/qtquick-example-setting-breakpoint3.webp Binary files differnew file mode 100644 index 0000000000..dfee8bc7cc --- /dev/null +++ b/doc/qtcreator/images/qtquick-example-setting-breakpoint3.webp diff --git a/doc/qtcreator/images/qtquick-example-stack.png b/doc/qtcreator/images/qtquick-example-stack.png Binary files differdeleted file mode 100644 index 943b0af3d7..0000000000 --- a/doc/qtcreator/images/qtquick-example-stack.png +++ /dev/null diff --git a/doc/qtcreator/images/qtquick-example-stack.webp b/doc/qtcreator/images/qtquick-example-stack.webp Binary files differnew file mode 100644 index 0000000000..2bf986d004 --- /dev/null +++ b/doc/qtcreator/images/qtquick-example-stack.webp diff --git a/doc/qtcreator/src/analyze/cpu-usage-analyzer.qdoc b/doc/qtcreator/src/analyze/cpu-usage-analyzer.qdoc index 77bc417d03..920bd6d390 100644 --- a/doc/qtcreator/src/analyze/cpu-usage-analyzer.qdoc +++ b/doc/qtcreator/src/analyze/cpu-usage-analyzer.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2022 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // ********************************************************************** @@ -8,136 +8,151 @@ // ********************************************************************** /*! - \previouspage creator-heob.html - \page creator-cpu-usage-analyzer.html - \nextpage creator-cppcheck.html - - \title Analyzing CPU Usage - - \QC is integrated with the Linux Perf tool that can be - used to analyze the CPU and memory usage of an application on embedded - devices and, to a limited extent, on Linux desktop platforms. The - Performance Analyzer uses the Perf tool bundled with the Linux kernel to - take periodic snapshots of the call chain of an application and visualizes - them in a timeline view or as a flame graph. - - \section1 Using the Performance Analyzer + \page creator-how-to-analyze-cpu-usage.html + \previouspage creator-how-tos.html - The Performance Analyzer usually needs to be able to locate debug symbols for - the binaries involved. + \ingroup creator-how-to-analyze - Profile builds produce optimized binaries with separate debug symbols and - should generally be used for profiling. + \title Analyze CPU usage - To manually set up a build configuration that generates separate debug - symbols, edit the project build settings: + With Perf, you can analyze the CPU and memory usage of an application + on Linux desktop and embedded devices. \l{Performance Analyzer} uses the + Perf tool bundled with the Linux kernel to take periodic snapshots of + the call chain of an application and visualizes them in a timeline view + or as a flame graph. - \list 1 - \li To generate debug symbols also for applications compiled in release - mode, select \uicontrol {Projects}, and then select - \uicontrol Enable in the \uicontrol {Separate debug info} field. - - \li Select \uicontrol Yes to recompile the project. + Usually, Performance Analyzer needs debug symbols for the profiled + binaries. Profile builds produce optimized binaries with separate debug + symbols, so use them for profiling. - \endlist + \section1 Collect data - You can start the Performance Analyzer in the following ways: + Start Performance Analyzer in the following ways to collect data: \list - \li Select \uicontrol Analyze > \uicontrol {Performance Analyzer} to + \li Go to \uicontrol Analyze > \uicontrol {Performance Analyzer} to profile the current application. - \li Select the - \inlineimage icons/qtcreator-analyze-start-button.png - (\uicontrol Start) button to start the application from the + \li Select \inlineimage icons/qtcreator-analyze-start-button.png + (\uicontrol Start) to start the application from the \uicontrol {Performance Analyzer}. - \inlineimage qtcreator-performance-analyzer-toolbar.png "Performance Analyzer toolbar" + \image qtcreator-performance-analyzer-toolbar.png {Performance Analyzer toolbar} \endlist - \note If data collection does not start automatically, select the + \note If data collection does not start automatically, select \inlineimage icons/recordfill.png - (\uicontrol {Collect profile data}) button. + (\uicontrol {Collect profile data}). When you start analyzing an application, the application is launched, and - the Performance Analyzer immediately begins to collect data. This is indicated - by the time running in the \uicontrol Recorded field. However, as the data + Performance Analyzer immediately begins to collect data. This is indicated + by the time running in \uicontrol Recorded. However, as the data is passed through the Perf tool and an extra helper program bundled with \QC, and both buffer and process it on the fly, data may arrive in \QC - several seconds after it was generated. An estimate for this delay is given - in the \uicontrol {Processing delay} field. + several seconds after it was generated. \uicontrol {Processing delay} shows + an estimate of the delay. - Data is collected until you select the - \uicontrol {Stop collecting profile data} button or terminate the - application. + Data is collected until you select \inlineimage icons/recordfill.png + (\uicontrol {Stop collecting profile data}) or close the application. - Select the \uicontrol {Stop collecting profile data} button to disable the + Select \uicontrol {Stop collecting profile data} to turn off the automatic start of the data collection when an application is launched. - Profile data will still be generated, but \QC will discard it until you + Profile data is still generated, but \QC discards it until you select the button again. - \section1 Profiling Memory Usage on Devices + \section1 Profile memory usage on devices - To create trace points for profiling memory usage on a target device, select - \uicontrol Analyze > \uicontrol {Performance Analyzer Options} > - \uicontrol {Create Memory Trace Points} or select - \inlineimage icons/create-tracepoint.png - on the \uicontrol {Performance Analyzer} toolbar. + To create trace points for profiling memory usage on a target device: - In the \uicontrol {Create Memory Trace Points} dialog, you can modify the + \list + \li Go to \uicontrol Analyze > \uicontrol {Performance Analyzer Options} + > \uicontrol {Create Memory Trace Points}. + \li Select \inlineimage icons/create-tracepoint.png + on the \uicontrol {Performance Analyzer} toolbar. + \endlist + + In the \uicontrol {Create Memory Trace Points} dialog, modify the script to run. - \image qtcreator-performance-analyzer-create-memory-trace-points.png "Create Memory Trace Points dialog" + \image qtcreator-performance-analyzer-create-memory-trace-points.png {Create Memory Trace Points dialog} If you need root privileges to run scripts as root, select the privileges to - use in the \uicontrol {Elevate privileges using} field. + use in \uicontrol {Elevate privileges using}. Select \uicontrol OK to run the script. To add events for the trace points, see \l{Choosing Event Types}. - You can record a memory trace to view usage graphs in the samples rows of + Record a memory trace to view usage graphs in the samples rows of the timeline and to view memory allocations, peaks, and releases in the flame graph. - \section1 Specifying Performance Analyzer Settings + \section1 Generate separate debug info for qmake projects + + To manually set up a build configuration that generates debug symbols also + for applications compiled for release, edit the build settings of a qmake + project: + + \list 1 + \li Go to \uicontrol {Projects} > \uicontrol {Build Settings}. + \li In \uicontrol {Separate debug info}, select \uicontrol Enable. + \li Select \uicontrol Yes to recompile the project. + \endlist + + \sa {Analyze}{How To: Analyze}, {Analyzers}, {Performance Analyzer}, + {Analyzing Code} +*/ + +/*! + \page creator-cpu-usage-analyzer.html + \previouspage creator-reference.html + + \ingroup creator-reference-analyzer + + \title Performance Analyzer + + \brief Analyze the CPU and memory usage of an application on Linux desktop + and embedded devices. + + To set global preferences for Performance Analyzer, go to \preferences > + \uicontrol Analyzer > \uicontrol {CPU Usage}. + + To set preferences for a particular run configuration, go to + \uicontrol Projects > \uicontrol Run, and then select \uicontrol Details + next to \uicontrol {Performance Analyzer Settings}. - To specify global settings for the Performance Analyzer, select - \preferences > \uicontrol Analyzer > - \uicontrol {CPU Usage}. For each run configuration, you can also - use specialized settings. Select \uicontrol Projects > \uicontrol Run, and - then select \uicontrol Details next to - \uicontrol {Performance Analyzer Settings}. + \image qtcreator-performance-analyzer-settings.png {Performance Analyzer Settings} - \image qtcreator-performance-analyzer-settings.png + To edit the settings for the current run configuration, select the + drop down menu next to \inlineimage icons/recordfill.png on the + Performance Analyzer toolbar. - To edit the settings for the current run configuration, you can also select - the dropdown menu next to the \uicontrol {Collect profile data} button. + \image qtcreator-performance-analyzer-toolbar.png {Performance Analyzer toolbar} - \section2 Choosing Event Types + \section1 Choosing Event Types - In the \uicontrol Events table, you can specify which events should trigger - the Performance Analyzer to take a sample. The most common way of analyzing + The events table lists the events that trigger Performance Analyzer to take + a sample. The most common way of analyzing CPU usage involves periodic sampling, driven by hardware performance counters that react to the number of instructions or CPU cycles executed. - Alternatively, a software counter that uses the CPU clock can be chosen. + You can also select a software counter that uses the CPU clock. Select \uicontrol {Add Event} to add events to the table. - In the \uicontrol {Event Type} column, you can choose the general type of + In \uicontrol {Event Type}, select the general type of event to be sampled, most commonly \uicontrol {hardware} or - \uicontrol {software}. In the \uicontrol {Counter} column, you can choose - which specific counter should be used for the sampling. For example, + \uicontrol {software}. In \uicontrol {Counter}, select the counter + for the sampling. For example, \uicontrol {instructions} in the \uicontrol {hardware} group or \uicontrol {cpu-clock} in the \uicontrol {software} group. More specialized sampling, for example by cache misses or cache hits, is - possible. However, support for it depends on specific features of the CPU - involved. For those specialized events, you can give more detailed sampling - instructions in the \uicontrol {Operation} and \uicontrol {Result} columns. - For example, you can choose a \uicontrol {cache} event for + possible. However, support for it depends on specific features of the CPU. + For those specialized events, give more detailed sampling + instructions in \uicontrol {Operation} and \uicontrol {Result}. + For example, select a \uicontrol {cache} event for \uicontrol {L1-dcache} on the \uicontrol {load} operation with a result - of \uicontrol {misses}. That would sample L1-dcache misses on reading. + of \uicontrol {misses} to sample L1-dcache misses on reading. Select \uicontrol {Remove Event} to remove the selected event from the table. @@ -145,29 +160,28 @@ Select \uicontrol {Use Trace Points} to replace the current selection of events with trace points defined on the target device and set the \uicontrol {Sample mode} to \uicontrol {event count} and the - \uicontrol {Sample period} to \c {1}. If the trace points on the target - were defined using the \uicontrol {Create Trace Points} option, the - Performance Analyzer will automatically use them to profile memory usage. + \uicontrol {Sample period} to \c {1}. If \uicontrol {Create Trace Points} + defines the trace points on the target, Performance Analyzer automatically + uses them to profile memory usage. - Select \uicontrol {Reset} to revert the selection of events, as well as the + Select \uicontrol {Reset} to revert the selection of events, as well as \uicontrol {Sample mode} and \uicontrol {Sample period} to the default values. - \section2 Choosing a Sampling Mode and Period + \section1 Choosing a Sampling Mode and Period - In the \uicontrol {Sample mode} and \uicontrol {Sample period} fields, you - can specify how samples are triggered: + In \uicontrol {Sample mode} and \uicontrol {Sample period}, specify how + samples are triggered: \list \li Sampling by \uicontrol {event count} instructs the kernel to take a sample every \c n times one of the chosen events has occurred, - where \c n is specified in the \uicontrol {Sample period} field. + where \c n is set in \uicontrol {Sample period}. \li Sampling by \uicontrol {frequency (Hz)} instructs the kernel to try and take a sample \c n times per second, by automatically adjusting the - sampling period. Specify \c n in the \uicontrol {Sample period} - field. + sampling period. Set \c n in \uicontrol {Sample period}. \endlist @@ -178,15 +192,15 @@ There may be a significant difference between the sampling period you request and the actual result. - In general, if you configure the Performance Analyzer to collect more data + In general, if you configure Performance Analyzer to collect more data than it can transmit over the connection between the target and the host device, the application may get blocked while Perf is trying to send the data, and the processing delay may grow excessively. You should then change - the \uicontrol {Sample period} or the \uicontrol {Stack snapshot size}. + the value of \uicontrol {Sample period} or \uicontrol {Stack snapshot size}. - \section2 Selecting Call Graph Mode + \section1 Selecting Call Graph Mode - In the \uicontrol {Call graph mode} field, you can specify how the + In \uicontrol {Call graph mode}, you can specify how Performance Analyzer recovers call chains from your application: \list @@ -210,32 +224,32 @@ Qt and most system libraries are compiled without frame pointers by default, so the frame pointer mode is only useful with customized systems. - \section2 Setting Stack Snapshot Size + \section1 Setting Stack Snapshot Size - The Performance Analyzer will analyze and \e unwind the stack snapshots - generated by Perf in dwarf mode. Set the size of the stack snapshots in the - \uicontrol {Stack snapshot size} field. Large stack snapshots result in a + Performance Analyzer analyzes and \e unwinds the stack snapshots + generated by Perf in dwarf mode. Set the size of the stack snapshots in + \uicontrol {Stack snapshot size}. Large stack snapshots result in a larger volume of data to be transferred and processed. Small stack snapshots may fail to capture call chains of highly recursive applications or other intense stack usage. - \section2 Adding Command-Line Options for Perf + \section1 Adding Command-Line Options for Perf - You can specify additional command-line options to be passed to Perf when - recording data in the \uicontrol {Additional arguments} field. You may want - to specify \c{--no-delay} or \c{--no-buffering} to reduce the processing + Set additional command-line options to pass to Perf when + recording data in \uicontrol {Additional arguments}. Set \c{--no-delay} + or \c{--no-buffering} to reduce the processing delay. However, those options are not supported by all versions of Perf and Perf may not start if an unsupported option is given. - \section2 Resolving Names for JIT-compiled JavaScript Functions + \section1 Resolving Names for JIT-compiled JavaScript Functions Since version 5.6.0, Qt can generate perf.map files with information about - JavaScript functions. The Performance Analyzer will read them and show the + JavaScript functions. Performance Analyzer will read them and show the function names in the \uicontrol Timeline, \uicontrol Statistics, and \uicontrol {Flame Graph} views. This only works if the process being profiled is running on the host computer, not on the target device. To switch on the generation of perf.map files, add the environment variable - \c QV4_PROFILE_WRITE_PERF_MAP to the \uicontrol {Run Environment} and set + \c QV4_PROFILE_WRITE_PERF_MAP to \uicontrol {Run Environment} and set its value to \c 1. \section1 Analyzing Collected Data @@ -243,36 +257,35 @@ The \uicontrol Timeline view displays a graphical representation of CPU usage per thread and a condensed view of all recorded events. - \image qtcreator-performance-analyzer-timeline.png "Performance Analyzer" + \image qtcreator-performance-analyzer-timeline.png {Performance Analyzer} Each category in the timeline describes a thread in the application. Move the cursor on an event (5) on a row to see how long it takes and which function in the source it represents. To display the information only when - an event is selected, disable the - \uicontrol {View Event Information on Mouseover} button (4). + an event is selected, turn off + \uicontrol {View Event Information on Mouseover} (4). The outline (9) summarizes the period for which data was collected. Drag the zoom range (7) or click the outline to move on the outline. You can - also move between events by selecting the - \uicontrol {Jump to Previous Event} and \uicontrol {Jump to Next Event} - buttons (1). + also move between events by selecting \uicontrol {Jump to Previous Event} + and \uicontrol {Jump to Next Event} (1). - Select the \uicontrol {Show Zoom Slider} button (2) to open a slider that - you can use to set the zoom level. You can also drag the zoom handles (8). + Select \uicontrol {Show Zoom Slider} button (2) to open a slider that + sets the zoom level. You can also drag the zoom handles (8). To reset the default zoom level, right-click the timeline to open the context menu, and select \uicontrol {Reset Zoom}. \section2 Selecting Event Ranges - You can select an event range (6) to view the time it represents or to zoom - into a specific region of the trace. Select the \uicontrol {Select Range} - button (3) to activate the selection tool. Then click in the timeline to + Select an event range (6) to view the time it represents or to zoom + into a specific region of the trace. Select \uicontrol {Select Range} + (3) to activate the selection tool. Then click in the timeline to specify the beginning of the event range. Drag the selection handle to define the end of the range. - You can use event ranges also to measure delays between two subsequent + Use event ranges also to measure delays between two subsequent events. Place a range between the end of the first event and the beginning - of the second event. The \uicontrol Duration field displays the delay + of the second event. \uicontrol Duration shows the delay between the events in milliseconds. To zoom into an event range, double-click it. @@ -294,10 +307,10 @@ events to move the cursor in the code editor to the part of the code the event is associated with. - As the Perf tool only collects periodic samples, the Performance Analyzer + As the Perf tool only collects periodic samples, Performance Analyzer cannot determine the exact time when a function was called or when it returned. You can, however, see exactly when a sample was taken in the - second row of each thread. The Performance Analyzer assumes that if the same + second row of each thread. Performance Analyzer assumes that if the same function is present at the same place in the call chain in multiple consecutive samples, then this represents a single call to the respective function. This is, of course, a simplification. Also, there may be other @@ -369,7 +382,7 @@ taken for a certain function, relative to the same aspect of all samples together. The nesting shows which functions were called by which other ones. - The \uicontrol {Visualize} button lets you choose what aspect to show in the + The \uicontrol {Visualize} button lets you select what aspect to show in the \uicontrol {Flame Graph}. \list @@ -396,7 +409,7 @@ \uicontrol {Releases} modes will only show any data if samples from memory trace points have been recorded. - \section2 Interaction between the views + \section2 Interaction between the Views When you select a stack frame in either of the \uicontrol {Timeline}, \uicontrol {Flame Graph}, or \uicontrol {Statistics} views, information @@ -415,7 +428,7 @@ \image qtcreator-cpu-usage-analyzer-load-perf-trace.png - The Performance Analyzer needs to know the context in which the + Performance Analyzer needs to know the context in which the data was recorded to find the debug symbols. Therefore, you have to specify the kit that the application was built with and the folder where the application executable is located. @@ -423,15 +436,15 @@ The Perf data files are generated by calling \c {perf record}. Make sure to generate call graphs when recording data by starting Perf with the \c {--call-graph} option. Also check that the necessary debug symbols are - available to the Performance Analyzer, either at a standard location + available to Performance Analyzer, either at a standard location (\c /usr/lib/debug or next to the binaries), or as part of the Qt package you are using. - The Performance Analyzer can read Perf data files generated in either frame + Performance Analyzer can read Perf data files generated in either frame pointer or dwarf mode. However, to generate the files correctly, numerous preconditions have to be met. All system images for the - \l{https://doc.qt.io/Boot2Qt/qtdc-supported-platforms.html} - {Boot2Qt:Supported Target Devices and Development Hosts} are correctly set + \l{Support Levels for Target Hardware}{supported embedded platforms} + are correctly set up for profiling in the dwarf mode. For other devices, check whether Perf can read back its own data in a sensible way by checking the output of \c {perf report} or \c {perf script} for the recorded Perf data files. @@ -443,15 +456,16 @@ \uicontrol {Performance Analyzer Options}. This format is self-contained, and therefore loading it does not require you to specify the recording environment. You can transfer such trace files to a different computer - without any tool chain or debug symbols and analyze them there. + without any toolchain or debug symbols and analyze them there. \section1 Troubleshooting - The Performance Analyzer might fail to record data for the following reasons: + Performance Analyzer might fail to record data for the following reasons: \list \li Perf events may be globally disabled on your system. - The preconfigured \l Boot2Qt images come with perf events enabled. + The preconfigured \l{\B2Q: Documentation}{\B2Q} images come with Perf + events enabled. For a custom configuration you need to make sure that the file \c {/proc/sys/kernel/perf_event_paranoid} contains a value smaller than \c {2}. For maximum flexibility in recording traces you can @@ -471,16 +485,16 @@ the values of the \uicontrol {Stack snapshot size} or \uicontrol {Sample period} settings. \li Perf may be buffering the data forever, never sending it. Add - \c {--no-delay} or \c {--no-buffering} to the - \uicontrol {Additional arguments} field. + \c {--no-delay} or \c {--no-buffering} to + \uicontrol {Additional arguments}. \li Some versions of Perf will not start recording unless given a - certain minimum sampling frequency. Try with a - \uicontrol {Sample period} value of 1000. + certain minimum sampling frequency. Try setting + \uicontrol {Sample period} to 1000. \li On some devices, in particular various i.MX6 Boards, the hardware performance counters are dysfunctional and the Linux kernel may randomly fail to record data after some time. Perf can use different types of events to trigger samples. You can get a list of available - event types by running \c {perf list} on the device and then choose + event types by running \c {perf list} on the device and then select the respective event types in the settings. The choice of event type affects the performance and stability of the sampling. The \c {cpu-clock} \c {software} event is a safe but relatively slow @@ -489,8 +503,7 @@ reboot the device. The kernel may have disabled important parts of the performance counters system. \li Perf might not be installed. The way to install it depends on your - Linux distribution. For example, you might try the following - commands: + Linux distribution. For example, try the following commands: \list \li On Ubuntu 22.04: @@ -506,5 +519,5 @@ The \l {Application Output} view shows some information even if the Performance Analyzer displays error messages. - \sa {Profiling Function Execution} + \sa {Analyze}{How To: Analyze}, {Analyzers}, {Analyzing Code} */ diff --git a/doc/qtcreator/src/analyze/creator-analyze.qdoc b/doc/qtcreator/src/analyze/creator-analyze.qdoc index f57d97b8c0..e2333cee77 100644 --- a/doc/qtcreator/src/analyze/creator-analyze.qdoc +++ b/doc/qtcreator/src/analyze/creator-analyze.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2023 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // ********************************************************************** @@ -17,70 +17,139 @@ To use a code analysis tool, select it in the \uicontrol {Analyze Menu} or in the pull-down menu of the \inlineimage icons/qtcreator-debug-button.png (\uicontrol {Start Debugging of Startup Project}) button. - When you are in the \uicontrol Debug mode, you can switch between tools by - selecting them in the menu on the debugger toolbar. + In the \uicontrol Debug mode, switch between tools by selecting them in the + menu on the debugger toolbar. - You can drag and drop the views in the \uicontrol Debug mode to new + \image qtcreator-performance-analyzer-toolbar.png {Performance Analyzer in Debug mode} + + Drag the views in the \uicontrol Debug mode to new positions on the screen. The size and position of views are saved for future sessions. Select \uicontrol View > \uicontrol Views > \uicontrol {Reset to Default Layout} to reset the views to their original sizes and positions. - You can use the following code analysis tools in the \uicontrol Debug - mode: + \section1 Improving QML Performance + + \QC comes with the \l{Profiling QML Applications}{QML Profiler} for + inspecting binding evaluations and signal handling when running QML code. + This is useful for identifying potential bottlenecks, especially in the + evaluation of bindings. + + \section1 Finding Issues in QML Code + + Run \l{JavaScript and QML Checks}{static checks} on the QML and JavaScript + code in your project to find common problems, similarly to using + \l{http://www.jslint.com}{JSLint}. + + \section1 Finding Issues in C++ Code with Clang Tools + + \QC comes with the following Clang tools for finding problems in C, C++, and + Objective-C source code by using static analysis: \list + \li \l{https://clang.llvm.org/extra/clang-tidy/}{Clang-Tidy}, which + has diagnostics and fixes for typical programming errors, + such as style violations or interface misuse. + \li \l{https://github.com/KDE/clazy/blob/master/README.md}{Clazy}, which + helps Clang understand Qt semantics. It displays Qt-related compiler + warnings, ranging from unnecessary memory allocation to misuse of + API and has refactoring actions for fixing some of the issues. + \endlist - \li \l{Profiling QML Applications}{QML Profiler} + \section1 Finding Issues in C++ Code with Cppcheck - Inspect binding evaluations, signal handling, and - painting operations when running QML code. This is useful for - identifying potential bottlenecks, especially in the evaluation - of bindings. + Install the \l{http://cppcheck.sourceforge.net/}{Cppcheck} static analysis + tool to detect undefined behavior and dangerous coding constructs in + C++ code. Cppcheck analyzes the source code without actually running the + application. - \li \l{Checking Code Coverage}{Coco} + \section1 Checking Code Coverage - Analyze the way an application runs as part of a test suite, for - example, and use the results to make the tests more efficient and - complete. + Install the \l{https://doc.qt.io/coco/}{Coco} code coverage toolchain for + Tcl, QML, C# and C/C++ programs on \macOS, Linux, or Windows to analyze the + way an application runs as part of a test suite, for example. Use the + results to make the tests more efficient and complete. - \li \l{Prevent code erosion}{Axivion} + You can: - Do static code analysis and architecture analysis to detect and - eliminate unnecessary complexity of code. + \list + \li Find untested code sections. + \li Find redundant tests which can then be eliminated. Coco can + identify portions of the source code that are covered by a test. It + can detect whether a new test covers lines in the source code that + the existing tests do not cover. + \li Find dead code by displaying code that is never executed. + \li Calculate the optimum test execution order so as to maximize + test coverage for each run. This is particularly useful for manual + testing. + \li Analyze two separate versions of an application and compare the + differences. This makes it possible to see which tests are affected + by source code modifications and also to get some measure of the + test coverage of a patch or hot fix. + \li Measure the execution time of applications and tests. + \endlist - \li \l{Using Valgrind Code Analysis Tools}{Valgrind Code Analysis Tools} + \section1 Preventing Code Erosion - Detect problems in memory management by using the Memcheck - tool and find cache misses in the code by using the Callgrind tool. + Install \l{https://www.axivion.com/en/products/axivion-suite/}{Axivion Suite} + to protect software from erosion. With static code analysis, + architecture analysis, and code-smells-detection, you can: - \li \l{Clang Tools} + \list + \li Check the source code for potential runtime errors. + \li Use metrics to generate quantitative information about the + internal quality of the source code. + \li Run style checks to achieve compliance with coding guidelines. + \li Detect both duplicates and similar pieces of code in the source code. + \li Recognize cyclical dependencies at different levels. + \li Detect unreachable code. + \endlist - Detect problems in C, C++, and Objective-C programs by - using Clang-Tidy and Clazy. + \section1 Profiling with Valgrind Tools - \li \l{Detecting Memory Leaks with Heob}{Heob} + Install Memcheck and Callgrind from \l{Valgrind's Tool Suite} to detect + memory leaks and profile function execution. - Use the Heob heap observer on Windows to detect buffer - overruns and memory leaks. + You can run the Valgrind tools either \e locally on the development host or + \e remotely on another host. You can use them to analyze both applications + for which you set up a project in \QC and applications for which you do not + have a project. - \li \l{Analyzing CPU Usage}{Performance Analyzer} + Valgrind tools are supported locally only on Linux and \macos. However, + according to Valgrind.org, support on \macos 10.8 and 10.9 is experimental and + mostly broken. You can run the tools on a remote Linux machine or device + from any development host. - Analyze the CPU usage of embedded applications and Linux - desktop applications with the Performance Analyzer that integrates - the Linux Perf tool. + To run the Valgrind tools to analyze an application for which you have a + project, open the project in \QC and select the kit to run the project. The + kit specifies whether the Valgrind tools are run locally or remotely. - \li \l{Analyzing Code with Cppcheck}{Cppcheck} + For more information about analyzing applications for which you do not have + a project, see \l{Run Valgrind tools on external applications}. - Use the experimental Cppcheck plugin to detect undefined - behavior and dangerous coding constructs. + To set preferences for the Valgrind tools, select \preferences > + \uicontrol Analyzer. You can override the general + settings for each project in the \uicontrol {Run Settings} for the project. - \li \l{Visualizing Chrome Trace Events}{Chrome Trace Format Visualizer} + \section1 Detecting Memory Leaks with Heob - Use the Chrome Trace Format (CTF) Visualizer to view - Chrome trace events. This is especially useful when viewing - large trace files that are difficult to visualize using the - built-in trace-viewer (\c{chrome://tracing}). - \endlist + On Windows, install the \l{https://github.com/ssbssa/heob}{Heob} + heap observer to detect buffer overruns and memory leaks. + + \section1 Analyzing CPU Usage + + On Linux, use Perf to analyze the CPU and memory usage of an application + on Linux desktop and embedded devices. + + \l{Performance Analyzer} uses the Perf tool bundled with the Linux kernel to + take periodic snapshots of the call chain of an application and visualizes + them in a timeline view or as a flame graph. + + \section1 Visualizing Chrome Trace Events + + Use the \l{Chrome Trace Format Visualizer} to view Chrome trace events. This + is especially useful when viewing large trace files that are difficult to + visualize using the built-in trace-viewer (\c{chrome://tracing}). + \sa {Analyze}{How To: Analyze}, {Analyzers} */ diff --git a/doc/qtcreator/src/analyze/creator-axivion.qdoc b/doc/qtcreator/src/analyze/creator-axivion.qdoc index ddfbcdf288..53735a9c31 100644 --- a/doc/qtcreator/src/analyze/creator-axivion.qdoc +++ b/doc/qtcreator/src/analyze/creator-axivion.qdoc @@ -9,20 +9,6 @@ \title Prevent code erosion - \l{https://www.axivion.com/en/products/axivion-suite/}{Axivion Suite} is - a tool suite for protecting software from erosion. With static code analysis, - architecture analysis, and code-smells-detection, you can: - - \list - \li Check the source code for potential runtime errors. - \li Use metrics to generate quantitative information about the - internal quality of the source code. - \li Run style checks to achieve compliance with coding guidelines. - \li Detect both duplicates and similar pieces of code in the source code. - \li Recognize cyclical dependencies at different levels. - \li Detect unreachable code. - \endlist - Connect to an Axivion dashboard server from \QC to view results of code analysis. @@ -132,8 +118,9 @@ select the link in the details or in the \uicontrol {Right Path} or \uicontrol {Target Path} column. - \sa {Enable and disable plugins}, {Link projects to Axivion dashboards}, - {Axivion} + \sa {Enable and disable plugins}, {Analyze}{How To: Analyze}, + {Link projects to Axivion dashboards}, {Analyzers}, {Axivion}, + {Analyzing Code} */ /*! @@ -153,12 +140,18 @@ To connect to an Axivion dashboard server: - \list 1 - \li Select \uicontrol Edit to create a connection to the Axivion + \list + \li Select \uicontrol Add to add a new connection to an Axivion dashboard server. + \li Select \uicontrol Edit to modify an existing connection to + an Axivion dashboard server. \image qtcreator-edit-dashboard-configuration.webp {Edit Dashboard Configuration dialog} - \li In \uicontrol {Dashboard URL}, enter the URL of the server. - \li In \uicontrol Username, enter the username to access the server. + \list + \li In \uicontrol {Dashboard URL}, enter the URL of the server. + \li In \uicontrol Username, enter the username to access the server. + \endlist + \li Select \uicontrol Remove to remove the current selected connection + to an Axivion dashboard server. \endlist The first time you access the server, you must enter the password that @@ -186,6 +179,8 @@ \li Go to \uicontrol Projects > \uicontrol {Project Settings} > \uicontrol Axivion. \image qtcreator-preferences-axivion-project.webp {Axivion settings in Project Settings} + \li From \uicontrol {Dashboard} select one of the configured Axivion + dashboard configurations. \li Select \uicontrol {Fetch Projects} to list projects from Axivion. \li Select a project, and then select \uicontrol {Link Project} to link to it. diff --git a/doc/qtcreator/src/analyze/creator-clang-static-analyzer.qdoc b/doc/qtcreator/src/analyze/creator-clang-static-analyzer.qdoc index b1b1cd9a8f..be7eda671d 100644 --- a/doc/qtcreator/src/analyze/creator-clang-static-analyzer.qdoc +++ b/doc/qtcreator/src/analyze/creator-clang-static-analyzer.qdoc @@ -15,22 +15,6 @@ \title Analyze code with Clang-Tidy and Clazy - \QC comes with the following Clang tools for finding problems in C, C++, and - Objective-C source code by using static analysis: - - \list - - \li \l{https://clang.llvm.org/extra/clang-tidy/}{Clang-Tidy}, which - has diagnostics and fixes for typical programming errors, - such as style violations or interface misuse. - - \li \l{https://github.com/KDE/clazy/blob/master/README.md}{Clazy}, which - helps Clang understand Qt semantics. It displays Qt related compiler - warnings, ranging from unnecessary memory allocation to misuse of - API and has refactoring actions for fixing some of the issues. - - \endlist - \note The Clang static analyzer checks are a part of Clang-Tidy. To use the checks, you must create a custom configuration for the Clang tools and enable them for Clang-Tidy. @@ -106,7 +90,8 @@ to load diagnostics from \l{https://yaml.org/}{YAML} files that you exported using the \c {-export fixes} option. - \sa {Configure Clang Diagnostics}, {Speficy Clang tools settings}, + \sa {Check code syntax}, {Configure Clang Diagnostics}, + {Analyze}{How To: Analyze}, {Specify Clang tools settings}, {Analyzers}, {Clang Tools} */ @@ -116,7 +101,7 @@ \ingroup creator-how-to-projects-configure - \title Speficy Clang tools settings + \title Specify Clang tools settings To set Clang-Tidy and Clazy checks to run for the current project: @@ -189,7 +174,7 @@ \endlist \sa {Configure Clang diagnostics}, {Analyze code with Clang-Tidy and Clazy}, - {Speficy Clang tools settings} + {Specify Clang tools settings} */ /*! @@ -311,5 +296,5 @@ file into the \uicontrol {Edit Checks as String} field, select additional checks, and copy-paste the contents of the field to the .clang-tidy file. - \sa {Analyze code with Clang-Tidy and Clazy}, {Speficy Clang tools settings}, {Clang Tools} + \sa {Analyze code with Clang-Tidy and Clazy}, {Specify Clang tools settings}, {Clang Tools} */ diff --git a/doc/qtcreator/src/analyze/creator-coco.qdoc b/doc/qtcreator/src/analyze/creator-coco.qdoc index 341db9fc09..4b1337e123 100644 --- a/doc/qtcreator/src/analyze/creator-coco.qdoc +++ b/doc/qtcreator/src/analyze/creator-coco.qdoc @@ -2,72 +2,46 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \previouspage creator-qml-performance-monitor.html \page creator-coco.html - \nextpage creator-axivion.html + \previouspage creator-how-tos.html - \title Checking Code Coverage + \ingroup creator-how-to-analyze - \l{https://doc.qt.io/coco/}{Coco} is a complete code coverage tool chain for - Tcl, QML, C# and C/C++ programs, which runs on \macOS, Linux, and Windows. + \title Check code coverage - Coco analyzes the way an application runs, as part of a test suite, - for example. The results enable you to make the tests more efficient and - complete. - - You can: - - \list - \li Find untested code sections. - \li Find redundant tests which can then be eliminated. Coco can - identify portions of the source code that are covered by a test. It - can detect whether a new test covers lines in the source code that - the existing tests do not cover. - \li Find dead code by displaying code that is never executed. - \li Calculate the optimum test execution order so as to maximize - test coverage for each run. This is particularly useful for manual - testing. - \li Analyze two separate versions of an application and compare the - differences. This makes it possible to see which tests are affected - by source code modifications and also to get some measure of the - test coverage of a patch or hot fix. - \li Measure the execution time of applications and tests. - \endlist - - The experimental Coco plugin integrates Coco CoverageBrowser into \QC. - It enables you to analyze the test coverage by loading an instrumentation - database (a .csmes file), which was generated by Coco CoverageScanner. - It is currently supported only on Windows, with Coco version 6.0, - or later. + With Coco CoverageBrowser, you can analyze the test coverage by loading an + instrumentation database (a .csmes file), which was generated by Coco + CoverageScanner. The experimental Coco plugin is currently supported only on + Windows, with Coco version 6.0, or later. To use the plugin, you must download and install Coco. \note Enable the Coco plugin to use it. - \section1 Configuring Coco + \section1 Configure Coco \list 1 - \li Select \uicontrol Analyze > \uicontrol {Squish Coco}. - \image qtcreator-coco.png "Coco CoverageBrowser and CSMes file" + \li Go to \uicontrol Analyze > \uicontrol {Squish Coco}. + \image qtcreator-coco.png {Coco CoverageBrowser and CSMes file} \li In \uicontrol {CoverageBrowser}, enter the path to the Coco coverage browser to use for analyzing a .csmes file. \li In \uicontrol CSMes, select the instrumentation database to load. \li Select \uicontrol Open to start CoverageBrowser. - \li In CoverageBrowser, select \uicontrol File > + \li In CoverageBrowser, go to \uicontrol File > \uicontrol {Load Execution Report} and select the .csexe for the coverage scan. - \image coco-coveragebrowser-load-execution-report.png "Load Execution Report dialog" - \li If you want to reuse the execution report, deselect the - \uicontrol {Delete execution report after loading} check box. + \image coco-coveragebrowser-load-execution-report.png {Load Execution Report dialog} + \li To keep the execution report, clear + \uicontrol {Delete execution report after loading}. \endlist - Open the analyzed files in \QC. The results of the analysis are displayed + Open the analyzed files in \QC. You can see the results of the analysis after the code in \uicontrol Edit mode. You can change the fonts and colors used for different types of results. \section1 Changing Fonts and Colors - To change the default fonts and colors, select \preferences > + To change the default fonts and colors, go to \preferences > \uicontrol {Text Editor} > \uicontrol {Font & Colors}. Create your own color scheme and select new fonts and colors for the following results: @@ -85,5 +59,6 @@ \li Implicit Manual Coverage Validation \endlist - \sa {Enable and disable plugins}, {Font & Colors} + \sa {Enable and disable plugins}, {Analyze}{How To: Analyze}, {Analyzers}, + {Font & Colors}, {Analyzing Code} */ diff --git a/doc/qtcreator/src/analyze/creator-cppcheck.qdoc b/doc/qtcreator/src/analyze/creator-cppcheck.qdoc index e3cc393d70..6f34cd5180 100644 --- a/doc/qtcreator/src/analyze/creator-cppcheck.qdoc +++ b/doc/qtcreator/src/analyze/creator-cppcheck.qdoc @@ -1,58 +1,51 @@ -// 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-cpu-usage-analyzer.html \page creator-cppcheck.html - \nextpage creator-ctf-visualizer.html + \previouspage creator-how-tos.html - \title Analyzing Code with Cppcheck + \ingroup creator-how-to-analyze - \l{http://cppcheck.sourceforge.net/}{Cppcheck} is a static analysis tool - that detects errors in C++ code. Static analysis is performed on the source - code without actually executing the application. + \title Detect errors in C++ code with Cppcheck - The experimental Cppcheck Diagnostics plugin integrates diagnostics - that are generated by the Cppcheck tool into the C++ editor. - - \note Enable the Cppcheck plugin to use it. + Enable the experimental Cppcheck plugin to view diagnostics that are + generated by the Cppcheck tool in the C++ editor. Cppcheck is automatically run on open files. To select the files to - check in the currently active project, select \uicontrol Analyze > + check in the currently active project, go to \uicontrol Analyze > \uicontrol Cppcheck. - - \section1 Running Cppcheck on Selected Files + \section1 Analyze selected files \list 1 - \li Select \uicontrol Analyze > \uicontrol Cppcheck. - \image qtcreator-cppcheck-run-configuration.png "Cppcheck run configuration" - \li In the \uicontrol Binary field, enter the path to the Cppcheck - executable file. - \li In the \uicontrol Checks group, select the checks to perform. + \li Go to \uicontrol Analyze > \uicontrol Cppcheck. + \image qtcreator-cppcheck-run-configuration.png {Cppcheck run configuration} + \li In uicontrol Binary, enter the path to the Cppcheck executable file. + \li In \uicontrol Checks, select the checks to perform. \note By default, Cppcheck uses multiple threads to perform checks. - Selecting the \uicontrol {Unused functions} option disables the - default behavior. - \li In the \uicontrol {Custom arguments} field, enter additional + Select \uicontrol {Unused functions} to turn off the default + behavior. + \li In \uicontrol {Custom arguments}, enter additional arguments for running Cppcheck. The arguments might be shadowed by automatically generated ones. To avoid possible conflicts in - configuration, select the \uicontrol {Show raw output} check box - to see the final arguments. - \li In the \uicontrol {Ignored file patterns} field, enter a filter + configuration, select \uicontrol {Show raw output} and check the + final arguments. + \li In \uicontrol {Ignored file patterns}, enter a filter for ignoring files that match the pattern (wildcard). You can enter multiple patterns separated by commas. Even though Cppcheck is not run on files that match the patterns, they might be implicitly checked if other files include them. - \li Select the \uicontrol {Inconclusive errors} check box to also - mark possible false positives. - \li Select the \uicontrol {Check all define combinations} check box to - check all define combinations. Enabling this option can significantly + \li Select \uicontrol {Inconclusive errors} to also mark possible false + positives. + \li Select \uicontrol {Check all define combinations} to + check all define combinations. This can significantly slow down analysis, but might help to find more issues. - \li Select the \uicontrol {Add include paths} check box to pass the - current project's include paths to Cppcheck. Enabling this option + \li Select \uicontrol {Add include paths} to pass the + current project's include paths to Cppcheck. This slows down checks on big projects, but can help Cppcheck to find missing includes. - \li Select the \uicontrol {Calculate additional arguments} check box to + \li Select \uicontrol {Calculate additional arguments} to calculate additional arguments based on current project's settings (such as the language used and standard version) and pass them to Cppcheck. @@ -64,8 +57,9 @@ marks or annotations. To specify the settings above for the automatically run checks, - select \preferences > \uicontrol Analyzer + go to \preferences > \uicontrol Analyzer > \uicontrol Cppcheck. - \sa {Enable and disable plugins} + \sa {Enable and disable plugins}, {Analyze}{How To: Analyze}, + {Analyzing Code}, {Analyzers} */ diff --git a/doc/qtcreator/src/analyze/creator-ctf-visualizer.qdoc b/doc/qtcreator/src/analyze/creator-ctf-visualizer.qdoc index a2bf118f3f..8f02ee0607 100644 --- a/doc/qtcreator/src/analyze/creator-ctf-visualizer.qdoc +++ b/doc/qtcreator/src/analyze/creator-ctf-visualizer.qdoc @@ -8,11 +8,14 @@ // ********************************************************************** /*! - \previouspage creator-cppcheck.html \page creator-ctf-visualizer.html - \nextpage creator-autotest.html + \previouspage creator-reference.html - \title Visualizing Chrome Trace Events + \ingroup creator-reference-analyzer + + \title Chrome Trace Format Visualizer + + \brief Visualize Chrome trace events generated in Chrome Trace Format (CTF). You can use \e {full stack tracing} to trace from the top level QML or JavaScript down to the C++ and all the way to the kernel space. This @@ -110,7 +113,7 @@ LTTng is a tracing toolkit for Linux that you can apply on embedded Linux systems to find out how to optimize the startup time of an application. - Since Qt 5.13, Qt has a set of kernel trace points and a tracing + Qt has a set of kernel trace points and a tracing subsystem for custom user space trace points. \section2 Configuring the Kernel @@ -218,4 +221,6 @@ \code ctf2ctf -o trace.json path/to/lttng trace/ \endcode + + \sa {Analyze}{How To: Analyze}, {Analyzers}, {Analyzing Code} */ diff --git a/doc/qtcreator/src/analyze/creator-heob.qdoc b/doc/qtcreator/src/analyze/creator-heob.qdoc index 449d3cc86a..45f2b269ed 100644 --- a/doc/qtcreator/src/analyze/creator-heob.qdoc +++ b/doc/qtcreator/src/analyze/creator-heob.qdoc @@ -1,4 +1,4 @@ -// 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 // ********************************************************************** @@ -8,17 +8,15 @@ // ********************************************************************** /*! + \page creator-how-to-use-heob.html \previouspage creator-clang-tools.html - \page creator-heob.html - \nextpage creator-cpu-usage-analyzer.html - \title Detecting Memory Leaks with Heob + \ingroup creator-how-to-analyze - \QC integrates the \l{https://github.com/ssbssa/heob}{Heob} heap observer - for detecting buffer overruns and memory leaks. You must download and - install Heob to run it from \QC. + \title Detect memory leaks with Heob - \image qtcreator-heob-settings.png + On Windows, use the Heob heap observer to detect buffer overruns and memory + leaks. To run Heob on the currently open project: @@ -26,35 +24,48 @@ \li Select \uicontrol Analyze > \uicontrol Heob. + \image qtcreator-heob-settings.png {Heob settings} + \li Select the Heob settings profile to use, or select \uicontrol New to create a new profile. - \li In the \uicontrol {Heob path} field, enter the path to the Heob + \li In \uicontrol {Heob path}, enter the path to the Heob executable. - \li Specify additional settings for running the checks. For more - information about the available options, see - \l{Specifying Heob Settings}. + \li Specify \l{Heob}{settings} for running the checks. \li Select \uicontrol OK to run Heob. \endlist - \QC runs the application, and then it runs Heob in a console window. + \QC runs the application, and then it runs Heob in a terminal. - \image qtcreator-heob.png + \image qtcreator-heob-in-terminal.webp {Heob running in a terminal} Heob raises an access violation on buffer overruns and records stack traces - of the offending instruction and buffer allocation. The results are - displayed when Heob exits normally. + of the offending instruction and buffer allocation. You can see the results + in the \uicontrol Memcheck view after Heob exits normally. + + \image qtcreator-heob-output.png {Results from Heob in the Memcheck view} - \image qtcreator-heob-output.png + \sa {Analyze}{How To: Analyze}, {Analyzers}, {Heob}, {Analyzing Code} +*/ - \section1 Specifying Heob Settings +/*! + \page creator-heob.html + \previouspage creator-reference.html - To specify settings for Heob, select \uicontrol Analyze > \uicontrol Heob. + \ingroup creator-reference-analyzer - In the \uicontrol {Extra arguments} field, enter additional arguments for + \title Heob + + \brief Detect memory leaks with Heob. + + To specify settings for Heob, go to \uicontrol Analyze > \uicontrol Heob. + + \image qtcreator-heob-settings.png {Heob settings} + + In \uicontrol {Extra arguments}, enter additional arguments for running Heob. To list the available arguments in the Heob console, enter \c -H in this field and press \key Enter. @@ -63,19 +74,19 @@ leaks visually in the file and the \c -L1024 option to record leak contents up to 1024 bytes in the file. For example, \c {-oleaks.html -g2 -L1024} - To save the settings profile, select \uicontrol Save. + To save your changes as default settings, select + \inlineimage icons/savefile.png. To remove a customized settings profile, select the profile, and then select \uicontrol Delete. The following sections describe the available options in more detail. - \section2 Recording Results + \section1 Recording Results The results of the checks are displayed in the \uicontrol Memcheck view and - recorded in a file. You can specify the file name in the - \uicontrol {XML output file} field. Heob creates the file in the project - directory. + recorded in a file. Specify the file name in \uicontrol {XML output file}. + Heob creates the file in the project directory. You can use the process identifier (PID) as a variable in the file name. For example, \c leaks-%p.xml. This injects Heob into the child processes, @@ -87,9 +98,9 @@ If you use variables, \QC cannot open the file automatically, but you can open it from the project directory. - \section2 Handling Exceptions + \section1 Handling Exceptions - In the \uicontrol {Handle exceptions} list, select \uicontrol Off to use the + In \uicontrol {Handle exceptions}, select \uicontrol Off to use the standard exception handler and have the debugger automatically attached if the application crashes. This works only if you register \QC is as a post-mortem debugger by selecting \preferences > @@ -105,7 +116,7 @@ crash is displayed. Therefore, this option is mostly useful when using Heob on the console or running it for child processes, as well. - \section2 Raising Exceptions on Errors + \section1 Raising Exceptions on Errors Select the \uicontrol {Raise breakpoint exception on error} check box to display errors when the application runs. @@ -119,9 +130,9 @@ This is mostly useful when used with the \uicontrol {Run with debugger} option, which runs Heob under the debugger. - \section2 Protecting Pages + \section1 Protecting Pages - In the \uicontrol {Page protection} list, select \uicontrol Off to use + In \uicontrol {Page protection}, select \uicontrol Off to use standard memory allocation functions and enable only memory leak detection. Select \uicontrol After to place a protected page at the end of each @@ -135,9 +146,9 @@ useful for \e use-after-free and \e double-free detection. However, the available memory address space can run out fast for 32-bit programs. - \section2 Handling Leak Data + \section1 Handling Leak Data - In the \uicontrol {Leak details} list, determine how to handle the + In \uicontrol {Leak details}, determine how to handle the collected leak data when the process exits. Selecting \uicontrol None means that no leak data is collected. If you activate leak type detection, Heob might need more time to collect the data when the process exits. @@ -163,10 +174,10 @@ block. Select \uicontrol {Detect Leak Types (Show Reachable)} to also record the reachable blocks in the results file. - In the \uicontrol {Minimum leak size} list, select the size of + In \uicontrol {Minimum leak size}, select the size of leaks to detect in bytes. - In the \uicontrol {Control leak recording} list, select \uicontrol Off to + In \uicontrol {Control leak recording}, select \uicontrol Off to record all leaks. You cannot change leak recording while it is running. To start Heob without starting leak recording, select @@ -177,4 +188,7 @@ To start leak recording when Heob starts and still have the option to control the recording, select \uicontrol {On (Start Enabled)}. + + \sa {Detect memory leaks with Heob}, {Analyze}{How To: Analyze}, {Analyzers}, + {Analyzing Code} */ diff --git a/doc/qtcreator/src/analyze/creator-valgrind-overview.qdoc b/doc/qtcreator/src/analyze/creator-valgrind-overview.qdoc deleted file mode 100644 index 61aca06cfd..0000000000 --- a/doc/qtcreator/src/analyze/creator-valgrind-overview.qdoc +++ /dev/null @@ -1,54 +0,0 @@ -// Copyright (C) 2018 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-axivion.html - \page creator-valgrind-overview.html - \nextpage creator-analyzer.html - - \title Using Valgrind Code Analysis Tools - - \QC integrates \l{http://valgrind.org/info/tools.html}{Valgrind code - analysis tools} for detecting memory leaks and - profiling function execution. You must download and install them separately - to use them from \QC. - - You can run the Valgrind tools either \e locally on the development host or - \e remotely on another host. You can use them to analyze both applications - for which you set up a project in \QC and applications for which you do not - have a project. - - Valgrind tools are supported locally only on Linux and \macos. However, - according to Valgrind.org, support on \macos 10.8 and 10.9 is experimental and - mostly broken. You can run the tools on a remote Linux machine or device - from any development host. - - To run the Valgrind tools to analyze an application for which you have a - project, open the project in \QC and select the kit to run the project. The - kit specifies whether the Valgrind tools are run locally or remotely. - - For more information about analyzing applications for which you do not have - a project, see \l{Running Valgrind Tools on External Applications}. - - To set preferences for the Valgrind tools, select \preferences > - \uicontrol Analyzer. You can override the general - settings for each project in the \uicontrol {Run Settings} for the project. - - The following sections describe how to use the Valgrind tools: - - \list - - \li \l{Detecting Memory Leaks with Memcheck} - - \li \l{Profiling Function Execution} - - \endlist - - \sa {Specify Valgrind settings for a project} -*/ diff --git a/doc/qtcreator/src/analyze/creator-valgrind.qdoc b/doc/qtcreator/src/analyze/creator-valgrind.qdoc index 47d4b8c1d6..d044e58119 100644 --- a/doc/qtcreator/src/analyze/creator-valgrind.qdoc +++ b/doc/qtcreator/src/analyze/creator-valgrind.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // ********************************************************************** @@ -8,92 +8,116 @@ // ********************************************************************** /*! - \previouspage creator-valgrind-overview.html - \page creator-analyzer.html - \nextpage creator-cache-profiler.html + \page creator-how-to-memcheck.html + \previouspage creator-how-tos.html - \title Detecting Memory Leaks with Memcheck + \ingroup creator-how-to-analyze - You can use the Memcheck tool included in the Valgrind tool suite to detect - problems that are related to memory management in applications. You can use + \title Detect memory leaks with Memcheck + + With the Memcheck tool in \l{Valgrind's Tool Suite}, you can detect + problems that are related to memory management in applications. Use the tool together with the GDB debugger. When a problem is detected, the application is interrupted and you can debug it. \note You can install and run Memcheck locally on Linux. You can run - it on a remote host or device from any development machine. On Windows, + it on a remote host or device from any computer. On Windows, you can use the \l{Detecting Memory Leaks with Heob}{Heob} heap observer to receive similar results. After you download and install Valgrind tools, you can use Memcheck from \QC. - To analyze applications: + To detect memory leaks in applications: \list 1 - \li In the \uicontrol Projects mode, select a debug build configuration. + \li Go to the \uicontrol Projects mode, and select a debug build + configuration. - \li Select \uicontrol Debug to open the \uicontrol Debug mode, and then - select \uicontrol Memcheck on the toolbar. + \li In the mode selector, select \uicontrol Debug > \uicontrol Memcheck. - \li Select the - \inlineimage icons/qtcreator-analyze-start-button.png "Start button" - button to start the application. + \image qtcreator-valgrind-memcheck.webp {Memcheck view} + + \li Select \inlineimage icons/qtcreator-analyze-start-button.png + to start the application. \li Use the application to analyze it. - \li Select the \inlineimage icons/stop_small.png "Stop button" - button to view the results of the analysis in the - \uicontrol {Analysis} view. + \li Select \inlineimage icons/stop_small.png to view the results of the + analysis in \uicontrol {Memory Issues}. + + \endlist + + \section1 View memory issues + While the application is running, Memcheck does the following: + + \list + \li Checks all reads and writes of memory. + \li Intercepts calls that allocate or free memory or create or + delete memory blocks. \endlist - While the application is running, Memcheck checks all reads and writes of - memory and intercepts calls that allocate or free memory or create or - delete memory blocks. The results are displayed when you stop Memcheck. - Click a line to view where a memory leak - occurred and a stack trace that shows what caused it. + You can see the results when you stop Memcheck. - As an alternative to collecting data, you can select \inlineimage icons/open.png + Select a line to see the place where a memory leak occurred and a stack trace + that shows what caused it. + + As an alternative to collecting data, select \inlineimage icons/open.png to load an external log file in XML format into the \uicontrol Memcheck view. - \image qtcreator-valgrind-memcheck.png "Memcheck view" - Move the mouse on a row to view more information about the function. To move between rows, select \inlineimage icons/prev.png - or \inlineimage icons/next.png - . + or \inlineimage icons/next.png. - To filter the results, select \inlineimage icons/filtericon.png - , and then select the types of issues to display in the view. You + To filter the results, select \inlineimage icons/filtericon.png, and + then select the types of issues to display in the view. You can view and hide definite and possible memory leaks, uninitialized values, invalid calls to \c free(), and external errors. For more information about using Memcheck, see - \l{http://valgrind.org/docs/manual/quick-start.html#quick-start.mcrun} - {Interpreting Memcheck's Output} in the Valgrind documentation. + \l{Interpreting Memcheck's Output} in the Valgrind documentation. + + \sa {Analyze}{How To: Analyze}, {Profile function execution}, + {Run Valgrind tools on external applications}, + {Specify Valgrind settings for a project}, {Analyzers}, {Valgrind Callgrind}, + {Valgrind Memcheck}, {Analyzing Code} +*/ + +/*! + \page creator-preferences-memcheck.html + \previouspage creator-reference.html - \section1 Selecting Options for Memory Analysis + \ingroup creator-reference-preferences-analyzer - You can specify analyzer settings either globally for all projects or - separately for each project in the \l{Specifying Run Settings}{run settings} - of the project. + \title Valgrind Memcheck - To specify global settings for Valgrind, select \preferences > - \uicontrol Analyzer. The \uicontrol {Memcheck Memory Analysis Options} - group has Memcheck options. + \brief Set preferences for Valgrind Memcheck. + + Set \l{Valgrind's Tool Suite}{Valgrind} preferences either globally for all + projects or separately for each project in the \l{Specifying Run Settings} + {run settings} of the project. + + To set global preferences for Valgrind, select \preferences > + \uicontrol Analyzer. Set Memcheck preferences in + \uicontrol {Memcheck Memory Analysis Options}. + + \image qtcreator-valgrind-memcheck-options.png {Memory Analysis options} In \uicontrol {Extra Memcheck arguments}, specify additional arguments for launching the executable. + \section1 Setting Stack Trace Length + Stack traces can get quite large and confusing, and therefore, reading them from the bottom up can help. If the stack trace is not big enough or it is too big, select \preferences > \uicontrol Analyzer and define the length of the stack trace in the \uicontrol {Backtrace frame count} field. - \image qtcreator-valgrind-memcheck-options.png "Memory Analysis options" + \section1 Tracking Origins of Uninitialized Memory Memcheck also reports uses of uninitialised values, most commonly with the message \uicontrol {Conditional jump or move depends on uninitialised value(s).} @@ -101,12 +125,14 @@ uninitialized memory} check box is selected by default. You can deselect it to make Memcheck run faster. + \section1 Viewing a Summary + Memcheck searches for memory leaks when the client application finishes. To view the amount of leaks that occurred, select \uicontrol {Summary Only} in the \uicontrol {Check for leaks on finish} field. To also view details of each leak, select \uicontrol Full. - \section2 Showing Reachable and Indirectly Lost Blocks + \section1 Showing Reachable and Indirectly Lost Blocks \e Reachable blocks are blocks that are pointed at by a pointer or chain of pointers and that might have been freed before the application exited. @@ -118,7 +144,7 @@ To have them reported, select the \uicontrol {Show reachable and indirectly lost blocks}. - \section2 Suppressing Errors + \section1 Suppressing Errors Memcheck detects numerous problems in the system libraries, such as the C library, which come pre-installed with your OS. As you cannot easily fix @@ -127,37 +153,40 @@ when the system is built. You can write your own suppression files if parts of your project have - errors you cannot fix and you do not want to be reminded of them. Click + errors you cannot fix and you do not want to be reminded of them. Select \uicontrol Add in the \uicontrol {MemCheck Memory Analysis} dialog to add the suppression files. + For more information about writing suppression files, see - \l{http://valgrind.org/docs/manual/manual-core.html#manual-core.suppress} - {Suppressing Errors} in the Valgrind documentation. + \l{Suppressing Errors} in the Valgrind documentation. + \sa {Detect memory leaks with Memcheck}, {Profile function execution}, + {Run Valgrind tools on external applications}, + {Specify Valgrind settings for a project}, {Valgrind Callgrind} */ /*! - \previouspage creator-analyzer.html \page creator-cache-profiler.html - \nextpage creator-running-valgrind-remotely.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-analyze - \title Profiling Function Execution + \title Profile function execution - You can use the Callgrind tool included in the - \l{http://valgrind.org/info/tools.html}{Valgrind tool suite} to detect - problems that are related to executing functions. In addition, you - can load the data files generated by Callgrind into the - \l{https://kcachegrind.github.io/html/Home.html}{KCachegrind} - profile data visualization tool for browsing the performance results. + With the Callgrind tool in \l{Valgrind's Tool Suite}, you can detect problems + that are related to executing functions. Load the data files generated by + Callgrind into the \l{https://kcachegrind.github.io/html/Home.html} + {KCachegrind} profile data visualization tool to browse the performance + results. After you download and install Valgrind tools and KCachegrind, you can use Callgrind and KCachegrind from \QC. \note You can install and run Callgrind and KCachegrind locally on Linux. You can run Callgrind on a remote Linux machine or device from any - development machine. + computer. - \section1 Building Apps for Profiling + \section1 Build apps for profiling Callgrind records the call history of functions that are executed when the application is run. It collects the number of instructions that are @@ -181,28 +210,26 @@ options for GCC are: \c{-g -O2}. It is advisable to use such a setup for Callgrind profiling. - \section1 Collecting Data + \section1 Collect data To analyze applications: \list 1 - \li In the \uicontrol Projects mode, select a release build configuration. + \li Go to the \uicontrol Projects mode, and select a release build + configuration. - \li Select \uicontrol Debug to open the \uicontrol Debug mode, and then - select \uicontrol Callgrind on the toolbar. + \li In the mode selector, select \uicontrol Debug > \uicontrol Callgrind. - \image qtcreator-valgrind-callgrind-toolbar.png "Callgrind view toolbar" + \image qtcreator-valgrind-callgrind-toolbar.png {Callgrind view toolbar} - \li Select the - \inlineimage icons/qtcreator-analyze-start-button.png "Start button" - button to start the application. + \li Select \inlineimage icons/qtcreator-analyze-start-button.png + to start the application. \li Use the application to analyze it. - \li Select the \inlineimage icons/stop_small.png "Stop button" - button to view the results of the analysis in the - \uicontrol Functions view. + \li Select \inlineimage icons/stop_small.png to view the results of the + analysis in the \uicontrol Functions view. \endlist @@ -220,7 +247,7 @@ to view the data in KCachegrind. \QC launches KCachegrind and loads the data into it for visualization. - \section1 Viewing Collected Data + \section1 View collected data The results of the analysis are displayed in the \uicontrol Callgrind views. You can detach views and move them around. To revert the changes, select @@ -261,17 +288,31 @@ To remove template parameter lists when displaying function names, select \uicontrol <>. - \section1 Selecting Profiling Options + \sa {Detect memory leaks with Memcheck}, {Profile function execution}, + {Run Valgrind tools on external applications}, + {Specify Valgrind settings for a project}, {Valgrind Callgrind}, + {Valgrind Memcheck} +*/ + +/*! + \page creator-preferences-callgrind.html + \previouspage creator-reference.html + + \ingroup creator-reference-preferences-analyzer - You can specify analyzer settings either globally for all projects or - separately for each project in the \l{Specifying Run Settings}{run settings} - of the project. + \title Valgrind Callgrind - To specify global settings for Valgrind, select \preferences > - \uicontrol Analyzer. The \uicontrol {Callgrind Profiling Options} - group has Callgrind options. + \brief Set preferences for Valgrind Callgrind. - \image qtcreator-valgrind-callgrind-options.png "Valgrind options" + Set \l{Valgrind's Tool Suite}{Valgrind} preferences either globally for all + projects or separately for each project in the \l{Specifying Run Settings} + {run settings} of the project. + + To set global preferences for Valgrind, select \preferences > + \uicontrol Analyzer. Set Callgrind preferences in + \uicontrol {Callgrind Profiling Options}. + + \image qtcreator-valgrind-callgrind-options.png {Callgrind Profiling Options} In the \uicontrol {KCachegrind executable} field, enter the path to the KCachegrind executable to launch. @@ -292,7 +333,7 @@ global bus events of the event type \c Ge that are executed, select \uicontrol {Collect global bus events}. - \section2 Enabling Full Cache Simulation + \section1 Enabling Full Cache Simulation By default, only instruction read accesses (Ir) are counted. To fully simulate the cache, select the \uicontrol {Enable cache simulation} check box. @@ -308,7 +349,7 @@ \endlist - \section2 Enabling Branch Prediction Simulation + \section1 Enabling Branch Prediction Simulation To enable the following additional event counters, select the \uicontrol {Enable branch prediction simulation} check box: @@ -323,32 +364,39 @@ \endlist - \sa {Analyzing CPU Usage}, {Detach views} + \sa {Analyzing CPU Usage}, {Detect memory leaks with Memcheck}, + {Detach views}, {Run Valgrind tools on external applications}, + {Specify Valgrind settings for a project}, + {Valgrind Memcheck} */ /*! - \previouspage creator-cache-profiler.html \page creator-running-valgrind-remotely.html - \nextpage creator-clang-tools.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-analyze - \title Running Valgrind Tools on External Applications + \title Run Valgrind tools on external applications - \QC integrates Valgrind code analysis tools for detecting memory - leaks and profiling function execution. + With \l{Valgrind's Tool Suite}, you can detect memory leaks and profile + function execution. To run the Valgrind tools to analyze external applications for which you do not have a \QC project: \list 1 - \li Select \uicontrol Analyze > \uicontrol {Valgrind Memory Analyzer (External + \li Go to \uicontrol Analyze > \uicontrol {Valgrind Memory Analyzer (External Application)} or \uicontrol {Valgrind Function Profiler (External Application)}. - \image qtcreator-valgrind-remote-settings.png "Start Remote Analysis dialog" + \image qtcreator-valgrind-remote-settings.png {Start Remote Analysis dialog} - \li Specify the application to run and analyze, and the \l{glossary-buildandrun-kit}{kit} - to use. + \li Select the application to run and analyze, as well as the + \l{glossary-buildandrun-kit}{kit} to use. \endlist + \sa {Detect memory leaks with Memcheck}, {Profile function execution}, + {Kits}, {Specify Valgrind settings for a project}, {Valgrind Callgrind}, + {Valgrind Memcheck} */ diff --git a/doc/qtcreator/src/android/androiddev.qdoc b/doc/qtcreator/src/android/androiddev.qdoc index c0fe2cedea..ab6ae2d909 100644 --- a/doc/qtcreator/src/android/androiddev.qdoc +++ b/doc/qtcreator/src/android/androiddev.qdoc @@ -3,28 +3,30 @@ /*! \page creator-developing-android.html - \previouspage creator-connecting-mobile.html - \nextpage creator-developing-baremetal.html + \previouspage creator-reference.html - \title Connecting Android Devices + \ingroup creator-reference-devices - You can connect Android devices to the development PC using USB cables to - build, run, debug, and analyze applications from \QC. + \title Developing for Android - To develop for Android, you must install a tool chain for building - applications for Android devices on the development PC. \QC can automatically - download and install the tool chain and create a suitable build and run - \l{glossary-buildandrun-kit}{kit} that has the tool chain and the Qt - version for Android for the device's architecture. + \brief Set up the toolchain for building applications for Android devices. - To enable helpful code editing features for Java, such as code completion, + Install a Qt version targeting Android and the Android SDK and NDK to develop + Qt applications for Android devices. To check the Android version supported + by each Qt version, see the \l {Qt for Android} documentation for the Qt + version. + + To get helpful code editing features for Java, such as code completion, highlighting, function tooltips, and navigating in code, add a \l{Add a Java language server}{Java language server}. \QC integrates the Android Debug Bridge (\c adb) command-line tool for deploying applications to Android devices, running them, and reading their logs. The \c adb tool includes a client and server that run on - the development host and a daemon that runs on the emulator or device. + the computer and a daemon that runs on the Android emulator or device. + + \note \QC only detects a device and connects to it after you + \l{Debug on Android Devices}{enable USB debugging on it}. The following video shows the whole process from installing Qt for Android to debugging an application on an Android device: @@ -33,18 +35,30 @@ \section1 Requirements - To use \QC to develop Qt applications for Android, you need - \l {Qt for Android} and a tool chain that \QC can automatically - download, install, and configure for you. For more information - about the requirements for developing with a particular Qt version, - see the documentation for that Qt version. The links in this manual - lead to the latest released Qt reference documentation. + To use \QC to develop Qt applications for Android, you need: + + \list + \li \l {Qt for Android} + \li \l {Android Development Prerequisites}{Android tools} that \QC can + automatically download, install, and configure for you. + \endlist + + \sa {Android}{How To: Develop for Android} +*/ + +/*! + \page creator-how-to-set-android-preferences.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-android - \section1 Specifying Android Device Settings + \title Set up Android development environment \QC offers to automatically install all the necessary packages and tools and - to set up your development environment by creating debuggers, tool chains, - and kits. You can use \QC to: + to set up your \l{Qt for Android} development environment by creating + debuggers, toolchains, and kits. + + Use \QC to: \list \li Download and extract the Android SDK Command-line Tools. @@ -55,12 +69,12 @@ To set up the development environment for Android: \list 1 - \li Select \preferences > \uicontrol Devices > \uicontrol Android. - \image qtcreator-options-android-main.png {Android preferences} - \li In the \uicontrol {JDK location} field, set the path to the JDK. + \li Go to \preferences > \uicontrol Devices > \uicontrol Android. + \image qtcreator-preferences-android.webp {Android preferences} + \li In \uicontrol {JDK location}, set the path to the JDK. \QC checks the JDK installation and reports errors. - By default, \QC tries to find a supported \l{AdoptOpenJDK} or + By default, \QC tries to find a supported \l{Adoptium OpenJDK} or \l{OpenJDK} installation. If it cannot find one, you must set the path manually. If you have not installed a supported JDK, select \inlineimage icons/online.png @@ -68,46 +82,42 @@ \note Use a 64-bit JDK because the 32-bit one might cause issues with \c cmdline-tools, and some packages might not appear in the list. - \li In the \uicontrol {Android SDK location} field, set the path to the + \li In \uicontrol {Android SDK location}, set the path to the folder to install the \l{Android SDK Command-line Tools}. \li Select \uicontrol {Set Up SDK} to automatically download and extract the Android SDK Command-line Tools to the selected path. - The SDK Manager checks that you have the necessary tools. If you need - more packages or updates, the SDK Manager offers to add or remove + SDK Manager checks that you have the necessary tools. If you need + more packages or updates, SDK Manager offers to add or remove the appropriate packages. Before taking action, it prompts you to accept the changes. In addition, it prompts you to accept Google licenses, as necessary. - \li The \uicontrol {Android NDK list} lists the installed NDK versions. - The SDK Manager installed the locked items. You can modify them only + \li \uicontrol {Android NDK list} lists the installed NDK versions. + SDK Manager installed the locked items. You can modify them only from the \uicontrol {Android SDK Manager} dialog. For more - information, see \l{Managing Android NDK Packages}. - \li Select the \uicontrol {Automatically create kits for Android tool chains} - check box to allow \QC to create the kits for you. \QC displays a + information, see \l{Manage Android NDK Packages}. + \li Select \uicontrol {Automatically create kits for Android tool chains} + to automatically create the necessary kits. \QC displays a warning if it cannot find a suitable Qt version. - \li Optionally, in the \uicontrol {Android OpenSSL Settings} group, set + \li Optionally, in \uicontrol {Android OpenSSL Settings} group, set the path to the prebuilt OpenSSL libraries. - For Qt applications that require OpenSSL support, you can - quickly add the \l {Android OpenSSL support} to your project. - For more information, see \l{Adding External Libraries}. + For Qt applications that require OpenSSL support, add + \l {Android OpenSSL support} to your project, as instructed in + \l{Adding External Libraries}. \li Select \uicontrol {Download OpenSSL} to download the OpenSSL repository to the selected path. If the automatic download fails, the download web page opens for manual download. \endlist - \section2 Manual Setup - - \note Use the latest Android SDK Command-Line Tools. \QC does not support - Android SDK Tools version 25.2.5 or earlier because it cannot fully - integrate them. + \section1 Manual setup - However, if the automatic setup does not meet your needs, you can download + If the automatic setup does not meet your needs, download and install Android SDK Command-line Tools, and then install or update the necessary NDKs, tools, and packages. For more information, see \l{Getting Started with Qt for Android}. - \section2 Viewing Android Tool Chain Settings + \section1 View Android toolchain settings A JSON configuration file defines the Android SDK Command-Line Tools download URL, the essential packages list, and the appropriate NDK for each Qt version. @@ -121,45 +131,73 @@ C:\Users\Username\AppData\Local\QtProject\qtcreator\android\sdk_definitions.json \endcode - For example, the SDK configuration file sets the NDK version 19.2.5345600 - for use with Qt 5.12.0 to 5.12.5 and Qt 5.13.0 to 5.13.1: + For example, the SDK configuration file sets the NDK version 22.1.7171670 + for use with Qt 6.3, Qt 6.2, and Qt 5.15.9 to 5.15.20: \badcode "specific_qt_versions": [ - { - "versions": ["5.12.[0-5]", "5.13.[0-1]"], - "sdk_essential_packages": ["build-tools;28.0.2", "ndk;19.2.5345600"], - "ndk_path": "ndk/19.2.5345600" - } + { "versions": ["6.3", "6.2", "5.15.[9-20]"], + "sdk_essential_packages": ["build-tools;31.0.0", "ndk;22.1.7171670"] + }, ] \endcode You can view the latest version of the configuration file that is up-to-date with the Android SDK and NDK changes, \l{sdk_definitions.json}, in Git. - \section2 Managing Android NDK Packages + \note For Qt 6.5 or later, \QC reads the NDK version that was used for + building Qt from \c modules/Core.json and uses it instead of the version + in \c sdk_definitions.json. + + \sa {Android}{How To: Develop for Android}, + {Developing for Android} +*/ + +/*! + \page creator-how-to-manage-android-ndk.html + \previouspage creator-how-tos.html - To view the installed \l{Android NDK} versions, select \preferences > + \ingroup creator-how-to-android + + \title Manage Android NDK packages + + To view the \l{Android NDK} versions that \QC installed, go to \preferences > \uicontrol Devices > \uicontrol Android. - \image qtcreator-options-android-sdk-tools.png {Android NDK and SDK checks} + \image qtcreator-preferences-android.webp {Android preferences} - The SDK Manager installed the locked items. You can modify them only + SDK Manager installed the locked items. You can modify them only in the \uicontrol {Android SDK Manager} dialog. - For more information, see \l{Managing Android SDK Packages}. + For more information, see \l{Manage Android SDK packages}. + + \section1 Download Android NDKs + + To manually download NDKs, select \inlineimage icons/online.png. - To manually download NDKs, select \inlineimage icons/online.png - . + \section1 Set default NDK To use the selected NDK version for all Qt versions by default, select \uicontrol {Make Default}. + \section1 Add NDK paths + To add custom NDK paths manually to the global list of NDKs, select - \uicontrol Add. This creates custom tool chains and debuggers associated - to that NDK. However, you have to manually create a kit that uses the - custom NDK. For more information, see \l{Add kits}. + \uicontrol Add. This creates custom toolchains and debuggers associated + to that NDK. + + You have to manually create a kit that uses the custom NDK. + + \sa {Add kits}, {Android}{How To: Develop for Android}, + {Developing for Android} +*/ + +/*! + \page creator-how-to-manage-android-sdk.html + \previouspage creator-how-tos.html - \section2 Managing Android SDK Packages + \ingroup creator-how-to-android + + \title Manage Android SDK packages Since Android SDK Tools version 25.3.0, Android has only a command-line tool, \l {sdkmanager}, for SDK package management. To make SDK management @@ -172,66 +210,105 @@ \image qtcreator-android-sdk-manager.webp {Android SDK Manager} - You can show packages for the release channel you select in - \uicontrol {Show Packages} > \uicontrol Channel. Common channel IDs include - \uicontrol Stable, \uicontrol Beta, \uicontrol Dev, and \uicontrol Canary. + \section1 Show SDK packages + + To show packages for a release channel in \uicontrol Package, select the + channel in \uicontrol {Show Packages} > \uicontrol Channel. Common channel + IDs include \uicontrol Stable, \uicontrol Beta, \uicontrol Dev, and + \uicontrol Canary. + To show and update also obsolete packages, select - \uicontrol {Include obsolete}. To filter packages, select - \uicontrol Available, \uicontrol Installed, or \uicontrol All. + \uicontrol {Include obsolete}. + + To filter packages, select \uicontrol Available, \uicontrol Installed, or + \uicontrol All. - To update the installed Android SDK packages, select - \uicontrol {Update Installed}. Select the packages to update, and then - select \uicontrol Apply. + \section1 Update SDK packages - To specify advanced \c sdkmanager settings, select - \uicontrol {Advanced Options} and enter arguments in the - \uicontrol {SDK Manager arguments} field. \uicontrol {Available arguments} - lists the arguments with descriptions. + To update the installed Android SDK packages: + \list 1 + \li Select \uicontrol {Update Installed}. + \li Select the packages to update. + \li Select \uicontrol Apply. + \endlist + + \section1 Set sdkmanager options + + To set advanced \c sdkmanager options: + + \list 1 + \li Select \uicontrol {Advanced Options}. + \li In \uicontrol {SDK Manager arguments}, enter sdkmanager options from + \uicontrol {Available arguments}. \image qtcreator-android-sdk-manager-arguments.png {Android SDK Manager Arguments dialog} + \endlist + + \sa {Android}{How To: Develop for Android}, {Developing for Android} +*/ + +/*! + \page creator-how-to-manage-avd.html + \previouspage creator-how-tos.html - \section1 Managing Android Virtual Devices (AVD) + \ingroup creator-how-to-android - To view the available AVDs, select \preferences > \uicontrol Devices. - You can add more AVDs. + \title Manage AVDs + + To view and add Android Virtual Devices (AVD), go to \preferences > + \uicontrol Devices. \image qtcreator-android-avd-manager.webp {Android device in Devices} - You can see the status of the selected device in \uicontrol {Current state}. + Select an AVD in \uicontrol Device to see its status in + \uicontrol {Current state}. + To update the status information, select \uicontrol Refresh. - To start an AVD, select \uicontrol {Start AVD}. Usually, you don't need to - start AVDs separately because \QC starts them when you - select them in the \l{Build for many platforms}{kit selector} to - \l{Deploying to Android}{deploy applications} to them. + \section1 Start AVDs - To remove an AVD from the list and the kit selector, select - \uicontrol {Erase AVD}. + To start an AVD, select \uicontrol {Start AVD}. Usually, \QC starts an AVD + when you select it in the \l{Build for many platforms}{kit selector} to + \l{Android Deploy Configuration}{deploy applications} to it. + + \section1 Set prefrences for starting AVDs - To specify options for starting an AVD, select \uicontrol {AVD Arguments}. + To set preferences for starting an AVD, select \uicontrol {AVD Arguments}. \image qtcreator-android-avd-arguments.png {Startup options for AVDs} - Specify the options in \uicontrol {Emulator command-line startup options}. + Set the preferences in \uicontrol {Emulator command-line startup options}. For available options, see \l{Start the emulator from the command line}. - \note The Android Emulator has a bug that prevents it from starting on some - systems. If an AVD does not start, you can try starting it manually by - running the following commands: + To start the emulator manually from the terminal, enter: \badcode - cd <ANDROID_SDK>/emulator + cd <ANDROID_SDK_ROOT>/emulator ./emulator -avd <AVD_NAME> \endcode - \section2 Creating a New AVD + \section1 Remove AVDs - To create new virtual devices: + To remove an AVD from the list and the kit selector, select + \uicontrol {Erase AVD}. + + \sa {Android}{How To: Develop for Android}, {Developing for Android} +*/ + +/*! + \page creator-how-to-create-avd.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-android + + \title Create an Android Virtual Device (AVD) + + To create a new Android Virtual Device (AVD): \list 1 - \li Select \preferences > \uicontrol Devices > - \uicontrol Add > \uicontrol {Android Device} to open the - \uicontrol {Create New AVD} dialog. + \li Go to \preferences > \uicontrol Devices. + \li Select \uicontrol Add > \uicontrol {Android Device} > + \uicontrol {Start Wizard}. \image qtcreator-android-create-avd.png {Create New AVD dialog} \li Set the name, definition, architecture, target API level, and SD card size of the device. @@ -241,14 +318,21 @@ For more advanced options for creating a new AVD, use the command-line tool \l{avdmanager} or the Android Studio's native AVD Manager UI. - \section1 Debugging on Android Devices + \sa {Android}{How To: Develop for Android}, {Developing for Android} +*/ + +/*! + \page creator-how-to-debug-android.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-android + + \title Debug on Android devices You enable debugging 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 - only when you tap the \uicontrol {Build number} field in \uicontrol Settings - > \uicontrol About several times. For more information, see - \l {Configure on-device developer options}. + Look for \uicontrol {USB Debugging} under \uicontrol {Developer Options}. + Tap \uicontrol {Build number} in \uicontrol Settings > \uicontrol About + several times to show \uicontrol {Developer Options}. Select a \l{glossary-build-config}{debug build configuration} to build the application for debugging. @@ -260,4 +344,7 @@ \badcode Ignoring second debugger -accepting and dropping. \endcode + + \sa {Android}{How To: Develop for Android}, {Developing for Android}, + {Configure on-device developer options} */ diff --git a/doc/qtcreator/src/android/creator-projects-settings-run-android.qdoc b/doc/qtcreator/src/android/creator-projects-settings-run-android.qdoc index 8904f69785..8753e83864 100644 --- a/doc/qtcreator/src/android/creator-projects-settings-run-android.qdoc +++ b/doc/qtcreator/src/android/creator-projects-settings-run-android.qdoc @@ -17,7 +17,7 @@ To run and debug an application on an Android device, you must create connections from the development host to the device, as instructed in - \l {Connecting Android Devices}. + \l {Developing for Android}. \section1 am Start Options @@ -66,5 +66,5 @@ \endcode \sa {Activate kits for a project}, {Configure projects for running}, - {Connecting Android Devices} + {Android}{How To: Develop for Android} */ diff --git a/doc/qtcreator/src/android/deploying-android.qdoc b/doc/qtcreator/src/android/deploying-android.qdoc index 2b3441290f..e1b83d5e04 100644 --- a/doc/qtcreator/src/android/deploying-android.qdoc +++ b/doc/qtcreator/src/android/deploying-android.qdoc @@ -2,11 +2,15 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \previouspage creator-deployment.html \page creator-deploying-android.html - \nextpage creator-deployment-b2qt.html + \previouspage creator-reference.html - \title Deploying to Android + \ingroup creator-reference-deploy-configurations + + \title Android Deploy Configuration + + \brief Create Application Packages (APK) or Android App Bundles (AAB) to + install and run on devices or to upload to the Google Play store. Android applications are packaged as ZIP files called Application Packages (APK) or Android App Bundles (AAB). You can install and run APK files on a @@ -26,7 +30,7 @@ All Qt versions do not support AABs. Qt 6.3.0 and later support multi-abi builds for applications that you build with CMake. For - more information, see \l{Qt for Android - Building User Projects}. + more information, see \l{Deploying an Application on Android}. \endlist \note Since \QC 4.12, Ministro is not supported. @@ -204,7 +208,8 @@ To add OpenSSL libraries, select \uicontrol {Include prebuilt OpenSSL libraries} in the \uicontrol {Additional Libraries} group. This will add the OpenSSL - include project defined in \l{Specifying Android Device Settings}{device settings} + include project defined in \l{Set up Android development environment} + {device settings} in \uicontrol {Android OpenSSL} group. This can be used for qmake and CMake projects. @@ -492,5 +497,8 @@ \c {android.permission.ACCESS_BACKGROUND_LOCATION} for \l{Qt Positioning}. To add a permission, select it from the list, and then click \uicontrol Add. + + \sa {Build and Run}{How To: Build and Run}, + {Android}{How To: Develop for Android}, {Android Run Settings} */ diff --git a/doc/qtcreator/src/appman/creator-appman-how-to-run.qdoc b/doc/qtcreator/src/appman/creator-appman-how-to-run.qdoc index a6319a7f2a..af2ffacaae 100644 --- a/doc/qtcreator/src/appman/creator-appman-how-to-run.qdoc +++ b/doc/qtcreator/src/appman/creator-appman-how-to-run.qdoc @@ -11,7 +11,7 @@ If you have set up \l{Qt Application Manager}, you can deploy, run, and debug applications on the desktop, remote generic SSH Linux targets, or - \l{Boot2Qt}{Boot2Qt devices}. The applications can be either + \B2Q devices. The applications can be either \e {built-in applications} or \e {third-party applications}. The former are part of the System UI or the base installation, while the latter are dynamically installed, updated, and uninstalled. @@ -118,7 +118,7 @@ \li The path to the controller that installs the application package into the target system. - When you run applications on a Boot2Qt device, you can see the device + When you run applications on a \B2Q device, you can see the device ID here. \row \li \uicontrol {Application ID} @@ -148,7 +148,10 @@ slowness and unresponsive, stuttering user interfaces. You cannot profile an in-process runtime as an individual process. - \sa {Activate kits for a project}, {Connecting Boot2Qt Devices}, - {Connecting Remote Linux Devices}, {Enable and disable plugins}, - {Run on many platforms}, {Debugging}, {Profiling QML Applications} + \sa {Activate kits for a project}, {Enable and disable plugins}, + {\B2Q}{How To: Develop for \B2Q}, + {Remote Linux}{How To: Develop for remote Linux}, + {Run on many platforms}, {Debugging}, {Debuggers}, {Debugger}, + {Developing for \B2Q Devices}, {Developing for Remote Linux Devices}, + {Profiling QML Applications} */ diff --git a/doc/qtcreator/src/baremetal/creator-baremetal-dev.qdoc b/doc/qtcreator/src/baremetal/creator-baremetal-dev.qdoc index 96fabb3624..70ded6fc36 100644 --- a/doc/qtcreator/src/baremetal/creator-baremetal-dev.qdoc +++ b/doc/qtcreator/src/baremetal/creator-baremetal-dev.qdoc @@ -1,24 +1,33 @@ -// 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-developing-android.html \page creator-developing-baremetal.html - \nextpage creator-developing-b2qt.html + \previouspage creator-reference.html - \title Connecting Bare Metal Devices + \ingroup creator-reference-devices - You can configure build and run kits to use Bare Metal tool chains installed - on the development host to build applications for Bare Metal devices. You - can connect the devices to the development host to run and debug - applications on them from \QC using GDB or a hardware debugger. This enables - you to debug on small devices that are not supported by the generic remote - Linux device plugin. + \title Developing for Bare Metal Devices + + \brief Create kits to use Bare Metal toolchains installed on the computer + to build applications for and run and debug them on connected Bare Metal + devices. + + Run and debug applications on small devices that are not supported + by the remote Linux device plugin by using GDB or a hardware debugger. + + \note Enable the Bare Metal plugin to use it. + + Install Bare Metal toolchains on the computer to build applications for + Bare Metal devices. Connect the devices to the computer to run and debug + applications on them. \note If you use qmake to build the project and the device does not have - Qt libraries, you need a fake Qt installation. + Qt libraries, you need a Qt installation that meets the requirements in + \l{Self-built Qt versions}. In addition, the \c mkspecs directory needs + to be complete enough to parse .pro files. - The following tool chains are supported for building applications: + The following toolchains are supported for building applications: \list \li GCC: Microchip Technology (AVR, AVR32, PIC16, PIC32), @@ -42,227 +51,284 @@ the device preferences. You can specify the commands to execute when connecting using a particular debug server provider. + \section1 Debug Server Providers + The following debug server providers are supported when using GDB: \list - \li \l EBlink - \li \l J-Link - \li \l OpenOCD - \li \l ST-Link + \li \l {Set up EBlink}{EBlink} + \li \l {Set up J-Link}{J-Link} + \li \l {Set up OpenOCD}{OpenOCD} + \li \l {Set up ST-Link}{ST-Link} \endlist ST-Link and J-Link debug server providers can be used together with - the \l {uVision IDE}. - - \note Enable the Bare Metal plugin to use it. - - \section1 Specifying Settings for Debug Server Providers + the \l {Set up the uVision IDE}{uVision IDE}. To create connections to bare metal devices using a debug server provider, - select \preferences > \uicontrol Devices > \uicontrol {Bare Metal} > + go to \preferences > \uicontrol Devices > \uicontrol {Bare Metal} and select \uicontrol Add. The available settings depend on the debug server provider. - \section2 EBlink + \sa {Enable and disable plugins}, {Bare Metal}{How To: Develop for Bare Metal} +*/ + +/*! + \page creator-how-to-eblink.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-bare-metal + + \title Set up EBlink \l{https://github.com/EmBitz/EBlink}{EBlink} is an ARM Cortex-M debug tool that supports squirrel scripting, live variables, and hot-plugging. \image qtcreator-baremetal-eblink.webp {Bare metal device preferences for EBlink} - To specify settings for \EBlink: + To set preferences for \EBlink: \list 1 - \include creator-baremetal-settings.qdocinc baremetal-common + \include creator-baremetal-settings.qdocinc {baremetal-common} {EBlink} - \li In the \uicontrol {Script file} field, enter the path + \li In \uicontrol {Script file}, enter the path to a device script file. - \li In the \uicontrol {Verbosity level} field, enter the level of + \li In \uicontrol {Verbosity level}, enter the level of verbose logging. - \li Select the \uicontrol {Connect under reset} check box to use - the ST-Link interface. Deselect the check box for hot-plugging. + \li Select \uicontrol {Connect under reset} to use + the ST-Link interface. Clear it for hot-plugging. - \li In the \uicontrol Type field, select the interface type. + \li In \uicontrol Type, select the interface type. - \li In the \uicontrol Speed field, enter the interface speed between + \li In \uicontrol Speed, enter the interface speed between 120 and 8000 kilohertz (kHz). - \li Select the \uicontrol {Disable cache} check box to disable the + \li Select \uicontrol {Disable cache} to disable the \EBlink flash cache. - \li Select the \uicontrol {Auto shutdown} check box to automatically + \li Select \uicontrol {Auto shutdown} to automatically shut down the \EBlink server after disconnecting. \include creator-baremetal-settings.qdocinc baremetal-init-reset \endlist - \section2 J-Link + \sa {Bare Metal}{How To: Develop for Bare Metal}, + {Developing for Bare Metal Devices} +*/ + +/*! + \page creator-how-to-jlink.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-bare-metal + + \title Set up J-Link \l{https://www.segger.com/products/debug-probes/j-link/}{J-Link} is a line of debug probes by Segger. - \image qtcreator-baremetal-jlink.webp "Bare metal device preferences for J-Link" + \image qtcreator-baremetal-jlink.webp {Bare metal device preferences for J-Link} - To specify settings for J-Link debug probes: + To set preferences for J-Link debug probes: \list 1 - \include creator-baremetal-settings.qdocinc baremetal-common + \include creator-baremetal-settings.qdocinc {baremetal-common} {J-Link} - \li In the \uicontrol {Host interface} field, select the connection + \li In \uicontrol {Host interface}, select the connection type, IP or USB, or use the default connection. - \li In the \uicontrol {Target interface} field, select the target - interface type. + \li In \uicontrol {Target interface}, select the target interface type. - \li In the \uicontrol Speed field, enter the interface speed in kHz. + \li In \uicontrol Speed, enter the interface speed in kHz. - \li In the \uicontrol Device field, select the device to connect to. + \li In \uicontrol Device, select the device to connect to. - \li In the \uicontrol {Additional arguments} field, enter - arguments for the commands. + \li In \uicontrol {Additional arguments}, enter arguments for the + commands. \include creator-baremetal-settings.qdocinc baremetal-init-reset \endlist - \section2 OpenOCD + \sa {Bare Metal}{How To: Develop for Bare Metal}, + {Developing for Bare Metal Devices} +*/ + +/*! + \page creator-how-to-openocd.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-bare-metal + + \title Set up OpenOCD \l{http://openocd.org}{OpenOCD} (Open On-Chip Debugger) is an on-chip debug solution for targets based on the ARM7 and ARM9 family with Embedded-ICE (JTAG) facility. It enables source level debugging with the GDB compiled for the ARM architecture. - \image qtcreator-baremetal-openocd.webp "Bare metal device preferences for OpenOCD" + \image qtcreator-baremetal-openocd.webp {Bare metal device preferences for OpenOCD} - To specify settings for \OpenOCD: + To set preferences for \OpenOCD: \list 1 - \include creator-baremetal-settings.qdocinc baremetal-common + \include creator-baremetal-settings.qdocinc {baremetal-common} {OpenOCD} - \li In the \uicontrol {Root scripts directory} field, enter the + \li In \uicontrol {Root scripts directory}, enter the path to the directory that has configuration scripts. - \li In the \uicontrol {Configuration file} field, enter the path + \li In \uicontrol {Configuration file}, enter the path to the device configuration file. - \li In the \uicontrol {Additional arguments} field, enter + \li In \uicontrol {Additional arguments}, enter arguments for the commands. \include creator-baremetal-settings.qdocinc baremetal-init-reset \endlist - \section2 St-Link + \sa {Bare Metal}{How To: Develop for Bare Metal}, + {Developing for Bare Metal Devices} +*/ + +/*! + \page creator-how-to-stlink.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-bare-metal + + \title Set up St-Link \l{https://www.st.com/en/development-tools/stm32-programmers.html#products} {ST-LINK Utility} is used for programming STM32 microcontrollers. - \image qtcreator-baremetal-stlink.webp "Bare metal device preferences for St-Link" + \image qtcreator-baremetal-stlink.webp {Bare metal device preferences for St-Link} - To specify settings for St-Link: + To set preferences for St-Link: \list 1 - \include creator-baremetal-settings.qdocinc baremetal-common + \include creator-baremetal-settings.qdocinc {baremetal-common} {St-Link} - \li In the \uicontrol {Verbosity level} field, enter the level of + \li In \uicontrol {Verbosity level}, enter the level of verbose logging. - \li Select the \uicontrol {Extended mode} check box to continue + \li Select \uicontrol {Extended mode} to continue listening for connection requests after the connection is closed. - \li Select the \uicontrol {Reset on connection} check box to + \li Select \uicontrol {Reset on connection} to reset the board when the connection is created. - \li In the \uicontrol Version field, select the transport + \li In \uicontrol Version, select the transport layer type supported by the device. \include creator-baremetal-settings.qdocinc baremetal-init-reset \endlist - \section2 uVision IDE + \sa {Bare Metal}{How To: Develop for Bare Metal}, + {Developing for Bare Metal Devices} +*/ + +/*! + \page creator-how-to-uvision.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-bare-metal + + \title Set up the uVision IDE \l{http://www.keil.com/support/man/docs/uv4/uv4_overview.htm}{uVision} is - an IDE for developing applications for embedded devices. Applications can - be debugged by using uVision Simulator or directly on hardware by using + an IDE for developing applications for embedded devices. To debug + applications, use uVision Simulator, or debug directly on hardware by using St-Link and J-Link. - You can view the current state of peripheral registers in the - \uicontrol {Peripheral Registers} view in Debug mode. The view - is hidden by default. + The \uicontrol {Peripheral Registers} view in Debug mode shows the current + state of peripheral registers. The view is hidden by default. - \section3 uVision Simulator + \section1 uVision Simulator - \image qtcreator-baremetal-uvision-simulator.png "Bare metal device preferences for uVision Simulator" + \image qtcreator-baremetal-uvision-simulator.png {Bare metal device preferences for uVision Simulator} - To specify settings for uVision Simulator: + To set preferences for uVision Simulator: \list 1 - \include creator-baremetal-settings.qdocinc uvision-common + \include creator-baremetal-settings.qdocinc {uvision-common} {uVision Simulator} - \li Select the \uicontrol {Limit speed to real-time} check box to limit + \li Select \uicontrol {Limit speed to real-time} to limit the connection speed. \li Select \uicontrol Apply to add the debug server provider. \endlist - \section3 uVision St-Link or JLink Debugger + \section1 uVision St-Link or JLink Debugger - \image qtcreator-baremetal-uvision-st-link.png "Bare metal device preferences for uVision St-Link" + \image qtcreator-baremetal-uvision-st-link.png {Bare metal device preferences for uVision St-Link} - To specify settings for uVision St-Link or JLink Debugger: + To set preferences for uVision St-Link or JLink Debugger: \list 1 - \include creator-baremetal-settings.qdocinc uvision-common + \include creator-baremetal-settings.qdocinc {uvision-common} {uVision St-Link or uVision JLink} - \li In the \uicontrol {Adapter options} field specify the adapter + \li In \uicontrol {Adapter options} specify the adapter interface type and speed in MHz. \li Select \uicontrol Apply to add the debug server provider. \endlist - \section1 Adding Bare Metal Devices + \sa {Bare Metal}{How To: Develop for Bare Metal}, + {Developing for Bare Metal Devices} +*/ + +/*! + \page creator-how-to-add-bare-metal-devices.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-bare-metal + + \title Add Bare Metal devices - \image qtcreator-baremetal-devices.png "Bare Metal device preferences" + Run and debug applications on small devices that are not supported + by the remote Linux device plugin by using GDB or a hardware debugger. To add a bare metal device: \list 1 - \li Select \preferences > \uicontrol Devices - > \uicontrol Add > \uicontrol {Bare Metal Device} > + \li Go to \preferences > \uicontrol Devices. + \image qtcreator-baremetal-devices.png {Bare Metal device preferences} + \li Select \uicontrol Add > \uicontrol {Bare Metal Device} > \uicontrol {Start Wizard}. - \li In the \uicontrol {Debug server provider} field, select a debug + \li In \uicontrol {Debug server provider}, select a debug server provider. \li Select \uicontrol Apply to add the device. \endlist - \section1 Building for and Running on Bare Metal Devices + \section1 Add the device to a kit To add a kit for building applications and running them on bare metal - devices, select \preferences > \uicontrol Kits - > \uicontrol Add. For more information, see \l{Add kits}. + devices, go to \preferences > \uicontrol Kits and select \uicontrol Add. - \image qtcreator-baremetal-kit.png "Kit preferences for Bare Metal" + \image qtcreator-baremetal-kit.png {Kit preferences for Bare Metal} - You can build applications for and run them on bare metal devices - in the same way as for and on the desktop. For more information, see - \l{Build for many platforms} and \l{Run on many platforms}. + Build applications for and run them on bare metal devices + in same way as for and on the desktop. - \sa {Enable and disable plugins} + \sa {Add kits}, {Build for many platforms}, + {Bare Metal}{How To: Develop for Bare Metal}, {Run on many platforms}, + {Developing for Bare Metal Devices} */ diff --git a/doc/qtcreator/src/baremetal/creator-baremetal-settings.qdocinc b/doc/qtcreator/src/baremetal/creator-baremetal-settings.qdocinc index ea35fe9855..a6688da00b 100644 --- a/doc/qtcreator/src/baremetal/creator-baremetal-settings.qdocinc +++ b/doc/qtcreator/src/baremetal/creator-baremetal-settings.qdocinc @@ -1,16 +1,19 @@ -// Copyright (C) 2023 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only //! [baremetal-common] - \li In the \uicontrol Name field, enter a name for the connection. - \li In the \uicontrol {Startup mode} field, select the mode to start + \li Go to \preferences > \uicontrol Devices > \uicontrol {Bare Metal}. + \li Select \uicontrol Add. + \li Select \uicontrol {\1}. + \li In \uicontrol Name, enter a name for the connection. + \li In \uicontrol {Startup mode}, select the mode to start the debug server provider in. - \li In the \uicontrol {Peripheral description file} field, specify a path to + \li In \uicontrol {Peripheral description file}, specify a path to a file that describes the peripherals on the device. - \li In the \uicontrol Host field, select the host name and port number + \li In \uicontrol Host, select the host name and port number to connect to the debug server provider. - \li In the \uicontrol {Executable file} field, enter the path to the + \li In \uicontrol {Executable file}, enter the path to the debug server provider executable. //! [baremetal-common] @@ -18,10 +21,10 @@ //! [baremetal-init-reset] - \li In the \uicontrol {Init commands} field, enter the commands - to execute when initializing the connection. - \li In the \uicontrol {Reset commands} field, enter the commands - to execute when resetting the connection. + \li In \uicontrol {Init commands}, enter the commands + to execute when initializing the connection. + \li In \uicontrol {Reset commands}, enter the commands + to execute when resetting the connection. \li Select \uicontrol Apply to add the debug server provider. //! [baremetal-init-reset] @@ -29,14 +32,16 @@ //! [uvision-common] - \li In the \uicontrol Name field, enter a name for the connection. - \li In the \uicontrol Host field, select the host name and port + \li Go to \preferences > \uicontrol Devices > \uicontrol {Bare Metal}. + \li Select \uicontrol Add. + \li Select \uicontrol {\1}. + \li In \uicontrol Name, enter a name for the connection. + \li In \uicontrol Host, select the host name and port number to connect to the debug server provider. - \li In the \uicontrol {Tools file path} field, enter the path to + \li In \uicontrol {Tools file path}, enter the path to the Keil toolset configuration file. - \li In the \uicontrol {Target device} field, select the device to - debug. - \li In the \uicontrol {Target driver} field, select the driver for + \li In \uicontrol {Target device}, select the device to debug. + \li In \uicontrol {Target driver}, select the driver for connecting to the target device. //! [uvision-common] diff --git a/doc/qtcreator/src/cmake/creator-how-to-debug-cmake-files.qdoc b/doc/qtcreator/src/cmake/creator-how-to-debug-cmake-files.qdoc index ac3ffb12a9..538bd7cd9a 100644 --- a/doc/qtcreator/src/cmake/creator-how-to-debug-cmake-files.qdoc +++ b/doc/qtcreator/src/cmake/creator-how-to-debug-cmake-files.qdoc @@ -20,7 +20,7 @@ \list 1 \li In the \uicontrol Edit mode, set breakpoints in a CMake file. - \li Select \uicontrol Debug > \uicontrol {Start Debugging} > + \li Go to \uicontrol Debug > \uicontrol {Start Debugging} > \uicontrol {Start CMake Debugging}. \image qtcreator-debugger-cmake.webp {DAP CMake Preset view in the Debug mode} \endlist @@ -28,6 +28,5 @@ When the application stops at a breakpoint, you can examine data in the \uicontrol Debug mode views. - \sa {Debugging},{Examining Data},{Debug Mode Views},{Setting Breakpoints}, - {CMake} + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger}, {CMake} */ diff --git a/doc/qtcreator/src/cmake/creator-how-to-profile-cmake-code.qdoc b/doc/qtcreator/src/cmake/creator-how-to-profile-cmake-code.qdoc index fc8cdd122c..a0f7b06c25 100644 --- a/doc/qtcreator/src/cmake/creator-how-to-profile-cmake-code.qdoc +++ b/doc/qtcreator/src/cmake/creator-how-to-profile-cmake-code.qdoc @@ -19,5 +19,5 @@ \image qtcreator-cmake-profiler.webp {CMake profiling information in Chrome Trace Format Visualizer} - \sa {CMake}, {Visualizing Chrome Trace Events} + \sa {CMake}, {Chrome Trace Format Visualizer} */ diff --git a/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc b/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc index 6c4b7d8ef0..1cc600123a 100644 --- a/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc +++ b/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc @@ -49,7 +49,7 @@ \sa {Configure projects for building}, {Configure projects for running}, {Build with CMake}{How To: Build with CMake}, {CMake Build Configuration}, - {Debug CMake project files}, {Deploying to Remote Linux}, {Open projects}, + {Debug CMake project files}, {Remote Linux Deploy Configuration}, {Open projects}, {Use compilation databases} */ diff --git a/doc/qtcreator/src/debugger/creator-debug-views.qdoc b/doc/qtcreator/src/debugger/creator-debug-views.qdoc index 149ac127a8..8880b64218 100644 --- a/doc/qtcreator/src/debugger/creator-debug-views.qdoc +++ b/doc/qtcreator/src/debugger/creator-debug-views.qdoc @@ -6,12 +6,17 @@ \if defined(qtdesignstudio) \previouspage creator-debugging-qml.html \else - \previouspage creator-debug-mode.html + \previouspage creator-reference.html \endif - \nextpage creator-breakpoints-view.html + + \ingroup creator-reference-debugger-views + \ingroup studio-debugger-views \title Viewing Call Stack Trace + \brief View the nested function calls leading to the current position as a + call stack trace. + When the application being debugged is interrupted, \QC displays the nested function calls leading to the current position as a call stack trace. This stack trace is built up from call stack frames, each representing a @@ -40,19 +45,27 @@ from the stopped executable and prepends the frames to the C++ frames, should it find any. You can click a frame in the QML stack to open the QML file in the editor. + + \if defined(qtcreator) + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} + \endif */ /*! \page creator-breakpoints-view.html - \previouspage creator-stack-view.html \if defined(qtdesignstudio) - \nextpage creator-locals-view.html + \previouspage creator-debugging-qml.html \else - \nextpage creator-threads-view.html + \previouspage creator-reference.html \endif + \ingroup creator-reference-debugger-views + \ingroup studio-debugger-views + \title Setting Breakpoints + \brief Set breakpoints to interrupt the application. + You can associate breakpoints with: \list @@ -128,7 +141,27 @@ \image qtcreator-debug-breakpoints.webp {Breakpoints view} - \section1 Adding Breakpoints + \if defined(qtdesignstudio) + For more information, see: + + \generatelist studio-how-to-debug + \else + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} + \endif +*/ + +/*! + \page creator-how-to-add-breakpoints.html + \if defined(qtdesignstudio) + \previouspage creator-breakpoints-view.html + \else + \previouspage creator-how-tos.html + \endif + + \ingroup creator-how-to-debug + \ingroup studio-how-to-debug + + \title Add breakpoints To add breakpoints: @@ -139,7 +172,7 @@ \list \li In the code editor, click the left margin or press \key F9 - (\key F8 on \macos) on a particular line you want the + (\key F8 on \macos) on a particular line where you want the application to stop. \li In the \uicontrol {Breakpoint Preset} view or the @@ -152,13 +185,13 @@ \endlist \endlist - \li In the \uicontrol {Breakpoint type} field, select the location in the + \li In \uicontrol {Breakpoint type}, select the location in the application code where you want the application to stop. \image qtcreator-add-breakpoint.webp {Add Breakpoints} dialog \endlist - Deselect the \uicontrol Enabled check box to make the breakpoint temporarily + Clear \uicontrol Enabled to make the breakpoint temporarily inoperative as if you had deleted it, but keep the information about the breakpoint, so that you can enable it again later. @@ -216,59 +249,37 @@ \endtable \if defined(qtcreator) - \section1 Specifying Breakpoint Settings - - You can specify settings for breakpoints in \preferences > - \uicontrol Debugger. For more information, see \l{Debugger Preferences}. - - \image qtcreator-debugger-general-options.png {General tab in Debugger preferences} - - To use a full absolute path in breakpoints, select the - \uicontrol {Set breakpoints using a full absolute path} check box. - - GDB and CDB enable setting breakpoints on source lines for which no code - was generated. In such situations, the breakpoint is shifted to the next - source code line for which the code was actually generated. To reflect - such temporary changes by moving the breakpoint markers in the source code - editor, select \uicontrol GDB > \uicontrol {Adjust breakpoint locations} - or \uicontrol CDB > \uicontrol {Correct breakpoint location}. - - When using GDB as backend, you can extend the ordinary GDB - breakpoint class by using Python. Select \uicontrol GDB > - \uicontrol {Use pseudo message tracepoints}. - - When using CDB as backend, you can specify that the debugger should break on - specific events, such as C++ exceptions, thread creation or exit, loading or - unloading \l{Viewing Modules}{application modules}, or particular output. - Select the appropriate check boxes in the \uicontrol CDB > - \uicontrol {Break on} group. To disable first-chance break on access - violation exceptions, select the \uicontrol {Ignore first chance access - violations} check box. The second occurrence of an access violation will - break into the debugger. - - You can automatically add breakpoints on some functions to catch error - and warning messages. For more information, see \l{Specifying CDB Settings} - and \l{Specifying GDB Settings}. - - For more information on breakpoints, see - \l{http://sourceware.org/gdb/onlinedocs/gdb/Breakpoints.html#Breakpoints} - {Breakpoints, Watchpoints, and Catchpoints} in GDB documentation. + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} + \endif +*/ + +/*! + \page creator-how-to-manage-breakpoints.html + \if defined(qtdesignstudio) + \previouspage creator-breakpoints-view.html + \else + \previouspage creator-how-tos.html \endif - \section1 Moving Breakpoints + \ingroup creator-how-to-debug + \ingroup studio-how-to-debug + + \title Manage breakpoints + + \section1 Move breakpoints To move a breakpoint: \list - \li Drag and drop a breakpoint marker to another line + \li Drag a breakpoint marker to another line in the text editor. \li In the \uicontrol {Breakpoint Preset} view or the \uicontrol Breakpoints view, select \uicontrol {Edit Selected Breakpoints}, and set the - line number in the \uicontrol {Line number} field. + line number in \uicontrol {Line number}. \endlist - \section1 Deleting Breakpoints + \section1 Delete breakpoints To delete breakpoints: @@ -288,9 +299,9 @@ \endlist - \section1 Enabling and Disabling Breakpoints + \section1 Turn breakpoints on and off - To temporarily disable a breakpoint without deleting it and losing associated + To temporarily turn off a breakpoint without deleting it and losing associated data like conditions and commands: \list @@ -316,7 +327,23 @@ Other than data breakpoints retain their enabled or disabled state when the debugged application is restarted. - \section1 Setting Data Breakpoints + \if defined(qtcreator) + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} + \endif +*/ + +/*! + \page creator-how-to-set-data-breakpoints.html + \if defined(qtdesignstudio) + \previouspage creator-breakpoints-view.html + \else + \previouspage creator-how-tos.html + \endif + + \ingroup creator-how-to-debug + \ingroup studio-how-to-debug + + \title Set data breakpoints A \e {data breakpoint} stops the application when data is read or written at the specified address. @@ -328,11 +355,10 @@ \li In the \uicontrol {Breakpoint Preset} or \uicontrol Breakpoints view, select \uicontrol {Add Breakpoint} in the context menu. - \li In the \uicontrol {Breakpoint type} field, select + \li In \uicontrol {Breakpoint type}, select \uicontrol {Break on data access at fixed address}. - \li In the \uicontrol Address field, specify the address of the memory - block. + \li In \uicontrol Address, specify the address of the memory block. \li Select \uicontrol OK. @@ -349,21 +375,25 @@ it manually. \if defined(qtcreator) - \sa {Debug CMake project files} + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} \endif */ /*! \page creator-locals-view.html \if defined(qtdesignstudio) - \previouspage creator-breakpoints-view.html + \previouspage creator-debugging-qml.html \else - \previouspage creator-source-files-view.html + \previouspage creator-reference.html \endif - \nextpage creator-expressions-view.html + + \ingroup creator-reference-debugger-views + \ingroup studio-debugger-views \title Local Variables and Function Parameters + \brief Inspect local variables and function parameters. + The \uicontrol {Locals} view consists of the \uicontrol Locals pane and the \uicontrol {Return Value} pane (hidden when empty). @@ -388,18 +418,18 @@ //! [0] \list \li Add and remove expression evaluators - \li Change \l{Changing Value Display format}{value display format} + \li \l{Change value display format} \li Expand and collapse view contents \li Copy view contents or expression values to the clipboard \li Open view contents in an editor \li Open memory editor \li Set data breakpoints - \li Use \l{Using Debugging Helpers}{debugging helpers} + \li Use \l{Debugging Helpers}{debugging helpers} \li Show and hide tooltips in the view when debugging \li Dereference pointers automatically \li Sort members of classes and structs alphabetically \li Use dynamic object type for display - \li Set \l{Debugger Preferences}{debugger preferences} + \li Set debugger preferences \endlist //! [0] \endif @@ -410,19 +440,27 @@ objects will be displayed. Select \uicontrol {Use dynamic object type for display} in the context menu. Keep in mind that choosing the dynamic type might be slower. + + \if defined(qtcreator) + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} + \endif */ /*! \page creator-expressions-view.html - \previouspage creator-locals-view.html \if defined(qtdesignstudio) - \nextpage creator-qml-debugging-example.html + \previouspage creator-debugging-qml.html \else - \nextpage creator-registers-view.html + \previouspage creator-reference.html \endif + \ingroup creator-reference-debugger-views + \ingroup studio-debugger-views + \title Evaluating Expressions + \brief Compute values of arithmetic expressions or function calls. + To compute values of arithmetic expressions or function calls, use expression evaluators in the \uicontrol Expressions view. @@ -515,5 +553,7 @@ appears uninitialized, its value is reported as \uicontrol {not in scope}. Not all uninitialized objects, however, can be recognized as such. + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} \endif */ diff --git a/doc/qtcreator/src/debugger/creator-only/creator-debugger-example.qdoc b/doc/qtcreator/src/debugger/creator-only/creator-debugger-example.qdoc index ccc9e82fd1..964bbaf5e1 100644 --- a/doc/qtcreator/src/debugger/creator-only/creator-debugger-example.qdoc +++ b/doc/qtcreator/src/debugger/creator-only/creator-debugger-example.qdoc @@ -95,5 +95,5 @@ (\uicontrol {Step Into}), and \inlineimage icons/debugger_stepout_small.png (\uicontrol {Step Out}). - \sa {Creating a Qt Widget Based Application}, {Debugging} + \sa {Creating a Qt Widget Based Application}, {Debugging}, {Debuggers}, {Debugger} */ diff --git a/doc/qtcreator/src/debugger/creator-only/creator-debugger-settings.qdoc b/doc/qtcreator/src/debugger/creator-only/creator-debugger-settings.qdoc index 4583460cb4..b3fef5c0e3 100644 --- a/doc/qtcreator/src/debugger/creator-only/creator-debugger-settings.qdoc +++ b/doc/qtcreator/src/debugger/creator-only/creator-debugger-settings.qdoc @@ -3,20 +3,22 @@ /*! \page creator-debugger-preferences.html - \previouspage creator-remote-debugging.html - \nextpage creator-debugging-helpers.html + \previouspage creator-reference.html - \title Debugger Preferences + \ingroup creator-reference-preferences-debugger - To specify settings for managing debugger processes, select \preferences > - \uicontrol Debugger. In the \uicontrol General tab,you can specify settings + \title General + + \brief Customize debug views and map source paths. + + To specify settings for managing debugger processes, go to \preferences > + \uicontrol Debugger. In the \uicontrol General tab, you can specify settings that are common to all debuggers. \image qtcreator-debugger-general-options.png "Debugger General preferences" - You can customize the appearance and behavior of the debug views, - \l{Specifying Breakpoint Settings}{specify settings for breakpoints}, - and map source paths to target paths. + You can customize the appearance and behavior of the debug views and + setting breakpoints, as well as map source paths to target paths. You can view debug output in the \l {Debugger Log} view. However, in some Linux distributions, such as Arch Linux, debug @@ -26,7 +28,39 @@ application, which effectively prevents storing debug output in system logs. - \section1 Mapping Source Paths + \section1 Breakpoints + + To use a full absolute path in breakpoints, select the + \uicontrol {Set breakpoints using a full absolute path} check box. + + GDB and CDB enable setting breakpoints on source lines for which no code + was generated. In such situations, the breakpoint is shifted to the next + source code line for which the code was actually generated. To reflect + such temporary changes by moving the breakpoint markers in the source code + editor, select \uicontrol GDB > \uicontrol {Adjust breakpoint locations} + or \uicontrol CDB > \uicontrol {Correct breakpoint location}. + + When using GDB as backend, you can extend the ordinary GDB + breakpoint class by using Python. Select \uicontrol GDB > + \uicontrol {Use pseudo message tracepoints}. + + When using CDB as backend, you can specify that the debugger should break on + specific events, such as C++ exceptions, thread creation or exit, loading or + unloading \l{Viewing Modules}{application modules}, or particular output. + Select the appropriate check boxes in the \uicontrol CDB > + \uicontrol {Break on} group. To disable first-chance break on access + violation exceptions, select the \uicontrol {Ignore first chance access + violations} check box. The second occurrence of an access violation will + break into the debugger. + + You can automatically add breakpoints on some functions to catch error + and warning messages. For more information, see \l{CDB} and \l{GDB}. + + For more information on breakpoints, see + \l{http://sourceware.org/gdb/onlinedocs/gdb/Breakpoints.html#Breakpoints} + {Breakpoints, Watchpoints, and Catchpoints} in GDB documentation. + + \section1 Source Paths Mapping To enable the debugger to step into the code and display the source code when using a copy of the source tree at a location different from the one @@ -48,52 +82,79 @@ of the source tree on the local machine. \endlist - \section1 Specifying GDB Settings - - To specify settings for managing the GDB process, select \preferences > - \uicontrol Debugger > \uicontrol GDB. - - \image qtcreator-preferences-debugger-gdb.webp {GDB preferences} - - To specify a timeout for terminating non-responsive GDB processes, set the - number of seconds to wait in the \uicontrol {GDB timeout} field. The default - value of 20 seconds should be sufficient for most applications, but if - loading big libraries or listing source files takes much longer than - that on slow machines, you should increase the value. - - To compress several steps into one step for less noisy debugging when - stepping into code, select the \uicontrol {Skip known frames when stepping} - check box. For example, the atomic reference counting code is skipped, and - a single \e {Step Into} for a signal emission ends up directly in the slot - connected to it. + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} +*/ - To display a message box as soon as your application receives a signal, such - as SIGSEGV, during debugging, select the \uicontrol {Show a message box when - receiving a signal} check box. +/*! + \page creator-preferences-debugger-gdb.html + \previouspage creator-reference.html - GDB allows setting breakpoints on source lines for which no code was - generated. In such situations, the breakpoint is shifted to the next - source code line for which the code was actually generated. To reflect - such temporary changes by moving the breakpoint markers in the source - code editor, select the \uicontrol {Adjust breakpoint locations} check box. + \ingroup creator-reference-preferences-debugger - To specify whether the dynamic or the static type of objects will be - displayed, select the \uicontrol {Use dynamic object type for display} - check box. Keep in mind that choosing the dynamic type might be slower. + \title GDB - To allow reading the user's default .gdbinit file on debugger startup, - select the \uicontrol {Load .gdbinit file on startup} check box. + \brief Manage the GDB process. - To use the default GDB pretty printers installed in your system - or linked to the libraries your application uses, select the - \uicontrol {Load system GDB pretty printers} check box. + To specify settings for managing the GDB process, go to \preferences > + \uicontrol Debugger > \uicontrol GDB. - By default, GDB shows AT&T style disassembly. To switch to the Intel style, - select the \uicontrol {Use Intel style disassembly} check box. + \image qtcreator-preferences-debugger-gdb.webp {GDB preferences} - To have GDB automatically save a copy of its symbol index in a cache - on disk and retrieve it from there when loading the same binary in the - future, select the \uicontrol {Use automatic symbol cache} check box. + The following table summarizes the preferences. + + \table + \header + \li Setting + \li Value + \row + \li \uicontrol {GDB timeout} + \li The timeout for terminating non-responsive GDB processes in seconds + The default value of 40 seconds should be sufficient for most + applications, but if loading big libraries or listing source files + takes much longer than that on slow machines, increase the value. + \row + \li \uicontrol {Skip known frames when stepping} + \li Compresses several steps into one step for less noisy debugging when + stepping into code. For example, the atomic reference counting code + is skipped, and a single \e {Step Into} for a signal emission ends up + directly in the slot connected to it. + \row + \li \uicontrol {Show a message box when receiving a signal} + \li Shows a message box as soon as your application receives a signal, + such as SIGSEGV, during debugging. + \row + \li \uicontrol {Adjust breakpoint locations} + \li GDB allows setting breakpoints on source lines for which no code was + generated. In such situations, the breakpoint is shifted to the next + source code line for which the code was actually generated. To reflect + such temporary changes by moving the breakpoint markers in the source + code editor, select this checkbox. + \row + \li \uicontrol {Use dynamic object type for display} + \li Whether the dynamic or the static type of objects will be + displayed. Choosing the dynamic type might make debugging slower. + \row + \li \uicontrol {Load .gdbinit file on startup} + \li Reads the user's default .gdbinit file on debugger startup. + \row + \li \uicontrol {Load system GDB pretty printers} + \li Uses the default GDB pretty printers installed on the computer + or linked to the libraries your application uses. + \row + \li \uicontrol {Use Intel style disassembly} + \li Switches from the default AT&T style disassembly to the Intel style. + \row + \li \uicontrol {Use automatic symbol cache} + \li Automatically saves a copy of the GDB symbol index in a cache on disk + and retrieves it from there when loading the same binary in the + future. + \row + \li \uicontrol {Use debug info daemon} + \li Tries to automatically retrieve debug information for system + packages. + \endtable + + \section1 Executing Additional Commands To execute GDB commands after GDB has been started, but before the debugged application is started or attached, and before the debugging helpers are @@ -111,85 +172,134 @@ To execute arbitrary Python scripts, use \c {python execfile('/path/to/script.py')}. - \section2 Extended GDB Settings + \section1 Extended GDB Settings The settings in the \uicontrol Extended group give access to advanced or experimental functions of GDB. Enabling them may negatively impact your debugging experience, so use them with care. - To use asynchronous mode to control the inferior, select the - respective check box. - - To add common paths to locations of debug information, such as - \c {/usr/src/debug}, when starting GDB, select the - \uicontrol {Use common locations for debug information} check box. + \table + \header + \li Setting + \li Value + \row + \li \uicontrol {Use asynchronous mode to control the inferior} + \li Execute commands in the background (asynchronous) mode. + GDB immediately opens a command prompt where you can issue + other commands while your program runs. + \row + \li \uicontrol {Use common locations for debug information} + \li Adds common paths to locations of debug information, such as + \c {/usr/src/debug}, when starting GDB. + \row + \li \uicontrol {Stop when qWarning() is called} + \li Adds a breakpoint on each \c qWarning() function. + \row + \li \uicontrol {Stop when qFatal() is called} + \li Adds a breakpoint on each \c qFatal() function. + \row + \li \uicontrol {Stop when abort() is called} + \li Adds a breakpoint on each \c abort() function. + \row + \li \uicontrol {Enable reverse debugging} + \li Enables stepping backwards. This feature is very slow and unstable + on the GDB side. It exhibits unpredictable behavior when steapping + backwards over system calls and is very likely to destroy your + debugging session. + \row + \li\uicontrol {Debug all child processes} + \li Keeps debugging all children after a fork. + \endtable + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} +*/ - To stop when \c qWarning, \c qFatal, or \c abort is called, select the - respective check box. +/*! + \page creator-preferences-debugger-cdb.html + \previouspage creator-reference.html - To enable stepping backwards, select the \uicontrol {Enable reverse - debugging} check box. This feature is very slow and unstable on the - GDB side. It exhibits unpredictable behavior when going backwards over - system calls and is very likely to destroy your debugging session. + \ingroup creator-reference-preferences-debugger - To keep debugging all children after a fork, select the - \uicontrol {Debug all child processes} check box. + \title CDB - \section1 Specifying CDB Settings + \brief Manage the CDB process. - To specify settings for managing the CDB process, select \preferences > + To specify settings for managing the CDB process, go to \preferences > \uicontrol Debugger > \uicontrol CDB. \image qtcreator-cdb-options.png "CDB preferences" - You can specify additional arguments for starting CDB in the - \uicontrol {Additional arguments} field. - - If a console application does not start up properly in the configured - console and the subsequent attach fails, you can diagnose the issue by - using CDB's native console. Select the \uicontrol {Use CDB console} - check box to override the console set in the Windows system - environment variables. Note that the native console does not - prompt on application exit. - - To automatically add a breakpoint on the \c CrtCbgReport() function, - select the \uicontrol {Stop when CrtCbgReport() is called} check box. - This catches runtime error messages caused by \c assert(), for example. - - In the \uicontrol {Break on} group, specify whether the debugger should - break on C++ exceptions, on thread creation or exit, on loading or - unloading the specified \l{Viewing Modules}{application modules}, or on - the specified output. - - To disable first-chance break on access violation exceptions, select the - \uicontrol {Ignore first chance access violations} check box. - The second occurrence of an access violation will break into the debugger. + The following table summarizes the preferences. + + \table + \header + \li Setting + \li Value + \row + \li \uicontrol {Additional arguments} + \li Additional arguments for starting CDB. + \row + \li \uicontrol {Use CDB console} + \li If a console application does not start up properly in the configured + console and the subsequent attach fails, diagnose the issue by + using CDB's native console. Select this checkbox to override the + console set in the Windows system environment variables. Note that + the native console does not prompt on application exit. + \row + \li \uicontrol {Ignore first chance access violations} + \li Disables first-chance break on access violation exceptions. + The second occurrence of an access violation will break into the + debugger. + \row + \li \uicontrol {Stop when CrtDbgReport() is called} + \li Automatically adds a breakpoint on the \c CrtDbgReport() function to + catch runtime error messages caused by \c assert(), for example. + \row + \li \uicontrol {Correct breakpoint location} + \li CDB enables setting breakpoints in comments or on source lines for + which no code was generated. In such situations, the breakpoint is + shifted to the next source code line for which the code was actually + generated. To reflect such temporary changes by moving the breakpoint + markers in the source code editor, select this checkbox. For more + information, see \l{Setting Breakpoints}. + \row + \li \uicontrol {Use Python dumper} + \li Uses the abstraction layer of Python Dumper classes to create a + description of data items in the \uicontrol Locals and + \uicontrol Expressions views. + For more information, see \l{Debugging Helper Implementation}. + \row + \li \uicontrol {Break on} + \li Whether the debugger should break on C++ exceptions, on thread + creation or exit, on loading or unloading the specified + \l{Viewing Modules}{application modules}, or on the specified output. + \row + \li \uicontrol {Add Exceptions to Issues View} + \li Shows information about first-chance and second-chance exceptions + in \l Issues. + \endtable + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} +*/ - CDB enables setting breakpoints in comments or on source lines for which - no code was generated. In such situations, the breakpoint is shifted to - the next source code line for which the code was actually generated. To - reflect such temporary changes by moving the breakpoint markers in the - source code editor, select the \uicontrol {Correct breakpoint location} - check box. For more information, see \l{Setting Breakpoints}. +/*! + \page creator-preferences-debugger-cdb-paths.html + \previouspage creator-reference.html - To use the abstraction layer of Python Dumper classes to create a description - of data items in the \uicontrol Locals and \uicontrol Expressions - views, select the \uicontrol {Use Python dumper} check box. - For more information, see \l{Debugging Helper Implementation}. + \ingroup creator-reference-preferences-debugger - To display information about first-chance and second-chance exceptions - in \l Issues, select the check boxes - in the \uicontrol {Add Exceptions to Issues View} group. + \title CDB Paths - \section1 Setting CDB Paths on Windows + \brief Add the Microsoft Symbol Server to the symbol search path of the + debugger. To obtain debugging information for the operating system libraries for debugging Windows applications, add the Microsoft Symbol Server to the symbol search path of the debugger: \list 1 - \li Select \preferences > \uicontrol Debugger > \uicontrol {CDB Paths}. + \li Go to \preferences > \uicontrol Debugger > \uicontrol {CDB Paths}. \image qtcreator-debugger-cdb-paths.png \li In the \uicontrol {Symbol Paths} group, select \uicontrol Insert. \li Select the directory where you want to store the cached information. @@ -204,4 +314,6 @@ To use the Source Server infrastructure for fetching missing source files directly from version control or the web, enter the following string in the \uicontrol {Source Paths} field: \c srv*. + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ diff --git a/doc/qtcreator/src/debugger/creator-only/creator-debugger-setup.qdoc b/doc/qtcreator/src/debugger/creator-only/creator-debugger-setup.qdoc index 66386d72c0..d2836a9c5f 100644 --- a/doc/qtcreator/src/debugger/creator-only/creator-debugger-setup.qdoc +++ b/doc/qtcreator/src/debugger/creator-only/creator-debugger-setup.qdoc @@ -9,61 +9,22 @@ /*! - \previouspage creator-debugging.html \page creator-debugger-engines.html - \nextpage creator-debugger-operating-modes.html + \previouspage creator-reference.html - \title Setting Up Debugger + \ingroup creator-reference-debugger - The main debugger preferences are associated with the - \l{kits-tab}{kit} you build and run your project with. To - specify the debugger and compiler to use for each kit, select - \preferences > \uicontrol Kits. + \title Supported Native Debuggers - \image qtcreator-kits.png {Kits preferences} - - You need to set up the debugger only if the automatic setup fails because - the native debugger is missing (for example, you must install the CDB - debugger on Windows yourself) or because \QC does not support the installed - version. For example, when your system does not have GDB - installed or the installed version is outdated, and you want to use a locally - installed replacement instead. - - To change the debugger in an automatically detected kit, select - \preferences > \uicontrol Kits > - \uicontrol Clone to create a copy of the kit, and change the - parameters in the cloned kit. Make sure to enable the cloned kit - for your project. - - If the debugger you want to use is not automatically detected, select - \preferences > \uicontrol Kits > - \uicontrol Debuggers > \uicontrol Add to add it. - - \image qtcreator-preferences-kits-debuggers.webp {Debuggers tab in Kits preferences} - - To use the debugging tools for Windows, you must install them. - Optionally, you can set up the Microsoft Symbol Server if you need - symbol information from Microsoft modules that is not found locally. - For more information, see \l{Setting CDB Paths on Windows}. - - To use the Free Software Foundation (FSF) version of GDB on \macos, you - must sign it and modify your kit preferences. - - This section describes the options you have for debugging C++ and Python code - and installing the supported native debuggers. It also - applies to code in other compiled languages such as C, FORTRAN, and Ada. - - For more information about launching the debugger in different modes, see - \l{Debugger Operating Modes}. - - \section1 Supported Native Debugger Versions + \brief Summary of supported debugger versions. \QC supports native debuggers for debugging compiled code. On most supported platforms, you can use the GNU Symbolic Debugger (GDB). - On Microsoft Windows, when using the Microsoft tool chain, you need the + On Microsoft Windows, when using the Microsoft toolchain, you need the Microsoft Console Debugger (CDB). On \macos and Linux, you can use the LLDB - debugger. On all supported platforms, you can use PDB to debug Python source - code. + debugger. + + On all supported platforms, you can use PDB to debug Python source code. \note You need a debugger version built with Python scripting support. @@ -85,7 +46,7 @@ \row \li \macos \li GCC, Clang - \li LLDB, FSF GDB (experimental) + \li LLDB \row \li Windows/\MinGW \li GCC @@ -96,7 +57,12 @@ \li Debugging Tools for Windows/CDB \endtable - \section2 Supported GDB Versions + The debugger plugin automatically selects a suitable native debugger for + each \l{kits-tab}{kit} from the ones found on the computer. The automatic + setup fails if the native debugger is not installed on the computer or + if \QC does not support the installed version. + + \section1 GDB Versions Use GDB 7.5, or later, with the Python scripting extension and Python version 3.5, or later. @@ -104,49 +70,6 @@ For remote debugging using GDB and GDB server, the minimum supported version of GDB server on the target \l{glossary-device}{device} is 7.0. - \section2 Supported CDB Versions - - \QC supports all versions of CDB targeting platforms that Qt supports. - - \section2 Supported LLDB Versions - - The LLDB native debugger has similar functionality to the GDB debugger. LLDB - is the default debugger in Xcode on \macos for C++ on the desktop. - LLDB is typically used with the Clang compiler (even though you can use it - with GCC, too). - - On \macos you can use the LLDB version delivered with Xcode or build from source. - The minimum supported version is LLDB 320.4. You need a LLDB version built - with Python support. - - On Linux, the minimum supported version is LLDB 3.8. - - \section2 GDB Run Modes - - The GDB native debugger used internally by the debugger plugin runs in - different modes to cope with the variety of supported platforms and - environments: - - \list - - \li Plain mode debugs locally started processes that do not need console input. - - \li Terminal mode debugs locally started processes that need a console. - - \li Attach mode debugs local processes started outside \QC. - - \li Core mode debugs core files generated from crashes. - - \li Remote mode interacts with the GDB server running on Linux. - - \endlist - - \section1 Installing Native Debuggers - - The following sections describe installing native debuggers. - - \section2 GDB - On Windows, use the Python-enabled GDB version that is bundled with the Qt package or comes with recent versions of \MinGW. On most Linux distributions, the GDB builds shipped with the system @@ -157,7 +80,9 @@ Builds of GDB shipped with Xcode on \macos are no longer supported. - \section2 Debugging Tools for Windows + \section1 Debugging Tools for Windows + + \QC supports all versions of CDB targeting platforms that Qt supports. To use the CDB debugger, install the \e {Debugging Tools for Windows} when you install \QC either by using \QOI (in \uicontrol Qt @@ -180,12 +105,12 @@ the required files in \c{"%ProgramFiles%\Debugging Tools for Windows"}. - \section2 Debugging Tools for \macos + \section1 Debugging Tools for \macos The Qt binary distribution has both debug and release variants of the libraries. However, you have to explicitly tell the runtime linker that you want to use the debug libraries even if - your application is compiled as debug, as release is the default + your application is compiled as \e debug because \e release is the default library. If you use a qmake based project in \QC, you can set a flag in @@ -196,88 +121,32 @@ For more detailed information about debugging on \macos, see: \l{http://developer.apple.com/library/mac/#technotes/tn2124/_index.html#//apple_ref/doc/uid/DTS10003391} {Mac OS X Debugging Magic}. + \section1 LLDB Versions + + The LLDB native debugger has similar functionality to the GDB debugger. LLDB + is the default debugger in Xcode on \macos for C++ on the desktop. + LLDB is typically used with the Clang compiler (even though you can use it + with GCC, too). - \section2 LLDB + On \macos you can use the LLDB version delivered with Xcode or build from source. + The minimum supported version is LLDB 320.4. You need a LLDB version built + with Python support. We recommend using the LLDB version that is delivered with the latest Xcode. - \section2 PDB + On Linux, the minimum supported version is LLDB 3.8. + + \section1 PDB Versions \l{https://docs.python.org/3/library/pdb.html}{PDB} is a source code debugger for Python applications. You can use it to debug projects that have a \l {Creating a Qt for Python Application with Qt Widgets}{.pyproject} configuration file. - You must install Python and set the interpreter to use in \uicontrol Projects - > \uicontrol Run: + Install Python and set the interpreter to use in \uicontrol Projects + > \uicontrol Run. \image qtcreator-run-settings-python.webp {Run settings for a Python project} - Start debugging the \c main.py file. If you encounter problems, check the - active build target in the kit selector. - - \QC does not support mixed-mode debugging, but you can attach GDB to the - Python interpreter to debug the C++ implementation of the corresponding - Python code. For more information, see - \l{https://doc.qt.io/qtforpython-6/tutorials/debugging/qtcreator/qtcreator.html} - {Debugging PySide with Qt Creator (Linux)}. - - \section1 Setting up FSF GDB for \macos - - To use FSF GDB on \macos, you must sign it and add it to the \QC - \l{glossary-buildandrun-kit}{kits}. - - \list 1 - - \li To create a key for signing FSF GDB, select - \uicontrol {Keychain Access} > \uicontrol {Certificate Assistant} > - \uicontrol {Create a Certificate}: - - \list 1 - - \li In the \uicontrol Name field, input \uicontrol fsfgdb to - replace the existing content. - - \li In the \uicontrol {Certificate Type} field, select - \uicontrol {Code Signing}. - - \li Select the \uicontrol {Let me override defaults} check box. - - \li Select \uicontrol Continue, and follow the instructions of the - wizard (use the default settings), until the - \uicontrol {Specify a Location For The Certificate} dialog - opens. - - \li In the \uicontrol Keychain field, select \uicontrol System. - - \li Select \uicontrol {Keychain Access} > \uicontrol System, and - locate the certificate. - - \li Double click the certificate to view certificate information. - - \li In the \uicontrol Trust section, select - \uicontrol {Always Trust} in the - \uicontrol {When using this certificate} field, and then close - the dialog. - - \endlist - - \li To sign the binary, enter the following command in the terminal: - - \code - codesign -f -s "fsfgdb" $INSTALL_LOCATION/fsfgdb - \endcode - - \li In \QC, select \uicontrol {\QC} > \uicontrol Preferences > - \uicontrol Kits > \uicontrol Add to - create a kit that uses FSF GDB. - - \li In the \uicontrol Debugger field, specify the path to FSF GDB - (\c $HOME/gdb72/bin/fsfgdb, but with an explicit value for - \c $HOME). - - \li To use the debugger, enable the kit in the \uicontrol {Build Settings} - of the project. - - \endlist + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ diff --git a/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc b/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc index d3441ab063..eee91df904 100644 --- a/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc +++ b/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc @@ -26,94 +26,202 @@ \li Debug Python source code - PDB. \endlist - The following sections describe how to set up, launch, and interact with the - debugger: + \section1 Setting Up the Debugger - \list + The debugger plugin automatically selects a suitable native debugger for + each \l{kits-tab}{kit} from the ones found on your system. You can select + another kit. To specify the debugger and compiler to use for each kit, go to + \preferences > \uicontrol Kits. - \li \l{Setting Up Debugger} + \image qtcreator-kits.png {Kits preferences} - The debugger plugin automatically selects a suitable - native debugger for each \l{glossary-buildandrun-kit}{kit} from the - ones found on your system. You can edit the kits to override this - choice. + You need to set up the debugger only if the automatic setup fails because + the native debugger is missing (for example, you must install the CDB + debugger on Windows yourself) or because \QC does not support the installed + version. For example, when your system does not have GDB + installed or the installed version is outdated, and you want to use a locally + installed replacement instead. - \li \l{Launching the Debugger} + To change the debugger in an automatically detected kit, go to + \preferences > \uicontrol Kits > + \uicontrol Clone to create a copy of the kit, and change the + parameters in the cloned kit. Make sure to enable the cloned kit + for your project. - To start an application from an open project under the control - of a debugger, select the \inlineimage icons/qtcreator-debug-button.png - (\uicontrol {Start Debugging of Startup Project}) button or press - \key F5. Other, less common start options are available in the - \uicontrol Debug > \uicontrol {Start Debugging} menu. + If the debugger you want to use is not automatically detected, go to + \preferences > \uicontrol Kits > + \uicontrol Debuggers > \uicontrol Add to add it. - \li \l{Debug Mode Views} + \image qtcreator-preferences-kits-debuggers.webp {Debuggers tab in Kits preferences} - Use the views in the \uicontrol Debug mode to inspect the - state of your application while debugging. + To use the debugging tools for Windows, you must install them. + Optionally, you can set up the Microsoft Symbol Server if you need + symbol information from Microsoft modules that is not found locally. - \li \l{Stopping Applications} + For more information, see \l{Supported Native Debuggers} and \l{CDB Paths}. - You can interrupt a running application before it terminates - or to find out why the application does not work correctly. - Set breakpoints to stop the application for examining and changing - variables, setting new breakpoints or removing old ones, and then - continue running the application. + \section1 Launching the Debugger - \li \l{Examining Data} + The debugger plugin can run the native debuggers in various operating modes + depending on where and how you start and run the debugged process. Some of + the modes are only available for a particular operating system or platform: - You can examine variable values and data structures in detail. + \list + \li \e{Start internal} to debug applications developed inside \QC, such as + a Qt Widgets-based application. This is the default start mode for + most projects, including all projects using a desktop Qt version and + plain C++ projects. + \li \e{Start external} to start and debug processes without a proper \QC + project setup, either locally or on a remote machine. + \li \e{Attach} to debug processes already started and running outside + \QC, either locally or on a remote machine. + \li \e{Core} to debug crashed processes on Unix. + \li \e{Post-mortem} to debug crashed processes on Windows. + \endlist - \li \l{Remote Debugging} + In general, \key F5 and the \uicontrol {Start Debugging of Startup Project} + button start the operating mode that fits the context. So, for a C++ + application that uses the \MinGW toolchain targeting desktop Windows, the GDB + engine starts in \e {start internal} mode. For a QML application that uses C++ + plugins, a \e mixed QML/C++ engine starts, with the C++ parts being + handled by GDB and GDB server remote debugging. - You can debug an application that runs on a remote target with the - necessary helper processes also running. + Change the run configuration parameters (such as + \uicontrol {Run in Terminal}) in the run settings of the project, or select + options from the \uicontrol Debug > \uicontrol {Start Debugging} menu to + select other modes of operation. - \li \l{Debugger Preferences} + \section2 GDB Run Modes - Specify preferences for managing debugger processes. You can specify - preferences that are common to all debuggers, or the native debugger - that you use, GDB or CDB. + The GDB native debugger used internally by the debugger plugin runs in + different modes to cope with the variety of supported platforms and + environments: - \li \l{Using Debugging Helpers} + \list + \li \e{Plain mode} debugs locally started processes that do not need + console input. + \li \e{Terminal mode} debugs locally started processes that need a + console. + \li \e{Attach mode} debugs local processes started outside \QC. + \li \e{Core mode} debugs core files generated from crashes. + \li \e{Remote mode} interacts with the GDB server running on Linux. + \endlist - \QC is able to show complex data types in a customized, - user-extensible manner. For this purpose, it takes advantage of - two technologies, collectively referred to as \e {debugging - helpers}. + \section1 Stopping Applications - \li \l{Debugging Qt Quick Projects} + You can interrupt a running application before it terminates + or to find out why the application does not work correctly. + Set breakpoints to stop the application for examining and changing + variables, setting new breakpoints or removing old ones, and then + continue running the application. - When debugging a Qt Quick application, you can inspect the state of - the application while debugging JavaScript functions. You can set - breakpoints, view call stack trace, and examine locals and - expressions. While the application is running, you can inspect QML - objects and user interfaces, as well as execute JavaScript - expressions. + Once the application starts running under the control of the debugger, it + behaves and performs as usual. - \li \l{Debugging a C++ Application} + To interrupt a running C++ application, go to \uicontrol Debug > + \uicontrol Interrupt. The debugger automatically interrupts + the application when it hits a \l {Setting Breakpoints}{breakpoint}. - Illustrates how to debug C++ applications in \QC. + Once the application stops, \QC: - \li \l{Debugging a Qt Quick Application} + \list - Illustrates how to debug Qt Quick applications in \QC. + \li Retrieves data representing the \l{Viewing Call Stack Trace} + {call stack} at the application's current position. - \li \l{Troubleshooting Debugger} + \li Retrieves the contents of \l{Local Variables and Function Parameters} + {local variables}. + + \li Examines \l{Evaluating Expressions}{expressions}. + + \li Updates the \l{Viewing and Editing Register State}{Registers}, + \l{Viewing Modules}{Modules}, and \l{Viewing Disassembled Code} + {Disassembler} views if you are debugging C++ based applications. - If you encounter problems while debugging, check for possible - solutions to them. \endlist - \sa {Debug CMake project files} -*/ + You can examine and change variables, set or remove breakpoints, and then + continue running the application. + + \section1 Examining Data + + When the application stops, you can examine certain data in the debugger. The + availability of data depends on the compiler settings when compiling the + application and the exact location where the application stops. + + Unexpected events are called \e exceptions and the debugger can stop + the application when they occur. Going to the location in the code where + the exception occurred helps you investigate the problem and find ways to + fix it. + + If you have a variable that shows text, but the application does not display + it correctly, for example, your data might be incorrect or the code that sets + the display text might do something wrong. You can step through the code and + examine changes to the variable to find out where the error occurs. + + The following video shows how to examine variable values: + + \youtube EhJ1eV_6RH8 + + \section1 Remote Debugging + + \QC makes remote debugging easy. In general, the remote debugging setup + consist of a probe running on the remote computer and a counterpart running + on the host. The probe is either integrated into the running + process (for example, for QML debugging) or runs a separate process + (for example, when using GDB server on embedded Linux). The host + side typically consists of \QC itself, often with the help of an external + process, such as GDB or CDB. + + While this setup might look daunting, it is mostly invisible to the user of + \QC. To start debugging on a remote target with the necessary helper + processes running, activate the corresponding \l{Activate kits for a project} + {kit} in \uicontrol Projects > \uicontrol {Build & Run}, and then select a + function to start remote debugging in the \uicontrol Debug > + \uicontrol {Start Debugging} menu. + Special use cases, such as attaching to a running process on the target, + might still require manual setup. You can debug an application that runs on + a remote target with the necessary helper processes also running. + + For more information, see \l{Debug remotely with GDB} and + \l{Debug remotely with CDB}. + + \section1 Using Debugging Helpers + + To show complex structures, such as \c QObjects or associative containers, + in a clear and concise manner, \QC uses Python scripts that are called + \l{Debugging Helpers}{debugging helpers}. + + \QC ships with debugging helpers for more than 200 of the most popular Qt + classes, standard C++ containers, and smart pointers, covering the usual + needs of a C++ application developer out-of-the-box. + + You can customize and add debugging helpers. + + \section1 QML and Qt Quick + + When debugging a Qt Quick application, you can inspect the state of + the application while debugging JavaScript functions. You can set + breakpoints, view call stack trace, and examine locals and + expressions. While the application is running, you can inspect QML + objects and user interfaces, as well as execute JavaScript + expressions. + + For more information, see \l{Debugging Qt Quick Projects} and + \l{Debugging a Qt Quick Application}. + + \sa {Debugging a C++ Application}, {Debug}{How To: Debug}, {Debuggers}, + {Debugger} +*/ /*! - \previouspage creator-debugger-engines.html - \page creator-debugger-operating-modes.html - \nextpage creator-debug-mode.html + \page creator-how-to-start-debugging.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-debug - \title Launching the Debugger + \title Start debugging You can start an application from an open project under the control of a debugger in the following ways: @@ -128,75 +236,46 @@ \endlist \QC checks whether the compiled application is up-to-date, and rebuilds and - deploys it if you set the \uicontrol {Build before deploying} field to - build the whole project or the application to run and select the - \uicontrol {Always deploy before running} check box in \preferences > + deploys it if you set \uicontrol {Build before deploying} to + build the whole project or the application to run and select + \uicontrol {Always deploy before running} in \preferences > \uicontrol {Build & Run} > \uicontrol General. To debug the application - without deploying it, select \uicontrol Debug > \uicontrol {Start Debugging} + without deploying it, go to \uicontrol Debug > \uicontrol {Start Debugging} > \uicontrol {Start Debugging Without Deployment}. The debugger then takes over and starts the application with suitable parameters. + You can specify breakpoints before or after launching the debugger. + For more information, see \l{Setting Breakpoints}. + + \section1 Execute GDB or CDB commands + When using GDB or CDB as debug backend, you can specify additional commands to execute before and after the backend and debugged application are started or attached in \preferences > \uicontrol Debugger > - \uicontrol GDB and \uicontrol CDB. For more information, see - \l{Debugger Preferences}. + \l GDB and \l CDB. To let the debugger read the user's default .gdbinit file when it starts, - select the \uicontrol {Load .gdbinit file on startup} check box in - GDB settings. For more information, see \l{Specifying GDB Settings}. + select \uicontrol {Load .gdbinit file on startup} in GDB settings. \note Starting a C++ application under the control of the debugger can take a long time. Typically, in the range of several seconds to minutes if you use complex features. + \section1 Debug Python projects + For \l {Creating a Qt for Python Application with Qt Widgets}{Python} projects, start debugging the \c main.py file. If you encounter problems, check the active build target in the \l{Build for many platforms}{kit selector}. - \section1 Debugger Operating Modes - - The debugger plugin can run the native debuggers in various operating modes - depending on where and how you start and run the debugged process. Some of - the modes are only available for a particular operating system or platform. - - In general, \key F5 and the \uicontrol {Start Debugging of Startup Project} - button start the operating mode that fits the context. So, for a C++ - application that uses the \MinGW toolchain targeting desktop Windows, the GDB - engine starts in \e {start internal} mode. For a QML application that uses C++ - plugins, a \e mixed QML/C++ engine starts, with the C++ parts being - handled by GDB and GDB server remote debugging. - - Change the run configuration parameters (such as - \uicontrol {Run in Terminal}) in the run settings of the project, or select - options from the \uicontrol Debug > \uicontrol {Start Debugging} menu to - select other modes of operation. - - The debugger can run in the following modes: - - \list - - \li \e{Start internal} to debug applications developed inside \QC, such as - a Qt Widgets-based application. - - \li \e{Start external} to start and debug processes without a proper \QC - project setup, either locally or on a remote machine. - - \li \e{Attach} to debug processes already started and running outside - \QC, either locally or on a remote machine. - - \li \e{Core} to debug crashed processes on Unix. - - \li \e{Post-mortem} to debug crashed processes on Windows. - - \endlist + \QC does not support mixed-mode debugging, but you can attach GDB to the + Python interpreter to debug the C++ implementation of the corresponding + Python code. For more information, see + \l{https://doc.qt.io/qtforpython-6/tutorials/debugging/qtcreator/qtcreator.html} + {Debugging PySide with Qt Creator (Linux)}. - \section2 Start Internal - - Start internal mode is the default start mode for most projects, including - all projects using a desktop Qt version and plain C++ projects. + \section1 Debug console applications If you need a console window to operate your application, for example because it accepts console input from the user, go to \uicontrol Projects > @@ -205,46 +284,49 @@ If a console application does not start up properly in the configured console and the subsequent attach fails, you can diagnose the issue by - using CDB's native console. Select \preferences > + using CDB's native console. Go to \preferences > \uicontrol Debugger > \uicontrol CDB > \uicontrol {Use CDB console} to override the console set in the Windows system environment variables. Note that the native console does not prompt on application exit. - To launch the debugger in start internal mode, click the - \uicontrol {Start Debugging} button for the active project. + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} +*/ - You can specify breakpoints before or after launching the debugger. - For more information, see \l{Setting Breakpoints}. +/*! + \page creator-how-to-debug-external-apps.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-debug - \section2 Start External + \title Start and debug an external application - You can debug any executable on your local or on a remote - machine without using a project. You specify a build and run kit that + To debug any executable on your local or on a remote + machine without using a project, specify a build and run kit that identifies the device to debug the application on. - While this mode does not strictly require a project to be open in \QC, - opening it makes setting breakpoints and stepping through the code easier. + While the \e{start external} debugger mode does not strictly require a + project to be open in \QC, opening it makes setting breakpoints and + stepping through the code easier. To start and debug an external application: \list 1 - \li Select \uicontrol Debug > \uicontrol {Start Debugging} > + \li Go to \uicontrol Debug > \uicontrol {Start Debugging} > \uicontrol {Start and Debug External Application}. \image qtcreator-debugger-start-external.png - \li In the \uicontrol Kit field, select the build and run kit to + \li In \uicontrol Kit, select the build and run kit to use for building the project. - \li In the \uicontrol {Local executable} field, specify the path to the + \li In \uicontrol {Local executable}, specify the path to the application executable on the local machine. - \li In the \uicontrol {Command line arguments} field, specify command + \li In \uicontrol {Command line arguments}, specify command line arguments to be passed to the executable. - \li In the \uicontrol {Working directory} field, specify the working + \li In \uicontrol {Working directory}, specify the working directory. It defaults to the directory of the build result. - \li Select the \uicontrol{Run in terminal} check box for console - applications. - \li Select the \uicontrol {Break at "main"} check box to stop the - debugger at the main function. - \li Select the \uicontrol {Use target extended-remote to connect} - check box to create the connection in the + \li Select \uicontrol{Run in terminal} for console applications. + \li Select \uicontrol {Break at "main"} to stop the debugger at + the main function. + \li Select \uicontrol {Use target extended-remote to connect} + to create the connection in the \c {target extended-remote mode}. In this mode, when the debugged application exits or you detach from it, the debugger remains connected to the target. You can rerun the application, attach @@ -252,29 +334,33 @@ target. For example, GDB does not exit unless it was invoked using the \c {--once} option, but you can make it exit by using the \c {monitor exit} command. - \li In the \uicontrol {Override SysRoot} field, specify the path to + \li In \uicontrol {Override SysRoot}, specify the path to the \c sysroot to use instead of the default \c sysroot. - \li In the \uicontrol {Debug information} field, specify the location + \li In \uicontrol {Debug information}, specify the location for storing debug information. You cannot use an empty path. - \li In the \uicontrol Recent field, you can select a recent + \li In \uicontrol Recent, you can select a recent configuration to use. \endlist - \section2 Attach + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} +*/ + +/*! + \page creator-how-to-attach-debugger-to-running-apps.html + \previouspage creator-how-tos.html - You can attach the debugger to applications that are already running or - instruct the debugger to attach to an application when it starts. + \ingroup creator-how-to-debug - \section3 Attaching to Running Applications + \title Attach the debugger to running applications To attach the debugger to an application already running on your local or on a remote machine: \list 1 - \li Select \uicontrol Debug > \uicontrol {Start Debugging} > + \li Go to \uicontrol Debug > \uicontrol {Start Debugging} > \uicontrol {Attach to Running Application}. \image qtcreator-debugger-attach-to-running.png - \li In the \uicontrol Filter field, enter a string to filter processes + \li In \uicontrol Filter, enter a string to filter processes by their process ID or name. \li Select a process in the list, and then select \uicontrol {Attach to Process} to start debugging. @@ -290,28 +376,46 @@ You can specify breakpoints before or after attaching the debugger to the application. For more information, see \l{Setting Breakpoints}. - \section3 Attaching to Processes when They Start + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} +*/ + +/*! + \page creator-how-to-attach-debugger-to-starting-processes.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-debug + + \title Attach the debugger to starting processes To instruct the debugger to watch an application process and to attach to it when it starts: \list 1 - \li Select \uicontrol Debug > \uicontrol {Start Debugging} > + \li Go to \uicontrol Debug > \uicontrol {Start Debugging} > \uicontrol {Attach to Unstarted Application}. \image qtcreator-debugger-attach-to-process-not-yet-started.png - \li In the \uicontrol Kit field, select the build and run kit to + \li In \uicontrol Kit, select the build and run kit to use for building the project. - \li In the \uicontrol Executable field, specify the path to the + \li In \uicontrol Executable, specify the path to the application executable. - \li Select the \uicontrol {Reopen dialog when application finishes} - check box to return to this dialog when the application is closed. - \li Select the \uicontrol {Continue on attach} check box to instruct + \li Select \uicontrol {Reopen dialog when application finishes} + to return to this dialog when the application is closed. + \li Select \uicontrol {Continue on attach} to instruct the debugger to keep the application running after attaching to it. \li Select \uicontrol {Start Watching} to wait for the application process to start. \endlist - \section2 Core + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} +*/ + +/*! + \page creator-how-to-load-core-files-to-debugger.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-debug + + \title Load core files to the debugger Use the core mode to inspect \e {core} files (crash dumps) that are generated from crashed processes on Linux and Unix systems if the system is @@ -327,38 +431,46 @@ To launch the debugger in the core mode: \list 1 - \li Select \uicontrol Debug > \uicontrol {Start Debugging} > + \li Go to \uicontrol Debug > \uicontrol {Start Debugging} > \uicontrol {Load Core File}. \image qtcreator-debugger-load-core-file.png - \li In the \uicontrol Kit field, select a build and run kit that was + \li In \uicontrol Kit, select a build and run kit that was used for building the binary for which the core file was created. If the core file stems from a binary not built by \QC or a process not initiated by \QC, select a kit that matches the setup used as - closely as possible, in respect to the specified device, tool chain, + closely as possible, in respect to the specified device, toolchain, debugger, and sysroot. - \li In the \uicontrol {Core file} field, specify the core file to - inspect. - \li In the \uicontrol {Executable of symbol file} field, specify + \li In \uicontrol {Core file}, specify the core file to inspect. + \li In \uicontrol {Executable of symbol file}, specify a file that has debug information corresponding to the core file. Typically, this is the executable file or a \c {.debug} file if the debug information is stored separately from the executable. - \li In the \uicontrol {Override start script} field, specify a + \li In \uicontrol {Override start script}, specify a script file to run instead of the default start script. - \li In the \uicontrol {Override SysRoot} field, specify the path to + \li In \uicontrol {Override SysRoot}, specify the path to the \c sysroot to use instead of the default \c sysroot. \endlist Even though using a properly configured project that has the sources of the crashed application is not strictly necessary, it is helpful. - \section2 Post-Mortem + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger}, {Kits} +*/ + +/*! + \page creator-how-to-debug-post-mortem.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-debug + + \title Debug crashed processes on Windows - The post-mortem mode is available only on Windows, if you installed the - debugging tools for Windows. + The \e{post-mortem} debugger operating mode is available only on Windows, + if you installed the debugging tools for Windows. The \QC installation program asks you whether you want to register \QC as a - post-mortem debugger. To change the setting, select + post-mortem debugger. To change the setting, go to \preferences > \uicontrol Debugger > \uicontrol General > \uicontrol {Use \QC for post-mortem debugging}. @@ -366,7 +478,16 @@ crashes on Windows. Click the \uicontrol {Debug in \QC} button in the error message from the Windows operating system. - \section1 Starting the Debugger from the Command Line + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} +*/ + +/*! + \page creator-how-to-start-debugger-from-cli.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-debug + + \title Start debugging from the command line You can use the \QC debugger interface from the command line. To attach it to a running process, specify the process ID as a parameter for the @@ -386,35 +507,17 @@ \endlist - For more information, see \l{Command-Line Options}. + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger}, + {Command-Line Options} */ /*! - \page creator-remote-debugging.html - \previouspage creator-debugger-examining-data.html - \nextpage creator-debugger-preferences.html + \page creator-how-to-debug-remotely-gdb.html + \previouspage creator-how-tos.html - \title Remote Debugging + \ingroup creator-how-to-debug - \QC makes remote debugging easy. - In general, the remote debugging setup consist of a probe running on the - remote machine and a counterpart running on the host side. The probe is - either integrated into the running process (e.g. for QML debugging) or runs - a separate process (e.g. when using GDB server on embedded Linux). The host - side typically consists of \QC itself, often with the help of an external - process, such as GDB or CDB. - - While this setup might look daunting, it is mostly invisible to the user of - \QC. To start debugging on a remote target with the necessary helper - processes running, select the corresponding - \l{glossary-buildandrun-kit}{kit} in \uicontrol Projects > - \uicontrol {Build & Run}, and then select a function to start remote - debugging in the \uicontrol Debug > \uicontrol {Start Debugging} menu. - - Special use cases, such as attaching to a running process on the target, - might still require manual setup. - - \section1 Using GDB + \title Debug remotely with GDB When debugging on a target supported by GDB server, a local GDB process talks to a GDB server running on the remote machine that controls the @@ -437,25 +540,24 @@ \list 1 - \li Select \uicontrol Debug > \uicontrol {Start Debugging} > + \li Go to \uicontrol Debug > \uicontrol {Start Debugging} > \uicontrol {Attach to Running Debug Server}. \image qtcreator-debugger-attach-to-running-debug-server.png - \li In the \uicontrol Kit field, select the build and run kit to + \li In \uicontrol Kit, select the build and run kit to use for building the project. - \li In the \uicontrol {Server port} field, enter the name of the remote + \li In \uicontrol {Server port}, enter the name of the remote machine and the port number to use. - \li In the \uicontrol {Local executable} field, specify the path to the + \li In \uicontrol {Local executable}, specify the path to the application executable on the local machine. - \li In the \uicontrol {Command line arguments} field, specify command + \li In \uicontrol {Command line arguments}, specify command line arguments to be passed to the executable. - \li In the \uicontrol {Working directory} field, specify the working + \li In \uicontrol {Working directory}, specify the working directory. It defaults to the directory of the build result. - \li Select the \uicontrol{Run in terminal} check box for console - applications. - \li Select the \uicontrol {Break at "main"} check box to stop the + \li Select \uicontrol{Run in terminal} for console applications. + \li Select \uicontrol {Break at "main"} to stop the debugger at the main function. - \li Select the \uicontrol {Use target extended-remote to connect} - check box to create the connection in the + \li Select \uicontrol {Use target extended-remote to connect} + to create the connection in the \c {target extended-remote mode}. In this mode, when the debugged application exits or you detach from it, the debugger remains connected to the target. You can rerun the application, attach @@ -463,34 +565,41 @@ target. For example, GDB does not exit unless it was invoked using the \c {--once} option, but you can make it exit by using the \c {monitor exit} command. - \li In the \uicontrol {Override SysRoot} field, specify the path to + \li In \uicontrol {Override SysRoot}, specify the path to the \c sysroot to use instead of the default \c sysroot. - \li In the \uicontrol {Init commands} field, enter the commands + \li In \uicontrol {Init commands}, enter the commands to execute immediately after the connection to a target has been established. - \li In the \uicontrol {Reset commands} field, enter the commands + \li In \uicontrol {Reset commands}, enter the commands to execute when resetting the connection to a target. - \li In the \uicontrol {Debug information} field, specify the location + \li In \uicontrol {Debug information}, specify the location for storing debug information. You cannot use an empty path. - \li In the \uicontrol {Override server channel} field, specify a + \li In \uicontrol {Override server channel}, specify a communication channel to use, such as a serial line or custom port. - \li In the \uicontrol Recent field, you can select a recent - configuration to use. + \li In \uicontrol Recent, select a recent configuration to use. \li Select \uicontrol OK to start debugging. \endlist - By default, a non-responsive GDB process is terminated after 20 seconds. - To increase the timeout in the \uicontrol {GDB timeout} field, select - \preferences > \uicontrol Debugger > - \uicontrol GDB. For more information about settings that you can specify - to manage the GDB process, see \l{Specifying GDB Settings}. + By default, a non-responsive GDB process is terminated after 40 seconds. + To increase the timeout in \uicontrol {GDB timeout}, go to \preferences > + \uicontrol Debugger > \uicontrol GDB. For more information about connecting with \c {target extended-remote} mode in GDB, see \l{https://sourceware.org/gdb/onlinedocs/gdb/Connecting.html} {Debugging with GDB: Connecting to a Remote Target}. - \section1 Using CDB + \sa {Debug}{How To: Debug}, {GDB}, {Debugging}, + {Debuggers}, {Debugger}, {Kits} +*/ + +/*! + \page creator-how-to-debug-remotely-cdb.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-debug + + \title Debug remotely with CDB In remote mode, the local CDB process talks to a CDB process that runs on the remote machine. The process is started with special command-line options @@ -555,23 +664,23 @@ \endlist - To specify settings for managing the CDB process, select \preferences > - \uicontrol Debugger > \uicontrol CDB. For more information, see - \l{Specifying CDB Settings}. + To specify settings for managing the CDB process, go to \preferences > + \uicontrol Debugger > \uicontrol CDB. + + \sa {Debug}{How To: Debug}, {CDB}, {Debugging}, {Debuggers}, {Debugger} */ /*! \page creator-debug-mode.html - \if defined(qtdesignstudio) - \previouspage studio-debugging.html - \else - \previouspage creator-debugger-operating-modes.html - \endif - \nextpage creator-stack-view.html + \previouspage creator-reference.html + + \ingroup creator-reference-debugger-views \title Debug Mode Views + \brief Inspect the state of your application while debugging. + In the \uicontrol Debug mode, you can inspect the state of your application while debugging. @@ -685,7 +794,7 @@ During debugging, the mode shows the views that you usually need to debug C++ or QML applications. To show other views or to hide views, - select \uicontrol Views. + go to \uicontrol Views. You can drag the views in \QC to new positions on the screen. \QC saves the size and position of views as a perspective for future sessions. Select @@ -714,70 +823,17 @@ interrupted. \endlist - For more information, see \l{Debugger Preferences}. -*/ - -/*! - \page creator-debugger-stopping.html - \previouspage creator-disassembler-view.html - \nextpage creator-debugger-examining-data.html - - \title Stopping Applications - - Once the application starts running under the control of the debugger, it - behaves and performs as usual. - - To interrupt a running C++ application, select \uicontrol Debug > - \uicontrol Interrupt. The debugger automatically interrupts - the application when it hits a \l {Setting Breakpoints}{breakpoint}. - - Once the application stops, \QC: - - \list - - \li Retrieves data representing the \l{Viewing Call Stack Trace} - {call stack} at the application's current position. - - \li Retrieves the contents of \l{Local Variables and Function Parameters} - {local variables}. - - \li Examines \l{Evaluating Expressions}{expressions}. - - \li Updates the \l{Viewing and Editing Register State}{Registers}, - \l{Viewing Modules}{Modules}, and \l{Viewing Disassembled Code} - {Disassembler} views if you are debugging C++ based applications. - - \endlist - You can \l{Examining Data}{Examine} and change variables, set or remove - breakpoints, and then continue running the application. + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger}, + {Debugger Views} */ /*! \page creator-debugger-examining-data.html - \previouspage creator-debugger-stopping.html - \nextpage creator-remote-debugging.html - - \title Examining Data - - When the application stops, you can examine certain data in the debugger. The - availability of data depends on the compiler settings when compiling the - application and the exact location where the application stops. - - Unexpected events are called \e exceptions and the debugger can stop - the application when they occur. Going to the location in the code where - the exception occurred helps you investigate the problem and find ways to - fix it. - - If you have a variable that shows text, but the application does not display - it correctly, for example, your data might be incorrect or the code that sets - the display text might do something wrong. You can step through the code and - examine changes to the variable to find out where the error occurs. + \previouspage creator-how-tos.html - The following video shows how to examine variable values: - - \youtube EhJ1eV_6RH8 + \ingroup creator-how-to-debug - \section1 Showing Tooltips for Simple Values + \title Show tooltips for simple values To display the value of a simple variable, hover the mouse pointer over its name in the code editor. @@ -791,11 +847,21 @@ select \uicontrol {Close Editor Tooltips} in the context menu in the \uicontrol Locals or \uicontrol Expressions view. - To disable tooltips for performance reasons, select \preferences > + To disable tooltips for performance reasons, go to \preferences > \uicontrol Debugger > \uicontrol General > \uicontrol {Use tooltips in main editor when debugging}. - \section1 Examining Complex Values in Debug Views + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger}, + {Debugger Views} +*/ + +/*! + \page creator-how-to-examine-complex-values.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-debug + + \title Examine complex values in Debug views \QC displays the raw information from the native debuggers in a clear and concise manner to simplify the debugging process without losing the power @@ -826,7 +892,7 @@ To show complex structures, such as \c QObjects or associative containers, in a clear and concise manner, \QC uses Python scripts that are called - \l{Using Debugging Helpers}{debugging helpers}. + \l{Debugging Helpers}{debugging helpers}. In addition to the generic IDE functionality of the \l {Viewing Call Stack Trace}{Stack}, \uicontrol {Locals}, @@ -839,10 +905,21 @@ classes in a useful way. To change the number of array elements that are - requested when expanding entries, select \preferences > \uicontrol {Debugger} + requested when expanding entries, go to \preferences > \uicontrol {Debugging} > \uicontrol {Locals & Expressions} > \uicontrol {Default array size}. - \section1 Stepping Through Code + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger}, + {Debugger Views} +*/ + +/*! + \page creator-how-to-step-through-code.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-debug + + \title Step through code The following table summarizes the functions that you can use to step through the code and examine the changes in variables. @@ -900,17 +977,17 @@ stopped. \endtable - \section2 Compressing Steps in GDB + \section1 Compress steps in GDB When using GDB as the debugging backend, you can compress several steps into one step for less noisy debugging. For more information, see - \l{Specifying GDB Settings}. + \l{GDB}. The extended GDB settings have the option to step backwards in code, but this option should be used with care, as it is slow and unstable on the - GDB side. For more information, see \l{Specifying GDB Settings}. + GDB side. For more information, see \l{GDB}. - \section2 Stepping into Frameworks in \macos + \section1 Step into Frameworks in \macos In \macos, external libraries are usually built into so-called Frameworks, which may have both release and debug versions of the library. When you @@ -919,7 +996,17 @@ \uicontrol {Use debug versions of Frameworks} option in the project run settings. - \section1 Inspecting Basic Qt Objects + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger}, + {Debugger Views} +*/ + +/*! + \page creator-how-to-inspect-basic-qt-objects.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-debug + + \title Inspect basic Qt objects The most powerful feature of the debugger is that the \uicontrol {Locals} and \uicontrol {Expressions} views show the data that belongs to @@ -931,16 +1018,16 @@ displays the contents of a QHash or QMap in an orderly manner. Also, the debugger shows access data for QFileInfo and the \e real contents of QVariant. - \section2 Changing Value Display format + \section1 Change value display format In the \uicontrol {Locals} or the \uicontrol {Expressions} view, select \uicontrol {Change Value Display Format} in the context menu to change the value display format. The available options depend on the type of the - current items, and are provided by the debugging helpers. + current items, and are provided by \l{Debugging Helpers}{debugging helpers}. - To force a plain C-like display of structures, select \preferences > - \uicontrol Debugger > \uicontrol {Locals & Expressions}, and then deselect the - \uicontrol {Use Debugging Helpers} check box. This still uses the + To force a plain C-like display of structures, go to \preferences > + \uicontrol Debugger > \uicontrol {Locals & Expressions}, and then clear + \uicontrol {Use Debugging Helpers}. This still uses the Python scripts, but generates more basic output. To force the plain display for a single object or for all objects of a given type, select \uicontrol {Change Value Display Format} > \uicontrol Raw in the context @@ -961,7 +1048,7 @@ instead of a single line item in the view. For QPixmap, you can see the pixmap being created pixel-by-pixel when stepping through the code. - \section2 Changing Variable Values + \section1 Change variable values You can use the \uicontrol {Locals} and \uicontrol {Expressions} view to change the contents of variables of simple data types, for example, \c int, \c float, @@ -975,11 +1062,11 @@ applies the changes only if the new content fits into the old memory and if the debugger supports changing values. - \section2 Signal-Slot Connections + \section1 Signal-slot connections If an instance of a class is derived from QObject, you can find all other objects connected to this object's slots with Qt's signals and slots - mechanism. Select \preferences > \uicontrol {Debugger} > + mechanism. Go to \preferences > \uicontrol {Debugging} > \uicontrol {Locals & Expressions} > \uicontrol {Use Debugging Helpers}. \image qtcreator-debugging-helper-options.webp {Locals & Expressions preferences} @@ -988,7 +1075,7 @@ in the \e slots subitem. The view shows the objects connected to this slot as children of the slot. Similarly, you can show the children of signals. - \section2 Low-level Data + \section1 Low-level data If you cannot debug Qt objects because their data is corrupted, you can switch off the debugging helpers to make low-level structures visible. @@ -998,7 +1085,7 @@ \uicontrol Debugger > \uicontrol {Locals & Expressions}. \omit - \section2 Creating Snapshots + \section1 Create snapshots A snapshot has the complete state of the debugged application at a time, including the full memory contents. @@ -1015,15 +1102,20 @@ \l{https://sourceware.org/gdb/onlinedocs/gdb/Core-File-Generation.html}. \endomit + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ /*! \page creator-threads-view.html - \previouspage creator-breakpoints-view.html - \nextpage creator-modules-view.html + \previouspage creator-debug-mode.html + + \ingroup creator-reference-debugger-views \title Viewing Threads + \brief View the threads currently active in a multi-threaded application. + An application can have more than one thread of execution that share one address space, which means that they can examine and change the same variables. However, each thread has its own registers, execution stack, @@ -1042,15 +1134,20 @@ The \l {Viewing Call Stack Trace}{Stack} view adjusts its contents accordingly. + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ /*! \page creator-modules-view.html - \previouspage creator-threads-view.html - \nextpage creator-source-files-view.html + \previouspage creator-debug-mode.html + + \ingroup creator-reference-debugger-views \title Viewing Modules + \brief View information about the modules included in a debugged application. + The \uicontrol Modules view displays information that the debugger plugin has about modules included in the application that is being debugged. @@ -1088,7 +1185,7 @@ \li Show sections in modules - \li Set \l{Debugger Preferences}{debugger preferences} + \li Set \l{Debugger}{debugger preferences} \endlist @@ -1099,21 +1196,26 @@ When using CDB as debug backend, you can specify that the debugger should break when application modules are loaded or unloaded. To enable breaking - for the specified modules, select \preferences > \uicontrol Debugger > + for the specified modules, go to \preferences > \uicontrol Debugger > \uicontrol CDB. \image qtcreator-cdb-options.png {CDB tab in Debugger preferences} - For more information, see \l{Specifying CDB Settings}. + For more information, see \l{CDB}. + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ /*! \page creator-source-files-view.html - \previouspage creator-modules-view.html - \nextpage creator-locals-view.html + \previouspage creator-debug-mode.html + + \ingroup creator-reference-debugger-views \title Viewing Source Files + \brief View source files included in a debugged project. + The \uicontrol {Source Files} view lists all the source files included in the project. If you cannot step into an instruction, you can check whether the source file is actually part of the project, or whether it was compiled @@ -1126,7 +1228,7 @@ \list \li Reload data \li Open the selected file - \li Set \l{Debugger Preferences}{debugger preferences} + \li Set \l{Debugger}{debugger preferences} \endlist By default, the \uicontrol {Source Files} view is hidden. To show it, select @@ -1137,20 +1239,26 @@ To enable the debugger to step into the code and display the source code when using a copy of the source tree at a location different from the one at which the libraries were built, you can map source paths to target - paths in \preferences > \uicontrol Debugger > \uicontrol General: + paths in \preferences > \uicontrol Debugger > \uicontrol General. \image qtcreator-debugger-general-options.png {General tab in Debugger preferences} - For more information, see \l{Mapping Source Paths}. + For more information, see \l{Source Paths Mapping}. + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ /*! \page creator-registers-view.html - \previouspage creator-expressions-view.html - \nextpage creator-peripheral-registers-view.html + \previouspage creator-debug-mode.html + + \ingroup creator-reference-debugger-views \title Viewing and Editing Register State + \brief View the current state of general-purpose and special-purpose CPU + registers. + \e {Machine code} consists of machine language instructions that make the CPU perform tasks, such as load or store, on units of data in the CPU's registers or memory. @@ -1177,7 +1285,7 @@ \li Open \l {Examining Memory}{Memory Editor} at the selected value. \li Open the \l {Viewing Disassembled Code}{Disassembler} view. \li Display a value in hexadecimal, decimal, octal, or binary format. - \li Set \l{Debugger Preferences}{debugger preferences}. + \li Set \l{Debugger}{debugger preferences}. \endlist By default, the \uicontrol Registers view is hidden. To show it, select it in @@ -1203,15 +1311,21 @@ \li Set a data breakpoint on the selection. \li Jump to the selected address in the current data view or a new one. \endlist + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ /*! \page creator-peripheral-registers-view.html - \previouspage creator-registers-view.html - \nextpage creator-debugger-log-view.html + \previouspage creator-debug-mode.html + + \ingroup creator-reference-debugger-views \title Peripheral Registers + \brief View the current state of peripheral devices, such as a mouse, + keyboard, display, printer, or USB drive. + The \uicontrol {Peripheral Registers} view displays the current state of peripheral devices, such as a mouse, keyboard, display, printer, or USB drive. Applications write registers to send information to the device and @@ -1231,28 +1345,33 @@ \list \li View register groups. - \li Set \l{Debugger Preferences}{debugger preferences}. + \li Set \l{Debugger}{debugger preferences}. \endlist By default, the \uicontrol {Peripheral Registers} view is hidden. To show it, select it in \uicontrol Views on the debugger toolbar. + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ /*! \page creator-debugger-log-view.html - \previouspage creator-peripheral-registers-view.html - \nextpage creator-disassembler-view.html + \previouspage creator-debug-mode.html + + \ingroup creator-reference-debugger-views \title Debugger Log + \brief Troubleshoot the debugger. + You can view debug output in the \uicontrol {Debugger Log} view to \l {Debugger Does Not Work}{troubleshoot the debugger}. \image qtcreator-debugger-log-view.webp {Debugger Log view} - If debug output is sent to the system log, select \preferences > - \uicontrol Debugger > \uicontrol General > - \uicontrol {Force logging to console} check box. + If debug output is sent to the system log, go to \preferences > + \uicontrol Debugger > \uicontrol General and select + \uicontrol {Force logging to console}. Right-click the view to select the following actions: @@ -1265,7 +1384,7 @@ \li Log time stamps. \li Reload debugging helpers after \l{Adding Custom Debugging Helpers} {adding custom debugging helpers}. - \li Set \l{Debugger Preferences}{debugger preferences}. + \li Set \l{Debugger}{debugger preferences}. \endlist \section1 Directly Interacting with Native Debuggers @@ -1282,15 +1401,20 @@ handle the task. For example, instead of using the GDB \c print command from the command line, you can evaluate an expression in the \l {Evaluating Expressions}{Expressions} view. + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ /*! \page creator-disassembler-view.html - \previouspage creator-debugger-log-view.html - \nextpage creator-debugger-stopping.html + \previouspage creator-debug-mode.html + + \ingroup creator-reference-debugger-views \title Viewing Disassembled Code + \brief View disassembled code for the current function. + A \e disassembler translates machine language into assembly language for human-readability. @@ -1301,13 +1425,13 @@ \image qtcreator-debugger-disassembler-view.webp {Disassembler view} By default, GDB shows AT&T style disassembly. To switch to the Intel style, - select \preferences > \uicontrol Debugger > + go to \preferences > \uicontrol Debugger > \uicontrol GDB > \uicontrol {Use Intel style disassembly}. To open the \uicontrol Disassembler view: \list - \li Select \uicontrol Debug > \uicontrol {Operate by Instruction} while + \li Go to \uicontrol Debug > \uicontrol {Operate by Instruction} while the debugger is running. \li Select the \inlineimage icons/debugger_singleinstructionmode.png (\uicontrol {Operate by Instruction}) tool button on the debugger @@ -1323,24 +1447,19 @@ \uicontrol {Open Disassembler} and set the disassembler address: \image qcreator-debugger-select-start-address.webp {Select Start Address dialog} + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ /*! - \previouspage creator-debugger-preferences.html \page creator-debugging-helpers.html - \nextpage creator-debugging-qml.html + \previouspage creator-debug-mode.html - \title Using Debugging Helpers + \ingroup creator-reference-debugger - To show complex structures, such as \c QObjects or associative containers, - in a clear and concise manner, \QC uses Python scripts that are called - \e {debugging helpers}. - - \QC ships with debugging helpers for more than 200 of the most popular Qt - classes, standard C++ containers, and smart pointers, covering the usual - needs of a C++ application developer out-of-the-box. + \title Debugging Helpers - \section1 Extending Debugging Helpers + \brief Load, customize, and add debugging helpers. \QC uses Python scripts to translate raw memory contents and type information data from native debugger backends (GDB, LLDB, and CDB are currently supported) @@ -1357,17 +1476,17 @@ least one of the three supported backends is available. To use the default GDB pretty printers installed in your system or linked - to the libraries your application uses, select \preferences > + to the libraries your application uses, go to \preferences > \uicontrol Debugger > \uicontrol GDB > \uicontrol {Load system GDB pretty - printers}. For more information, see \l{Specifying GDB Settings}. + printers}. For more information, see \l{GDB}. \image qtcreator-preferences-debugger-gdb.webp {GDB preferences} - \section2 Customizing Built-In Debugging Helpers + \section1 Customizing Built-In Debugging Helpers You can have commands executed after built-in debugging helpers have been loaded and fully initialized. To load additional debugging helpers or - modify existing ones, select \preferences > \uicontrol Debugger > + modify existing ones, go to \preferences > \uicontrol Debugger > \uicontrol {Locals & Expressions}, and enter the commands in the \uicontrol {Debugging Helper Customization} field. @@ -1389,10 +1508,10 @@ \endcode To display a message box as soon as your application receives a signal - during debugging, select \preferences > \uicontrol Debugger > \uicontrol GDB > + during debugging, go to \preferences > \uicontrol Debugger > \uicontrol GDB > \uicontrol {Show a message box when receiving a signal}. - \section2 Adding Custom Debugging Helpers + \section1 Adding Custom Debugging Helpers To add debugging helpers for your own types, no compilation is required, just adding a few lines of Python. The scripts can address multiple versions @@ -1444,7 +1563,7 @@ \uicontrol {Reload Debugging Helpers} from the context menu of the \l {Debugger Log} view. - \section2 Debugging Helper Overview + \section1 Debugging Helper Overview The implementation of a debugging helper typically consists of a single Python function, which needs to be named \c{qdump__NS__Foo}, where @@ -1532,7 +1651,7 @@ d.putArrayData(base, size, typeobj) \endcode - \section2 Debugging Helper Implementation + \section1 Debugging Helper Implementation A debugging helper creates a description of the displayed data item in a format that is similar to GDB/MI and JSON. @@ -1586,7 +1705,7 @@ members specified in \c qtcreator\share\qtcreator\debugger\dumper.py. - \section3 Dumper Class + \section2 Dumper Class The \c Dumper class has generic bookkeeping, low-level, and convenience functions: @@ -1752,7 +1871,7 @@ \endlist - \section3 Dumper.Type Class + \section2 Dumper.Type Class The \c{Dumper.Type} class describes the type of a piece of data, typically a C++ class or struct, a pointer to a struct, or a primitive type, such as @@ -1807,7 +1926,7 @@ \endlist - \section3 Dumper.Field Class + \section2 Dumper.Field Class The \c{Dumper.Field} class describes a base class or a data member of a type object: @@ -1830,7 +1949,7 @@ \endlist - \section3 Dumper.Value Class + \section2 Dumper.Value Class The \c{Dumper.Value} class describes a piece of data, such as instances of C++ classes or primitive data types. It can also be used to describe @@ -1892,7 +2011,7 @@ \endlist - \section3 Children and SubItem Class + \section2 Children and SubItem Class The attempt to create child items might lead to errors if data is uninitialized or corrupted. To gracefully recover in such situations, use @@ -1931,16 +2050,21 @@ d.putSubItem("key", key) d.putSubItem("value", value) \endcode + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ /*! - \previouspage creator-qml-debugging-example.html \page creator-troubleshooting-debugging.html - \nextpage creator-analyze-mode.html + \previouspage creator-reference.html + + \ingroup creator-reference-debugger \title Troubleshooting Debugger + \brief Solve problems that you might encounter while debugging. + This section lists some typical problems that you might encounter while debugging and solutions to them. @@ -1984,9 +2108,9 @@ \l {Run on many platforms}{build and run kit selector} picked a runnable target and you can run the application. - \li Make sure the debugger is \l{Setting Up Debugger}{set up properly}. + \li Make sure the debugger is \l{Supported Native Debuggers}{set up properly}. - \li In the \uicontrol Debug mode, select \uicontrol View > + \li In the \uicontrol Debug mode, go to \uicontrol View > \uicontrol Views > \uicontrol {Debugger Log} to open the \l {Debugger Log} view. Browse the contents of the pane on the right hand side to find out what went wrong. Always attach the @@ -2026,7 +2150,7 @@ When using GDB as backend, you can automatically save a copy of its symbol index in a cache on disk and retrieve it from there - when loading the same binary in the future. Select \preferences > + when loading the same binary in the future. Go to \preferences > \uicontrol Debugger > \uicontrol GDB > \uicontrol {Use automatic symbol cache}. \image qtcreator-preferences-debugger-gdb.webp {GDB preferences} @@ -2082,4 +2206,5 @@ calls \c{prctl(0x59616d61, getppid(), 0, 0, 0);}, such as the one in \c{$QTCREATORDIR/lib/libptracepreload.so} to the LD_PRELOAD environment. + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ diff --git a/doc/qtcreator/src/debugger/qtquick-debugger-example.qdoc b/doc/qtcreator/src/debugger/qtquick-debugger-example.qdoc index 614219ce63..e7141a99f2 100644 --- a/doc/qtcreator/src/debugger/qtquick-debugger-example.qdoc +++ b/doc/qtcreator/src/debugger/qtquick-debugger-example.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2018 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // ********************************************************************** @@ -33,7 +33,7 @@ \if defined(qtdesignstudio) \note In this tutorial, you are using advanced menu items. These are not visible by default. To toggle the visibility of advanced menu items, see - \l{Customizing the Menu}. + \l{Customizing the Menu Bar}. \endif @@ -47,13 +47,13 @@ border on the line where the \c startNewGame() function is called (1). - \image qtquick-example-setting-breakpoint1.png + \image qtquick-example-setting-breakpoint1.webp {Breakpoint in the code editor} The red circle indicates that a breakpoint is now set on that line number. - \li Select \uicontrol Debug > \uicontrol {Start Debugging} > - \uicontrol {Start Debugging of Startup Project} or press + \li Go to \uicontrol Debug > \uicontrol {Start Debugging} > + \uicontrol {Start Debugging of Startup Project}, or press \key{F5}. \li Once the Same Game application starts, select \uicontrol {Puzzle} @@ -63,26 +63,26 @@ \li When the debugger hits the breakpoint, it interrupts the application. \QC displays the nested function calls leading to the - current position as a call stack trace (1). + current position as a call stack trace. - \image qtquick-example-setting-breakpoint2.png + \image qtquick-example-setting-breakpoint2.webp {Debugger view} - \li Click the \inlineimage icons/debugger_stepinto_small.png - (\uicontrol {Step Into}) button on the toolbar or press \key F11 to step + \li Select \inlineimage icons/debugger_stepinto_small.png + (\uicontrol {Step Into}) on the toolbar or press \key F11 to step into the code in the stack. The samegame.js file opens in the code editor at the function that starts a new game. - \image qtquick-example-stack.png + \image qtquick-example-stack.webp {Stack view} \li Examine the local variables in the \uicontrol Locals view. Step through the code to see how the information changes in the view. \li Add a breakpoint at the end of the \c {startNewGame()} function, and - click \inlineimage icons/qtcreator-debugging-continue.png + select \inlineimage icons/qtcreator-debugging-continue.png (\uicontrol Continue) to hit the breakpoint. - \image qtquick-example-setting-breakpoint3.png + \image qtquick-example-setting-breakpoint3.webp {Second breakpoint in the Breakpoints view} \li To execute JavaScript commands in the current context, open the \uicontrol {QML Debugger Console}. @@ -97,11 +97,11 @@ \image qtquick-example-qml-inspector.png - \li Select \uicontrol Debug > \uicontrol {Show Application on Top} to + \li Go to \uicontrol Debug > \uicontrol {Show Application on Top} to keep the application visible while you interact with the debugger. - \li Select \uicontrol Debug > \uicontrol Select to activate selection - mode and then click the \uicontrol Menu button to move into the + \li Go to \uicontrol Debug > \uicontrol Select to activate selection + mode, and then select \uicontrol Menu to move into the \uicontrol menuButton component in the \uicontrol Locals view and the code editor. diff --git a/doc/qtcreator/src/debugger/qtquick-debugging.qdoc b/doc/qtcreator/src/debugger/qtquick-debugging.qdoc index 325e53bc3f..1d4f41f789 100644 --- a/doc/qtcreator/src/debugger/qtquick-debugging.qdoc +++ b/doc/qtcreator/src/debugger/qtquick-debugging.qdoc @@ -13,15 +13,17 @@ \previouspage studio-debugging.html \nextpage creator-stack-view.html \else - \previouspage creator-debugging-helpers.html - \nextpage creator-debugging-example.html + \previouspage creator-reference.html \endif + \ingroup creator-reference-debugger + \ingroup studio-debugger + \title Debugging Qt Quick Projects - \if defined(qtcreator) - \note You need Qt 5.0 or later to debug Qt Quick projects. - \endif + \brief Debug JavaScript functions, execute JavaScript expressions to get + information about the state of the UI, and inspect QML properties and + JavaScript variables, as well as change their values temporarily at runtime. For an example of how to debug Qt Quick Projects, see \l{Debugging a Qt Quick Application}. @@ -29,7 +31,7 @@ \if defined(qtdesignstudio) \note In this section, you are using advanced menu items. These are not visible by default. To toggle the visibility of advanced menu items, see - \l{Customizing the Menu}. + \l{Customizing the Menu Bar}. \endif \section1 Setting Up QML Debugging @@ -56,8 +58,9 @@ \list 1 \li To create a build configuration that supports QML debugging, - select \uicontrol {Projects} > \uicontrol {Build} > - \uicontrol {QML debugging and profiling} > \uicontrol Enable. + go to \uicontrol {Projects} > \uicontrol {Build}. + + \li In \uicontrol {QML debugging and profiling}, select \uicontrol Enable. \image qtcreator-build-settings-cmake-configure.webp {Build settings for a CMake project} @@ -79,7 +82,7 @@ rebuild the project. \li To debug applications on \l{glossary-device}{devices}, check that - Qt 5.0, or later, libraries are installed on the device and + Qt libraries are installed on the device and \l{Run on many platforms}{select the corresponding kit for the device} before you start debugging. @@ -179,7 +182,7 @@ \note Setting breakpoints is only possible if the application is started with block mode. - \li Select \uicontrol Debug > \uicontrol {Start Debugging} > + \li Go to \uicontrol Debug > \uicontrol {Start Debugging} > \uicontrol {Attach to QML Port}. Choose the kit configured for the device where the application to @@ -225,7 +228,7 @@ \li Select the item in the code editor. - \li Select \uicontrol Debug > \uicontrol Select to activate selection + \li Go to \uicontrol Debug > \uicontrol Select to activate selection mode and then click an item in the running application. \endlist @@ -243,12 +246,6 @@ application to jump to their definitions in the code. The properties of the selected item are displayed in the \uicontrol {Locals} view. - \if defined(qtcreator) - The \uicontrol Select tool will be enabled either if your application is - using Qt 5.7 or later, or if your application is using an earlier version - of Qt and is based on the \c QQuickView class. - \endif - You can also view the item hierarchy in the running application: Double-click an item in the running application to cycle through the item @@ -282,4 +279,8 @@ When you change property values in the \uicontrol {QML Debugger Console} or in the \uicontrol Locals or \uicontrol Expression view, they are immediately updated in the running application, but not in the source code. + + \if defined(qtcreator) + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} + \endif */ diff --git a/doc/qtcreator/src/docker/creator-docker.qdoc b/doc/qtcreator/src/docker/creator-docker.qdoc index 15f147d475..4f1167b359 100644 --- a/doc/qtcreator/src/docker/creator-docker.qdoc +++ b/doc/qtcreator/src/docker/creator-docker.qdoc @@ -3,12 +3,13 @@ /*! \page creator-adding-docker-devices.html - \previouspage creator-developing-b2qt.html - \nextpage creator-developing-ios.html + \previouspage creator-how-tos.html - \title Adding Docker Devices + \ingroup creator-how-to-docker - Create Docker devices from \l{ https://docs.docker.com/get-started/overview/} + \title Add Docker devices + + Create Docker devices from \l{https://docs.docker.com/get-started/overview/} {Docker images} and use them to build, run, and debug applications. A Docker container operates like a virtual machine but uses less system resources at the cost of being less flexible. @@ -16,37 +17,78 @@ While Linux, \macos, and Windows hosts are supported in principle, Linux is the recommended platform. - To build, run, and debug applications on Docker devices, you must install and + To build, run, and debug applications on Docker devices, install and configure \c docker-cli on the development host. \QC automatically detects \l{kits-tab}{build and run kit} items, such \l{Add debuggers} {debuggers} and \l{Add Qt versions}{Qt versions}, in the Docker container and creates kits for the devices. - You can use CMake or qmake to build applications in the Docker container. + You are advised to use CMake to build applications in the Docker container. + + \note Enable the Docker plugin to use it. To pull images from Docker hub or other registries, use the \l{https://docs.docker.com/engine/reference/commandline/pull/}{docker pull} command. - \section1 Adding Docker Images as Devices + \section1 Add Docker images as devices To add a Docker image as a device: \list 1 - \li Select \preferences > \uicontrol Devices - > \uicontrol Docker and enter the path to the Docker CLI in - the \uicontrol Command field. - \image qtcreator-preferences-devices-docker.webp "Docker tab in Devices preferences" - \li Select \uicontrol Devices > \uicontrol Add > - \uicontrol {Docker Device} > \uicontrol {Start Wizard} - to search for images in your local Docker installation. - \li Select the Docker image to use, and then select \uicontrol OK. + \li Go to \preferences > \uicontrol Devices > \uicontrol Docker. + \li In \uicontrol Command, enter the path to the Docker CLI. + \image qtcreator-preferences-devices-docker.webp {Docker tab in Devices preferences} + \li Go to \uicontrol Devices. + \li Select \uicontrol Add > \uicontrol {Docker Device} > + \uicontrol {Start Wizard} to search for images in your + local Docker installation. + \li Select a Docker image, and then select \uicontrol OK. \li In \uicontrol Devices, check and change Docker device preferences. - \image qtcreator-preferences-devices-docker-device.png "Docker device preferences" + \image qtcreator-preferences-devices-docker-device.png {Docker device preferences} \li Select \uicontrol Apply to save your changes. \endlist - The following table summarizes the options you can set. + \section2 Select Docker images + + The \uicontrol {Docker Image Selection} dialog displays a list of Docker + images in your local Docker installation. You can sort the images according + to the repository name or tag or the image ID or size. + + \image qtcreator-docker-image-selection.webp {Docker Image Selection dialog} + + Select \uicontrol {Show unnamed images} to show images that are not tagged. + + Double-click an image to select it. + + \section1 Edit Docker device kits + + Go to \preferences > \uicontrol Kits to check + that the automatically generated kits point to the appropriate kit items. + + \sa {Enable and disable plugins}, {Docker}{How To: Develop for Docker}, + {Manage Kits}{How To: Manage Kits} +*/ + +/*! + \page creator-preferences-docker.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-docker + + \title Set preferences for Docker devices + + \note Enable the Docker plugin to use it. + + To set preferences for Docker devices: + + \list 1 + \li Go to \preferences > \uicontrol Devices > \uicontrol Devices. + \li In \uicontrol Device, select a Docker device. + \image qtcreator-preferences-devices-docker-device.png {Docker device preferences} + \endlist + + The following table summarizes the preferences you can set. \table \header @@ -59,7 +101,7 @@ on Windows. \row \li \uicontrol {Do not modify entry point} - \li Stops \QC from modifying the \l {Modifying Entry Points}{entry point} + \li Stops \QC from modifying the \l {Modify entry points}{entry point} of the image. Make sure that the entry point starts a shell. \row \li \uicontrol {Enable flags needed for LLDB} @@ -69,33 +111,18 @@ \endcode \row \li \uicontrol {Clangd executable} - \li The path to a remote Clangd executable to use for a remote code - model. + \li The path to a remote Clangd executable for a remote code model. \row \li \uicontrol {Paths to mount} - \li Host directories to \l{Specifying Paths to Mount}{mount} into the + \li Host directories to \l{Specify paths to mount}{mount} into the container, such as the project directory. \row \li \uicontrol {Search locations} - \li Where to \l{Auto-detecting Kit Items}{automatically detect} kit + \li Where to \l{Auto-detect kit items}{automatically detect} kit items. \endtable - The following sections describe the Docker device preferences in more detail. - - \section2 Selecting Docker Images - - The \uicontrol {Docker Image Selection} dialog displays a list of Docker - images in your local Docker installation. You can sort the images according - to the repository name or tag or the image ID or size. - - \image qtcreator-docker-image-selection.webp "Docker Image Selection dialog" - - Select \uicontrol {Show unnamed images} to show images that are not tagged. - - Double-click an image to select it. - - \section2 Modifying Entry Points + \section1 Modify entry points The entry point of a Docker container is specified in the container settings and started as the main process when starting the container. The entry point @@ -107,9 +134,9 @@ \uicontrol {Do not modify entry point}. However, if the entry point you specify is not a shell, \QC cannot start the container. - \section2 Specifying Paths to Mount + \section1 Specify paths to mount - You can either copy your project files into the Docker container or specify + Copy your project files into the Docker container or specify paths to them in \uicontrol {Paths to mount}. Shared mounts are restricted to locations in the host system that can end up in the same absolute location in the Docker container. On Windows, network mounts cannot be used as shared @@ -120,7 +147,7 @@ \uicontrol {Delete Line} to delete the selected path or \uicontrol Clear to delete all paths. - \section2 Auto-detecting Kit Items + \section1 Auto-detect kit items Select \uicontrol {Auto-detect Kit Items} to find kit items and create kits for the Docker device. You can search for kit items in the device's PATH or @@ -143,20 +170,32 @@ \uicontrol {List Auto-Detected Kit Items}. To remove them, select \uicontrol {Remove Auto-Detected Kit Items}. - \section1 Editing Docker Device Kits + \sa {Enable and disable plugins}, {Docker}{How To: Develop for Docker}, + {Manage Kits}{How To: Manage Kits} +*/ + +/*! + \page creator-how-to-build-run-docker.html + \previouspage creator-how-tos.html - Select \preferences > \uicontrol Kits to check - that the automatically generated kits point to the appropriate kit items. + \ingroup creator-how-to-docker + + \title Build for and run on Docker devices - To specify build settings: + \note Enable the Docker plugin to use it. + + To specify build settings for Docker images: \list 1 \li Open a project for an application you want to develop for the device. - \li Select \uicontrol Projects > \uicontrol {Build & Run} to enable - the kit that you specified above. + \li Go to \uicontrol Projects > \uicontrol {Build & Run}, and + activate the kit for Docker devices. \endlist Select \uicontrol Run to specify run settings. Usually, you can use the default settings. + + \sa {Enable and disable plugins}, {Docker}{How To: Develop for Docker}, + {Manage Kits}{How To: Manage Kits} */ diff --git a/doc/qtcreator/src/editors/creator-code-syntax.qdoc b/doc/qtcreator/src/editors/creator-code-syntax.qdoc index f20ecadb8e..f59ba0fd94 100644 --- a/doc/qtcreator/src/editors/creator-code-syntax.qdoc +++ b/doc/qtcreator/src/editors/creator-code-syntax.qdoc @@ -9,7 +9,7 @@ \previouspage creator-how-tos.html \endif - \ingroup creator-how-to-edit + \ingroup creator-how-to-analyze \ingroup studio-how-to-code \title Check code syntax @@ -66,12 +66,9 @@ \section1 Set line annotation positions - To specify the position of the line annotations when looking at them in the - code editor, select \uicontrol {Annotation Settings} in the tooltip popup. - To specify the position where the annotations are displayed, go to \preferences > \uicontrol {Text Editor} > - \uicontrol Display > \uicontrol {Line annotations}, and then select + \uicontrol Display > \uicontrol {Line Annotations}, and then select whether to display the annotations directly next to the code, aligned to the right of the code, or in the right margin. Showing annotations between lines can be useful if there is usually not enough space to @@ -82,17 +79,11 @@ If you hide the annotations, you can move the mouse pointer over an icon to view them. - \if defined(qtcreator) - \section1 Inspect QML and JavaScript - - To inspect QML and JavaScript properties, methods, and enums, move the - cursor over them and go to \uicontrol Tools > \uicontrol {QML/JS} > - \uicontrol {Inspect API for Element Under Cursor}. + \sa {JavaScript and QML Checks} - \sa {Clangd} + \if defined(qtcreator) + \sa {Analyze}{How To: Analyze}, {Analyzers}, {Analyzing Code} \endif - - \sa {JavaScript and QML Checks} */ /*! @@ -760,24 +751,25 @@ \section1 Resetting the Code Model - If you change the build and run kit when you have QML files open in the code - editor, the code model might become corrupt. The following error message - indicates that this might have happened: \e{Using Qt Quick 1 code model - instead of Qt Quick 2}. + If you see the following error messages after you add a new QML module, + try building the project and then resetting the code model: + + \list + \li QML module not found. + \li Unknown Component (M300). + \endlist - To see the error message, move the mouse pointer over code that + To see an error message, move the mouse pointer over code that \QC underlines in the code editor or when you open a QML file in \QDS. To reset the code model, select \uicontrol Tools > \uicontrol {QML/JS} > \uicontrol {Reset Code Model}. + \sa {Check code syntax}, {Using QML Modules with Plugins} + \if defined(qtcreator) - If this does not help, try changing the QML emulation layer to the one that - was built with the same Qt version as the one selected in the build and run - kit. + \sa {Analyzing Code} \endif - - \sa {Check code syntax} */ /*! diff --git a/doc/qtcreator/src/editors/creator-only/creator-clang-codemodel.qdoc b/doc/qtcreator/src/editors/creator-only/creator-clang-codemodel.qdoc index f07a79e986..d8bba6edf6 100644 --- a/doc/qtcreator/src/editors/creator-only/creator-clang-codemodel.qdoc +++ b/doc/qtcreator/src/editors/creator-only/creator-clang-codemodel.qdoc @@ -124,54 +124,83 @@ The document outline in the \l{Outline} view is backed by clangd's document symbol support, which makes the results more reliable than before. - \sa {Code Model}, {Clangd}, {Specify clangd settings}, - {Speficy Clang tools settings}, {Use compilation databases} + \sa {Configure C++ code model}, {Specify clangd settings}, + {Specify Clang tools settings}, {Use compilation databases}, + {Code Model}, {Clangd} */ /*! - \page creator-preferences-cpp-code-model.html - \previouspage creator-reference.html - - \ingroup creator-reference-preferences-cpp + \page creator-how-to-cpp-code-model.html + \previouspage creator-how-tos.html - \title Code Model + \ingroup creator-how-to-configure-editors + \ingroup creator-how-to-projects-configure - \brief Sets global preferences for the code model. + \title Configure C++ code model - The Clang code model offers services such as code completion, syntactic and + The code model offers services such as code completion, syntactic and semantic highlighting, and diagnostics. - To configure the Clang code model globally: + To configure the C++ code model for a project: \list 1 + \li Go to \uicontrol Projects > \uicontrol {Project Settings} > + \uicontrol {C++ Code Model}. + \image qtcreator-projects-cpp-code-model.webp {C++ Code Model settings} + \li Clear \uicontrol {Use global settings}. + \li Set \uicontrol {C++ Code Model} settings for the project. + \endlist - \li Select \preferences > \uicontrol C++ > - \uicontrol {Code Model}. + \sa {Code Model} +*/ - \image qtcreator-preferences-code-model.webp {C++ Code Model preferences} +/*! + \page creator-preferences-cpp-code-model.html + \previouspage creator-reference.html + + \ingroup creator-reference-preferences-cpp - \li To instruct the code model to interpret ambiguous header files as C - language files if you develop mainly using C, select the - \uicontrol {Interpret ambiguous headers as C headers} check box. + \title Code Model - \li To process precompiled headers, deselect the - \uicontrol {Ignore precompiled headers} check box. + \brief Sets global preferences for the code model. - \li To use the built-in preprocessor to show the - pre-processed source file in the editor, select - \uicontrol {Use built-in preprocessor to show pre-processed files}. + The code model offers services such as code completion, syntactic and + semantic highlighting, and diagnostics. + To configure the C++ code model globally, go to \preferences > + \uicontrol C++ > \uicontrol {Code Model}. + + \image qtcreator-preferences-code-model.webp {C++ Code Model preferences} + + The following table summarizes the preferences. + + \table + \header + \li Setting + \li Value + \row + \li \uicontrol {Interpret ambiguous headers as C headers} + \li Instructs the code model to interpret ambiguous header files as C + language files. Select this checkbox if you develop mainly using C. + \row + \li \uicontrol {Ignore precompiled headers} + \li Clear this checkbox to process precompiled headers. + \row + \li \uicontrol {Use built-in preprocessor to show pre-processed files} + \li Uses the built-in preprocessor to show the + pre-processed source file in the editor. + \row + \li \uicontrol {Do not index files greater than} \li To avoid out-of-memory crashes caused by indexing huge source files that are typically auto-generated by scripts or code, the size of - files to index is limited to 5MB by default. To adjust the limit, - edit the value for the \uicontrol {Do not index files greater than} - check box. To index all files, deselect the check box. + files to index is limited to 5MB by default. - \li To ignore files that match wildcard patterns, select the - \uicontrol {Ignore files} check box and enter each wildcard pattern - on a separate line in the field. - - \endlist + To index all files, clear the checkbox. + \row + \li \uicontrol {Ignore files} + \li To ignore files that match wildcard patterns, enter each wildcard + pattern on a separate line in the field. + \endtable \section1 Inspect preprocessed C++ code @@ -186,7 +215,8 @@ this action also expands all \c {"#include <foo.h>"} statements to their actual contents. - \sa {Specify clangd settings}, {Clang Code Model}, {Clangd} + \sa {Configure C++ code model}, {Specify clangd settings}, + {Clang Code Model}, {Clangd} */ /*! 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 0e8bba269a..9bbfe729d9 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. @@ -184,7 +184,8 @@ \title Move between files - The editor toolbar shows the file that is currently open (1) in the editor. + The editor toolbar shows the name of the file that is currently open (1) in + the editor. \image qtcreator-editor-open-files.webp {Current file shown on Edit mode toolbar} @@ -416,18 +417,18 @@ \image qtcreator-options-texteditor-behavior-file-encodings.png {File encoding preferences} - Qt 5 and Qt 6 require UTF-8 encoded source files, and therefore the default + Qt requires UTF-8 encoded source files, and therefore the default encoding is set to \uicontrol UTF-8. - Detecting the correct encoding is tricky, so \QC will not try to do so. - Instead, it displays the following error message when you try to edit a file - that is not UTF-8 encoded: \uicontrol {Error: Could not decode "filename" with + + If you try to edit a file that is not UTF-8 encoded, you see the following + error message: \uicontrol {Error: Could not decode "filename" with "UTF-8"-encoding. Editing not possible.} To resolve the issue, use a file conversion tool to convert the file - encoding to UTF-8 when developing Qt 5 applications. Otherwise, conversion - of string constants to QString might not work as expected. + encoding to UTF-8. Otherwise, conversion of string constants to + QString might not work as expected. - If you develop only Qt 4 applications or other than Qt applications, you + If you do not develop Qt applications, you can set other encoding options as the default encoding. Select the \uicontrol System option to use the file encoding used by your system. diff --git a/doc/qtcreator/src/editors/creator-only/creator-language-server.qdoc b/doc/qtcreator/src/editors/creator-only/creator-language-server.qdoc index 8c01b9cfef..27a632955c 100644 --- a/doc/qtcreator/src/editors/creator-only/creator-language-server.qdoc +++ b/doc/qtcreator/src/editors/creator-only/creator-language-server.qdoc @@ -62,7 +62,8 @@ \section1 Adding Language Servers - \QC adds a Python language server by default. + \QC adds a \l{Configure Python language servers}{Python language server} by + default. Also, it offers to install language servers for JSON and YAML files when you open them in the editor if it can find the @@ -71,18 +72,22 @@ \image qtcreator-language-server-json.webp {Prompt to install JSON language server} - Add a Java language server for \l{Connecting Android Devices} - {Android development}. For other languages, add generic stdIO language - servers. + \l{Add a Java language server} for \l{Developing for Android} + {Android development}. For other languages, + \l{Add generic language servers}{add generic stdIO language servers}. To add language servers, go to \preferences > \uicontrol {Language Client} and select \uicontrol Add. \image qtcreator-language-client-options-java.png {Java language server preferences} - To enable a language server, select the check box next to the language + To enable a language server, select the checkbox next to the language server name and set server preferences. + To turn on \l{Turn on \QMLLS}{\QMLLS}, go to + \preferences > \uicontrol {Qt Quick} > \uicontrol {QML/JS Editing} and + select \uicontrol {Enable \QMLLS}. + To remove language servers from the list, select \uicontrol Delete. \section1 Supported Locator Filters @@ -218,23 +223,23 @@ \ingroup creator-how-to-lsp - \title Turn on QML Language Server + \title Turn on \QMLLS - Since Qt 6.4, the QML language server offers code completion and + Since Qt 6.4, \QMLLS offers code completion and issues warnings for QML. To use it, go to \preferences > \uicontrol {Qt Quick} > \uicontrol {QML/JS Editing} and select - \uicontrol {Enable QML Language Server}. + \uicontrol {Enable \QMLLS}. - By default, enabling the QML language server will only enable warning messages + By default, enabling \QMLLS will only enable warning messages and code completion, while advanced features such as renaming and finding usages will be handled by the embedded code model. - To disable the embedded code model and use the QML language server for everything, - select \uicontrol {Use QML Language Server advanced features}. + To disable the embedded code model and use \QMLLS for everything, + select \uicontrol {Use \QMLLS advanced features}. - Also, \QC tries to use the QML language server shipped with - the Qt version in your current kit. To override that behavior and always use the - QML language server of the highest registered Qt version, select - \uicontrol {Use QML Language Server from latest Qt version}. + Also, \QC tries to use \QMLLS shipped with + the Qt version in your current kit. To override that behavior and always use + \QMLLS of the highest registered Qt version, select + \uicontrol {Use \QMLLS from latest Qt version}. \image qtcreator-qml-js-editing.webp {QML/JS Editing preferences} diff --git a/doc/qtcreator/src/editors/creator-only/creator-locator.qdoc b/doc/qtcreator/src/editors/creator-only/creator-locator.qdoc index eab661647f..d739bd3445 100644 --- a/doc/qtcreator/src/editors/creator-only/creator-locator.qdoc +++ b/doc/qtcreator/src/editors/creator-only/creator-locator.qdoc @@ -261,6 +261,16 @@ \endlist + \section1 Hiding Long Paths + + To hide the common part of absolute paths in the locator: + + \list 1 + \li Go to \preferences > \uicontrol Environment > \uicontrol Locator. + \li Select \uicontrol {Show Paths in Relation to Active Project} to + show relative paths. + \endlist + \sa {Navigate with locator}, {Search}{How To: Search}, {Perform calculations}, {Locator} */ diff --git a/doc/qtcreator/src/external-resources/external-resources-qds.qdoc b/doc/qtcreator/src/external-resources/external-resources-qds.qdoc index d5b7fcf1bd..2a340b9ea9 100644 --- a/doc/qtcreator/src/external-resources/external-resources-qds.qdoc +++ b/doc/qtcreator/src/external-resources/external-resources-qds.qdoc @@ -69,3 +69,39 @@ \externalpage https://www.qt.io/download \title Try Qt */ +/*! + \externalpage https://doc.qt.io/qt-5/custom-material-reference.html + \title Qt Quick 3D Custom Material Reference +*/ +/*! + \externalpage https://doc.qt.io/qt-5/qml-qtquick3d-arealight.html + \title AreaLight +*/ +/*! + \externalpage https://doc.qt.io/qt-5/qml-qtquick3d-shaderinfo.html + \title ShaderInfo +*/ +/*! + \externalpage https://doc.qt.io/qt-5/qml-qtquick3d-bufferblit.html + \title BufferBlit +*/ +/*! + \externalpage https://doc.qt.io/qt-5/qml-qtquick3d-cullmode.html + \title CullMode +*/ +/*! + \externalpage https://doc.qt.io/qt-5/qml-qtquick3d-depthinput.html + \title DepthInput +*/ +/*! + \externalpage https://doc.qt.io/qt-5/qml-qtquick3d-renderstate.html + \title RenderState +*/ +/*! + \externalpage https://doc.qt.io/qt/i18n-source-translation.html#mark-strings-for-translation + \title Mark Strings for Translation +*/ +/*! + \externalpage https://doc.qt.io/qt/linguist-id-based-i18n.html + \title Text ID based translations +*/ diff --git a/doc/qtcreator/src/external-resources/external-resources.qdoc b/doc/qtcreator/src/external-resources/external-resources.qdoc index 3eceb28e56..05cba5ba53 100644 --- a/doc/qtcreator/src/external-resources/external-resources.qdoc +++ b/doc/qtcreator/src/external-resources/external-resources.qdoc @@ -2,6 +2,26 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! + \externalpage https://www.perforce.com/manuals/cmdref/Content/CmdRef/P4CONFIG.html + \title Perforce: P4CONFIG +*/ +/*! + \externalpage https://doc.qt.io/qt-6/qtdesigner-manual.html + \title Qt Widgets Designer Manual +*/ +/*! + \externalpage https://doc.qt.io/qt-6/designer-using-custom-widgets.html + \title Using Custom Widgets with Qt Widgets Designer +*/ +/*! + \externalpage https://doc.qt.io/Boot2Qt/index.html + \title \B2Q: Documentation +*/ +/*! + \externalpage https://doc.qt.io/Boot2Qt/b2qt-requirements-x11.html#setting-up-usb-access-to-embedded-devices + \title \B2Q: Setting Up USB Access to Embedded Devices +*/ +/*! \externalpage https://doc.qt.io/qt/qtqml-index.html \title Qt Qml */ @@ -18,6 +38,10 @@ \title \QMCU - Supported Target Platforms */ /*! + \externalpage https://doc.qt.io/QtForMCUs/qtul-prerequisites.html + \title \QMCU - Prerequisites +*/ +/*! \externalpage https://doc.qt.io/QtForMCUs/qtul-getting-started-renesas.html \title Getting Started on Renesas */ @@ -30,12 +54,16 @@ \title Getting Started on NXP */ /*! + \externalpage https://doc.qt.io/QtForMCUs/qtul-getting-started-on-infineon.html + \title Getting Started on Infineon +*/ +/*! \externalpage https://doc.qt.io/QtForMCUs/qtul-getting-started-windows.html \title Getting Started on Windows */ /*! - \externalpage https://adoptopenjdk.net/ - \title AdoptOpenJDK + \externalpage https://adoptium.net/ + \title Adoptium OpenJDK */ /*! \externalpage http://openjdk.java.net @@ -185,3 +213,19 @@ \externalpage https://doc-snapshots.qt.io/applicationmanager-dev/cmake-qt6-am-create-installable-package.html \title qt6_am_create_installable_package */ +/*! + \externalpage https://valgrind.org/info/tools.html + \title Valgrind's Tool Suite +*/ +/*! + \externalpage https://valgrind.org/docs/manual/quick-start.html#quick-start.interpret + \title Interpreting Memcheck's Output +*/ +/*! + \externalpage https://valgrind.org/docs/manual/manual-core.html#manual-core.suppress + \title Suppressing Errors +*/ +/*! + \externalpage https://www.openssh.com/ + \title OpenSSH +*/ diff --git a/doc/qtcreator/src/howto/creator-external-tools.qdoc b/doc/qtcreator/src/howto/creator-external-tools.qdoc index 13927f3d67..fa58a1e80a 100644 --- a/doc/qtcreator/src/howto/creator-external-tools.qdoc +++ b/doc/qtcreator/src/howto/creator-external-tools.qdoc @@ -77,7 +77,7 @@ {build environment} or \l {Specify the run environment} {run environment} of the active project. Select the build or run environment if the system environment does not have the necessary - PATH settings to find the tool chain, for example. + PATH settings to find the toolchain, for example. \else \li In the \uicontrol {Base environment} field, use the default settings. \endif @@ -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/howto/creator-only/creator-autotest.qdoc b/doc/qtcreator/src/howto/creator-only/creator-autotest.qdoc index f05c16181a..f6006e8ede 100644 --- a/doc/qtcreator/src/howto/creator-only/creator-autotest.qdoc +++ b/doc/qtcreator/src/howto/creator-only/creator-autotest.qdoc @@ -359,10 +359,6 @@ found by the code based test frameworks and are registered as test with the build system. - If a test takes more than a minute to execute, the default timeout might - stop the test execution. To increase the timeout, go to \preferences > - \uicontrol {Testing} > \uicontrol General. - \section1 Select tests to run The \uicontrol Tests view shows all the tests found for the currently active @@ -501,7 +497,7 @@ the current project. \row \li \uicontrol {Timeout} - \li The maximum time in seconds to execute a test case. + \li Set a maximum time in seconds to execute a test case. \row \li \uicontrol {Reset Cached Choices} \li Sometimes, \QC cannot deduce which executable or run configuration to @@ -751,7 +747,7 @@ \li Re-run tests, as determined by \uicontrol {Repetition mode}. Set the maximum number of times for repeating a test in \uicontrol {Count}. \row - \li \uicontrol {Run in parallel} + \li \uicontrol {Run in Parallel} \li Run the tests in parallel using the specified number of \uicontrol {Jobs}. In \uicontrol {Test load}, limit the parallel execution. CTest will not start a new test if it would cause the @@ -853,8 +849,7 @@ \section1 Blacklisting Tests - Since Qt 5.4, you can add a BLACKLIST file for tests. It is mainly used - internally by the Qt CI system. + A BLACKLIST file for tests is mainly used internally by the Qt CI system. \table \header diff --git a/doc/qtcreator/src/howto/creator-only/creator-cli.qdoc b/doc/qtcreator/src/howto/creator-only/creator-cli.qdoc index fbc885df05..a0e9129c6b 100644 --- a/doc/qtcreator/src/howto/creator-only/creator-cli.qdoc +++ b/doc/qtcreator/src/howto/creator-only/creator-cli.qdoc @@ -93,7 +93,7 @@ \row \li -installsettingspath <path> \li Override the default path from where user-independent settings are read - (for example written by the installer). + (for example, those written by the installer). \row \li -temporarycleansettings, -tcs @@ -104,6 +104,10 @@ \li -language <locale> \li Set the UI language. + Use a lowercase, two-letter + \l {https://www.iso.org/iso-639-language-codes.html} + {ISO 639 language code}, such as \e de, \e en, or \e fr. + \row \li -test <plugin>[,testfunction[:testdata]] ... \li For \QC plugin developers: run the plugin's tests using a diff --git a/doc/qtcreator/src/howto/creator-only/creator-how-to-find-settings-files.qdoc b/doc/qtcreator/src/howto/creator-only/creator-how-to-find-settings-files.qdoc index 8bfb773a40..81bc78e307 100644 --- a/doc/qtcreator/src/howto/creator-only/creator-how-to-find-settings-files.qdoc +++ b/doc/qtcreator/src/howto/creator-only/creator-how-to-find-settings-files.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2023 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -7,9 +7,9 @@ \ingroup creator-how-to-use - \title Find settings files + \title Reset \QC settings - \QC creates the following files and directories: + To reset all \QC settings, remove the settings files that it creates: \list \li QtCreator.db @@ -29,4 +29,32 @@ \li On Windows, look in \c {%appdata%\QtProject} and \c {%localappdata%\QtProject}. \endlist + + To check whether the settings are causing a problem before resetting them, + start \QC from the command line with options. + + \section1 Override the default settings path + + To override the default path where user settings are stored, enter: + + \badcode + qtcreator -settingspath <path> + \endcode + + To override the default path from where user-independent settings are read + (for example, those written by the installer), enter: + + \badcode + qtcreator -installsettingspath <path> + \endcode + + \section1 Start \QC with temporary clean settings + + To use clean settings that are deleted when you quit \QC, enter: + + \badcode + qtcreator -tcs + \endcode + + \sa {Run Qt Creator from the command line} */ diff --git a/doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc b/doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc index 1b545943e3..baf079c08f 100644 --- a/doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc +++ b/doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc @@ -80,6 +80,75 @@ \generatelist creator-how-to-design + \section1 Develop for Devices + + Install the toolchain for building applications for the targeted + embedded or mobile platform on the computer, and use \QOI to + install Qt libraries that are built for the platform. Then add a + kit with the toolchain and the Qt version for the device's architecture. + When possible, \QOI creates suitable kits for you. Connect the devices + to the computer to run, debug, and analyze applications on them. + + \section2 Android + + Install \l {Qt for Android} and Android tools, and connect Android devices to + the computer. + + \generatelist creator-how-to-android + + \section2 Bare Metal + + Run and debug applications on small Linux devices that are not supported + by the remote Linux device plugin by using GDB or a hardware debugger. + + \generatelist creator-how-to-bare-metal + + \section2 \B2Q + + Run, debug, and analyze applications on \l{\B2Q: Documentation}{\B2Q} + devices. + + \generatelist creator-how-to-b2qt + + \section2 Docker + + Create \e {Docker devices} from \e {Docker images} and use them to build, + run, and debug applications. + + \generatelist creator-how-to-docker + + \section2 iOS + + Install \l {Qt for iOS} and Xcode, and connect iOS devices to the computer. + + \generatelist creator-how-to-ios + + \section2 MCUs + + Install \l {Qt for MCUs}, and connect microcontrollers to the computer. + + \generatelist creator-how-to-mcu + + \section2 QNX Neutrino + + Install \l {Qt for QNX}, and connect QNX Neutrino devices to the computer. + + \generatelist creator-how-to-qnx + + \section2 Remote Linux + + Add kits for toolchains for building applications for generic Linux + devices, and connect the devices to the computer. + + \generatelist creator-how-to-remote-linux + + \section2 WebAssembly + + Install \l{Qt for WebAssembly} to build applications for the web and run them + in a web browser. + + \generatelist creator-how-to-webassembly + \section1 Edit Code The code editor offers useful features for editing C++ and QML code, such @@ -115,7 +184,7 @@ \QC groups build and run specific settings as kits to make cross-platform development easier. Each kit consists of a set of values that define one - environment, such as a device, tool chain, Qt version, and debugger command + environment, such as a device, toolchain, Qt version, and debugger command to use. \generatelist creator-how-to-manage-kits @@ -423,6 +492,12 @@ \uicontrol {Find References to Symbol Under Cursor}. \endlist + \section1 Inspect QML and JavaScript + + To inspect QML and JavaScript properties, methods, and enums, place the + cursor over them and go to \uicontrol Tools > \uicontrol {QML/JS} > + \uicontrol {Inspect API for Element Under Cursor}. + \section1 Move between QML and C++ To move to the C++ implementation of a QML type in the code editor, place the @@ -433,7 +508,8 @@ \li Go to \uicontrol {Follow Symbol Under Cursor} in the context menu. \endlist - \sa {Edit Code}{How To: Edit Code}, {Edit Mode}, {Navigate with locator} + \sa {Edit Code}{How To: Edit Code}, {Clangd}, {Edit Mode}, + {Navigate with locator} */ /*! diff --git a/doc/qtcreator/src/howto/creator-only/creator-squish.qdoc b/doc/qtcreator/src/howto/creator-only/creator-squish.qdoc index 4284085e72..9aaf0506f2 100644 --- a/doc/qtcreator/src/howto/creator-only/creator-squish.qdoc +++ b/doc/qtcreator/src/howto/creator-only/creator-squish.qdoc @@ -2,82 +2,66 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \previouspage creator-autotest.html - \page creator-squish.html - \nextpage creator-advanced.html + \page creator-how-to-connect-squish-server.html + \previouspage creator-how-tos.html - \title Using Squish + \ingroup creator-how-to-test - \l{https://www.qt.io/product/quality-assurance/squish}{Squish} is an automated GUI - testing framework for testing Android, iOS, Java, \macos, Qt, Tk, Windows, and - XView applications, as well as HTML-based web applications running in - browsers, such as Apple Safari, Mozilla Firefox, Google Chrome, and - Microsoft Internet Explorer and Edge. + \title Connect to Squish Server - The experimental Squish plugin integrates Squish into \QC. You can: - - \list - \li Open existing Squish test suites. - \li Create new test suites and test cases. - \li Record test cases (in a very limited way compared to what you can do - inside the Squish IDE). - \li Use Squish Runner and Server to run test suites or cases and view - the results in the \uicontrol Squish \l{View output}{output}. - \li Set breakpoints before running tests to stop at certain locations and - inspect the local variables, similarly to when debugging a test. - \endlist - - When running test suites or cases, the Squish Runner instructs the Squish - Server to start the application under test (AUT). The server can be running - on multiple machines, and the AUT can be located on a different path on each - of them. Therefore, you must either map AUTs to their corresponding paths or - specify AUT paths to search from in the server settings. - - In addition, you can test an already running application by attaching to it. - This enables you to test your application using a Squish Server running on - another machine. However, you can have only one server attached to your - application at a time. Also, the attached application is not closed when the - test case is completed. - - To use the plugin, you must download and install Squish, create a connection - to the Squish Server, and specify AUTs to run. - - \note Enable the Squish plugin to use it. - - \section1 Specifying a Squish Server - - To specify a Squish Server to run: + To create a connection to Squish Server: \list 1 \li Select \preferences > \uicontrol Squish. - \image qtcreator-squish-preferences.png "Squish general preferences" - \li In the \uicontrol {Squish path} field, specify the path to the Squish + \image qtcreator-squish-preferences.png {Squish general preferences} + \li In \uicontrol {Squish path}, specify the path to the Squish installation directory. - \li In the \uicontrol {License path} field, specify the path to your + \li In \uicontrol {License path}, specify the path to your Squish license file if it is not located in your home folder. For example, if you have a global installation with several users, where the license key is installed in the global folder. - \li Select the \uicontrol {Local server} check box to use a locally - installed \c {squishserver.exe}. To use a server running in another - machine, deselect the check box and specify the server address in the - \uicontrol {Server host} field and the port number in the - \uicontrol {Server port} field. If no port is specified, \QC starts + \li Select \uicontrol {Local server} to use a locally + installed \c {squishserver.exe}. To use a server running on another + computer, clear the checkbox and specify the server address in the + \uicontrol {Server host} and the port number in the + \uicontrol {Server port}. If no port is specified, \QC starts \c squishserver in a way that enables it to automatically select an open port. - \li Select the \uicontrol {Verbose log} check box to include additional + \li Select \uicontrol {Verbose log} to include additional logging levels in the log output. - \li Select the \uicontrol {Minimize IDE} check box to automatically + \li Select \uicontrol {Minimize IDE} to automatically minimize \QC when running or recording test cases. \endlist - \section1 Specifying AUTs + \sa {Create Squish test suites}, {Enable and disable plugins}, + {Manage Squish test suites and cases}, {Select Squish AUTs}, {Squish} +*/ + +/*! + \page creator-how-to-select-squish-auts.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-test + + \title Select Squish AUTs - To specify applications to test using Squish, select \uicontrol {Tools} > + To select applications to test using Squish, go to \uicontrol {Tools} > \uicontrol {Squish} > \uicontrol {Server Settings}. - \image qtcreator-squish-server-settings.png "Squish Server Settings" + \image qtcreator-squish-server-settings.png {Squish Server Settings} + + When running test suites or cases, the Squish Runner instructs the Squish + Server to start the application under test (AUT). The server can be running + on multiple computers, and the AUT can be located on a different path on each + of them. Therefore, you must either map AUTs to their corresponding paths or + specify AUT paths to search from in the server settings. + + To test an already running application using a Squish Server running on + another computer, attach to the application. You can attach only one server + to your application at a time. The attached application is not closed when + the test case is completed. - \section2 Mapping AUTs + \section1 Map AUTs To specify the path to an AUT to run, select \uicontrol {Mapped AUTs} > \uicontrol Add and locate the AUT. @@ -88,13 +72,13 @@ Mapping AUTs prevents the server from accidentally executing the wrong AUT if two different executables have the same name, as the server executes the - first matching AUT it finds in the \uicontrol {AUT Paths} list. + first matching AUT it finds in \uicontrol {AUT Paths}. To change the path to the selected AUT, select \uicontrol {Edit}. To remove the mapping to the selected AUT, select \uicontrol {Remove}. - \section2 Specifying AUT Paths + \section1 Specify AUT paths To specify a path to search AUTs from, select \uicontrol {AUT Paths} > \uicontrol Add. @@ -107,32 +91,60 @@ To remove the selected AUT path, select \uicontrol {Remove}. - \section2 Adding Attachable AUTs + \section1 Add attachable AUTs To specify the path to a running AUT, select \uicontrol {Attachable AUTs} > \uicontrol Add. In the \uicontrol {Add Attachable AUT} dialog, specify a connection to a running application to register an attachable AUT. - \image qtcreator-squish-server-settings-add-attachable-aut.png "Add Attachable AUT dialog" + \image qtcreator-squish-server-settings-add-attachable-aut.png {Add Attachable AUT dialog} To change the connection to the selected AUT, select \uicontrol {Edit}. To remove the connection to the selected AUT, select \uicontrol {Remove}. - \section1 Managing Test Suites and Cases + \section1 Specify settings for running tests - You can manage Squish test suites and cases in the \uicontrol Squish - \l {Show and hide sidebars}{view}. + To specify settings for running tests: - \image qtcreator-squish-view.png "Squish sidebar view" + \list + \li In \uicontrol {Maximum startup time}, set the maximum time + to wait for the AUT to start before throwing an error. + \li In \uicontrol {Maximum response time}, set the maximum time + to wait for the AUT to respond before throwing an error. + \li In \uicontrol {Maximum post-mortem wait time}, set the + maximum time to wait after the main AUT has exited. This is useful + for AUTs invoked through launcher applications, such as shell scripts + or batch files. + \li Select \uicontrol {Animate mouse cursor} to animate + the mouse cursor when playing back a test. + \endlist + + \sa {Connect to Squish Server}, {Create Squish test suites}, + {Enable and disable plugins}, {Manage Squish test suites and cases}, + {Squish} +*/ + +/*! + \page creator-how-to-manage-squish-test-suites.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-test + + \title Manage Squish test suites and cases + + Manage Squish test suites and cases in the \uicontrol Squish + \l {Show and hide sidebars}{sidebar view}. + + \image qtcreator-squish-view.png {Squish sidebar view} To show existing test suites in \uicontrol {Test Suites}, select \uicontrol {Open Squish Suites} in the context menu. - \image qtcreator-squish-view-open-squish-suites.png "Open Squish Test Suites dialog" + \image qtcreator-squish-view-open-squish-suites.png {Open Squish Test Suites dialog} - You can open the \uicontrol {Squish Test Suite} wizard for creating a new - test suite by selecting \uicontrol {Create New Test Suite} in the context + To open the \uicontrol {Squish Test Suite} wizard for creating a new + test suite, select \uicontrol {Create New Test Suite} in the context menu. To add a test case to a test suite, select it and then select @@ -148,73 +160,40 @@ Double-click a test suite in \uicontrol {Test Suites} to open the \c {suite.conf} configuration file for editing. - \section2 Creating Test Suites - - To create a new test suite: - - \list 1 - \li Select \uicontrol File > \uicontrol {New Project} - > \uicontrol {Squish} > \uicontrol {Squish Test Suite} > - \uicontrol Choose. - \image qtcreator-squish-create-test-suite.png "Create Squish Test Suite wizard" - \li On the \uicontrol {Location} page, in \uicontrol {Test Suite Name}, - enter a name for the test suite. - \image qtcreator-squish-create-test-suite-location.png "Location page" - \li In \uicontrol {Test Suite folder's parent folder}, enter the path to - the folder to create the test suite folder, and then select - \uicontrol Next. - \li On the \uicontrol Setup page, select the GUI toolkit used by the AUT, - and then select \uicontrol Next. - \image qtcreator-squish-create-test-suite-setup.png "Setup page" - Currently, only desktop GUI toolkits are supported. - \li On the \uicontrol {Script Language} page, select the scripting - language to use for the test suite's test script, and then select - \uicontrol Next. - \image qtcreator-squish-create-test-suite-language.png "Languages page" - \li On the \uicontrol {AUT} page, select the AUT to test, and then select - \uicontrol Next. - \image qtcreator-squish-create-test-suite-aut.png "AUT page" - \li On the \uicontrol {Summary} page review the test suite settings, and - then select \uicontrol Finish to create the test suite. - \endlist - - The test suite is listed in \uicontrol {Test Suites} in the \uicontrol Squish - sidebar view. - - \section2 Recording Test Cases + \section1 Record test cases Squish records tests using the scripting language that you specified for the test suite. Recordings are made into existing test cases. In \uicontrol {Test Suites}, select the \inlineimage icons/recordfill.png - (\uicontrol {Record Test Case}) button next to the test case name. The AUT - that you selected for the test suite is displayed and you can start recording - the test case. + (\uicontrol {Record Test Case}) button next to the test case name. The + application under test (AUT) that you selected for the test suite is + displayed and you can start recording the test case. - \image qtcreator-squish-control-bar-record-test-case.png "Squish control bar for recording test cases" + \image qtcreator-squish-control-bar-record-test-case.png {Squish control bar for recording test cases} When you are done, select the \inlineimage icons/stop_small.png (\uicontrol {Stop}) button in the \uicontrol {Control Bar}. - You can edit recorded test scripts or copy parts of them into manually + Edit recorded test scripts or copy parts of them into manually created test scripts. - \image qtcreator-squish-test-script-edit.png "A test script open in the editor" + \image qtcreator-squish-test-script-edit.png {A test script open in the editor} - \section2 Running Test Suites + \section1 Run test suites - You can run a recorded test case to have Squish repeat all the actions that + Run a recorded test case to have Squish repeat all the actions that you applied when recording the test, but without the pauses that humans are prone to but which computers don't need. To run a test case, select the \inlineimage icons/run_small.png (\uicontrol {Run}) button next to the test case in \uicontrol {Test Suites}. - \image qtcreator-squish-control-bar-run-test-case.png "Squish control bar for running test cases" + \image qtcreator-squish-control-bar-run-test-case.png {Squish control bar for running test cases} While the test is running, you can view test results as well as interrupt and stop tests in the \uicontrol {Control Bar}. - \section2 Mapping Symbolic Names + \section1 Map symbolic names When Squish records a test, it uses \e {symbolic names} to identify the UI elements. Symbolic names are stored in an object map that can be either @@ -237,7 +216,7 @@ (\uicontrol {Object Map}) button next to the test suite in \uicontrol {Test Suites}. - \image qtcreator-squish-symbolic-names.png "Symbolic Names view" + \image qtcreator-squish-symbolic-names.png {Symbolic Names view} You can filter the symbolic names in the \uicontrol {Symbolic Names} view. To edit a symbolic name or the names or values of its properties, @@ -253,49 +232,87 @@ property, select \inlineimage icons/jumpto.png . - \section2 Inspecting Local Variables + \section1 Inspect local variables If you set breakpoints in the test code before running the test, the test execution is automatically interrupted when a breakpoint is hit. You can inspect the contents of local variables in the \uicontrol {Squish Locals} view. - \image qtcreator-squish-locals.png "Squish Locals view" + \image qtcreator-squish-locals.png {Squish Locals view} Use the \uicontrol {Step Into}, \uicontrol {Step Over}, and \uicontrol {Step Out} buttons in the \uicontrol Squish debugging view to step through the code. - \image qtcreator-squish-debugging-view.png "Squish debugging view" + \image qtcreator-squish-debugging-view.png {Squish debugging view} - \section2 Specifying Settings for Running Tests + \sa {Connect to Squish Server}, {Create Squish test suites}, + {Enable and disable plugins}, {Select Squish AUTs}, {Squish} +*/ - To specify settings for running tests, select \uicontrol Tools > - \uicontrol Squish > \uicontrol {Server Settings}: +/*! + \page creator-how-to-create-squish-test-suites.html + \previouspage creator-how-tos.html - \list - \li In the \uicontrol {Maximum startup time} field, set the maximum time - to wait for the AUT to start before throwing an error. - \li In the \uicontrol {Maximum response time} field, set the maximum time - to wait for the AUT to respond before throwing an error. - \li In the \uicontrol {Maximum post-mortem wait time} field, set the - maximum time to wait after the main AUT has exited. This is useful - for AUTs invoked through launcher applications, such as shell scripts - or batch files. - \li Select the \uicontrol {Animate mouse cursor} check box to animate - the mouse cursor when playing back a test. + \ingroup creator-how-to-test + + \title Create Squish test suites + + To create a new test suite: + + \list 1 + \li Go to \uicontrol File > \uicontrol {New Project}. + \li Select \uicontrol {Squish} > \uicontrol {Squish Test Suite} > + \uicontrol Choose. + \image qtcreator-squish-create-test-suite.png {Create Squish Test Suite wizard} + \li On the \uicontrol {Location} page, in \uicontrol {Test Suite Name}, + enter a name for the test suite. + \image qtcreator-squish-create-test-suite-location.png {Location page} + \li In \uicontrol {Test Suite folder's parent folder}, enter the path to + the folder to create the test suite folder, and then select + \uicontrol Next. + \li On the \uicontrol Setup page, select the GUI toolkit used by the + application under test (AUT), and then select \uicontrol Next. + \image qtcreator-squish-create-test-suite-setup.png {Setup page} + Currently, only desktop GUI toolkits are supported. + \li On the \uicontrol {Script Language} page, select the scripting + language to use for the test suite's test scripts, and then select + \uicontrol Next. + \image qtcreator-squish-create-test-suite-language.png {Languages page} + \li On the \uicontrol {AUT} page, select the AUT to test, and then select + \uicontrol Next. + \image qtcreator-squish-create-test-suite-aut.png {AUT page} + \li On the \uicontrol {Summary} page, review the test suite settings, and + then select \uicontrol Finish to create the test suite. \endlist - \section1 Viewing Test Results + The test suite is listed in \uicontrol {Test Suites} in the \uicontrol Squish + sidebar view. + + \sa {Connect to Squish Server}, {Manage Squish test suites and cases}, {Enable and disable plugins}, + {Select Squish AUTs}, {Squish} +*/ + +/*! + \page creator-reference-squish-output.html + \previouspage creator-reference.html + + \ingroup creator-reference-output-views + + \title Squish + + \brief View Squish test, runner, and server logs. Squish uses compare, verify, and exception functions to record the results of - tests applied to a running AUT in the test log as \e {passes} or \e {fails}. - In addition, any kind of test results can be recorded in the test log. + tests applied to a running application under test (AUT) in the test log as + \e {passes} or \e {fails}. In addition, any kind of test results can be + recorded in the test log. - You can view the test log in the \uicontrol Squish output, + To view the test log, go to the \uicontrol Squish output, \uicontrol {Test Results} tab. - \image qtcreator-squish-output-test-results.png "Test Results output" + \image qtcreator-squish-output-test-results.png {Test Results output} The \uicontrol Result column displays the time when each test run started and finished, log information and warnings, and test result status: @@ -314,12 +331,14 @@ the type of the operation that was performed: comparison, verification, or exception. - \section1 Viewing Squish Runner and Server Logs + \section1 View Squish runner and server logs - You can view the Squish Runner and Server logs in the \uicontrol Squish + To view the Squish Runner and Server logs, go to the \uicontrol Squish output, \uicontrol {Runner/Server Log} tab. - \image qtcreator-squish-output-runner-server-log.png "Runner and Server Log output" + \image qtcreator-squish-output-runner-server-log.png {Runner and Server Log output} - \sa {Enable and disable plugins} + \sa {Connect to Squish Server}, {Create Squish test suites}, + {Enable and disable plugins}, {Manage Squish test suites and cases}, + {Select Squish AUTs}, {View output} */ diff --git a/doc/qtcreator/src/howto/creator-only/qtcreator-faq.qdoc b/doc/qtcreator/src/howto/creator-only/qtcreator-faq.qdoc index beadc0eb86..967031f69b 100644 --- a/doc/qtcreator/src/howto/creator-only/qtcreator-faq.qdoc +++ b/doc/qtcreator/src/howto/creator-only/qtcreator-faq.qdoc @@ -18,14 +18,6 @@ \section1 General Questions - - \b {How do I reset all \QC settings?} - - Remove the settings files created by \QC. - - For more information about where the files are located on each supported - platform, see \l {Find settings files}. - \b {\QC comes with \MinGW, should I use this version with Qt?} Use the version that was built against the Qt version. @@ -41,15 +33,6 @@ This is especially relevant for the \macos where \c {/usr/local/bin} might not be in the path when \QC is started. - \b {How do I change the interface language for \QC?} - - \QC has been localized into several languages. If the system - language is one of the supported languages, it is automatically selected. - To change the language, select \preferences > - \uicontrol Environment and select a language in the \uicontrol Language - field. Select \uicontrol {Restart Now} to restart \QC and have the change - take effect. - \b {Has a reported issue been addressed?} You can look up any issue in the @@ -138,14 +121,10 @@ \b {The Qt API Reference Documentation is missing and context help does not find topics. What can I do?} - \QC comes fully integrated with Qt documentation and examples using - the Qt Help plugin. The integrated Qt Reference Documentation is available - for Qt 4.4 and later. \QC and other Qt deliverables have - documentation as .qch files. All the documentation is accessible in the - \uicontrol Help mode. + Install a Qt version and Qt documentation with \QOI. - To view the documentation that is available and to add documentation, - select \preferences > \uicontrol Help > + To view the installed documentation (.qch files) and to add documentation, + go to \preferences > \uicontrol Help > \uicontrol Documentation. For more information, see \l{Add external documentation}. @@ -164,12 +143,12 @@ You must use Python version 2.6 or 2.7. - For more information on setting up debugger, see \l{Setting Up Debugger}. + For more information, see \l{Supported Native Debuggers}. \b {How do I generate a core file in \QC?} To trigger the GDB command that generates a core file while debugging, - select \uicontrol View > \uicontrol Views > \l {Debugger Log}. + go to \uicontrol View > \uicontrol Views > \l {Debugger Log}. In the \uicontrol Command field, type \c gcore and press \key Enter. The core file is created in the current working directory. You can specify another location for the file, including a relative or absolute path, as an diff --git a/doc/qtcreator/src/howto/creator-only/qtcreator-how-to-change-ui-language.qdoc b/doc/qtcreator/src/howto/creator-only/qtcreator-how-to-change-ui-language.qdoc new file mode 100644 index 0000000000..913b1b6fa9 --- /dev/null +++ b/doc/qtcreator/src/howto/creator-only/qtcreator-how-to-change-ui-language.qdoc @@ -0,0 +1,38 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page creator-how-to-change-ui-language.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-ui + + \title Change the UI language + + \QC has been localized into several languages. If the system + language is one of the supported languages, it is automatically selected. + + To change the language: + + \list 1 + \li Go to \preferences > \uicontrol Environment. + \li In \uicontrol Language, select a language. + \li Select \uicontrol OK. + \li Select \uicontrol {Restart Now} to restart \QC and have the change + take effect. + \endlist + + \section1 Set the language from the command line + + To set the UI language when you start \QC from the command line, enter: + + \badcode + qtcreator -language <locale> + \endcode + + Use a lowercase, two-letter + \l {https://www.iso.org/iso-639-language-codes.html} + {ISO 639 language code}, such as \e de, \e en, or \e fr. + + \sa {Run Qt Creator from the command line} +*/ diff --git a/doc/qtcreator/src/howto/creator-sessions.qdoc b/doc/qtcreator/src/howto/creator-sessions.qdoc index 318502e54c..0f455cbc0f 100644 --- a/doc/qtcreator/src/howto/creator-sessions.qdoc +++ b/doc/qtcreator/src/howto/creator-sessions.qdoc @@ -60,7 +60,7 @@ To manage sessions, select \uicontrol File > \uicontrol Sessions > \uicontrol Manage. - \image qtcreator-session-manager.png + \image qtcreator-session-manager.png {Session Manager} To save a session under a new name, select \uicontrol Clone. @@ -97,7 +97,7 @@ \key Ctrl+Alt+<number>, where \e <number> is the number of the session to open (available for the first nine sessions). - \image qtcreator-welcome-session.png + \image qtcreator-welcome-session.webp {Sessions in the Welcome mode} To view more information about a session, select the down arrow icon that appears when you move the mouse cursor over the session name. Select actions diff --git a/doc/qtcreator/src/ios/creator-ios-dev.qdoc b/doc/qtcreator/src/ios/creator-ios-dev.qdoc index d1e15e58b5..f02397f149 100644 --- a/doc/qtcreator/src/ios/creator-ios-dev.qdoc +++ b/doc/qtcreator/src/ios/creator-ios-dev.qdoc @@ -2,23 +2,22 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \previouspage creator-adding-docker-devices.html \page creator-developing-ios.html - \nextpage creator-developing-mcu.html + \previouspage creator-reference.html - \title Connecting iOS Devices + \ingroup creator-reference-devices - You can connect iOS devices to your local machine with a USB cable to - run applications built for them from \QC. + \title Developing for iOS - To be able to use \QC on \macos, you must install Xcode, and therefore, - you already have the tool chain for building applications for iOS. \QC - automatically detects the tool chain and creates the necessary - \l{glossary-buildandrun-kit}{kits} to build applications for and run them on + \brief Connect iOS devices to your local machine with a USB cable to + run applications on them. + + After you install Xcode, \QC automatically detects the toolchain and creates + the necessary \l{Kits}{kits} to build applications for and run them on configured iOS devices. - You only need Qt libraries that are built for iOS. You can install them as - part of Qt 5.2, or later. + You only need Qt libraries that are built for iOS. You can install Qt for iOS + with \QOI. \section1 iOS 17 Devices @@ -29,7 +28,36 @@ physical devices with iOS 17 or later because of limitations of the Apple tool for accessing these devices. - \section1 Configuring Devices + \section1 Specifying Supported iOS Versions + + You can build applications for the latest iOS version and deploy them to + previous versions. For the most part, this works automatically. However, + you must take care when you manually set your own target version. If you set + it to a value higher than what Qt requires and supply your own \c Info.plist + file, you must add an \c LSMinimumSystemVersion entry to the \c Info.plist + that matches the value of \l{CMake: CMAKE_OSX_DEPLOYMENT_TARGET} + {CMAKE_OSX_DEPLOYMENT_TARGET} (when using CMake), + \l QMAKE_IOS_DEPLOYMENT_TARGET (when using qmake), or + \l{https://doc.qt.io/qbs/qml-qbsmodules-cpp.html#minimumIosVersion-prop} + {cpp.minimumIosVersion} (when using Qbs) because iOS (and the App Store) + will use the \c LSMinimumSystemVersion value as the authoritative one. + + If you specify a deployment target value lower than what Qt requires, your + application will almost certainly crash somewhere in the Qt libraries when + run on an older version than Qt supports. Therefore, make sure that the + actual build system code reflects the minimum iOS version that is actually + required. + + \sa {iOS}{How To: Develop for iOS}, {Expressing Supported iOS Versions} +*/ + +/*! + \page creator-how-to-connect-ios-devices.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-ios + + \title Connect iOS devices The connections between \QC and an iOS device are protected by using a certificate that you receive from Apple when you @@ -40,26 +68,27 @@ The first time you connect the device to your local machine, you are asked to enable developer mode on the device. The next time you connect the device, \QC detects it automatically. To disable automatic connections to a device that - you do not use for development, select \uicontrol Preferences > - \uicontrol iOS, and deselect the \uicontrol {Ask about devices not in - developer mode} check box. + you do not use for development, go to preferences > \uicontrol iOS + and clear \uicontrol {Ask about devices not in developer mode}. \note The process of configuring devices and the UI varies slightly depending on the Xcode version that you use. We recommend that you use the latest available Xcode version. + \section1 Create a connection to an iOS device + To configure connections between \QC and an iOS device: \list 1 - \li Make sure that you have Xcode and Qt for iOS installed. + \li Check that you installed Xcode and \l{Qt for iOS}. \li Connect the device to your local machine with a USB cable. \li Start Xcode to configure the device. - For example, in Xcode version 15, select \uicontrol Window > - \uicontrol Devices and Simulators > \uicontrol Devices > + For example, in Xcode version 15, go to \uicontrol Window > + \uicontrol Devices and Simulators > \uicontrol Devices, and select \uicontrol + to add the connected device. \li To specify build settings: @@ -69,7 +98,7 @@ \li Open a project for an application you want to develop for the device. - \li Select \uicontrol Projects > \uicontrol {Build & Run} to select + \li Go to \uicontrol Projects > \uicontrol {Build & Run} to select the kit for building applications for and running them on iOS. \image qtcreator-ios-add-kit.png "Build & Run Settings" @@ -81,7 +110,7 @@ \image qtcreator-build-settings-ios.png "iOS build settings" - \li Select the \uicontrol {Automatically manage signing} check box + \li Select \uicontrol {Automatically manage signing} to automatically select the provisioning profile and signing certificate on your local machine that matches the entitlements and the bundle identifier of the iOS device. @@ -101,46 +130,33 @@ \endlist \note If you cannot deploy applications because a provisioning profile is - missing, check that provisioning profiles are listed in Xcode by selecting + missing, check that provisioning profiles are listed in Xcode by going to \uicontrol Xcode > \uicontrol Preferences > \uicontrol Accounts. For more information about how to acquire and install a provisioning profile, see Apple documentation. - \section1 Viewing Device Connection Status + \section1 View device connection status When you connect an iOS device to your local machine with USB, \QC automatically detects the device if you have configured it by using Xcode. - To view information about the connected device, select \uicontrol Preferences > + To view information about the connected device, go to \uicontrol Preferences > \uicontrol Devices. - \image qtcreator-ios-device-configurations.png "Devices dialog" + \image qtcreator-ios-device-configurations.png {Devices dialog} If the current device state is \uicontrol Connected, (the traffic light icon is orange), you need to configure the device using Xcode. - \section1 Specifying Supported iOS Versions - - You can build applications for the latest iOS version and deploy them to - previous versions. For the most part, this works automatically. However, - you must take care when you manually set your own target version. If you set - it to a value higher than what Qt requires and supply your own \c Info.plist - file, you must add an \c LSMinimumSystemVersion entry to the \c Info.plist - that matches the value of \l{CMake: CMAKE_OSX_DEPLOYMENT_TARGET} - {CMAKE_OSX_DEPLOYMENT_TARGET} (when using CMake), - \l QMAKE_IOS_DEPLOYMENT_TARGET (when using qmake), or - \l{https://doc.qt.io/qbs/qml-qbsmodules-cpp.html#minimumIosVersion-prop} - {cpp.minimumIosVersion} (when using Qbs) because iOS (and the App Store) - will use the \c LSMinimumSystemVersion value as the authoritative one. + \sa {iOS}{How To: Develop for iOS}, {Developing for iOS} +*/ - If you specify a deployment target value lower than what Qt requires, your - application will almost certainly crash somewhere in the Qt libraries when - run on an older version than Qt supports. Therefore, make sure that the - actual build system code reflects the minimum iOS version that is actually - required. +/*! + \page creator-how-to-test-on-ios-simulator.html + \previouspage creator-how-tos.html - For more information, see \l{Expressing Supported iOS Versions}. + \ingroup creator-how-to-ios - \section1 Testing on Simulator + \title Test on iOS Simulator If you do not have an iOS device or you do not want to create an account, you can test applications on @@ -149,48 +165,19 @@ simulates a predefined set of hardware devices and software versions. You can change the simulated hardware and software version in the run - settings for the project. Select \uicontrol Projects > \uicontrol Run, and then select + settings for the project. Go to \uicontrol Projects > \uicontrol Run, and then select the device to simulate in the \uicontrol {Device type} field. \image qtcreator-ios-simulator-deploy.png - The simulator is started automatically when you run the application. - To start the simulator manually, select \uicontrol Preferences > - \uicontrol Devices > \uicontrol iOS > \uicontrol Start. - - To take screenshots of the simulator, select \uicontrol Preferences > - \uicontrol Devices > \uicontrol iOS > \uicontrol Screenshot. The screenshots - are stored in the directory specified in the - \uicontrol {Screenshot directory} field. - - \section2 Managing Simulators - - The available simulators are listed in \uicontrol Preferences > - \uicontrol Devices > \uicontrol iOS. - - \image qtcreator-ios-preferences.png - - To create a new simulator instance: - - \list - - \li Select \uicontrol Create. - - \li In the \uicontrol {Device type} field, select the device type from - a list of devices supported by the Xcode version set as current on - your local machine. - - \li In the \uicontrol {OS version} field, select an OS version from a - list of OS versions supported by the selected device and the current - Xcode version. - - \endlist - - To rename the selected simulator, select \uicontrol Rename. - - To reset the contents and settings of the selected simulators, select - \uicontrol Reset. + The simulator starts automatically when you run the application. + To start the simulator manually, either start the Simulator application + directly with Spotlight, or go to \uicontrol Xcode > \uicontrol {Open Developer Tool} + in Xcode. - To delete the selected simulator, select \uicontrol Delete. + Manage the available simulator devices + \l{https://developer.apple.com/documentation/xcode/running-your-app-in-simulator-or-on-a-device/#Configure-the-list-of-simulated-devices} + {in Xcode}. + \sa {iOS}{How To: Develop for iOS}, {Developing for iOS} */ diff --git a/doc/qtcreator/src/linux-mobile/b2qtdev.qdoc b/doc/qtcreator/src/linux-mobile/b2qtdev.qdoc index 3f7499b5b5..04dceb4916 100644 --- a/doc/qtcreator/src/linux-mobile/b2qtdev.qdoc +++ b/doc/qtcreator/src/linux-mobile/b2qtdev.qdoc @@ -1,144 +1,79 @@ -// Copyright (C) 2023 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 creator-developing-b2qt.html - \previouspage creator-developing-baremetal.html - \nextpage creator-adding-docker-devices.html + \previouspage creator-reference.html - \title Connecting Boot2Qt Devices + \ingroup creator-reference-devices - You can connect \l{Boot2Qt} devices to the development PC to run, debug, - and analyze applications built for them from \QC. For this, you need the - appropriate \l{http://qt.io/licensing/}{Qt license}. + \title Developing for \B2Q Devices - If you have a tool chain for building applications for Boot2Qt devices - installed on the development PC, you can add it to \QC. You can then - select a \l{glossary-buildandrun-kit}{kit} with the \uicontrol Boot2Qt - device type to build applications for and run them on the devices. + \brief Connect \B2Q devices to the computer to run, + debug, and analyze applications built for them from \QC. - To be able to run and debug applications on Boot2Qt devices, - you must add devices and select them in the \QC - \l{kits-tab}{kit}. + The \l{\B2Q: Documentation}{\B2Q} stack runs on a variety of hardware. + \l{http://qt.io/licensing/}{Qt license} holders can customize the contents of + the stack and take it into production hardware. - \section1 Enabling the Boot2Qt Plugin + \note Enable the \B2Q plugin to use it. - To enable the Boot2Qt plugin: - - \list 1 - \li Select \uicontrol Help > \uicontrol {About Plugins} > - \uicontrol {Device Support} > \uicontrol Boot2Qt to - enable the plugin. - \li Select \uicontrol {Restart Now} to restart \QC and load the plugin. - \endlist - - \section1 Adding Boot2Qt Devices - - If \QC does not automatically detect a device you connected with USB, select - \preferences > \uicontrol Devices > - \uicontrol Devices > \uicontrol Add > \uicontrol {Boot2Qt Device} to create - either a network connection or a USB connection to it. + If you have a toolchain for building applications for \B2Q devices + installed on the computer, add it to a \l{Kits}{kit} with the + \uicontrol \B2Q device type to build applications for and run them on + the devices. \image qtcreator-boot2qt-device-configurations.webp {Devices tab in Preferences} - To add a device without using a wizard, select \uicontrol {Boot2Qt Device} in - the pull-down menu of the \uicontrol Add button. - - \note On Ubuntu Linux, the development user account must have access to the - plugged-in devices. To grant them access to the device via USB, create a new - \c udev rule, as described in - \l{https://doc.qt.io/Boot2Qt/b2qt-requirements-x11.html#setting-up-usb-access-to-embedded-devices} - {Boot2Qt: Setting Up USB Access to Embedded Devices}. - - You can edit the settings later in \preferences > - \uicontrol Devices > \uicontrol Devices. + \include linuxdev.qdoc openssh - To reboot the selected device, select \uicontrol {Reboot Device}. - - To restore the default application to the device, select - \uicontrol {Restore Default App}. - - \section2 Protecting Connections - - You can protect the connections between \QC and a device by using an - \l{https://www.openssh.com/}{OpenSSH} connection. OpenSSH is a - connectivity tool for remote login using the SSH protocol. The OpenSSH - suite is not delivered with \QC, so you must download it and install it - on the development PC. Then, you must configure the paths to the tools in - \QC. For more information, see \l {Configuring SSH Connections}. - - You need either a password or an SSH public and private key pair for - authentication. If you do not have an SSH key, you can use the \c ssh-keygen - tool to create it in \QC. For more information, see \l {Generating SSH Keys}. - - \QC does not store passwords. If you use password authentication, you may - need to enter the password upon every connection to the device, or if - caching is enabled, at every \QC restart. If you frequently run into the - timeout, consider using key-based authentication. On \macos and Linux, you - can also select \preferences > \uicontrol Devices > \uicontrol SSH - and increase the time (in minutes) to use the same SSH connection in the - \uicontrol {Connection sharing timeout} field. Windows does not support - shared connections. + \sa {\B2Q}{How To: Develop for \B2Q}, + {Manage Kits}{How To: Manage Kits}, {Run in Qt Application Manager}, + {\B2Q Deploy Configuration}, {\B2Q Run Settings}, + {\B2Q: Documentation} +*/ - \image qtcreator-ssh-options.png {SSH preferences} +/*! + \page creator-how-to-connect-b2qt.html + \previouspage creator-how-tos.html - \section1 Flashing Boot2Qt Devices + \ingroup creator-how-to-b2qt - To flash the Boot2Qt image to an SD card with Flashing Wizard, select - \uicontrol Tools > \uicontrol {Flash Boot to Qt Device} and follow the - instructions of the wizard. + \title Connect \B2Q devices - \image qtcreator-boot2qt-flashing-wizard.png {Boot2Qt Flashing Wizard} + Create connections between \l{\B2Q: Documentation}{\B2Q} devices and + \QC to run, debug, and analyze applications on them. - \section1 Configuring Connections + \note Enable the \B2Q plugin to use it. - To configure connections between \QC and a Boot2Qt device and to - specify build and run settings for the device: + To configure connections between \QC and a \B2Q device: \list 1 \li Check that you can reach the IP address of the device, or use USB to connect it. - \li Select \preferences > \uicontrol Kits > \uicontrol {Qt Versions} > - \uicontrol Add to add the Qt version for Boot2Qt. - \li Select \preferences > \uicontrol Kits > - \uicontrol Compilers > \uicontrol Add to add the compiler for - building the applications. - \li Select \uicontrol Tools > \uicontrol {Flash Boot to Qt Device} - to flash the Boot2Qt image to an SD card with Flashing Wizard. - \li To deploy applications and run them remotely on devices, specify - parameters for connecting to the devices over the network (\QC - automatically detects devices connected with USB): - \list 1 - \li Select \preferences > \uicontrol Devices > - \uicontrol Devices > \uicontrol Add > \uicontrol Boot2Qt. - \image qtcreator-devices-boot2qt.png {Boot2Qt Network Device Setup wizard} - \li In the \uicontrol {Device name} field, enter a name for - the connection. - \li In the \uicontrol {Device address} field, enter the host - name or IP address of the device. This value will be - available in the \c %{Device:HostAddress} variable. - \li Click \uicontrol {Finish} to test the connection and - add the device. - - You can edit the connection parameters in the - \uicontrol Devices tab. The wizard does not show - parameters that have sensible default values. One of - these is the SSH port number, which is available in - the variable \c %{Device:SshPort}. - - To add a device without using the wizard, select - \uicontrol {Boot2Qt Device} in the pull-down menu of the - \uicontrol Add button. - \endlist - \li Select \preferences > \uicontrol Kits > - \uicontrol Add to add a kit for building applications for the - device. Select the Qt version, compiler, and device that you - added above, and choose \uicontrol Boot2Qt as the device type. + \li Go to \preferences > \uicontrol Kits > \uicontrol {Qt Versions}. + \li Select \uicontrol Add to add the Qt version for \B2Q. + \li Go to \preferences > \uicontrol Kits > \uicontrol Compilers. + \li Select \uicontrol Add to add the compiler for building the + applications. + \li Go to \uicontrol Tools > \uicontrol {Flash \B2Q} + to flash the \B2Q image to an SD card with \B2Q Flashing Wizard. + \image qtcreator-boot2qt-flashing-wizard.png {\B2Q Flashing Wizard} + \li Follow the instructions of the wizard to flash the image to the SD + card. + \li Go to \preferences > \uicontrol Devices > \uicontrol Devices. + \li Select \uicontrol Add to add a \B2Q device. + + \QC automatically detects devices connected with USB. + \li Go to \preferences > \uicontrol Kits. + \li Select \uicontrol Add to add a kit for building for the device. + \li Select the Qt version, compiler, and device that you added above. + \li In \uicontrol {Run device type}, select \uicontrol {Boot2Qt Device}. \li To specify build settings: \list 1 \li Open a project for an application you want to develop for the device. - \li Select \uicontrol Projects > \uicontrol {Build & Run} to enable + \li Go to \uicontrol Projects > \uicontrol {Build & Run} to activate the kit that you specified above. \endlist \li Select \uicontrol Run to specify run settings. Usually, you can use @@ -146,7 +81,66 @@ When you run the project, \QC deploys the application as specified by the deploy steps. By default, \QC copies the - application files to the device. For more information, see - \l{Boot2Qt Run Settings}. + application files to the device. + \endlist + + \sa {Configure SSH connections}, {Generate SSH keys}, + {Enable and disable plugins}, {\B2Q}{How To: Develop for \B2Q}, + {Manage Kits}{How To: Manage Kits}, {\B2Q Deploy Configuration}, + {\B2Q Run Settings}, {Developing for \B2Q Devices} +*/ + +/*! + \page creator-how-to-add-b2qt.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-b2qt + + \title Add \B2Q devices + + \note Enable the \B2Q plugin to use it. + + If \QC does not automatically detect a \B2Q device you connect with USB, + check that you followed the instructions in the \l{\B2Q: Documentation} + {Quick Start Guide} for the device. + + If that does not help, but you can reach the IP address of the device, + create a network connection to it: + + \list 1 + \li Go to \preferences > \uicontrol Devices > \uicontrol Devices. + \image qtcreator-boot2qt-device-configurations.webp {Devices tab in Preferences} + \li Select \uicontrol Add > \uicontrol {Boot2Qt Device} to create + a network connection to the device. + \image qtcreator-devices-boot2qt.png {Boot to Qt Network Device Setup wizard} + \li In \uicontrol {Device name}, enter a name for the connection. + \li In \uicontrol {Device address}, enter the host + name or IP address of the device. This value becomes the value of the + \c %{Device:HostAddress} variable. + \li Select \uicontrol {Finish} to test the connection and add the device. \endlist + + The wizard does not show parameters that have sensible default values, such + as the SSH port number. It is available in the variable \c %{Device:SshPort}. + + To add a device without using a wizard, select \uicontrol {Boot2Qt Device} in + the pull-down menu of the \uicontrol Add button. + + \note On Ubuntu Linux, the development user account must have access to the + plugged-in devices. To grant them access to the device via USB, create a new + \c udev rule, as described in + \l{\B2Q: Setting Up USB Access to Embedded Devices}. + + \section1 Reboot devices + + To reboot the selected device, select \uicontrol {Reboot Device}. + + \section1 Restore default applications + + To restore the default application to the device, select + \uicontrol {Restore Default App}. + + \sa {Enable and disable plugins}, {\B2Q}{How To: Develop for \B2Q}, + {Developing for \B2Q Devices}, + {\B2Q: Setting Up USB Access to Embedded Devices} */ diff --git a/doc/qtcreator/src/linux-mobile/creator-deployment-b2qt.qdoc b/doc/qtcreator/src/linux-mobile/creator-deployment-b2qt.qdoc index 73301bb173..298865d794 100644 --- a/doc/qtcreator/src/linux-mobile/creator-deployment-b2qt.qdoc +++ b/doc/qtcreator/src/linux-mobile/creator-deployment-b2qt.qdoc @@ -1,25 +1,32 @@ -// Copyright (C) 2022 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 creator-deployment-b2qt.html - \previouspage creator-deploying-android.html - \nextpage creator-deployment-qnx.html + \previouspage creator-reference.html - \title Deploying to Boot2Qt + \ingroup creator-reference-deploy-configurations - You can specify settings for deploying applications to \l{Boot2Qt} devices - in the project configuration file and in \uicontrol Projects > - \uicontrol {Run Settings} > \uicontrol Deployment. + \title \B2Q Deploy Configuration - \image qtcreator-boot2qt-deployment-steps.png "Boot2Qt deployment steps" + \brief Copy application files to \B2Q devices. + + Specify settings for deploying applications to \l{\B2Q: Documentation} + {\B2Q} devices in the project configuration file and in \uicontrol Projects + > \uicontrol {Run Settings} > \uicontrol Deployment. + + \image qtcreator-boot2qt-deployment-steps.png {Boot to Qt deployment steps} The deployment process is described in more detail in - \l{Deploying to Remote Linux}. + \l{Remote Linux Deploy Configuration}. \section1 Launching Applications on Boot - In addition, to have your application launch on boot, select + To have your application launch on boot, select \uicontrol {Add Deploy Step} > \uicontrol {Change default application} > \uicontrol {Set this application to start by default}. + + \sa {Build and Run}{How To: Build and Run}, + {\B2Q}{How To: Develop for \B2Q}, {\B2Q Run Settings}, + {Developing for \B2Q Devices} */ diff --git a/doc/qtcreator/src/linux-mobile/creator-deployment-embedded-linux.qdoc b/doc/qtcreator/src/linux-mobile/creator-deployment-embedded-linux.qdoc index 38c6823fa3..87c54e26fa 100644 --- a/doc/qtcreator/src/linux-mobile/creator-deployment-embedded-linux.qdoc +++ b/doc/qtcreator/src/linux-mobile/creator-deployment-embedded-linux.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2022 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // ********************************************************************** @@ -9,14 +9,18 @@ /*! \page creator-deployment-embedded-linux.html - \previouspage creator-deployment-qnx.html - \nextpage creator-connecting-mobile.html + \previouspage creator-reference.html - \title Deploying to Remote Linux + \ingroup creator-reference-deploy-configurations - You can specify settings for deploying applications to generic remote - Linux devices in the project configuration file and in the - \uicontrol Projects mode, in \uicontrol {Run Settings}. + \title Remote Linux Deploy Configuration + + \brief Copy application files to generic remote Linux devices or create a + tarball. + + Specify settings for deploying applications to generic remote + Linux devices in the project configuration file and in \uicontrol Projects > + \uicontrol {Run Settings} > \uicontrol Deployment. \image qtcreator-embedded-linux-deployment-details.png "Deploy to remote Linux devices" @@ -107,4 +111,7 @@ The \uicontrol {Deploy tarball via SFTP upload} step specifies that \QC uploads the tarball to the device and extracts it. + + \sa {Build and Run}{How To: Build and Run}, + {Remote Linux}{How To: Develop for remote Linux}, {Remote Linux Run Settings} */ diff --git a/doc/qtcreator/src/linux-mobile/creator-embedded-platforms.qdoc b/doc/qtcreator/src/linux-mobile/creator-embedded-platforms.qdoc deleted file mode 100644 index 39ff44f112..0000000000 --- a/doc/qtcreator/src/linux-mobile/creator-embedded-platforms.qdoc +++ /dev/null @@ -1,117 +0,0 @@ -// Copyright (C) 2022 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! - \page creator-embedded-platforms.html - \previouspage creator-reference.html - - \ingroup creator-reference-platforms - - \title Embedded Platforms - - \brief Embedded platforms that you can develop applications for. - - You can develop applications for the following embedded platforms: - - \list - \li \l {Bare Metal} - \li \l {Boot2Qt} - \li \l {Remote Linux} - \li \l {Microcontroller Units (MCU)} - \li \l QNX - \endlist - - You must install the tool chain for building applications for the targeted - embedded platform on the development PC and use \QMT to - install Qt libraries that are built for the platform. You can then add a - \l{glossary-buildandrun-kit}{kit} with the tool chain and the Qt version - for the device's architecture. When possible, \QMT creates - suitable kits for you. - - You can connect embedded devices to the development PC to run, debug, and - analyze applications built for them from \QC. - - \section1 Bare Metal - - You can run and debug applications on small devices that are not supported - by the remote Linux device plugin by using GDB or a hardware - debugger. - - For more information about developing applications for Bare Metal devices, - see \l{Connecting Bare Metal Devices}. - - \section1 Boot2Qt - - The Boot2Qt stack runs on a variety of hardware. License holders can use - tools to customize the contents of the stack and to take it into - production hardware. - - You need either Windows 10 64-bit or later or Ubuntu Linux 64-bit 20.04 LTS - or later to install and use Boot2Qt. - - The following topics have more information about developing applications - for Boot2Qt devices: - - \list - \li \l{https://doc.qt.io/Boot2Qt/qtdc-supported-platforms.html} - {Boot2Qt: Supported Target Devices and Development Hosts} - \li \l{https://doc.qt.io/Boot2Qt/b2qt-installation-guides.html} - {Boot2Qt: Installation Guides} - \li \l{Connecting Boot2Qt Devices} - \li \l{Boot2Qt Run Settings} - \li \l{Deploying to Boot2Qt} - \li \l{Run in Qt Application Manager} - \endlist - - \section1 Remote Linux - - You must have a tool chain for building applications for embedded Linux - devices installed on the development PC. - - The following topics have more information about developing applications - for remote Linux devices: - - \list - \li \l{Adding Docker Devices} - \li \l{Connecting Remote Linux Devices} - \li \l{Deploying to Remote Linux} - \li \l{Remote Linux Run Settings} - \li \l{Run on remote Linux devices} - \li \l{Run in Qt Application Manager} - \endlist - - \section1 Microcontroller Units (MCU) - - You need the GNU Arm Embedded GCC compiler, libraries, and other GNU tools - necessary for bare metal software development on devices based on the Arm - Cortex-M processors. - - The following topics have more information about developing applications - for MCUs: - - \list - \li \l{Connecting MCUs} - \li \l{Running Applications on MCUs} - \li \l{https://doc.qt.io/QtForMCUs/index.html}{\QMCU} - \endlist - - \section1 QNX - - The QNX Neutrino RTOS has more command-line tools - and services, as described in \l {Qt for QNX}. - - \note In Qt 6, \QC support for QNX is considered experimental. - - The following topics have more information about developing applications - for QNX devices: - - \list - \li \l{Connecting QNX Devices} - \li \l{Deploying to QNX Neutrino} - \li \l{QNX Run Settings} - \li \l{Run on QNX devices} - \li \l{Qt for QNX} - \endlist - - \sa {Supported Platforms} -*/ diff --git a/doc/qtcreator/src/linux-mobile/creator-projects-how-to-run-generic-linux.qdoc b/doc/qtcreator/src/linux-mobile/creator-projects-how-to-run-generic-linux.qdoc index b78dcd5ca2..d39f924f04 100644 --- a/doc/qtcreator/src/linux-mobile/creator-projects-how-to-run-generic-linux.qdoc +++ b/doc/qtcreator/src/linux-mobile/creator-projects-how-to-run-generic-linux.qdoc @@ -5,7 +5,7 @@ \page creator-how-to-run-on-remote-linux.html \previouspage creator-how-tos.html - \ingroup creator-how-to-run + \ingroup creator-how-to-remote-linux \title Run on remote Linux devices @@ -19,7 +19,7 @@ \endlist - \QC uses the compiler from the kit (tool chain) to build the application. + \QC uses the compiler from the kit (toolchain) to build the application. \QC copies the application files to the connected device and runs the application. The application views are @@ -34,6 +34,6 @@ Debugging works transparently if GDB server is installed on the device and it is compatible with the GDB on the host. - \sa {Connecting Remote Linux Devices}, {Run on many platforms}, {Compilers}, + \sa {Remote Linux}{How To: Develop for remote Linux}, {Run on many platforms}, {Compilers}, {Embedded Platforms}, {kit-preferences}{Kits} */ diff --git a/doc/qtcreator/src/linux-mobile/creator-projects-settings-run-b2qt.qdoc b/doc/qtcreator/src/linux-mobile/creator-projects-settings-run-b2qt.qdoc index 1391cfcfd4..a8d3093cfb 100644 --- a/doc/qtcreator/src/linux-mobile/creator-projects-settings-run-b2qt.qdoc +++ b/doc/qtcreator/src/linux-mobile/creator-projects-settings-run-b2qt.qdoc @@ -1,30 +1,30 @@ -// Copyright (C) 2023 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 creator-run-settings-boot2qt.html + \page creator-run-settings-\B2Q.html \previouspage creator-reference.html \ingroup creator-reference-run-configurations - \title Boot2Qt Run Settings + \title \B2Q Run Settings - \brief Settings for running applications on Boot2Qt devices. + \brief Settings for running applications on \B2Q devices. Specify settings for running applications on the \l {kits-tab}{Run device} that you select for a kit in \uicontrol Projects > \uicontrol {Build & Run} > \uicontrol Run > \uicontrol {Run Settings}. - To run and debug an application on a \l Boot2Qt device (commercial only), you - must create connections from the development host to the device and add the - device configurations to kits. Select \uicontrol {Manage Kits} to add devices - to kits. For more information, see - \l{http://doc.qt.io/Boot2Qt/b2qt-installation-guides.html} - {Boot2Qt: Installation Guide}. + To run and debug an application on a \l{\B2Q: Documentation}{\B2Q} device + (commercial only), create connections from the development host to the device + and add the device configurations to kits. + + Select \uicontrol {Manage Kits} to add devices to kits. The run settings display the path to the executable file on the development host and on the device. - \sa {Activate kits for a project}, {Configure projects for running}, {kits-tab}{Kits}, - {Deploying to Boot2Qt} + \sa {\B2Q}{How To: Develop for \B2Q}, {Manage Kits}{How To: Manage Kits}, + {Configure projects for running}, {kits-tab}{Kits}, + {\B2Q Deploy Configuration} */ diff --git a/doc/qtcreator/src/linux-mobile/creator-projects-settings-run-linux.qdoc b/doc/qtcreator/src/linux-mobile/creator-projects-settings-run-linux.qdoc index 4e2a08e132..adc27d6a93 100644 --- a/doc/qtcreator/src/linux-mobile/creator-projects-settings-run-linux.qdoc +++ b/doc/qtcreator/src/linux-mobile/creator-projects-settings-run-linux.qdoc @@ -19,7 +19,7 @@ connections from the development host to the device and add the device configurations to kits. Select \uicontrol {Manage Kits} to add devices to kits. For more information, see - \l {Connecting Remote Linux Devices}. + \l {Remote Linux}{How To: Develop for remote Linux}. When you run the application, \QC copies the files to the connected device. @@ -38,5 +38,5 @@ running X11 client on a local display. \sa {Activate kits for a project}, {Configure projects for running}, {kits-tab}{Kits}, - {Connecting Remote Linux Devices} + {Remote Linux}{How To: Develop for remote Linux} */ diff --git a/doc/qtcreator/src/linux-mobile/linuxdev-keys.qdoc b/doc/qtcreator/src/linux-mobile/linuxdev-keys.qdoc new file mode 100644 index 0000000000..9af4de44ed --- /dev/null +++ b/doc/qtcreator/src/linux-mobile/linuxdev-keys.qdoc @@ -0,0 +1,82 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page creator-how-to-configure-ssh.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-remote-linux + + \title Configure SSH connections + + To protect the connections between \QC and a device, install the \l{OpenSSH} + suite, which includes the \c ssh, \c sftp, and \c ssh-keygen tools on the + computer. + + SSH connections are established via an OpenSSH client running in master + mode, if possible. By default, multiple sessions are shared over a single SSH + onnection. Establishing a connection once and then re-using it for subsequent + run and deploy procedures reduces connection setup overhead particularly + with embedded devices. Because connection sharing is not supported on + Windows, a new SSH connection is created for each deploy or run procedure. + + To set the paths to the directories where the tools are installed: + + \list 1 + \li Go to \preferences > \uicontrol Devices > \uicontrol SSH. + \image qtcreator-ssh-options.png "SSH preferences" + \li Clear \uicontrol {Enable connection sharing} to + create a new SSH connection for each deploy and run procedure. This + option is grayed on Windows, where connection sharing is not + supported. + \li In \uicontrol {Connection sharing timeout}, specify the + timeout for reusing the SSH connection in minutes. + \li In \uicontrol {Path to ssh executable}, enter the path + to the directory where the OpenSSH executable is installed. + \li In \uicontrol {Path to sftp executable}, enter the path + to the directory where the SFTP executable is installed. + \li In \uicontrol {Path to ssh-askpass executable}, enter the + path to the directory where the ssh-askpass executable is installed. + Usually, you can use the default path that points to the + implementation of the tool delivered with \QC, qtc-askpass. + \li In \uicontrol {Path to ssh-keygen executable}, enter the + path to the directory where the ssh-keygen executable is installed. + \endlist + + \sa {Remote Linux}{How To: Develop for remote Linux}, + {Developing for Remote Linux Devices} +*/ + +/*! + \page creator-how-to-generate-ssh-keys.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-remote-linux + + \title Generate SSH keys + + To protect the connections between \QC and a device, use \l{OpenSSH}. + + If you do not have an SSH public and private key pair, you can generate it + in \QC. The connection wizard can create the key pair for you, or you can + create it separately. + + You can specify key length and the key algorithm, RSA or ECDSA. + If you only use the keys to protect connections to the emulator or + device, you can use the default values. + + \list 1 + \li Go to \preferences > \uicontrol Devices > \uicontrol Devices + \li Select \uicontrol {Create New}. + \image qtcreator-ssh-key-configuration.png {SSH Key Configuration dialog} + \li In \uicontrol {Private key file}, select the location to save + the private key. + \uicontrol {Public key file} displays the location to save the + corresponding public key. + \li Select \uicontrol {Generate And Save Key Pair} to generate and save the + keys at the specified locations. + \endlist + + \sa {Remote Linux}{How To: Develop for remote Linux}, + {Developing for remote Linux devices} +*/ diff --git a/doc/qtcreator/src/linux-mobile/linuxdev-keys.qdocinc b/doc/qtcreator/src/linux-mobile/linuxdev-keys.qdocinc deleted file mode 100644 index f3582f2373..0000000000 --- a/doc/qtcreator/src/linux-mobile/linuxdev-keys.qdocinc +++ /dev/null @@ -1,80 +0,0 @@ -// Copyright (C) 2019 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! - -//! [configuring ssh] - \section2 Configuring SSH Connections - - SSH connections are established via an OpenSSH client running in master - mode, if possible. Connection sharing is enabled by default to allow - sharing multiple sessions over a single SSH connection. This way, a - connection is only established once and then re-used by subsequent run - and deploy procedures, saving connection setup overhead particularly - with embedded devices. Because connection sharing is not supported on - Windows, a new SSH connection is created for each deploy or run procedure. - - To create SSH connections, you must install the \l{https://www.openssh.com/} - {OpenSSH} suite, which includes the ssh, sftp, and ssh-keygen tools on the - development PC. - - To tell \QC where it can find the tools, specify the paths to the - directories where the tools are installed in \preferences > - \uicontrol Devices > \uicontrol SSH: - - \image qtcreator-ssh-options.png "SSH preferences" - - \list - \li Deselect the \uicontrol {Enable connection sharing} check box to - create a new SSH connection for each deploy and run procedure. This - option is grayed on Windows, where connection sharing is not - supported. - \li In the \uicontrol {Connection sharing timeout} field, specify the - timeout for reusing the SSH connection in minutes. - \li In the \uicontrol {Path to ssh executable} field, enter the path - to the directory where the OpenSSH executable is installed. - \li In the \uicontrol {Path to sftp executable} field, enter the path - to the directory where the SFTP executable is installed. - \li In the \uicontrol {Path to ssh-askpass executable} field, enter the - path to the directory where the ssh-askpass executable is installed. - Usually, you can use the default path that points to the - implementation of the tool delivered with \QC, qtc-askpass. - \li In the \uicontrol {Path to ssh-keygen executable} field, enter the - path to the directory where the ssh-keygen executable is installed. - \endlist - -//! [configuring ssh] - - -//! [generating ssh keys] - - \section2 Generating SSH Keys - - If you do not have an SSH public and private key pair, you can generate it - in \QC. The connection wizard can create the key pair for you, or you can - create it separately. - - You can specify key length and the key algorithm, RSA or ECDSA. - If you only use the keys to protect connections to the emulator or - device, you can use the default values. - - \list 1 - - \li Select \preferences > \uicontrol Devices - > \uicontrol Devices > \uicontrol {Create New}. - - \image qtcreator-ssh-key-configuration.png "SSH Key Configuration dialog" - - \li In the \uicontrol {Private key file} field, select the location to save - the private key. - - The \uicontrol {Public key file} field displays the location to save the - corresponding public key. - - \li Select \uicontrol {Generate And Save Key Pair} to generate and save the - keys at the specified locations. - - \endlist - -//! [generating ssh keys] -*/ diff --git a/doc/qtcreator/src/linux-mobile/linuxdev-processes.qdoc b/doc/qtcreator/src/linux-mobile/linuxdev-processes.qdoc new file mode 100644 index 0000000000..db73410dca --- /dev/null +++ b/doc/qtcreator/src/linux-mobile/linuxdev-processes.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page creator-how-to-manage-device-processes.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-remote-linux + + \title Manage device processes + + To view and end processes running on embedded platforms: + + \list 1 + \li Go to \preferences > \uicontrol Devices > \uicontrol Devices. + \li Select an embedded device. + \image qtcreator-preferences-devices-remote-linux.webp {Remote Linux Device in Devices} + \li Select \uicontrol {Show Running Processes}. + \li Filter the processes by name or ID. + \li To update the process list, select \uicontrol {Update List}. + \li To end a process, select it in the list, and then select + \uicontrol {Kill Process}. + \endlist + + \sa {Develop for Devices}{How To: Develop for Devices}, {Devices} +*/ diff --git a/doc/qtcreator/src/linux-mobile/linuxdev-processes.qdocinc b/doc/qtcreator/src/linux-mobile/linuxdev-processes.qdocinc deleted file mode 100644 index 1c9c2d0a4a..0000000000 --- a/doc/qtcreator/src/linux-mobile/linuxdev-processes.qdocinc +++ /dev/null @@ -1,22 +0,0 @@ -// Copyright (C) 2019 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! -//! [managing device processes] - - \section2 Managing Device Processes - - You can view processes running on devices and kill them. Select - \preferences > \uicontrol Devices > - \uicontrol Devices > \uicontrol {Show Running Processes}. - - You can filter the processes by name or ID in the - \uicontrol {List of Processes} dialog. - - To update the process list, select \uicontrol {Update List}. - - To kill a process, select it in the list, and then select \uicontrol {Kill - Process}. - -//! [managing device processes] -*/ diff --git a/doc/qtcreator/src/linux-mobile/linuxdev.qdoc b/doc/qtcreator/src/linux-mobile/linuxdev.qdoc index 401fdbd8c1..e0ec120b85 100644 --- a/doc/qtcreator/src/linux-mobile/linuxdev.qdoc +++ b/doc/qtcreator/src/linux-mobile/linuxdev.qdoc @@ -1,122 +1,99 @@ -// Copyright (C) 2021 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 creator-developing-generic-linux.html - \previouspage creator-developing-qnx.html - \nextpage creator-setup-webassembly.html + \previouspage creator-reference.html - \title Connecting Remote Linux Devices + \ingroup creator-reference-devices - You can connect generic Linux devices to the development PC to run, + \title Developing for Remote Linux Devices + + \brief Connect generic Linux devices to the computer to run, debug, and analyze applications built for them from \QC. - If you have a tool chain for building applications for embedded Linux - devices installed on the development PC, you can add - it to \QC. You can then select a \l{glossary-buildandrun-kit}{kit} + If you have a toolchain for building applications for embedded Linux + devices installed on the computer, add it to a \l{Kits}{kit} with the device type \uicontrol {Remote Linux Device} to build applications for and run them on the devices. - To be able to run and debug applications on remote Linux devices, - you must add devices and select them in the \QC \l{glossary-buildandrun-kit} - {kit}. + Use a wizard to connect remote Linux devices to the computer. You can edit + the settings later in \preferences > \uicontrol Devices > \uicontrol Devices. - You use a wizard to create the connections. You can edit the settings later - in \preferences > \uicontrol Devices > - \uicontrol Devices. + \image qtcreator-preferences-devices-remote-linux.webp {Remote Linux Device in Devices} - \image qtcreator-preferences-devices-remote-linux.webp "Remote Linux Device in the Devices tab" + //! [openssh] + \section1 Protecting Device Connections - You can protect the connections between \QC and a device by using an - \l{https://www.openssh.com/}{OpenSSH} connection. OpenSSH is a - connectivity tool for remote login using the SSH protocol. The OpenSSH - suite is not delivered with \QC, so you must download it and install it - on the development PC. Then, you must configure the paths to the tools in - \QC. For more information, see \l {Configuring SSH Connections}. + To protect the connections between \QC and a device, use \l{OpenSSH} for + remote login over the SSH protocol. The OpenSSH suite is not delivered with + \QC, so download it and install it on the computer. Then, configure the paths + to the tools in \QC. You need either a password or an SSH public and private key pair for - authentication. If you do not have an SSH key, you can use the ssh-keygen - tool to create it in \QC. For more information, see \l {Generating SSH Keys}. + authentication. If you do not have an SSH key, use the \c ssh-keygen + tool to create it in \QC. \note \QC does not store passwords, so if you use password authentication, you may need to enter the password on every connection to the device, or, if caching is enabled, at every \QC restart. - To configure connections between \QC and a remote Linux device and to - specify build and run settings for the device: - - \list 1 + If you frequently run into the timeout, consider using key-based + authentication. Create an SSH key in \QC with the \c ssh-keygen tool. - \li Make sure that your device can be reached via an IP address. + On \macos and Linux, go to \preferences > \uicontrol Devices > \uicontrol SSH + and increase the time (in minutes) for sharing an SSH connection in the + \uicontrol {Connection sharing timeout} field. Windows does not support + shared connections. - \li Select \preferences > \uicontrol Kits > - \uicontrol {Qt Versions} > \uicontrol Add to add the Qt version - for embedded Linux. + \image qtcreator-ssh-options.png {SSH preferences} + //! [openssh] - \li Select \preferences > \uicontrol Kits > - \uicontrol Compilers > \uicontrol Add to add the compiler for - building the applications. + \sa {Add Docker devices}, {Remote Linux}{How To: Develop for remote Linux}, + {Run in Qt Application Manager}, {Remote Linux Deploy Configuration}, + {Remote Linux Run Settings} +*/ - \li To deploy applications and run them remotely on devices, specify - parameters for accessing the devices: +/*! + \page creator-how-to-connect-remote-linux.html + \previouspage creator-how-tos.html - \list a + \ingroup creator-how-to-remote-linux - \li Select \preferences > - \uicontrol Devices > \uicontrol Devices > \uicontrol Add > - \uicontrol {Remote Linux Device} - > \uicontrol {Start Wizard}. + \title Connect remote Linux devices - \image qtcreator-preferences-devices-remote-linux-connection.webp "Connection Data wizard" + Create connections between generic Linux devices and \QC to run, debug, and + analyze applications on them. - \li In \uicontrol {The name to identify this configuration}, - enter a name for the connection. + To configure connections between \QC and a remote Linux device: - \li In \uicontrol {The device's host name or IP address}, - enter the host name or IP address of the device. - This value will be available in the variable \c %{Device:HostAddress}. + \list 1 - \li In \uicontrol {The device's SSH port number}, enter the port - number to use for SSH connections. This value will be - available in the variable \c %{Device:SshPort}. - \li In \uicontrol {The username to log into the device}, - enter the username to log into the device and run the - application as. - This value will be available in the variable \c %{Device:UserName}. + \li Make sure that your device can be reached via an IP address. - \li Select \uicontrol {Next} to open the - \uicontrol {Key Deployment} dialog. + \li Go to \preferences > \uicontrol Kits > \uicontrol {Qt Versions}. - \image qtcreator-preferences-devices-remote-linux-key-deployment.webp "Key Deployment dialog" + \li Select \uicontrol Add to add the Qt version for embedded Linux. - \li In \uicontrol {Private key file}, select a private key file - to use for authentication. This value will be available in - the variable \c %{Device:PrivateKeyFile}. + \li Go to \preferences > \uicontrol Kits > \uicontrol Compilers. - \li If you do not have a public-private key pair, select - \uicontrol {Create New Key Pair}. For more information, - see \l{Generating SSH Keys}. + \li Select \uicontrol Add to add the compiler for building the + applications. - \li Select \uicontrol {Deploy Public Key} to copy the public - key to the device. + \li Go to \preferences > \uicontrol Devices > \uicontrol Devices. - \li Select \uicontrol {Next} to create the connection. + \li Select \uicontrol Add to add a remote Linux device. - \endlist + \li Go to \preferences > \uicontrol Kits. - All of these parameters can be edited later, as well as additional ones that the - wizard does not show because there are sensible default values. + \li Select \uicontrol Add to add a kit for building for the device. - To add a device without using the wizard, select - \uicontrol {Add Remote Linux Device} in the pull-down - menu of the \uicontrol Add button. + \li Select the Qt version, compiler, and device that you added above. - \li Select \preferences > \uicontrol Kits > - \uicontrol Add to add a kit for building for the device. Select the - Qt version, compiler, and device that you added above, and select - \uicontrol {Remote Linux Device} in \uicontrol {Run device type}. + \li In \uicontrol {Run device type}, select + \uicontrol {Remote Linux Device}. - To build on the remote device, select \uicontrol {Remote Linux Device} + \li To build on the remote device, select \uicontrol {Remote Linux Device} also in \uicontrol {Build device}. \li To specify build settings: @@ -134,13 +111,33 @@ \li Select \uicontrol Run to specify run settings. Usually, you can use the default settings. - When you run the project, \QC deploys the application as specified by the - deploy steps. By default, \QC copies the application files to the device. - For more information, see \l{Deploying to Remote Linux}. + When you run the project, \QC deploys the application as specified by + the deploy steps. \endlist - \include linux-mobile/linuxdev-keys.qdocinc configuring ssh - \include linux-mobile/linuxdev-keys.qdocinc generating ssh keys - \include linux-mobile/linuxdev-processes.qdocinc managing device processes + \sa {Remote Linux}{How To: Develop for remote Linux}, + {Manage Kits}{How To: Manage Kits}, {Developing for Remote Linux Devices}, + {Remote Linux Deploy Configuration}, {Remote Linux Run Settings} +*/ + +/*! + \page creator-how-to-add-remote-linux.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-remote-linux + + \title Add remote Linux devices + + Create connections between generic Linux devices and \QC to run, debug, and + analyze applications on them. + + \image qtcreator-preferences-devices-remote-linux.webp {Remote Linux Device in Devices} + \caption Remote Linux Device preferences + + \include qtcreator-add-linux-device.qdocinc {add linux device} {Remote Linux Device} + + \sa {Remote Linux}{How To: Develop for remote Linux}, + {Developing for Remote Linux Devices}, + {Remote Linux Deploy Configuration} */ diff --git a/doc/qtcreator/src/linux-mobile/qtcreator-add-linux-device.qdocinc b/doc/qtcreator/src/linux-mobile/qtcreator-add-linux-device.qdocinc new file mode 100644 index 0000000000..28fb464833 --- /dev/null +++ b/doc/qtcreator/src/linux-mobile/qtcreator-add-linux-device.qdocinc @@ -0,0 +1,47 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +//! [add linux device] + + \section1 Use a wizard to add a device + + To use a wizard to add \uicontrol {\1}: + + \list 1 + \li Go to \preferences > \uicontrol Devices > \uicontrol Devices. + \li Select \uicontrol Add > \uicontrol {\1} > \uicontrol {Start Wizard}. + \image qtcreator-preferences-devices-remote-linux-connection.webp {Connection Data wizard} + \li In \uicontrol {The name to identify this configuration}, + enter a name for the connection. + \li In \uicontrol {The device's host name or IP address}, + enter the host name or IP address of the device. + This becomes the value of the \c %{Device:HostAddress} variable. + \li In \uicontrol {The device's SSH port number}, enter the port + number for SSH connections. This becomes the value of the + \c %{Device:SshPort} variable. + \li In \uicontrol {The username to log into the device}, enter the + username to log into the device and run the application. This + becomes the value of the \c %{Device:UserName} variable. + \li Select \uicontrol {Next} to open the \uicontrol {Key Deployment} + dialog. + \image qtcreator-preferences-devices-remote-linux-key-deployment.webp {Key Deployment dialog} + \li In \uicontrol {Private key file}, select a private key file + for authentication. This becomes the value of the + \c %{Device:PrivateKeyFile} variable. + \li If you don't have a public-private key pair, select + \uicontrol {Create New Key Pair}. For more information, + see \l{Generate SSH keys}. + \li Select \uicontrol {Deploy Public Key} to copy the public + key to the device. + \li Select \uicontrol {Next} to create the connection. + \endlist + + To change device preferences, go to \preferences > \uicontrol Devices > + \uicontrol Devices and select a device in \uicontrol Device. + + \section1 Manually add a device + + To add a device without using the wizard, select \uicontrol {\1} in the + pull-down menu of the \uicontrol Add button. + +//! [add linux device] diff --git a/doc/qtcreator/src/mcu/creator-mcu-dev.qdoc b/doc/qtcreator/src/mcu/creator-mcu-dev.qdoc index 65fba314e2..19ba26bdca 100644 --- a/doc/qtcreator/src/mcu/creator-mcu-dev.qdoc +++ b/doc/qtcreator/src/mcu/creator-mcu-dev.qdoc @@ -1,31 +1,29 @@ -// 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-developing-ios.html \page creator-developing-mcu.html - \nextpage creator-developing-qnx.html + \previouspage creator-reference.html - \title Connecting MCUs + \ingroup creator-reference-devices - \QMCU enables you to use subsets of QML and Qt Quick Controls - to create user interfaces for devices that are powered by microcontroller - units (MCU). It includes a new graphics rendering engine that has a low - memory footprint and is optimized for MCUs and other resource-constrained - devices. + \title Developing for MCUs - You can connect MCU boards to a development host to build applications for - them using the GNU Arm Embedded GCC compiler, libraries, and other GNU tools - necessary for bare metal software development on devices based on the Arm - Cortex-M processors. You can deploy the applications on MCUs to run and - debug them using \QC. + \brief Connect MCU devices to the computer to run and debug applications on + them. - The toolchains are available for cross-compilation on Microsoft Windows, - Linux, and macOS. However, the Qt for \QMCU SDK is currently only available - for Windows and Linux. + \note Enable the McuSupport plugin to develop for MCUs. - For a list of \QMCU reference implementations, see the - \l{\QMCU - Supported Target Platforms}{\QMCU} documentation. + Use subsets of QML and Qt Quick Controls to create user interfaces for + devices that are powered by microcontroller units (MCU). \QMCU has a + new graphics rendering engine with a low memory footprint and optimization + for MCUs and other resource-constrained devices. + + Connect MCU boards to a computer to build applications for them. Deploy the + applications on MCUs to run and debug them. + + For a list of \QMCU reference implementations, see + \l{\QMCU - Supported Target Platforms}. \section1 Requirements @@ -33,52 +31,98 @@ \list \li \QMCU SDK (only available for Windows and Linux) - \li \l{https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm} - {GNU ARM Embedded Toolchain} + \li \l {\QMCU - Prerequisites}{Suitable toolchain} \endlist + The toolchains are available for cross-compilation on Microsoft Windows, + Linux, and macOS. However, the Qt for \QMCU SDK is currently only available + for Windows and Linux. + The hardware-specific requirements vary depending on the hardware platform you are developing for. For more information see: \list \li \l{Getting Started on NXP} \li \l{Getting Started on STM} \li \l{Getting Started on Renesas} + \li \l{Getting Started on Infineon} \endlist - \section1 Setting Up the Development Environment + \section1 \QMCU SDKs + + While you can use the latest \QC version to develop with any \QMCU SDK, the + following combinations have been tested to work well. + + \table + \header + \li \QC version + \li \QMCU SDK version + \row + \li 12.0.2 or later + \li 2.7 or later + \row + \li 11.0.3 + \li 2.6 + \row + \li 10.0.2 + \li 2.5 + \row + \li 10.0.0 + \li 2.4 + \row + \li 9.0.0 + \li 2.3 + \row + \li 7.0.0 up to 8.0.2 + \li 2.0 up to 2.2 + \row + \li 6.0.x + \li 1.3 up to 2.2 + \row + \li 4.12.4 up to 5.0.3 + \li 1.3 up to 1.9 + \row + \li 4.12.2 or 4.12.3 + \li 1.2 + \row + \li 4.12.0 or 4.12.1 + \li 1.1 + \row + \li 4.11.x + \li 1.0 + \endtable - You must download and install the required software and create connections - between \QC and MCUs. The following subsections guide you through the - setup process. + \sa {Enable and disable plugins}, {MCUs}{How To: Develop for MCUs}, + {Developing for MCUs}, {\QMCU} +*/ - \section2 MCU Plugin +/*! + \page creator-how-to-create-mcu-kits.html + \previouspage creator-how-tos.html - To be able to develop applications for MCUs, you need the MCU plugin. - This plugin is enabled automatically by \QOI when you - install \QMCU. + \ingroup creator-how-to-mcu - \section2 Specifying MCU Settings + \title Connect MCU devices - To configure a connection between \QC and your MCU board, select - \preferences > \uicontrol Devices > \uicontrol MCU: + \note Enable the McuSupport plugin to develop for MCUs. - \image qtcreator-mcu-options.png "MCU preferences" + To configure a connection between \QC and your MCU board: \list 1 - \li In the \uicontrol {\QMCU SDK} field, specify the path - to the directory where you installed \QMCU SDK. - \li In the \uicontrol {Targets supported by the \QMCU SDK} - field, select your MCU board. - \li In the \uicontrol Requirements section, ensure that the - platform-specific requirements are met. This varies depending - on the target chosen: + \li Go to \preferences > \uicontrol Devices > \uicontrol MCU. + \li In \uicontrol {\QMCU SDK}, specify the path to the directory where + you installed \QMCU SDK. + \image qtcreator-preferences-mcu.webp {MCU preferences} + \li In \uicontrol {Targets supported by the \QMCU SDK}, select your MCU + board. + \li In \uicontrol Requirements, check that the platform-specific + requirements are met. This depends on the target: \list \li For STM32 targets: \list \li The \uicontrol {GNU ARM Embedded Toolchain} or \uicontrol {IAR ARM Compiler} path. \li The \uicontrol {STM32CubeProgrammer} install path. - \li The \uicontrol {MCU SDK} for the chosen target. + \li The \uicontrol {Board SDK} for the chosen target. \li The \uicontrol {FreeRTOS Sources} for the chosen target. \endlist \li For NXP targets: @@ -86,7 +130,7 @@ \li The \uicontrol {GNU ARM Embedded Toolchain} or \uicontrol {IAR ARM Compiler} path. \li The \uicontrol {MCUXpresso IDE} install path. - \li The \uicontrol {MCU SDK} for the chosen target. + \li The \uicontrol {Board SDK} for the chosen target. \li The \uicontrol {FreeRTOS Sources} for the chosen target. \endlist \li For Renesas targets: @@ -94,74 +138,103 @@ \li The \uicontrol {Green Hills Compiler} path. \li The \uicontrol {Renesas Graphics Library} path. \endlist + \li For Infineon targets: + \list + \li The \uicontrol {Green Hills Compiler for ARM} path. + \li The \uicontrol {Graphics Driver for Traveo II Cluster Series} + path. + \li The \uicontrol {Infineon Auto Flash Utility} path. + \endlist \endlist - \li Select the + \li Select \uicontrol {Automatically create kits for all available targets on start} - option to create kits automatically the next time Qt Creator is - started. - \note You could also use \uicontrol {Create Kit} to manually - create kits for the chosen target. - \li Select \uicontrol Apply to save the settings. + to create kits automatically the next time \QC starts. + \note Select \uicontrol {Create Kit} to manually create kits for the + target. + \li Select \uicontrol Apply to save the preferences. \endlist - \note When updating to other versions of the \QMCU SDK, \QC will - ask you if you want to replace the existing kits, or create new ones - alongside. This can also be done manually, for each individual target, - via \uicontrol {Update Kit} and \uicontrol {Create Kit}, respectively. - - \section2 Adding MCU Devices - - \note This optional step is not necessary if you have already - set up the MCU SDK as outlined in \l{Specifying MCU Settings}. + \section1 Add MCU devices \QC automatically adds a default MCU device when you select \uicontrol Apply in the \uicontrol MCU tab after configuring the - MCU tool chain. + MCU toolchain. - \image qtcreator-mcu-device.png "MCU devices" + \image qtcreator-mcu-device.png {MCU devices} To add MCU devices, select \preferences > \uicontrol Devices > \uicontrol Add > \uicontrol {MCU Device} > \uicontrol {Start Wizard}: \list 1 - \li In the \uicontrol Name field, give the device a name. - \li In the \uicontrol Type field, select the board type. + \li In \uicontrol Name, give the device a name. + \li In \uicontrol Type, select the board type. \li Select \uicontrol Apply to add the device. \endlist - \section2 Managing MCU Kits + \sa {Enable and disable plugins}, {MCUs}{How To: Develop for MCUs}, + {Developing for MCUs} +*/ + + +/*! + \page creator-how-to-manage-mcu-kits.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-mcu - \QC automatically adds kits for all the available targets, if the + \title Manage MCU Kits + + \note Enable the McuSupport plugin to develop for MCUs. + + \QC automatically adds kits for all the available MCU targets if you select \uicontrol {Automatically create kits for all available targets on start} - option is enabled under the \uicontrol MCU settings tab. You can also - create kits for individual targets manually, as outlined - in \l{Specifying MCU Settings}. + in \preferences > \uicontrol Devices > \uicontrol MCU. + + \image qtcreator-preferences-kits-mcu.webp {MCU kit} - \image qtcreator-mcu-kit.png "MCU kits" + \note When you update the \QMCU SDK, \QC asks you whether you want to replace + the existing kits or create additional kits. To do this manually for each + target, select \uicontrol {Update Kit} or \uicontrol {Create Kit}. - You can edit and/or remove individual kits in \preferences > \uicontrol Kits. + To add new kits, go to \preferences > \uicontrol Devices > \uicontrol MCU, + and select \uicontrol {Create Kit}. This adds the paths to the kit's toolkits + and SDKs, and keeps them synchronized when you select \uicontrol Apply or + \uicontrol OK. - However, for adding new kits you should use the \uicontrol {Create Kit} - button in the {\QMCU} settings tab. This method adds the paths to - the kit's toolkits and SDKs, and keeps them synchronized when selecting - \uicontrol Apply or \uicontrol OK. + \section1 Change or remove MCU kits + + To change or remove individual kits, go to \preferences > \uicontrol Kits. The \uicontrol {MCU dependencies} field displays paths to 3rd party software required for MCU development with the current kit. - \section1 Running Applications on MCUs + \sa {Enable and disable plugins}, {MCUs}{How To: Develop for MCUs}, + {Developing for MCUs} +*/ + +/*! + \page creator-how-to-run-on-mcu-devices.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-mcu - You can use a wizard to set up a project for developing an application that - you can run on MCUs. The project uses a subset of QML and Qt Quick Controls + \title Create MCU projects + + \note Enable the McuSupport plugin to develop for MCUs. + + Create a project for developing an application that you can run on MCUs. + The project imports a subset of QML and Qt Quick Controls types that are supported by \QMCU. For more information about developing - applications for MCUs, see the \QMCU documentation. + applications for MCUs, see \l {Qt for MCUs}. To create an application and run it on a MCU board: \list 1 - \li Select \uicontrol File > \uicontrol {New Project} > - \uicontrol {Application (\QMCU)} > - \uicontrol {MCU Support Application} > \uicontrol Choose. + \li Go to \uicontrol File > \uicontrol {New Project}. + \image qtcreator-mcu-new-project.webp {New Project dialog} + \li Select \uicontrol {QmlProject Application (\QMCU)} > + \uicontrol {Qt for MCUs Empty Application} or + \uicontrol {Qt for MCUs Example Application} > \uicontrol Choose. \li Follow the instructions of the wizard to create the project. \li Select \uicontrol Projects > \uicontrol {Build & Run}, and then select the kit for building the application and running it on the @@ -170,37 +243,7 @@ Usually, you can use the default settings. \endlist - \section1 Supported \QMCU SDKs - - \note The \QMCU SDK 2.3 requires \QC 9.0.0, or later. - - The following table lists the \QC versions you can use to develop - applications with particular \QMCU SDK versions. - - \table - \header - \li \QC version - \li \QMCU SDK version - \row - \li 9.0.0 or later - \li 2.0 or later - \row - \li 7.0.0 up to 8.0.2 - \li 2.0 up to 2.2 - \row - \li 6.0.x - \li 1.3 up to 2.2 - \row - \li 4.12.4 up to 5.0.3 - \li 1.3 up to 1.9 - \row - \li 4.12.2 or 4.12.3 - \li 1.2 - \row - \li 4.12.0 or 4.12.1 - \li 1.1 - \row - \li 4.11.x - \li 1.0 - \endtable + \sa {Configure projects for running}, {Enable and disable plugins}, + {MCUs}{How To: Develop for MCUs}, {Use project wizards}, + {Developing for MCUs} */ diff --git a/doc/qtcreator/src/overview/creator-only/creator-configuring.qdoc b/doc/qtcreator/src/overview/creator-only/creator-configuring.qdoc index 1a1c04edfe..b2ea02c128 100644 --- a/doc/qtcreator/src/overview/creator-only/creator-configuring.qdoc +++ b/doc/qtcreator/src/overview/creator-only/creator-configuring.qdoc @@ -22,10 +22,10 @@ Qt versions and compilers by adding the paths to them and by creating \l{glossary-buildandrun-kit}{kits} that use them. - To make \QC behave more like your favorite code editor or IDE, you can - change the settings for keyboard shortcuts, color schemes, generic - highlighting, code snippets, and version control systems. In addition, - you can enable and disable \QC features by managing plugins. + To make \QC behave more like your favorite code editor or IDE, + change the preferences for keyboard shortcuts, color schemes, generic + highlighting, code snippets, and version control systems. Manage plugins + to turn on and off \QC features. The following sections summarize the options that you have and point you to detailed information to help you specify any required settings and to make @@ -33,8 +33,8 @@ \section1 Checking Build and Run Settings - \QC is an integrated development environment (IDE) that you can use to - develop Qt applications. While you can use \QOI to install \QC, + \QC is an integrated development environment (IDE) for creating + applications. While you can use \QOI to install \QC, the stand-alone \QC installer never installs Qt or any Qt tools, such as qmake. To use \QC for Qt development, you also need to install a Qt version and a compiler. If you update the compiler version later, you @@ -45,9 +45,7 @@ available in \QC. If it does not, you must add the kits yourself to tell \QC where everything is. - To add kits, select \preferences > \uicontrol Kits > \uicontrol Add. - - For more information, see \l{Add kits}. + To add kits, go to \preferences > \uicontrol Kits and select \uicontrol Add. Each kit consists of a set of values that define one environment, such as a \l{glossary-device}{device}, compiler, and Qt version. If \preferences > @@ -57,48 +55,41 @@ If \uicontrol Auto-detected still does not show the Qt version, select \uicontrol {Add} to add it manually. - For more information, see \l{Add Qt versions}. - Also check that \preferences > \uicontrol Kits > \uicontrol {Compilers} shows your compiler. - For more information, see \l{Add compilers}. + Connect devices to the computer via USB to run, debug, and analyze + applications on them. You can connect Linux-based devices also + over a WLAN. Configure a connection between \QC and the computer, and + select the device in a kit. - You can connect devices to the development PC to run, debug, and - analyze applications on them from \QC. You can connect the device to the - development PC via USB. Additionally, you can connect Linux-based devices - over a WLAN. You must also configure a connection between \QC and the - development PC and specify the device in a kit. + To add devices, go to \preferences > \uicontrol Devices > + \uicontrol Devices and select \uicontrol Add. - To add devices, select \preferences > \uicontrol Devices > - \uicontrol Devices > \uicontrol Add. - - For more information, see \l{Connecting Devices}. + For more information, see \l{Manage Kits}{How To: Manage Kits} and + \l{Develop for Devices}{How To: Develop for Devices}. \section1 Changing Keyboard Shortcuts You can use \QC with your favorite keyboard shortcuts. - To view and edit all keyboard shortcuts defined in \QC, select - \preferences > - \uicontrol Environment > - \uicontrol Keyboard. For more information, see \l{Keyboard Shortcuts}. + To view and edit all keyboard shortcuts defined in \QC, go to \preferences > + \uicontrol Environment > \uicontrol Keyboard. For more information, see + \l{Keyboard Shortcuts}. \section1 Changing Color Schemes - Themes enable you to customize the appearance of the \QC UI: widgets, - colors, and icons. + Themes set the appearance of the \QC UI: widgets, colors, and icons. - To switch themes, select \preferences > \uicontrol Environment > - \uicontrol Interface, and then select a theme in the \uicontrol Theme field. + To switch themes, go to \preferences > \uicontrol Environment > + \uicontrol Interface and select a theme in \uicontrol Theme. - You can use the \QC text and code editors with your favorite color scheme - that defines how to highlight code elements and which background color to - use. You can select one of the predefined color schemes or create custom - ones. The color schemes apply to highlighting C++ files, QML files, and - generic files. + Use the \QC text and code editors with your favorite color scheme that sets + highlighting of code elements and the background color. Select one of the + predefined color schemes or create custom ones. The color schemes apply to + highlighting C++ files, QML files, and generic files. - To change the color scheme, select \preferences > + To change the color scheme, go to \preferences > \uicontrol {Text Editor} > \uicontrol {Font & Colors}. For more information, see \l{Change editor colors}. @@ -108,7 +99,7 @@ highlighting engine for Kate syntax definitions. \QC comes with most of the commonly used syntax files, and you can download additional files. - To download and use highlight definition files, select \preferences > + To download and use highlight definition files, go to \preferences > \uicontrol {Text Editor} > \uicontrol {Generic Highlighter}. For more information, see \l{Download highlight definitions}. @@ -117,10 +108,10 @@ As you write code, \QC suggests properties, IDs, and code snippets to complete the code. It lists context-sensitive suggestions for - the statement currently under your cursor. You can add, modify, and remove + the statement currently under your cursor. Add, modify, and remove snippets in the snippet editor. - To open the snippet editor, select \preferences > + To open the snippet editor, go to \preferences > \uicontrol {Text Editor} > \uicontrol Snippets. For more information, see \l{Snippets}. @@ -131,8 +122,7 @@ to configure the version control in any special way to make it work with \QC. - However, some configuration options are available and you can set them in - \preferences > + However, you can set some configuration options in \preferences > \uicontrol {Version Control} > \uicontrol General. For more information about the supported functions, see @@ -144,13 +134,15 @@ You can \l{Enable and disable plugins}{enable} disabled plugins if you need them and disable plugins you don't need. - You can \l{Install plugins}{download and install} more plugins from + \l{Install plugins}{Download and install} more plugins from \l{https://marketplace.qt.io/}{Qt Marketplace} or some other source, such as \l{https://github.com/}{GitHub}. - To enable and disable plugins, select \uicontrol Help > + To enable and disable plugins, go to \uicontrol Help > \uicontrol {About Plugins}. - To install plugins, select \uicontrol Help > \uicontrol {About Plugins} > - \uicontrol {Install Plugins}. + To install plugins, go to \uicontrol Help > \uicontrol {About Plugins} and + select \uicontrol {Install Plugins}. + + \sa {Install \QC}, {Reset \QC settings}, {Preferences} */ diff --git a/doc/qtcreator/src/overview/creator-only/creator-deployment-overview.qdoc b/doc/qtcreator/src/overview/creator-only/creator-deployment-overview.qdoc deleted file mode 100644 index 000017249a..0000000000 --- a/doc/qtcreator/src/overview/creator-only/creator-deployment-overview.qdoc +++ /dev/null @@ -1,49 +0,0 @@ -// Copyright (C) 2020 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-running-targets.html - \page creator-deployment.html - \nextpage creator-deploying-android.html - - \title Deploying to Devices - - Deploy configurations in the \uicontrol Projects mode - \uicontrol {Run Settings} handle the packaging of the application as an - executable and copying it to a location you want to run the executable at. - The files can be copied to a location in the file system of the development - PC or a \l{glossary-device}{device}. - - \list - - \li \l{Deploying to Android} - - When you deploy the application to an Android device, \QC copies - the application files to the device. In addition, you can determine - the Qt libraries to use. - - \li \l {Deploying to Boot2Qt} - - When you deploy the application to a Boot2Qt device, \QC copies - the application files to the connected device. You can then test - and debug the application on the device with \QC. - - \li \l{Deploying to QNX Neutrino} - - When you deploy the application to a QNX Neutrino device, \QC copies - the application files to the connected device. You can then test and - debug the application on the device with \QC. - - \li \l{Deploying to Remote Linux} - - When you deploy the application to a generic Linux-based device, \QC - copies the application files to the connected device. You can then - test and debug the application on the device with \QC. - \endlist -*/ diff --git a/doc/qtcreator/src/overview/creator-only/creator-desktop-platforms.qdoc b/doc/qtcreator/src/overview/creator-only/creator-desktop-platforms.qdoc index 67605429f8..6a2602b34d 100644 --- a/doc/qtcreator/src/overview/creator-only/creator-desktop-platforms.qdoc +++ b/doc/qtcreator/src/overview/creator-only/creator-desktop-platforms.qdoc @@ -45,8 +45,7 @@ \li libxft-dev \li libxi-dev \li libxrandr-dev - \li libgl-dev and libglu-dev if you use Qt OpenGL (deprecated - in Qt 5) or Qt GUI OpenGL functions + \li libgl-dev and libglu-dev if you use Qt GUI OpenGL functions \endlist \section1 macOS diff --git a/doc/qtcreator/src/overview/creator-only/creator-getting-started.qdoc b/doc/qtcreator/src/overview/creator-only/creator-getting-started.qdoc index b1531ae685..e735c95adf 100644 --- a/doc/qtcreator/src/overview/creator-only/creator-getting-started.qdoc +++ b/doc/qtcreator/src/overview/creator-only/creator-getting-started.qdoc @@ -14,8 +14,9 @@ \title Getting Started - To learn the basics of \QC, take the \e {Getting Started with Qt Creator} - course in \l{https://www.qt.io/courses/}{Qt Learning}. + To learn the basics of \QC, take the + \l{https://www.qt.io/academy/course-catalog#getting-started-with-qt-creator} + {Getting Started with Qt Creator} course in Qt Academy. For more information about installing \QC, see \l{Install \QC}. diff --git a/doc/qtcreator/src/overview/creator-only/creator-glossary.qdoc b/doc/qtcreator/src/overview/creator-only/creator-glossary.qdoc index ac5e1cae6b..2cbac901aa 100644 --- a/doc/qtcreator/src/overview/creator-only/creator-glossary.qdoc +++ b/doc/qtcreator/src/overview/creator-only/creator-glossary.qdoc @@ -77,7 +77,7 @@ \li \QC groups build and run specific settings as kits to make cross-platform development easier. Each kit consists of a set of values that define one environment, such as a \e {device}, - tool chain, Qt version, and debugger command to use. Configure kits at + toolchain, Qt version, and debugger command to use. Configure kits at \preferences > \uicontrol Kits. \row diff --git a/doc/qtcreator/src/overview/creator-only/creator-issues.qdoc b/doc/qtcreator/src/overview/creator-only/creator-issues.qdoc index de7c8b45d3..8d31098332 100644 --- a/doc/qtcreator/src/overview/creator-only/creator-issues.qdoc +++ b/doc/qtcreator/src/overview/creator-only/creator-issues.qdoc @@ -41,7 +41,7 @@ settings are stored locally. \li The Okteta KDE custom widget plugin might be installed as part of - some Linux distributions. It can cause Qt Designer to crash. For + some Linux distributions. It can cause \QD to crash. For more information, see: \list diff --git a/doc/qtcreator/src/overview/creator-only/creator-mobile-platforms.qdoc b/doc/qtcreator/src/overview/creator-only/creator-mobile-platforms.qdoc deleted file mode 100644 index fef448c3f1..0000000000 --- a/doc/qtcreator/src/overview/creator-only/creator-mobile-platforms.qdoc +++ /dev/null @@ -1,73 +0,0 @@ -// Copyright (C) 2022 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! - \page creator-mobile-platforms.html - \previouspage creator-reference.html - - \ingroup creator-reference-platforms - - \title Mobile Platforms - - \brief Mobile platforms that you can develop applications for. - - You can develop applications for the following mobile platforms: - - \list - \li \l Android - \li \l iOS - \endlist - - You must install the tool chain for building applications for the targeted - mobile platform on the development PC and use \QMT to - install Qt libraries that are built for the platform. You can then add a - \l{glossary-buildandrun-kit}{kit} with the tool chain and the Qt version - for the device's architecture. When possible, \QMT creates - suitable kits for you. - - You can connect mobile devices to the development PC and select the - appropriate kit to build, run, debug, and analyze applications from \QC. - - Before starting application development, analyze and define the requirements, - scope, and functionality of the application to ensure efficient functionality - and a smooth user experience on mobile devices. - - \section1 Android - - Starting from Qt 5.14.0, the Qt for Android package has all the - architectures (ABIs) installed as one. You can let \QC automatically - create kits for installed Qt version and tool chains. - - The following topics have more information about developing applications - for Android devices: - - \list - \li \l{Connecting Android Devices} - \li \l{Deploying to Android} - \li \l{Run on many platforms} - \li \l{Creating a Mobile Application} - \li \l{Debugging on Android Devices} - \li \l{Qt for Android} - \endlist - - \section1 iOS - - \note Deployment, running, and debugging on iOS 17 devices are not supported. - - To be able to use \QC on \macos, you must install Xcode, and therefore - you should already have the tool chain for building applications for - iOS. \QC automatically detects the tool chain and creates the necessary - kits to build applications for and run them on configured iOS devices. - - The following topics have more information about developing applications - for iOS devices: - - \list - \li \l{Connecting iOS Devices} - \li \l{Run on many platforms} - \li \l{Creating a Mobile Application} - \li \l{Qt for iOS} - \endlist - - \sa {Optimizing Applications for Mobile Devices}, {Supported Platforms} -*/ diff --git a/doc/qtcreator/src/overview/creator-only/creator-mobile-targets.qdoc b/doc/qtcreator/src/overview/creator-only/creator-mobile-targets.qdoc deleted file mode 100644 index fc33900659..0000000000 --- a/doc/qtcreator/src/overview/creator-only/creator-mobile-targets.qdoc +++ /dev/null @@ -1,85 +0,0 @@ -// Copyright (C) 2022 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. -// ********************************************************************** - -/*! - \page creator-connecting-mobile.html - \previouspage creator-deployment-embedded-linux.html - \nextpage creator-developing-android.html - - \title Connecting Devices - - You can connect \l{glossary-device}{devices} to the development PC to run, debug, - and analyze applications built for them from \QC. When you install Qt for a - target platform, such as Android or QNX, - the build and run settings for the development targets might be set up - automatically in \QC. - - You can connect the device to the development PC using a USB connection. - Additionally, you can connect Linux-based devices by using a WLAN - connection. - - The experimental WebAssembly plugin enables you to build your applications - in WebAssembly format, to deploy them, and to run them in a web browser. - - \list - - \li \l{Connecting Android Devices} - - Qt applications for Android are compiled as \c {shared objects} that - are loaded by a Java launcher that is part of Qt. - This is totally transparent to users. As Qt is composed of libraries - referencing each other, Qt 5 applications are only supported on - Android version 4.1 (API level 16), or later, and Qt 6 applications - on Android version 6.0 (API level 23), or later. You must install a - Qt version targeting Android and the Android SDK and NDK to develop - for Android devices. - - \li \l{Connecting Bare Metal Devices} - - You can connect bare metal devices to the development PC and use \QC - to debug applications on them with GDB or a hardware debugger. - - \li \l{Connecting Boot2Qt Devices} - - You can connect \l{Boot2Qt} devices to the development PC to run, - debug, and analyze applications built for them from \QC. - - \li \l {Adding Docker Devices} - - Create Docker devices from Docker images and use them to build, run, - and debug applications from \QC. - - \li \l{Connecting iOS Devices} - - You use the tools delivered with Xcode to connect devices to \QC. - \QC detects the tools and configured devices automatically and uses - the tools to build, deploy, and run applications. - - \li \l{Connecting MCUs} - - You can connect MCU boards to a development host to deploy, run, and - debug applications on them from \QC. - - \li \l{Connecting QNX Devices} - - You can connect QNX devices to the development PC to deploy, run and - debug applications on them from within \QC. This is currently only - supported for QNX Neutrino devices, and requires the QNX SDK to be - installed on the development PC. - - \li \l{Connecting Remote Linux Devices} - - If you have a tool chain for building applications for embedded - Linux devices installed on the development - PC, you can add it and the device to \QC. - - \endlist - - \sa {Building Applications for the Web}, {Run in Qt Application Manager} -*/ diff --git a/doc/qtcreator/src/overview/creator-only/creator-overview.qdoc b/doc/qtcreator/src/overview/creator-only/creator-overview.qdoc index b164224e84..127a59cf0d 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}. @@ -186,35 +191,66 @@ build the project. Build applications for, deploy them to, and run them on the desktop - environment or a device. With kits, as well as build, run, and deployment + environment or a device. With kits, as well as build, deploy, and run configurations, you can quickly switch between different setups and target platforms. For more information, see \l{Build and Run}{How To: Build and Run}, \l{Build Systems}, \l{Build Configurations}, and \l{Run Configurations}. - \section2 On Devices + \section2 Embedded Platforms + + You can develop applications for the following embedded platforms: + + \list + \li \l {Bare Metal} + \li \l {\B2Q} + \li \l {MCUs} + \li \l {QNX Neutrino} + \li \l {Remote Linux} + \endlist - When you install tool chains for device types as part of a Qt distribution, - the build and run configurations 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 computer. + Install the toolchain for building applications for the targeted + embedded platform on the computer, and then use \QOI to install Qt + libraries that are built for the platform. Add a kit with the toolchain and + the Qt version for the device's architecture. When possible, \QOI creates + suitable kits for you. - Deployment configurations handle the packaging and copying of the necessary + You can connect embedded devices to the computer and select the appropriate + kit to run, debug, and analyze applications built for them from \QC. + + \e {Deploy configurations} handle the packaging and copying of the necessary files to a location you want to run the executable at, such as the file system of a device. - For more information, see \l{Connecting Devices} and \l{Deploying to Devices}. + For more information, see \l{Develop for Devices}{How To: Develop for Devices} + and \l{Devices}. - \section2 Previewing QML + \section2 Mobile Platforms - 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. + You can develop applications for the following mobile platforms: - For more information, see \l{Validating with Target Hardware}. + \list + \li \l Android + \li \l iOS + \endlist + + Install the toolchain for building applications for the targeted mobile + platform on the computer, and then use \QOI to install Qt libraries that are + built for the platform. Add a kit with the toolchain and the Qt version for + the device's architecture. When possible, \QOI creates suitable kits for you. + + You can connect mobile devices to the computer and select the + appropriate kit to build, run, debug, and analyze applications from \QC. + + Before starting application development, analyze and define the requirements, + scope, and functionality of the application to ensure efficient functionality + and a smooth user experience on mobile devices. + + For more information, see + \l{Develop for Devices}{How To: Develop for Devices}, + \l{Optimizing Applications for Mobile Devices}, \l {Supported Platforms}, and + \l{Deploy Configurations}. \section1 Debugging Applications @@ -230,7 +266,7 @@ to find the next one. \endlist - \QC integrates several external native debuggers for inspecting the state of + \QC integrates several native debuggers for inspecting the state of your application while debugging. The debugger plugin automatically selects a suitable native debugger for each kit from the ones it finds on the computer. Edit the kits to override this choice. @@ -242,20 +278,20 @@ Connect devices to your computer to debug processes running on the devices. - For more information, see \l{Debugging}. + For more information, see \l{Debugging} and \l{Debug}{How To: Debug}. - \section1 Analyzing Source Code + \section1 Finding Issues in Source Code Devices have limited memory and CPU power, so you should use them carefully. \QC integrates code analysis tools for detecting memory leaks, profiling function execution, analyzing CPU use, and eliminating unnecessary complexity of code. Other tools provide code coverage and visualize trace events. - Install and configure the tools on your system to use them from \QC. - However, the QML Profiler is installed as part of \QC for profiling - Qt Quick applications. + Some tools, such as QML Profiler and Clang Tools, are installed with + \QC. Install and configure the other supported tools on the computer to use + them from \QC. - For more information, see \l{Analyzing Code}. + For more information, see \l{Analyzing Code} and \l{Analyze}{How To: Analyze}. \section1 Running Tests @@ -287,10 +323,32 @@ \image qtcreator-autotests.png - Map AUTs (Application Under Test) to \QC and run Squish test suites - and cases from it. + \section2 Using Squish + + \brief The experimental Squish plugin integrates Squish into \QC. + + \l{https://www.qt.io/product/quality-assurance/squish}{Squish} is an + automated GUI testing framework for testing Android, iOS, Java, \macos, + Qt, Tk, Windows, and XView applications, as well as HTML-based web + applications running in browsers. + + In \QC, you can: + + \list + \li Open existing Squish test suites. + \li Create new test suites and test cases. + \li Record test cases (in a very limited way compared to what you can do + inside the Squish IDE). + \li Use Squish Runner and Server to run test suites or cases and view + the results in the \uicontrol Squish \l{View output}{output}. + \li Set breakpoints before running tests to stop at certain locations and + inspect the local variables, similarly to when debugging a test. + \endlist + + To use the plugin, you must download and install Squish, create a connection + to the Squish Server, and specify the application under test (AUT) to run. - For more information, see \l{Test}{How To: Test} and \l{Using Squish}. + For more information, see \l{Test}{How To: Test}. \section1 Publishing Applications diff --git a/doc/qtcreator/src/overview/creator-only/creator-reference.qdoc b/doc/qtcreator/src/overview/creator-only/creator-reference.qdoc index 45432f561b..7415815ff0 100644 --- a/doc/qtcreator/src/overview/creator-only/creator-reference.qdoc +++ b/doc/qtcreator/src/overview/creator-only/creator-reference.qdoc @@ -19,6 +19,20 @@ \annotatedlist creator-reference-analyzer + \section1 Debuggers + + Set up and use native debuggers to debug executable binary files, as well as + QML, Java, and Python source code. + + \annotatedlist creator-reference-debugger + + \section2 Debugger Views + + Inspect the state of your application while debugging in the + \uicontrol Debug mode. + + \annotatedlist creator-reference-debugger-views + \section1 Build Systems When you create projects, you can choose the build system to use for @@ -28,7 +42,7 @@ \annotatedlist creator-reference-build-systems - \section1 Build Configurations + \section2 Build Configurations Build configurations have everything you need to compile the sources into binaries. Build configurations use the tools and settings defined in their @@ -36,6 +50,35 @@ \annotatedlist creator-reference-build-configurations + \section1 Devices + + Connect devices to the computer to run, debug, and analyze applications + built for them from \QC. When you install Qt for a target platform, such + as Android or QNX, the build and run configurations for the development + targets might be set up automatically in \QC. + + \annotatedlist creator-reference-devices + + \section2 Deploy Configurations + + Deploy configurations handle the packaging of the application as an + executable and copying it to a location you want to run the executable at. + The files can be copied to a location in the file system of the computer + or a device. + + \annotatedlist creator-reference-deploy-configurations + + \section2 Run Configurations + + Run configurations start the application in the location where the + deploy configuration copied it. By default, when you select + \uicontrol Run, \QC builds the project, deploys it to the device + defined in the kit, and runs it there. If you did not make changes + to the project since you last built and deployed it, \QC simply runs + it again. + + \annotatedlist creator-reference-run-configurations + \section1 Editors When you open files, \QC chooses a suitable editor according to the file @@ -69,6 +112,10 @@ \annotatedlist creator-reference-preferences-cpp + \section2 Debugger + + \annotatedlist creator-reference-preferences-debugger + \section2 Kits Preferences for build and run kits. @@ -81,17 +128,6 @@ \annotatedlist creator-reference-preferences-text-editor - \section1 Run Configurations - - Run configurations start the application in the location where the - \e {deploy configuration} copied it. By default, when you select - \uicontrol Run, \QC builds the project, deploys it to the device - defined in the kit, and runs it there. If you did not make changes - to the project since you last built and deployed it, \QC simply runs - it again. - - \annotatedlist creator-reference-run-configurations - \section1 UI Design You can use a visual editor, \QD, for designing widget-based UIs diff --git a/doc/qtcreator/src/overview/creator-only/creator-supported-platforms.qdoc b/doc/qtcreator/src/overview/creator-only/creator-supported-platforms.qdoc index 9481519eb7..43c60144c4 100644 --- a/doc/qtcreator/src/overview/creator-only/creator-supported-platforms.qdoc +++ b/doc/qtcreator/src/overview/creator-only/creator-supported-platforms.qdoc @@ -38,12 +38,7 @@ \li \image ok.png \li \image ok.png \row - \li \l Boot2Qt - \li \image ok.png - \li \image ok.png - \li \image ok.png - \row - \li \l{Remote Linux} + \li \l {\B2Q} \li \image ok.png \li \image ok.png \li \image ok.png @@ -53,7 +48,7 @@ \li \image ok.png \li \row - \li \l{Microcontroller Units (MCU)}{MCUs} + \li \l{MCUs} \li \image ok.png \li \li \image ok.png @@ -63,7 +58,12 @@ \li \image ok.png \li \inlineimage ok.png \row - \li \l{Building Applications for the Web}{WebAssembly} + \li \l{Remote Linux} + \li \image ok.png + \li \image ok.png + \li \image ok.png + \row + \li \l{Build applications for the web}{WebAssembly} \li \image ok.png \li \image ok.png \li \image ok.png @@ -74,5 +74,6 @@ \QC automatically runs scheduled checks for updates based on the settings specified in \preferences > \uicontrol Environment > \uicontrol Update. - \sa {Desktop Platforms}, {Embedded Platforms}, {Mobile Platforms} + \sa {Develop for Devices}{How To: Develop for Devices}, {Desktop Platforms}, + {Devices} */ diff --git a/doc/qtcreator/src/projects/creator-only/creator-build-settings-qmake.qdoc b/doc/qtcreator/src/projects/creator-only/creator-build-settings-qmake.qdoc index 3f24273f09..78eb3ecf68 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-build-settings-qmake.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-build-settings-qmake.qdoc @@ -51,7 +51,7 @@ If debug info is being generated, you can have it placed into separate files, rather than embedded into the binary, by selecting \uicontrol Enable in the \uicontrol {Separate debug info} field. For - more information, see \l{Using the Performance Analyzer}. To use default + more information, see \l{Analyze CPU usage}. To use default settings, select \uicontrol {Leave at Default}. \section1 Compiling QML diff --git a/doc/qtcreator/src/projects/creator-only/creator-how-to-add-wizards.qdoc b/doc/qtcreator/src/projects/creator-only/creator-how-to-add-wizards.qdoc index fa7663f02d..e6cb582b9b 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-how-to-add-wizards.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-how-to-add-wizards.qdoc @@ -44,5 +44,5 @@ to specify the position of the wizard. For example, \c B.MyClass. \endlist -\sa {Custom Wizards}, {Find settings files} + \sa {Run Qt Creator from the command line}, {Custom Wizards} */ diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-build-run-tutorial.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-build-run-tutorial.qdoc index ac06f8cbd1..600b8f3079 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-build-run-tutorial.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-build-run-tutorial.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // ********************************************************************** @@ -23,13 +23,12 @@ To run an example application on an Android or iOS device, you must set up the development environment for Android or iOS. For more information, see - \l{Connecting Android Devices} and \l{Connecting iOS Devices}. + \l{Developing for Android} and \l{Developing for iOS}. - To run an example application on a Boot2Qt device, you must set up - Boot2Qt on the development host and create connections + To run an example application on a \B2Q device, you must set up + \B2Q on the development host and create connections between the host and devices. For more information, see - \l{https://doc.qt.io/Boot2Qt/b2qt-installation-guides.html} - {Boot2Qt: Installation Guides} + \l{\B2Q: Documentation}. If you have \l{Qt Design Studio Manual}{\QDS} installed, you can open \QDS examples from \QC in \QDS. @@ -48,13 +47,20 @@ \li Select an example in the list of examples. You can also use tags (3) to filter examples. For instance, enter - the \uicontrol Boot2Qt tag (commercial only) in the search field - (4) to list examples that you can run on Boot2Qt devices. + the \uicontrol \B2Q tag (commercial only) in the search field + (4) to list examples that you can run on \B2Q devices. + + \li In \uicontrol {Configure Project}, select + \l{glossary-buildandrun-kit}{kits} for building the example for the + target platforms. + + \image qtcreator-configure-project.webp {Configure Project view} + + \li Select \uicontrol {Configure Project}. \li To check that you can compile and link the application code for a - device, click the \uicontrol {Kit Selector} and select a - \l{glossary-buildandrun-kit}{kit} for the - device. + device, click the \uicontrol {Kit Selector} and select the kit for + the device. \image qtcreator-examples-kit-selector.webp {Selecting a kit to build with} @@ -62,7 +68,7 @@ automatically detected the installed kit. If you cannot see any kits, see \l{Add kits}. - \li Click \inlineimage icons/run_small.png + \li Select \inlineimage icons/run_small.png (\uicontrol Run) to build and run the application. \li To see the compilation progress, press \key{Alt+4} to open @@ -70,9 +76,8 @@ If build errors occur, check that you have a Qt version, a \l{Add compilers}{compiler}, and the necessary kits installed. If - you are building for an \l{Connecting Android Devices}{Android device} - or \l{Connecting iOS Devices}{iOS device}, check that you set up the - development environment correctly. + you are building for an Android or iOS device, check that you set up + the development environment correctly. The \uicontrol Build progress bar on the toolbar turns green when you build the project successfully. The application opens on the @@ -80,4 +85,7 @@ \endlist + \sa {Manage Kits}{How To: Manage Kits}, {Open projects}, + {Developing for Android}, {Developing for iOS}, + {Compile Output}, {\B2Q: Documentation}, {Qt Design Studio Manual} */ 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 bd4743a437..0000000000 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-building-running.qdoc +++ /dev/null @@ -1,50 +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{Deploying to Devices} - - \e {Deploy configurations} handle the packaging and copying of - the necessary files to a location you want to run the executable - at. The files can be copied to a location in the file system of - the development PC or a device. - - \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/projects/creator-only/creator-projects-building.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-building.qdoc index d42df965a7..7cfb8f86e0 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-building.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-building.qdoc @@ -36,7 +36,7 @@ \li Select the \uicontrol {Build and Run Kit Selector} icon or go to \uicontrol Build > \uicontrol {Open Build and Run Kit Selector} to select the build and run \l{glossary-buildandrun-kit}{kit} or an - \l{Managing Android Virtual Devices (AVD)}{Android device}. + \l{Manage AVDs}{Android device}. \image qtcreator-kit-selector.webp {Kit selector} @@ -105,7 +105,7 @@ \uicontrol Projects view. \sa {Configure projects for building}, {Build and Run}{How To: Build and Run}, - {Adding Docker Devices}, {Specifying Build Settings} + {Add Docker devices}, {Specifying Build Settings} */ /*! diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-compilers.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-compilers.qdoc index d92e8c90a4..42cc51bef9 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-compilers.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-compilers.qdoc @@ -103,8 +103,8 @@ \li Other than the listed compilers and remote compilers. \endtable - The emscripten compiler is tool chain for compiling to - \l{Building Applications for the Web}{WebAssembly}. + The emscripten compiler is toolchain for compiling to + \l{Build applications for the web}{WebAssembly}. \section2 Bare-metal compilers @@ -145,10 +145,10 @@ \endcode If these commands show paths, they have been added to the global PATH - variable during the installation of a tool chain based on Cygwin or \MinGW, + variable during the installation of a toolchain based on Cygwin or \MinGW, even though this is against Windows conventions. - To keep working with the third-party tool chain, create a new shell link + To keep working with the third-party toolchain, create a new shell link that adds the required paths (as Visual Studio and Qt do). The shell link must point to cmd.exe: @@ -157,19 +157,19 @@ where the /K parameter carries out the command specified in the bat file. Create the myenv.bat file at \e path_to, which should be in a convenient - location. In the file, specify the paths to the tool chains. For example, + location. In the file, specify the paths to the toolchains. For example, \c {set PATH=C:\path1;C:\path2;%PATH%} - where \e path1 and \e path2 are paths to the tool chains. + where \e path1 and \e path2 are paths to the toolchains. Finally, remove the paths from the global PATH, reboot the computer, and run the \c where commands again to verify that the global PATH is now clean. - You can use the shell link to run the tools in the third-party tool chains. + You can use the shell link to run the tools in the third-party toolchains. \sa {Compilers}, {Add Nim compilers}, {Add custom compilers}, - {Connecting Bare Metal Devices}, {Supported Platforms} + {Developing for Bare Metal Devices}, {Supported Platforms} */ /*! diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-creating.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-creating.qdoc index f91d6e2b0c..5388f7c6e5 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-creating.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-creating.qdoc @@ -45,7 +45,7 @@ \uicontrol {New File} dialogs you can see an icon (1), a display name (2), and a description (3) of the wizard. - \image qtcreator-custom-wizard.png {Wizard details in the New Project dialog} + \image qtcreator-custom-wizard.webp {Wizard details in the New File dialog} In most project wizards, you can choose the build system to use for building the project: qmake, CMake, Qbs, and possibly others, depending on @@ -66,7 +66,7 @@ The installers create \l{glossary-buildandrun-kit}{kits} and specify build and run settings for the installed device types. However, you might need to install and configure some additional software on the devices to be able to - \l{Connecting Devices}{connect} to them from the development PC. + \l{Develop for Devices}{connect} to them from the computer. \sa {Manage Projects}{How To: Manage Projects}, {Custom Wizards} */ @@ -146,7 +146,7 @@ launcher for debugging and analysis tools. \row \li Squish - \li Create new \l {Using Squish}{Squish test suites}. + \li Create new Squish test suites. \endtable diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-custom-wizards-json.qdocinc b/doc/qtcreator/src/projects/creator-only/creator-projects-custom-wizards-json.qdocinc index c2d2fe9e2d..f2d8d25424 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-custom-wizards-json.qdocinc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-custom-wizards-json.qdocinc @@ -238,7 +238,7 @@ { "key": "CN", "value": "%{JS: Cpp.className(value('Class'))}" }, { "key": "Base", "value": "%{JS: value('BaseCB') === '' ? value('BaseEdit') : value('BaseCB')}" }, { "key": "isQObject", "value": "%{JS: (value('Base') === 'QObject' || value('Base') === 'QWidget' || value('Base') === 'QMainWindow' || value('Base') === 'QQuickItem' ) ? 'true' : 'false'}" }, - { "key": "GUARD", "value": "%{JS: Cpp.classToHeaderGuard(value('Class'), Util.suffix(value('HdrFileName'))}" }, + { "key": "GUARD", "value": "%{JS: Cpp.headerGuard(value('HdrFileName'))}" }, { "key": "SharedDataInit", "value": "%{JS: value('IncludeQSharedData') ? 'data(new %{CN}Data)' : '' }" } ], \endcode diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-custom-wizards.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-custom-wizards.qdoc index 3abd3a1ab6..f4d7c81e63 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-custom-wizards.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-custom-wizards.qdoc @@ -45,7 +45,7 @@ and \uicontrol {New File} dialogs. For each wizard, it shows an icon (1), a display name (2), and a description (3). - \image qtcreator-custom-wizard.png + \image qtcreator-custom-wizard.webp {New File wizard} \section1 Wizard Types diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-debuggers.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-debuggers.qdoc index 8762a9e97b..59db592705 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-debuggers.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-debuggers.qdoc @@ -75,5 +75,6 @@ The debugger disappears from the list when you select \uicontrol Apply. Until then, you can cancel the deletion by clicking \uicontrol Restore. - \sa {Debugging}, {Setting Up Debugger}, {Troubleshooting Debugger} + \sa {Debugging}, {Debuggers}, {Debugger}, {Supported Native Debuggers}, + {Troubleshooting Debugger} */ diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-generic.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-generic.qdoc index e4e682d2a6..2a57fcfaac 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-generic.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-generic.qdoc @@ -125,7 +125,7 @@ you first need to deploy your executable and possibly other files. \QC does that for you automatically if you enter the necessary information. This works the same way as explained for CMake in - \l {Deploying to Remote Linux}, + \l {Remote Linux Deploy Configuration}, except that you also need to include your application binary in the list. \section1 Create a run configuration diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-kits.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-kits.qdoc index 4d0e903863..1e2b8ed818 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-kits.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-kits.qdoc @@ -25,18 +25,16 @@ You can add kits for the desktop and for the following types of devices: \list - \li \l{Connecting Android Devices}{Android} - \li \l{Connecting Bare Metal Devices}{Bare Metal} - \li \l{https://doc.qt.io/Boot2Qt/b2qt-installation-guides.html} - {Boot2Qt} (commercial only) - \li \l{Emulator}{Boot2Qt Emulator} (commercial only) - \li \l{Adding Docker Devices}{Docker} (experimental) - \li \l{Connecting iOS Devices}{iOS} + \li \l{Developing for Android}{Android} + \li \l{Developing for Bare Metal Devices}{Bare Metal} + \li \l{\B2Q: Documentation}{\B2Q} (commercial only) + \li \l{Add Docker devices}{Docker} (experimental) + \li \l{Developing for iOS}{iOS} \li iOS Simulator - \li \l{Connecting MCUs}{MCU} (commercial only) - \li \l{Connecting QNX Devices}{QNX} - \li \l{Connecting Remote Linux Devices}{Remote Linux} - \li \l{Building Applications for the Web}{WebAssembly Runtime} + \li \l{Developing for MCUs}{MCU} (commercial only) + \li \l{Add a QNX Neutrino device}{QNX} + \li \l{Developing for Remote Linux Devices}{Remote Linux} + \li \l{Build applications for the web}{WebAssembly Runtime} \endlist To add kits: @@ -74,7 +72,7 @@ \title Kits \brief Set kit preferences. A kit consists of a set of values that define - one environment, such as a \e {device}, tool chain, Qt version, and debugger + one environment, such as a \e {device}, toolchain, Qt version, and debugger command to use. Typically, only a subset of the kit preferences is relevant for a particular @@ -136,7 +134,7 @@ cross-compiling, leave this field empty. \row \li \uicontrol {Emulator skin} - \li Skin to use for the \l {Emulator}{Boot2Qt Emulator Device}. + \li Skin to use for the \l {Emulator}{\B2Q Emulator Device}. \row \li \uicontrol {Compiler} \li C or C++ compiler that you use to build the project. You can add @@ -147,6 +145,9 @@ This setting is used to tell the code model which compiler is used. If your project type and build tool support it, \QC also tells the build tool to use this compiler for building the project. + + \note qmake ignores the value of this field and fetches the compiler + information from \uicontrol {Qt mkspec}, which you can change. \row \li \uicontrol Environment \li Select \uicontrol Change to modify environment variable values for diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-opening.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-opening.qdoc index f631e67389..66b69a573f 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-opening.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-opening.qdoc @@ -63,15 +63,15 @@ To re-configure projects: \list 1 - \li In the \uicontrol {Configure Project} tab, select + \li In \uicontrol {Configure Project}, select \l{glossary-buildandrun-kit}{kits} for building and running your project. - \image qtcreator-open-project-kits.png {Configure Project tab} + \image qtcreator-configure-project.webp {Configure Project view} \li Select \uicontrol {Configure Project}. \endlist - The \uicontrol {Configure Project} tab displays a list of kits that you - install on the development PC and configure in \preferences > \uicontrol Kits. + \uicontrol {Configure Project} shows a list of kits that you + install on the computer and configure in \preferences > \uicontrol Kits. Even if you do not intend to build the project, the C++ and QML code models need a Qt version and compiler to offer code completion. To specify them, diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-qt-versions.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-qt-versions.qdoc index 0b06e1d84c..48958f8846 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-qt-versions.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-qt-versions.qdoc @@ -108,28 +108,45 @@ To verify the installation of a particular Qt version, \QC calls \c {qmake -query} and checks that the directories referenced in the - output exist. When \QC complains about the installation of a self-built Qt - version, try running \c {make install} in the build directory to actually - install Qt into the configured location. If you installed Qt using the Qt - Installer, run \QMT to check for updates or to reinstall - the Qt version. + output exist. If you installed Qt using \QOI, run + \QMT to check for updates or to reinstall the Qt version. - \section1 Minimum requirements - If your build of Qt is incomplete but you still want to use qmake as build - system, you need to ensure the following minimum requirements to use that - setup with \QC. + \section2 Self-built Qt versions - \list 1 + To build projects with a self-built Qt version, add it as described in + \l{Set up new Qt versions}. + + Your Qt has to meet the following minimum requirements: + + \list \li qmake is an executable that understands the \c -query command-line argument. \li The \c bin and \c include directories have to exist. \QC fetches these directories by running \c{qmake -query}. - \li The \c mkspecs directory should be complete enough to parse .pro - files. \endlist - If your Qt version has no \c libQtCore.so, \QC cannot detect the ABI. + Add a kit for the Qt version and configure it for CMake. + + \QC issues warnings if: + + \list + \li \c libQtCore.so is missing, so \QC cannot detect the ABI. + \li \c toolchain.cmake is missing. For example, you built Qt with the + \c -static option for an x86 platform. + \endlist + + Try the following: + + \list + \li Run \c {make install} in the build directory to install Qt into the + configured location. + \li Set the value of the \c CMAKE_PREFIX_PATH variable in \preferences > + \uicontrol Kits > \uicontrol Kits > \uicontrol {CMake Configuration} + to the location where you installed Qt. + \endlist + + \image qtcreator-edit-cmake-configuration-self-built-qt.webp {Setting the path to a self-built Qt} - \sa {kits-tab}{Kits} + \sa {Manage Kits}{How To: Manage Kits}, {kits-tab}{Kits} */ diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build-qbs.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build-qbs.qdoc index f1b08ac048..b177af0b8d 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build-qbs.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build-qbs.qdoc @@ -30,7 +30,7 @@ If debug info is being generated, you can have it placed into separate files, rather than embedded into the binary, by selecting \uicontrol Enable in the \uicontrol {Separate debug info} field. For - more information, see \l{Using the Performance Analyzer}. To use default + more information, see \l{Analyze CPU usage}. To use default settings, select \uicontrol {Leave at Default}. For more information about the QML debugging options, see @@ -59,7 +59,7 @@ \endlist \li In the \uicontrol ABIs field, select the ABIs for - the \l{Connecting Android Devices}{Android} device + the \l{Developing for Android}{Android} device architectures to build the project for. \li In the \uicontrol {Parallel jobs} field, specify the number of diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build.qdoc index 31bc8204d4..b3ababb5fb 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build.qdoc @@ -56,8 +56,8 @@ \section1 Build on remote devices - You can build applications on \l{Connecting Remote Linux Devices} - {remote Linux} or \l{Adding Docker Devices}{Docker} devices if you + You can build applications on \l{Developing for Remote Linux Devices} + {remote Linux} or \l{Add Docker devices}{Docker} devices if you have kits that specify the devices and toolchains to use. When the build device of the kit is a remote device, such as a remote Linux or Docker device, the \uicontrol Browse button next to the diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-environment.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-environment.qdoc index ce809fc536..db6aefeb64 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-environment.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-environment.qdoc @@ -141,6 +141,10 @@ Use the following syntax to enter environment variable names and values: \c {<VARIABLE>=<VALUE>}. + To temporarily disable a variable, add a hash character (#) to the beginning + of the line. + \note Using this approach for a different statement (append, prepend, unset) + may result in unexpected changes of the environment. To remove a variable value from the environment, enter the variable name. For example, \c TEST sets the value of the \c TEST variable empty when @@ -160,8 +164,8 @@ following lines. However, you can remove a value after you have referred to it on an earlier line. - To temporarily disable a variable, add a hash character (#) to the beginning - of the line. + To add a comment or disable any of the above actions, prefix it with two hash + characters (##). \sa {Specify the environment for projects}, {Configure projects for building}, {Configure projects for running}, {Use Qt Creator variables} diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-overview.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-overview.qdoc index 93510fa438..3f8e93f142 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-overview.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-overview.qdoc @@ -83,8 +83,9 @@ \list \li \l{Link projects to Axivion dashboards}{Axivion} \li \l{Specify clangd settings}{Clangd} - \li \l{Speficy Clang tools settings}{Clang Tools} + \li \l{Specify Clang tools settings}{Clang Tools} \li \l{Set Copilot preferences}{Copilot} + \li \l{Configure C++ code model}{C++ Code Model} \li \l{Specify code style}{C++ Code Style} \li \l{Set C++ file naming preferences}{C++ File Naming} \li \l{Specify dependencies}{Dependencies} @@ -132,7 +133,7 @@ Each kit consists of a set of values that define one environment, such as a \l{glossary-device}{device}, \l{Add compilers}{compiler}, - \l{Add debuggers}{debugger}, and \l{Add Qt versions}{Qt version}, as well + \l{Add debuggers}{Debugging}, and \l{Add Qt versions}{Qt version}, as well as steps for building, deploying, and running applications. To copy the build, deploy, and run steps from another kit, select diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-analyze.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-analyze.qdoc index 34233c90d8..99802a720b 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-analyze.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-analyze.qdoc @@ -13,8 +13,8 @@ you select for a kit in \uicontrol Projects > \uicontrol {Build & Run} > \uicontrol Run > \uicontrol {Run Settings}. - \QC integrates \l{Analyzing Code}{Valgrind code analysis tools} for - detecting memory leaks and profiling function execution. + With \l{Valgrind's Tool Suite}, you can detect memory leaks and profile + function execution. To specify Valgrind settings for the current project: @@ -38,11 +38,12 @@ \endlist - Click \uicontrol {Restore Global} to revert to the global settings. + Select \uicontrol {Restore Global} to revert to the global settings. To specify global Valgrind settings, select \preferences > \uicontrol Analyzer. - \sa {Configuring Projects}, {Selecting Options for Memory Analysis}, - {Selecting Profiling Options}, {Using Valgrind Code Analysis Tools} + \sa {Detect memory leaks with Memcheck}, {Profile function execution}, + {Run Valgrind tools on external applications}, {Configuring Projects}, + {Valgrind Callgrind}, {Valgrind Memcheck} */ diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-debug.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-debug.qdoc index 770478d5b6..b0609ab771 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-debug.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-debug.qdoc @@ -30,7 +30,7 @@ \list \li \l{Adding Custom Debugging Helpers}{Custom debugging helpers} - \li \l{Specifying GDB Settings}{GDB commands} to execute after GDB + \li \l{GDB}{GDB commands} to execute after GDB has started, but before the debugged program is started or attached, and before the debugging helpers are initialized \endlist @@ -42,5 +42,5 @@ {enable QML debugging} either globally or in the \uicontrol {Build Settings} of the project. - \sa {Configuring Projects}, {Debugging} + \sa {Configuring Projects}, {Debugging}, {Debuggers}, {Debugger} */ diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-desktop.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-desktop.qdoc index 01458baf26..72085701e1 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-desktop.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-desktop.qdoc @@ -32,10 +32,10 @@ \section1 Run in Terminal - For console applications, check the \uicontrol{Run in terminal} check box. - To specify the terminal to use on Linux and \macos, select \preferences > + For console applications, select \uicontrol{Run in terminal}. + To specify the terminal to use on Linux and \macos, go to \preferences > \uicontrol Environment > \uicontrol System. To use an \l{Terminal} - {internal terminal}, select \preferences > \uicontrol Terminal > + {internal terminal}, go to \preferences > \uicontrol Terminal > \uicontrol {Use internal terminal}. \section1 Linker Libraries @@ -48,22 +48,21 @@ \c {make install}, and want to make sure that the deployed application will find the libraries also when it is run without \QC. - To disable library linking for the current project, deselect the - \uicontrol {Add build library search path to PATH} check box. To disable - library linking for all projects, select \preferences > - \uicontrol {Build & Run}, and then deselect the - \uicontrol {Add linker library search paths to run environment} check box. + To disable library linking for the current project, clear + \uicontrol {Add build library search path to PATH}. To disable + library linking for all projects, go to \preferences > + \uicontrol {Build & Run} and then clear + \uicontrol {Add linker library search paths to run environment}. - \section1 \macos Options + \section1 Debugging Linked Frameworks - The \uicontrol {Use debug version of frameworks (DYLD_IMAGE_SUFFIX=_debug)} option - (only available on \macos) enables you to debug (for example, step into) - linked frameworks, such as the Qt framework itself. You do not need this - option for debugging your application code. + On \macos, select \uicontrol {Use debug version of frameworks (DYLD_IMAGE_SUFFIX=_debug)} + to debug (for example, step into) linked frameworks, such as the Qt framework + itself. You do not need this option for debugging your application code. - \section1 Linux Options + \section1 Running as root User - On Linux, select the \uicontrol {Run as root user} check box to run the + On Linux and \macos, select \uicontrol {Run as root user} to run the application with root user permissions. \sa {Configure projects for running}, {Specify a custom executable to run}, diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run.qdoc index 7f8ba6894b..bf816f4351 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run.qdoc @@ -27,7 +27,7 @@ \list \li \l {Android Run Settings}{Android} - \li \l {Boot2Qt Run Settings}{Boot2Qt} + \li \l {\B2Q Run Settings}{\B2Q} \li \l {Desktop Device Run Settings}{Desktop} \li \l {Python Run Settings}{Python} \li \l {QNX Run Settings}{QNX} diff --git a/doc/qtcreator/src/projects/creator-projects-running.qdoc b/doc/qtcreator/src/projects/creator-projects-running.qdoc index 0b39d0d707..1dd25de23a 100644 --- a/doc/qtcreator/src/projects/creator-projects-running.qdoc +++ b/doc/qtcreator/src/projects/creator-projects-running.qdoc @@ -40,7 +40,7 @@ If you have connected \l{Mobile Platforms}{mobile devices} or \l{Embedded Platforms}{embedded devices} to the computer - or added virtual devices, such as \l{Managing Android Virtual Devices (AVD)} + or added virtual devices, such as \l{Manage AVDs} {Android Virtual Devices (AVD)}, you can select them in the kit selector. Select \uicontrol Manage to manage device settings. For example, you can add diff --git a/doc/qtcreator/src/python/creator-python-development.qdoc b/doc/qtcreator/src/python/creator-python-development.qdoc index d5cd5fe31c..8978c09d60 100644 --- a/doc/qtcreator/src/python/creator-python-development.qdoc +++ b/doc/qtcreator/src/python/creator-python-development.qdoc @@ -25,8 +25,8 @@ \li \l{Configure Python language servers} \li \l{Run Python applications} \li \l{Python Run Settings} - \li \l{PDB} - \li \l{Launching the Debugger} + \li \l{PDB versions} + \li \l{Supported Native Debuggers} \endlist For more information about developing with Qt for Python, including diff --git a/doc/qtcreator/src/qnx/creator-deployment-qnx.qdoc b/doc/qtcreator/src/qnx/creator-deployment-qnx.qdoc index 06fcb20abd..eb68e9e0f8 100644 --- a/doc/qtcreator/src/qnx/creator-deployment-qnx.qdoc +++ b/doc/qtcreator/src/qnx/creator-deployment-qnx.qdoc @@ -9,22 +9,30 @@ // ********************************************************************** /*! - \previouspage creator-deployment-b2qt.html \page creator-deployment-qnx.html - \nextpage creator-deployment-embedded-linux.html - \title Deploying to QNX Neutrino + \previouspage creator-reference.html - You can specify settings for deploying applications to QNX Neutrino + \ingroup creator-reference-deploy-configurations + + \title QNX Neutrino Deploy Configuration + + \brief Copy application files to QNX Neutrino devices. + + Specify settings for deploying applications to QNX Neutrino devices in the project configuration file and in \uicontrol Projects > \uicontrol {Run Settings} > \uicontrol Deployment. \image qtcreator-qnx-deployment.png "Deploy to device" The deployment process is described in more detail in - \l{Deploying to Remote Linux}. + \l{Remote Linux Deploy Configuration}. \section1 Finding Configured Devices The \uicontrol {Check for a configured device} deployment step looks for a device that is ready for deployment. + + \sa {Build and Run}{How To: Build and Run}, {QNX Neutrino}{How To: Develop for QNX}, + {QNX Run Settings}, {Remote Linux Deploy Configuration}, + {Remote Linux Run Settings} */ diff --git a/doc/qtcreator/src/qnx/creator-developing-qnx.qdoc b/doc/qtcreator/src/qnx/creator-developing-qnx.qdoc index d7ec1e6417..f6990187c3 100644 --- a/doc/qtcreator/src/qnx/creator-developing-qnx.qdoc +++ b/doc/qtcreator/src/qnx/creator-developing-qnx.qdoc @@ -1,32 +1,51 @@ // Copyright (C) 2018 Blackberry -// Copyright (C) 2022 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-developing-mcu.html \page creator-developing-qnx.html - \nextpage creator-developing-generic-linux.html + \previouspage creator-how-tos.html - \title Connecting QNX Devices + \ingroup creator-how-to-qnx - You can connect QNX devices to the development PC to deploy, run and debug - applications on them from within \QC. The QNX Neutrino RTOS has additional + \title Add a QNX Neutrino device + + Create a connection between \QC and a QNX Neutrino device to run, debug, and + analyze applications on the device. The QNX Neutrino RTOS has additional command-line tools and services, as described in \l {Qt for QNX}. - \note In Qt 6, \QC support for QNX is considered experimental. + \image qtcreator-devices-qnx.webp {QNX device preferences} + \caption QNX device preferences + + \include qtcreator-add-linux-device.qdocinc {add linux device} {QNX Device} + + \sa {QNX Neutrino}{How To: Develop for QNX}, + {Remote Linux}{How To: Develop for remote Linux}, + {Manage Kits}{How To: Manage Kits} +*/ + +/*! + \page creator-how-to-create-qnx-kits.html + \previouspage creator-how-tos.html - \section1 Adding a QNX Neutrino Device in \QC + \ingroup creator-how-to-qnx - Adding a QNX Neutrino device is very similar to - \l{Connecting Remote Linux Devices}, except that - you need to select \uicontrol {QNX Device} in the - \uicontrol {Device Configuration} wizard. + \title Create kits for QNX Neutrino devices - \section1 Add kits for QNX Devices + To generate a build and run \l {Kits}{kit} for QNX Neutrino devices: - To view QNX device settings, select \preferences > - \uicontrol Devices > \uicontrol QNX. Select the \uicontrol {Generate kits} - check box to allow \QC to generate kits for QNX development. + \list 1 + \li Go to \preferences > \uicontrol Devices > \uicontrol Devices. + \li Select \uicontrol Add > \uicontrol {QNX Device} > + \uicontrol {Start Wizard} to add a QNX Neutrino device. + \li Select \uicontrol Apply to fetch the information needed for + creating kits. + \li Go to \preferences > \uicontrol Devices > \uicontrol QNX. + \li Select \uicontrol {Create Kit} to create a kit for a particular + platform. + \image qtcreator-preferences-qnx.webp {QNX Preferences} + \li Activate the kit for your project. + \endlist - \sa {Add kits} + \sa {QNX Neutrino}{How To: Develop for QNX}, {Activate kits for a project} */ diff --git a/doc/qtcreator/src/qnx/creator-projects-how-to-run-qnx.qdoc b/doc/qtcreator/src/qnx/creator-projects-how-to-run-qnx.qdoc index 364ee316bc..13fc502533 100644 --- a/doc/qtcreator/src/qnx/creator-projects-how-to-run-qnx.qdoc +++ b/doc/qtcreator/src/qnx/creator-projects-how-to-run-qnx.qdoc @@ -5,20 +5,22 @@ \page creator-how-to-run-on-qnx.html \previouspage creator-how-tos.html - \ingroup creator-how-to-run + \ingroup creator-how-to-qnx \title Run on QNX devices To build an application and run it on a device: \list 1 - \li Connect the device to the computer or to the Wi-Fi network. - \li Configure the device and specify a connection to it. + \li Connect the device to the computer or to a network. + \li Go to \preferences > \uicontrol Devices > \uicontrol Devices, + and add a QNX device. + \image qtcreator-devices-qnx.webp {QNX device preferences} \li Make sure that your kit has your QNX device set. \li Select \inlineimage icons/run_small.png (\uicontrol Run). \endlist - \QC uses the compiler specified in the QNX tool chain to build the + \QC uses the compiler specified in the QNX toolchain to build the application. \note Debugging is currently only fully supported on Linux and \macos. @@ -32,7 +34,7 @@ \section2 Debug output cannot be shown - For the command-line output to show up in the \uicontrol{Application Output}, + For the command-line output to show up in \l {Application Output}, \QC has to create an SSH connection to the device. This is only possible if QNX Momentics is not running, and the SSH key configured for the device is a 4096-bit key. @@ -48,6 +50,6 @@ \c printf, \c ps, \c read, \c sed, \c sleep, \c uname, \c slog2info, and \c cat. - \sa {Connecting QNX Devices}, {Run on many platforms}, {Compilers}, - {Embedded Platforms}, {kit-preferences}{Kits} + \sa {QNX Neutrino}{How To: Develop for QNX}, {Run on many platforms}, + {Compilers}, {kit-preferences}{Kits} */ diff --git a/doc/qtcreator/src/qnx/creator-projects-settings-run-qnx.qdoc b/doc/qtcreator/src/qnx/creator-projects-settings-run-qnx.qdoc index c3fd8861c0..4e39314d8f 100644 --- a/doc/qtcreator/src/qnx/creator-projects-settings-run-qnx.qdoc +++ b/doc/qtcreator/src/qnx/creator-projects-settings-run-qnx.qdoc @@ -15,13 +15,14 @@ you select for a kit in \uicontrol Projects > \uicontrol {Build & Run} > \uicontrol Run > \uicontrol {Run Settings}. - To run and debug an application on a QNX device, you must - create connections from the development PC to the device. Select - \uicontrol {Manage device configurations} to create a connection. + To run and debug an application on a QNX device, select + \uicontrol {Manage device configurations} to create a + connection between \QC and the device. Settings for QNX Neutrino devices are very similar to those for remote linux devices. - \sa {Remote Linux Run Settings}, {Activate kits for a project}, - {Configure projects for running}, {kits-tab}{Kits}, {Connecting QNX Devices} + \sa {QNX Neutrino}{How To: Develop for QNX}, {Manage Kits}{How To: Manage Kits}, + {Remote Linux Run Settings}, {Configure projects for running}, + {kits-tab}{Kits} */ diff --git a/doc/qtcreator/src/qtcreator-toc.qdoc b/doc/qtcreator/src/qtcreator-toc.qdoc index 0a60027451..442ff25835 100644 --- a/doc/qtcreator/src/qtcreator-toc.qdoc +++ b/doc/qtcreator/src/qtcreator-toc.qdoc @@ -22,72 +22,8 @@ \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{Deploying to Devices} - \list - \li \l{Deploying to Android} - \li \l{Deploying to Boot2Qt} - \li \l{Deploying to QNX Neutrino} - \li \l{Deploying to Remote Linux} - \endlist - \li \l{Connecting Devices} - \list - \li \l{Connecting Android Devices} - \li \l{Connecting Bare Metal Devices} - \li \l{Connecting Boot2Qt Devices} - \li \l{Adding Docker Devices} - \li \l{Connecting iOS Devices} - \li \l{Connecting MCUs} - \li \l{Connecting QNX Devices} - \li \l{Connecting Remote Linux Devices} - \li \l{Building Applications for the Web} - \endlist \li \l{Debugging} - \list - \li \l{Setting Up Debugger} - \li \l{Launching the Debugger} - \li \l{Debug Mode Views} - \list - \li \l{Viewing Call Stack Trace} - \li \l{Setting Breakpoints} - \li \l{Viewing Threads} - \li \l{Viewing Modules} - \li \l{Viewing Source Files} - \li \l{Local Variables and Function Parameters} - \li \l{Evaluating Expressions} - \li \l{Viewing and Editing Register State} - \li \l{Debugger Log} - \li \l{Viewing Disassembled Code} - \endlist - \li \l{Stopping Applications} - \li \l{Examining Data} - \li \l{Remote Debugging} - \li \l{Debugger Preferences} - \li \l{Using Debugging Helpers} - \li \l{Debugging Qt Quick Projects} - \li \l{Troubleshooting Debugger} - \endlist \li \l{Analyzing Code} - \list - \li \l{Profiling QML Applications} - \li \l{Checking Code Coverage} - \li \l{Using Valgrind Code Analysis Tools} - \list - \li \l{Detecting Memory Leaks with Memcheck} - \li \l{Profiling Function Execution} - \li \l{Running Valgrind Tools on External Applications} - \endlist - \li \l{Detecting Memory Leaks with Heob} - \li \l{Analyzing CPU Usage} - \li \l{Analyzing Code with Cppcheck} - \li \l{Visualizing Chrome Trace Events} - \endlist - \li \l{Using Squish} \endlist \li \l{Tutorials} \generatelist creator-tutorials @@ -109,6 +45,27 @@ \generatelist creator-how-to-debug \li Design UIs \generatelist creator-how-to-design + \li Develop for Devices + \list + \li Android + \generatelist creator-how-to-android + \li Bare Metal + \generatelist creator-how-to-bare-metal + \li \B2Q + \generatelist creator-how-to-b2qt + \li Docker + \generatelist creator-how-to-docker + \li iOS + \generatelist creator-how-to-ios + \li MCUs + \generatelist creator-how-to-mcu + \li QNX Neutrino + \generatelist creator-how-to-qnx + \li Remote Linux + \generatelist creator-how-to-remote-linux + \li WebAssembly + \generatelist creator-how-to-webassembly + \endlist \li Edit Code \generatelist creator-how-to-edit \list @@ -143,14 +100,28 @@ \li \l{Reference} \generatelist creator-reference \list + \li Analyzers + \generatelist creator-reference-analyzer \li Build Systems \generatelist creator-reference-build-systems \list \li Build Configurations \generatelist creator-reference-build-configurations + \endlist + \li Devices + \generatelist creator-reference-devices + \list + \li Deploy Configurations + \generatelist creator-reference-deploy-configurations \li Run Configurations \generatelist creator-reference-run-configurations \endlist + \li Debugger + \generatelist creator-reference-debugger + \list + \li Debugger Views + \generatelist creator-reference-debugger-views + \endlist \li Editors \generatelist creator-reference-editors \li Platforms diff --git a/doc/qtcreator/src/qtcreator.qdoc b/doc/qtcreator/src/qtcreator.qdoc index cc3352dd10..96bafe421d 100644 --- a/doc/qtcreator/src/qtcreator.qdoc +++ b/doc/qtcreator/src/qtcreator.qdoc @@ -21,7 +21,7 @@ operating systems. For more information, see \l{Supported Platforms}. In addition, you can use the experimental - \l{Building Applications for the Web}{WebAssembly plugin} + \l{Build applications for the web}{WebAssembly plugin} to build applications in web format and run them in web browsers. @@ -39,12 +39,8 @@ \li \l{Getting Started} \li \l{Creating Projects} \li \l{Configuring Projects} - \li \l{Validating with Target Hardware} - \li \l{Connecting Devices} - \li \l{Deploying to Devices} \li \l{Debugging} \li \l{Analyzing Code} - \li \l{Using Squish} \endlist \li \b {\l{Tutorials}} \generatelist creator-tutorials @@ -54,6 +50,7 @@ \li \l{Build and Run} \li \l{Debug} \li \l{Design UIs} + \li \l{Develop for Devices} \li \l{Edit Code} \li \l{Manage Projects} \li \l{Read Documentation} @@ -65,6 +62,7 @@ \list \li \l {Acknowledgements} \li \l {Build Systems} + \li \l {Devices} \li \l {Command-Line Options} \li \l {Custom Wizards} \li \l {Keyboard Shortcuts} diff --git a/doc/qtcreator/src/qtquick/creator-only/creator-mobile-app-tutorial.qdoc b/doc/qtcreator/src/qtquick/creator-only/creator-mobile-app-tutorial.qdoc index f06917784b..b6f01f38a5 100644 --- a/doc/qtcreator/src/qtquick/creator-only/creator-mobile-app-tutorial.qdoc +++ b/doc/qtcreator/src/qtquick/creator-only/creator-mobile-app-tutorial.qdoc @@ -32,12 +32,12 @@ To develop for Android devices, you must install \l{Qt for Android} and set up the development environment, as instructed in - \l{Connecting Android Devices}. + \l{Developing for Android}. To develop for iOS devices, you must install Xcode and use it to configure a device. For this, you need an Apple developer account and iOS Developer Program certificate that you receive from Apple. For more information, see - \l{Connecting iOS Devices}. + \l{Developing for iOS}. \include qtquick-tutorial-create-empty-project.qdocinc qtquick empty application 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-creating.qdoc b/doc/qtcreator/src/qtquick/creator-only/qtquick-creating.qdoc index 0ff290f0d0..0fbb4fdea0 100644 --- a/doc/qtcreator/src/qtquick/creator-only/qtquick-creating.qdoc +++ b/doc/qtcreator/src/qtquick/creator-only/qtquick-creating.qdoc @@ -149,8 +149,7 @@ imports that are used in the QML files. You can add imports later to combine Qt Quick basic types with - Qt Quick Controls, Qt Quick Dialogs, and Qt Quick Layouts (available - since Qt 5.1). + Qt Quick Controls, Qt Quick Dialogs, and Qt Quick Layouts. \li Select the \uicontrol {Use Qt Virtual Keyboard} check box to add support for \l{Qt Virtual Keyboard} to the application. 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-devices.qdoc b/doc/qtcreator/src/qtquick/qtquick-live-preview-devices.qdoc index 584db4bb43..87142f4a51 100644 --- a/doc/qtcreator/src/qtquick/qtquick-live-preview-devices.qdoc +++ b/doc/qtcreator/src/qtquick/qtquick-live-preview-devices.qdoc @@ -1,36 +1,46 @@ -// 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, you need to 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 UIs on Boot2Qt 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. + 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 a UI on a \B2Q 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 executable at. - \note To preview on a wirelessly connected device, select \preferences > \uicontrol Devices - and connect the device. + \note To preview on a wirelessly connected device, go to \preferences > + \uicontrol Devices and connect the device. To preview a UI on a device: \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-live-preview-kit.png + \image qtcreator-kit-selector-devices.webp {Kit selector} \else \li In the bottom toolbar, select \inlineimage icons/settings.png and enable the kit predefined for the device type. @@ -42,45 +52,36 @@ press \key {Alt+P}. \endlist - \section2 Previewing on Android Devices + \section2 On Android \if defined(qtcreator) - The USB debugging feature on Android devices enables creating connections - to the devices from \QDS and running 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 enabled in different ways on different Android devices. + 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 have enabled debugging, connect the Android device to the system + 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 \B2Q - \section2 Previewing on Boot2Qt Devices - - You can preview UIs on Boot2Qt devices. For a list of supported devices, see - \l{https://doc.qt.io/Boot2Qt/qtdc-supported-platforms.html} - {Boot2Qt: Supported Target Devices and Development Hosts}. + Preview a UI on a supported \B2Q device that you configure as + instructed in the \B2Q documentation. - You must configure the device as instructed in the - \l{https://doc.qt.io/Boot2Qt/b2qt-installation-guides.html} - {Boot2Qt: Installation Guides}. + \sa {\B2Q: Documentation}, {Support Levels for Target Hardware} - \note At the time of this writing, \macos is not supported as a development - host for Boot2Qt. This means that you cannot preview UIs on - devices if you are using \QC on \macos. For more information, see - \l {https://doc.qt.io/Boot2Qt/qtdc-supported-platforms.html#supported-development-hosts} - {Boot2Qt: Supported Development Hosts}. + \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 -*/ diff --git a/doc/qtcreator/src/qtquick/qtquick-modules-with-plugins.qdoc b/doc/qtcreator/src/qtquick/qtquick-modules-with-plugins.qdoc index 299bd05772..e1f7e3bce5 100644 --- a/doc/qtcreator/src/qtquick/qtquick-modules-with-plugins.qdoc +++ b/doc/qtcreator/src/qtquick/qtquick-modules-with-plugins.qdoc @@ -36,22 +36,25 @@ \list 1 \li Create custom components and place all the \c .qml files in a - directory dedicated to your module. For example: + directory dedicated to your module. For example, \c {imports\asset_imports}. - \li For Qt Quick UI Prototype projects (.qmlproject), specify the path to + \if defined(qtcreator) + \li For Qt Quick UI Prototype projects (.qmlproject), specify the path to the directory that has the module in the .qmlproject file of the application where you want to use the module - as a value of the \c importPaths variable. For example + as a value of the \c importPaths variable. For example, \c{importPaths: [ "imports", "asset_imports" ]}. - + \else + \li Specify the path to the directory that has the module in the + .qmlproject file of the application where you want to use the module + as a value of the \c importPaths variable. For example, + \c{importPaths: [ "imports", "asset_imports" ]}. + \endif \li Create a \c qmldir file for your module and place it in the module directory. For more information, see \l {Module Definition qmldir Files}. - \li Create a \c qmltypes file, as instructed in - \l {Generating Type Description Files}. - \li Create a directory named \c designer in your module directory. \li Create a \c .metainfo file for your module and place it in the @@ -66,18 +69,29 @@ \if defined(qtcreator) \li Import the module into the project, as instructed in \l {Importing QML Modules}. - \endlist \else \li Build your module using the same Qt version and compiler as \QDS. - For more information, see \l {Running QML Modules in Design Mode}. + + Your module and components should now appear in \uicontrol Components. + \endif + \endlist - Your module should now appear in \uicontrol Components. Your components - should appear in a subsection of \uicontrol Components if a valid - \c .metainfo file is in place. + \note If \QC cannot find the new QML module, build the project + and then go to \uicontrol {Tools} > \uicontrol {QML/JS} > + \uicontrol {Reset Code Model} to reset the code model. + \if defined(qtdesignstudio) + For more information about how to show the \uicontrol {Tools} menu, see + \l{Customizing the Menu Bar}. \endif - \section1 Generating Type Description Files + \if defined(qtcreator) + \section1 Developing with Qt 6.1 or Earlier + + Since Qt 6.2, CMake generates the \c qmltypes and \c qmldir files + automatically. + + \section2 Generating Type Description Files When \l{Defining QML Types from C++}{registering QML types}, make sure that the QML module has a \c{plugins.qmltypes} file. Ideally, it should be located @@ -110,6 +124,7 @@ \endcode The import path affects all the targets built by the CMake project. + \endif \if defined(qtdesignstudio) \section1 Running QML Modules in Design Mode @@ -128,4 +143,6 @@ environment variable to check whether the plugin is currently being run by an application or edited in the \uicontrol Design mode. \endif + + \sa {Resetting the Code Model} */ diff --git a/doc/qtcreator/src/qtquick/qtquick-profiler.qdoc b/doc/qtcreator/src/qtquick/qtquick-profiler.qdoc index 0fd232d8b9..b22bd5be5e 100644 --- a/doc/qtcreator/src/qtquick/qtquick-profiler.qdoc +++ b/doc/qtcreator/src/qtquick/qtquick-profiler.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // ********************************************************************** @@ -8,185 +8,220 @@ // ********************************************************************** /*! - \page creator-qml-performance-monitor.html + \page creator-how-to-profile-qml.html \if defined(qtdesignstudio) - \previouspage creator-qml-debugging-example.html + \previouspage creator-qml-performance-monitor.html \nextpage studio-advanced.html \else - \previouspage creator-analyze-mode.html - \nextpage creator-coco.html - \endif - - \title Profiling QML Applications - - You can use the QML Profiler to find causes for typical performance problems - in your applications, such as slowness and unresponsive, stuttering user - interfaces. Typical causes include executing too much JavaScript in too few - frames. All JavaScript must return before the GUI thread can proceed, and - frames are delayed or dropped if the GUI thread is not ready. - - Another typical cause for similar performance problems is creating, - painting, or updating invisible items, which takes time in the GUI thread. - - \if defined(qtcreator) - Triggering long-running C++ functions, such as paint methods and signal - handlers, also takes time in the GUI thread, but is more difficult to see in - the QML Profiler because it does not profile C++ code. + \previouspage creator-how-tos.html \endif - To find excessive use of JavaScript, check the frame rate in animations and - Scene Graph events, look for gaps, and check whether the application behaves - as expected. The JavaScript category displays the run time of functions, - which you should try to keep below 16 ms per frame. + \ingroup creator-how-to-analyze - To find problems caused by handling invisible items, look for dropped - frames and check that you are not using too many short bindings or signal - handlers that are updated per frame. You can also \l{Visualizing Overdraw} - {visualize Scene Graph overdraw} to check scene layout and find items that - are never visible to the users because they are located outside the screen - or hidden beneath other, visible elements. + \title Profile QML applications - \if defined(qtcreator) - If frames get dropped even though JavaScript is not being run, and there are - large, unexplained gaps in the timeline, check your custom QQuickItem - implementations. You can use \l{Using Valgrind Code Analysis Tools} - {Valgrind} or other general purpose profilers to analyze C++ code. - - You can use \e {full stack tracing} to trace from the top level QML or - JavaScript down to the C++ and all the way to the kernel space. You can - view the collected data in the \l{Visualizing Chrome Trace Events} - {Chrome Trace Format Viewer}. - \endif + With QML Profiler, you can find causes for typical performance problems + in your applications, such as slowness and unresponsive, stuttering user + interfaces. \if defined(qtdesignstudio) \note In this section, you are using advanced menu items. These are not visible by default. To toggle the visibility of advanced menu items, see - \l{Customizing the Menu}. + \l{Customizing the Menu Bar}. \endif - \section1 Using QML Profiler - To monitor the performance of an application in the QML Profiler: + To collect data about a QML application: \list 1 - - \li To be able to profile an application, you must set up QML debugging - for the project. For more information, see + \li Set up QML debugging for the project. For more information, see \l{Setting Up QML Debugging}. - \if defined(qtcreator) \li In the \uicontrol Projects mode, select a \l{glossary-buildandrun-kit} {kit} with Qt version 4.7.4 or later. \endif - \note To profile applications on \l{glossary-device}{devices}, you must install Qt libraries on them. - - \li Select \uicontrol Analyze > \uicontrol {QML Profiler} to profile the + \li Go to \uicontrol Analyze > \uicontrol {QML Profiler} to profile the current application. - - \li Select the - \inlineimage icons/qtcreator-analyze-start-button.png - (\uicontrol Start) button to start the application from the - QML Profiler. - - \note If data collection does not start automatically, select the - \inlineimage icons/recordfill.png - (\uicontrol {Enable Profiling}) button. - + \image qtcreator-qml-profiler-toolbar.webp {QML Profiler} + \li Select \inlineimage icons/qtcreator-analyze-start-button.png + (\uicontrol Start) to start the application from QML Profiler. \endlist - When you start analyzing an application, the application is launched, and - the QML Profiler immediately begins to collect data. This is indicated by + QML Profiler immediately begins to collect data, as indicated by the time running in the \uicontrol Elapsed field. - Data is collected until you select the \uicontrol {Enable Profiling} button. Data - collection - takes time, and therefore, there might be a delay - before the data is displayed. + \note If data collection does not start automatically, select + \inlineimage icons/recordfill.png (\uicontrol {Enable Profiling}). + + Data is collected until you select \inlineimage icons/recordfill.png again. + Data collection takes time, so expect a delay before seeing data. Do not use application commands to exit the application because data is - sent to the QML Profiler when you select the \uicontrol {Enable Profiling} button. - The application continues to run for some seconds, after which it is stopped - automatically. If you exit the application, the data is not sent. + sent to QML Profiler when you select \inlineimage icons/recordfill.png. + The application stops in seconds. If you exit the application, the data is + not sent. - Select the \uicontrol {Disable Profiling} button to disable the automatic - start of the data collection when an - application is launched. Data collection starts when you select the button - again. + Select \uicontrol {Disable Profiling} to disable the automatic start of the + data collection when an application is launched. Data collection starts when + you select the button again. To save all the collected data, select \uicontrol Analyze > \uicontrol {QML Profiler Options} > \uicontrol {Save QML Trace}. To view the saved data, select \uicontrol {Load QML Trace}. You can also deliver the saved data to others for examination or load data saved by them. - \section1 Specifying Flushing Settings + \section1 Flush data while profiling - You can specify flushing settings for the QML Profiler either globally for - all projects or separately for each project. To specify global settings, - select \preferences > \uicontrol Analyzer. + Set data flushing preferences either globally for all projects or separately + for each project. - To specify custom QML Profiler settings for a particular project, select - \uicontrol Projects > \uicontrol Run and then select \uicontrol Custom in - \uicontrol {QML Profiler Settings}. To restore the global settings for the - project, select \uicontrol {Restore Global}. + To set global preferences, go to \preferences > + \uicontrol Analyzer > \uicontrol {QML Profiler}. - \image qml-profiler-settings.png "QML Profiler Settings" + To specify custom QML Profiler settings for a particular project: - Select the \uicontrol {Flush data while profiling} check box to flush the - data periodically instead of flushing all data when profiling stops. This - saves memory on the target device and shortens the wait between the - profiling being stopped and the data being displayed. + \list 1 + \li Go to \uicontrol Projects > \uicontrol Run. + \li In \uicontrol {QML Profiler Settings}, select \uicontrol Custom. + \image qml-profiler-settings.png {QML Profiler Settings} + \endlist - In the \uicontrol {Flush interval} field, set the flush interval in - milliseconds. The shorter the interval, the more often the data is flushed. - The longer the interval, the more data has to be buffered in the target - application, potentially wasting memory. However, the flushing itself takes - time, which can distort the profiling results. + You can set the following preferences: - If you have multiple QML engines and you want to aggregate the data produced - by all of them into one trace, select the \uicontrol {Process data only when - process ends} check box. Otherwise, the profiling stops when one of the - engines stops. + \table + \header + \li Setting + \li Value + \row + \li \uicontrol {Flush data while profiling} + \li Flush the data periodically instead of flushing all data when + profiling stops. This saves memory on the target device and shortens + the wait between the profiling being stopped and the data + being displayed. + \row + \li \uicontrol {Flush interval} + \li Set the flush interval in + milliseconds. The shorter the interval, the more often the + data is flushed. The longer the interval, the more data has + to be buffered in the target application, potentially wasting + memory. However, the flushing itself takes time, which can + distort the profiling results. + \row + \li \uicontrol {Process data only when process ends} + \li Aggregate data from many QML engines into one trace. Otherwise, + the profiling stops when one of the engines stops. + \endtable + + To restore the global settings for the project, select + \uicontrol {Restore Global}. - \section1 Attaching to Running Qt Quick Applications + \section1 Attach to a running Qt Quick application - You can profile Qt Quick applications that are not launched by \QC. + You can profile a Qt Quick application that you do not run from \QC. However, you must enable QML debugging and profiling for the application in the project build settings. For more information, see \l{Setting Up QML Debugging}. - To attach to waiting applications: + To attach to a waiting application: \list 1 - \li Select \uicontrol Analyze > + \li Go to \uicontrol Analyze > \uicontrol {QML Profiler (Attach to Waiting Application)}. - \image qml-profiler-start-dialog.png "Start QML Profiler dialog" + \image qml-profiler-start-dialog.png {Start QML Profiler dialog} \li In \uicontrol Kit, select the kit used to build the application. \li In \uicontrol Port, specify the port to listen to. \li Select \uicontrol OK. \endlist + \sa {Profiling QML applications} + + \if defined(qtcreator) + \sa {Analyze}{How To: Analyze}, {Analyzers}, {Analyzing Code} + \endif +*/ + +/*! + \page creator-qml-performance-monitor.html + \if defined(qtdesignstudio) + \previouspage creator-qml-debugging-example.html + \nextpage creator-how-to-profile-qml.html + \else + \previouspage creator-reference.html + \endif + + \ingroup creator-reference-analyzer + + \title Profiling QML Applications + + \brief Improve the performance of QML applications. + + \if defined(qtdesignstudio) + \note In this section, you are using advanced menu items. These are not + visible by default. To toggle the visibility of advanced menu items, see + \l{Customizing the Menu}. + \endif + + With QML Profiler, you can find causes for typical performance problems + in your applications, such as slowness and unresponsive, stuttering user + interfaces. Typical causes include executing too much JavaScript in too few + frames. All JavaScript must return before the GUI thread can proceed, and + frames are delayed or dropped if the GUI thread is not ready. + + Another typical cause for similar performance problems is creating or + updating invisible items, which takes time in the GUI thread. + + \if defined(qtcreator) + Triggering long-running C++ functions, such as paint methods and signal + handlers, also takes time in the GUI thread, but is more difficult to see in + QML Profiler because it does not profile C++ code. + \endif + + To find excessive use of JavaScript, check the frame rate in animations and + Scene Graph events, look for gaps, and check whether the application behaves + as expected. The JavaScript category displays the run time of functions, + which you should try to keep below 16 ms per frame. + + To find problems caused by handling invisible items, look for dropped + frames and check that you are not using too many short bindings or signal + handlers that are updated per frame. You can also \l{Visualizing Overdraw} + {visualize Scene Graph overdraw} to check scene layout and find items that + are never visible to the users because they are located outside the screen + or hidden beneath other, visible elements. + + \if defined(qtcreator) + If frames get dropped even though JavaScript is not being run, and there are + large, unexplained gaps in the timeline, check your custom QQuickItem + implementations. You can use \l{Profile function execution} + {Valgrind Callgrind} or other general purpose profilers to analyze C++ code. + + You can use \e {full stack tracing} to trace from the top level QML or + JavaScript down to the C++ and all the way to the kernel space. You can + view the collected data in the \l{Chrome Trace Format Visualizer} + {Chrome Trace Format Viewer}. + \endif + \section1 Analyzing Collected Data The \uicontrol Timeline view displays graphical representations of QML and JavaScript execution and a condensed view of all recorded events. - \image qtcreator-qml-performance-monitor.png "QML Profiler" + \image qtcreator-qml-profiler.webp {QML Profiler} Each row in the timeline (6) describes a type of QML events that were recorded. Move the cursor on an event on a row to see how long it takes and where in the source it is being called. To display the information only when - an event is selected, disable the \uicontrol {View Event Information on Mouseover} - button (4). + an event is selected, turn off \uicontrol {View Event Information on Mouseover} + (4). The outline (10) summarizes the period for which data was collected. Drag the zoom range (8) or click the outline to move on the outline. You can - also move between events by selecting the \uicontrol {Jump to Previous Event} - and \uicontrol {Jump to Next Event} buttons (1). + also move between events by selecting \uicontrol {Jump to Previous Event} + and \uicontrol {Jump to Next Event} (1). - Select the \uicontrol {Show Zoom Slider} button (2) to open a slider that you can - use to set the zoom level. You can also drag the zoom handles (9). To reset + Select \uicontrol {Show Zoom Slider} (2) to open a slider that sets the zoom + level. You can also drag the zoom handles (9). To reset the default zoom level, right-click the timeline to open the context menu, and select \uicontrol {Reset Zoom}. @@ -194,16 +229,16 @@ \section2 Selecting Event Ranges - You can select an event range (7) to view the frame rate of events and to - compare it with the frame rate of similar events. Select the - \uicontrol {Select Range} button (3) to activate the selection tool. Then click in + Select an event range (7) to view the frame rate of events and to + compare it with the frame rate of similar events. Select + \uicontrol {Select Range} (3) to activate the selection tool. Then click in the timeline to specify the beginning of the event range. Drag the selection handle to define the end of the range. The length of the range indicates the frame rate of the event. - You can use event ranges also to measure delays between two subsequent - events. Place a range between the end of the first event and the beginning - of the second event. The \uicontrol Duration field displays the delay between the + To measure delays between two subsequent events, place an event range between + the end of the first event and the beginning of the second event. The + \uicontrol Duration field displays the delay between the events in milliseconds. To zoom into an event range, double-click it. @@ -222,37 +257,28 @@ they include location in source code, duration and some relevant parts of the source code itself. - You can click on an event to move the cursor in the code editor to the part + Select an event to move the cursor in the code editor to the part of the code the event is associated with. The following types of events are displayed in the timeline view on one or - several rows. The availability of event types depends on the version of Qt - the application was compiled with and the version of Qt Quick it is using. + several rows. \table \header \li Event Category \li Description - \li Minimum Qt Version - \li Qt Quick Version - \row \li \uicontrol {Pixmap Cache} \li Displays the general amount of pixmap data cached, in pixels. In addition, displays a separate event for each picture being loaded, with specifics about its file name and size. - \li Qt 5.1 - \li Qt Quick 2 \row \li \uicontrol {Scene Graph} \li Displays the time when scene graph frames are rendered and some additional timing information for the various stages executed to do so. - \li Qt 5.1 - \li Qt Quick 2 - \row \li \uicontrol {Memory Usage} \li Displays block allocations of the JavaScript memory manager. @@ -265,98 +291,64 @@ The second row displays the actual usage of the allocated memory. This is the amount of JavaScript heap the application has actually requested. - \li Qt 5.4 - \li Qt Quick 2 - \row \li \uicontrol {Input Events} \li Displays mouse and keyboard events. - \li Qt 4.7.4 - \li Qt Quick 1 or Qt Quick 2 - \row \li \uicontrol Painting - \li Displays the time spent painting the scene for each frame. - \li Qt 4.7.4 - \li Qt Quick 1 - + \li Not used. \row \li \uicontrol Animations \li Displays the amount of animations that are active and the frame rate that they are running at. - Information about render thread animations is displayed for - applications that are built with Qt 5.3 or later. Render thread - animations are shown in a separate row then. - \li Qt 5.0 (Qt 5.3) - \li Qt Quick 2 - + Render thread animations are shown on a separate row. \row \li \uicontrol Compiling \li Displays the time spent compiling the QML files. - \li Qt 4.7.4 - \li Qt Quick 1 or Qt Quick 2 - \row \li \uicontrol Creating - \li Displays the time spent creating the elements in the scene. In Qt - Quick 2, creation of elements takes place in two stages. The first + \li Displays the time spent creating the elements in the scene. + The creation of elements takes place in two stages. The first stage is for the creation of the data structures, including child elements. The second stage represents the completion callbacks. Not all elements trigger completion callbacks, though. The stages are shown as separate events in the timeline. - For Qt Quick 2 applications compiled with versions of Qt before - 5.2.1 only the creation of top-level elements is shown, as single - events. - \li Qt 4.7.4 (Qt 5.2.1) - \li Qt Quick 1 or Qt Quick 2 - \row \li \uicontrol Binding \li Displays the time when a binding is evaluated and how long the evaluation takes. - \li Qt 4.7.4 - \li Qt Quick 1 or Qt Quick 2 - \row \li \uicontrol {Handling Signal} \li Displays the time when a signal is handled and how long the handling takes. - \li Qt 4.7.4 - \li Qt Quick 1 or Qt Quick 2 - \row \li \uicontrol JavaScript \li Displays the time spent executing the actual JavaScript behind bindings and signal handlers. It lists all the JavaScript functions you may be using to evaluate bindings or handle signals. - \li Qt 5.3 - \li Qt Quick 2 - \row \li \uicontrol Quick3D \li Displays the time spent rendering Qt Quick 3D frames, timing information for frame preparation and synchronization, particle system update times and particle update count, as well as texture and mesh memory allocations and memory consumption. - \li Qt 6.3 - \li Qt Quick 3D + This event type is available since Qt 6.3. \endtable \section2 Analyzing Scene Graph Events - In order to understand the scene graph category, it's important to - understand how the Qt Quick scene graph works. See - \l {Qt Quick Scene Graph} and \l {Qt Quick Scene Graph Default Renderer} - for a detailed description. The following events are reported in the + To understand the scene graph category, read more about how + Qt Quick scene graph works in \l {Qt Quick Scene Graph} and + \l {Qt Quick Scene Graph Default Renderer}. The following events are reported in the \uicontrol {Scene Graph} category. Not all events are generated by all render loops. In the Windows and Basic render loops everything runs in the same thread and the distinction between GUI thread and render thread is meaningless. - If you set the environment variable QSG_RENDER_TIMING, you get a textual + Set the environment variable QSG_RENDER_TIMING, to get a textual output of similar, but slightly different timings from the application - being profiled. For easier orientation, the differences are listed below. + being profiled. The differences are listed below. \table \header @@ -365,7 +357,6 @@ \li Render Loop Types \li Label in output of QSG_RENDER_TIMING \li Description - \li Caveats \row \li \uicontrol {Polish} \li GUI @@ -373,8 +364,6 @@ \li polish \li Final touch-up of items before they are rendered using QQuickItem::updatePolish(). - \li Versions of Qt prior to Qt 5.4 record no polish times for the basic - render loop and incorrect ones for the windows render loop. \row \li \uicontrol {GUI Thread Wait} \li GUI @@ -385,14 +374,12 @@ the same mutex at \uicontrol {GUI Thread Sync}. If this starts long before \uicontrol {Render Thread Sync}, there is \e free time in the GUI thread you could be using for running additional QML or JavaScript. - \li None \row \li \uicontrol {GUI Thread Sync} \li GUI \li Threaded \li blockedForSync \li The time the GUI thread is blocked, waiting for the render thread. - \li None \row \li \uicontrol {Animations} \li GUI @@ -403,7 +390,6 @@ animation events will be shown when using the basic render loop. Watch the \uicontrol {Animations} category to see animation timing in this case. - \li None \row \li \uicontrol {Render Thread Sync} \li Render @@ -411,7 +397,6 @@ \li Frame rendered ... sync \li Synchronizing the QML state into the scene graph using QQuickItem::updatePaintNode(). - \li None \row \li \uicontrol {Render} \li Render @@ -421,20 +406,12 @@ uploading all the necessary data to the GPU. This is the \e gross render time. Do not confuse it with the \e net \uicontrol{Render Render} time below. - \li With versions of Qt prior to Qt 5.5, the gross render time and the - below breakup of render times may be misaligned by some - microseconds due to different, unsynchronized timers being used to - measure them. For example \uicontrol {Render Preprocess} might seem to - start before \uicontrol {Render Thread Sync} is finished. \row \li \uicontrol {Swap} \li Render \li Threaded, Basic, Windows \li Frame rendered ... swap \li Swapping frames after rendering. - \li The output of swap times triggered by setting QSG_RENDER_TIMING is - incorrect for the basic render loop and versions of Qt prior to - Qt 5.4. The QML profiler shows the correct swap times. \row \li \uicontrol {Render Preprocess} \li Render @@ -442,8 +419,6 @@ \li time in renderer ... preprocess \li Calling QSGNode::preprocess() on all nodes that need to be preprocessed. This is part of the gross \uicontrol {Render} step. - \li May not be properly aligned with \uicontrol {Render} with versions of Qt - prior to Qt 5.5. \row \li \uicontrol {Render Update} \li Render @@ -455,8 +430,6 @@ with state from the GUI thread. In \uicontrol {Render Update}, all the nodes are combined to create the final scene. This is part of the gross \uicontrol {Render} step. - \li May not be properly aligned with \uicontrol {Render} with versions of Qt - prior to Qt 5.5. \row \li \uicontrol {Render Bind} \li Render @@ -464,8 +437,6 @@ \li time in renderer ... binding \li Binding the correct framebuffer for OpenGL rendering. This is part of the gross \uicontrol {Render} step. - \li May not be properly aligned with \uicontrol {Render} with versions of Qt - prior to Qt 5.5. \row \li \uicontrol {Render Render} \li Render @@ -473,38 +444,30 @@ \li time in renderer ... rendering \li The actual process of sending all the data to the GPU via OpenGL. This is part of the gross \uicontrol {Render} step. - \li May not be properly aligned with \uicontrol {Render} with versions of Qt - prior to Qt 5.5. \row \li \uicontrol {Material Compile} \li Render \li Threaded, Basic, Windows \li shader compiled \li Compiling GLSL shader programs. - \li None \row \li \uicontrol {Glyph Render} \li Render \li Threaded, Basic, Windows \li glyphs ... rendering \li Rendering of font glyphs into textures. - \li Versions of Qt prior to Qt 5.4 report incorrect times for these - events. \row \li \uicontrol {Glyph Upload} \li Render \li Threaded, Basic, Windows \li glyphs ... upload \li Uploading of glyph textures to the GPU. - \li Versions of Qt prior to Qt 5.4 report incorrect times for these - events. \row \li \uicontrol {Texture Bind} \li Render \li Threaded, Basic, Windows \li plain texture ... bind \li Binding a texture in the OpenGL context using glBindTextures. - \li None \row \li \uicontrol {Texture Convert} \li Render @@ -512,35 +475,30 @@ \li plain texture ... convert \li Converting the format and downscaling an image to make it suitable for usage as a texture. - \li None \row \li \uicontrol {Texture Swizzle} \li Render \li Threaded, Basic, Windows \li plain texture ... swizzle \li Swizzling the texture data on the CPU if necessary. - \li None \row \li \uicontrol {Texture Upload} \li Render \li Threaded, Basic, Windows \li plain texture ... upload / atlastexture uploaded \li Uploading the texture data to the GPU. - \li None \row \li \uicontrol {Texture Mipmap} \li Render \li Threaded, Basic, Windows \li plain texture ... mipmap \li Mipmapping a texture on the GPU. - \li None \row \li \uicontrol {Texture Delete} \li Render \li Threaded, Basic, Windows \li plain texture deleted \li Deleting a texture from the GPU that became unnecessary. - \li None \endtable \section2 Analyzing Qt Quick 3D Events @@ -550,7 +508,7 @@ Synchronize happens in scene graph synchronizing phase, while prepare and render happen in scene graph rendering phase. - Setting the environment variable \c QSG_RENDERER_DEBUG=render will also give + Set the environment variable \c QSG_RENDERER_DEBUG=render to get additional textual output of render call counts of different rendering passes. These call counts are summed up in the Render Frame event. @@ -616,24 +574,24 @@ The \uicontrol Statistics view displays the number of times each binding, create, compile, JavaScript, or signal event is triggered and the average time it - takes. This allows you to examine which events you need to optimize. A high + takes. Examine the statistics to learn which events to optimize. A high number of occurrences might indicate that an event is triggered unnecessarily. To view the median, longest, and shortest time for the occurrences, select \uicontrol {Extended Event Statistics} in the context menu. - Click on an event to move to it in the source code + Select an event to move to it in the source code in the code editor. \image qml-profiler-statistics.png "Statistics view" - The \uicontrol Callers and \uicontrol Callees panes show dependencies between events. + \uicontrol Callers and \uicontrol Callees show dependencies between events. They allow you to examine the internal functions of the application. - The \uicontrol Callers pane summarizes the QML events that trigger a binding. + \uicontrol Callers summarizes the QML events that trigger a binding. This tells you what caused a change in a binding. - The \uicontrol Callees pane summarizes the QML events that a binding triggers. + \uicontrol Callees summarizes the QML events that a binding triggers. This tells you which QML events are affected if you change a binding. - Click on an event to move to it in the source code in the code editor. + Select an event to move to it in the source code in the code editor. When you select an event in the \uicontrol Timeline view, information about it is displayed in the \uicontrol Statistics and \uicontrol {Flame Graph} @@ -642,9 +600,6 @@ To copy the contents of one view or row to the clipboard, select \uicontrol {Copy Table} or \uicontrol {Copy Row} in the context menu. - JavaScript events are shown in the \uicontrol Statistics view only for applications - that use Qt Quick 2 and are compiled with Qt 5.3 or later. - \section2 Visualizing Statistics as Flame Graphs The \uicontrol {Flame Graph} view shows a more concise statistical overview @@ -671,4 +626,9 @@ suitable for analyzing per frame execution times. However, it is very easy to see the total impact of the various QML and JavaScript events there. + \sa {Profile QML applications} + + \if defined(qtcreator) + \sa {Analyze}{How To: Analyze}, {Analyzers}, {Analyzing Code} + \endif */ diff --git a/doc/qtcreator/src/user-interface/creator-file-system-view.qdoc b/doc/qtcreator/src/user-interface/creator-file-system-view.qdoc index 24f3b38479..a8ce9dbb5a 100644 --- a/doc/qtcreator/src/user-interface/creator-file-system-view.qdoc +++ b/doc/qtcreator/src/user-interface/creator-file-system-view.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2023 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -15,7 +15,11 @@ \title File System + \if defined(qtdesignstudio) + \brief View all the files in the current directory. + \else \brief Shows all the files in the current directory. + \endif \if defined(qtcreator) \note Usually, \l{Navigate with locator}{searching with the locator} @@ -25,14 +29,14 @@ \image qtcreator-filesystem-view.webp {File System view in the sidebar} \else - \image qtcreator-filesystem-view-design.png {File System view} + \image filesystem-view-design.webp {File System view} \endif - To move to the root directory of the file system, select \uicontrol Computer - in the menu (1). Select \uicontrol Home to move to the user's home - directory. Further, you can select a project to move to an open project - or \uicontrol Projects to move to the directory specified in the - \uicontrol {Projects directory} field in \preferences > + To go to the root directory of the file system, select \uicontrol Computer + in the menu (1). Select \uicontrol Home to go to the user's home + directory. Further, you can select a project to go to an open project + or \uicontrol Projects to go to the directory specified in + \uicontrol {Projects directory} in \preferences > \uicontrol {Build & Run} > \uicontrol General. The file that is currently active in the editor determines which folder @@ -46,12 +50,13 @@ \endlist To stop the synchronization between the editor and the - \uicontrol {File System} view, deselect the \inlineimage icons/linkicon.png - (\uicontrol {Synchronize Root Directory with Editor}) button. + \uicontrol {File System} view, clear \inlineimage icons/linkicon.png + (\uicontrol {Synchronize Root Directory with Editor}). The view displays the path to the active file as bread crumbs. You can move to any directory along the path by clicking it. + \if defined(qtcreator) \section1 File System Context Menu Use the context menu functions to: @@ -64,34 +69,24 @@ that has the file. To specify the terminal to use on Linux and \macos, select \preferences > \uicontrol Environment > \uicontrol System. - \if defined(qtcreator) To use an \l{Terminal} {internal terminal}, select \preferences > \uicontrol Terminal > \uicontrol {Use internal terminal}. - \endif \li Search in the selected directory. \li View file properties, such as name, path, MIME type, default editor, line endings, indentation, owner, size, last read and modified dates, and permissions. - \li Create new files. For more information, see - \if defined(qtdesignstudio) - \l{Adding Files to Projects}. - \else - \l{Create files}. - \endif + \li Create new files. For more information, see {Create files}. \li Rename existing files. To move the file to another directory, enter the relative or absolute path to its new location in addition to the new filename. \li Remove existing files. \li Create new folders. - \if defined(qtcreator) \li Compare the selected file with the currently open file in the diff editor. For more information, see \l{Compare files}. - \endif \li Display the contents of a particular directory in the view. \li Collapse all open folders. \endlist - \if defined(qtcreator) \section1 File System View Toolbar The toolbar in the \uicontrol {File System} view has additional @@ -101,16 +96,15 @@ (\uicontrol Options): \list - \li To hide the bread crumbs, deselect the - \uicontrol {Show Bread Crumbs} check box. + \li To hide the bread crumbs, clear \uicontrol {Show Bread Crumbs}. \li By default, the view separates folders from files and lists them - first. To list all items in alphabetic order, deselect the - \uicontrol {Show Folders on Top} check box. + first. To list all items in alphabetic order, clear + \uicontrol {Show Folders on Top}. \li To also show hidden files, select \uicontrol {Show Hidden Files}. \endlist To stop the synchronization with the file currently open in the - editor, deselect \inlineimage icons/linkicon.png + editor, clear \inlineimage icons/linkicon.png (\uicontrol {Synchronize with Editor}). \sa {View CMake project contents}, {Projects} diff --git a/doc/qtcreator/src/user-interface/creator-only/creator-how-to-show-and-hide-sidebars.qdoc b/doc/qtcreator/src/user-interface/creator-only/creator-how-to-show-and-hide-sidebars.qdoc index 230ce2adde..106562ab55 100644 --- a/doc/qtcreator/src/user-interface/creator-only/creator-how-to-show-and-hide-sidebars.qdoc +++ b/doc/qtcreator/src/user-interface/creator-only/creator-how-to-show-and-hide-sidebars.qdoc @@ -15,7 +15,7 @@ Select views in the sidebar menu (1): - \image qtcreator-sidebar.png + \image qtcreator-sidebar.webp {Views open in the sidebar} You can change the view of the sidebars in the following ways: diff --git a/doc/qtcreator/src/user-interface/creator-only/creator-reference-to-do-entries-view.qdoc b/doc/qtcreator/src/user-interface/creator-only/creator-reference-to-do-entries-view.qdoc index 5d78d8345c..61613519c3 100644 --- a/doc/qtcreator/src/user-interface/creator-only/creator-reference-to-do-entries-view.qdoc +++ b/doc/qtcreator/src/user-interface/creator-only/creator-reference-to-do-entries-view.qdoc @@ -63,7 +63,7 @@ \li To determine whether the keywords in the whole project, in the current file, or in a subproject are displayed by default, select - the appropriate option in the \uicontrol {Scanning scope} group. + the appropriate option in the \uicontrol {Scanning Scope} group. \endlist diff --git a/doc/qtcreator/src/user-interface/creator-open-documents-view.qdoc b/doc/qtcreator/src/user-interface/creator-open-documents-view.qdoc index 87760c448c..67c0134c78 100644 --- a/doc/qtcreator/src/user-interface/creator-open-documents-view.qdoc +++ b/doc/qtcreator/src/user-interface/creator-open-documents-view.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2023 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -16,13 +16,26 @@ \title Open Documents + \if defined(qtdesignstudio) + \brief View currently open files. + \else \brief Shows currently open files. + \endif + \if defined(qtdesignstudio) + \image open-documents-view.webp {Open Documents view} + \else \image qtcreator-open-documents-view.png {Open Documents view} + \endif You can use the context menu to apply some of the functions also available - in the \uicontrol File menu and in the \l {File System Context Menu} - {File System} view to the file that you select in the view. + in the \uicontrol File menu and in the + \if defined(qtcreator) + \l {File System Context Menu}{File System} + \else + \uicontrol {File System} + \endif + view to the file that you select in the view. In addition, you can: diff --git a/doc/qtcreator/src/user-interface/creator-projects-view.qdoc b/doc/qtcreator/src/user-interface/creator-projects-view.qdoc index b6b74f0993..d28e6f9ef0 100644 --- a/doc/qtcreator/src/user-interface/creator-projects-view.qdoc +++ b/doc/qtcreator/src/user-interface/creator-projects-view.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2023 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -15,7 +15,11 @@ \title Projects + \if defined(qtdesignstudio) + \brief View a list of the files contained within the open project. + \else \brief Shows a list of projects in a project tree. + \endif \if defined(qtcreator) The project tree has a list of all projects open in the current @@ -29,7 +33,7 @@ is the fastest way to find a particular project, file, class, or function, or almost anything else in your project. \else - \image qtcreator-projects-view-design.png {Projects view} + \image projects-view-design.webp {Projects view} \endif You can use the project tree in the following ways: @@ -43,14 +47,19 @@ Use the \l{Switch between modes} {mode selector} to open the current file in another editor. \endif - \li To bring up a \l{Projects View Context Menu}{context menu} + \li To open a + \if defined(qtcreator) + \l{Projects View Context Menu}{context menu} + \else + context menu + \endif that has the actions most commonly needed, right-click an item in the project tree. For example, through the menu of the project root directory you can, among other actions, run and close the project. \li To see the absolute path of a file, move the mouse pointer over the file name. - \li To move files from one project to another, drag-and-drop them + \li To move files from one project to another, drag them in the project tree. \QC makes the necessary changes to project configuration files. \endlist @@ -58,6 +67,7 @@ \note If you cannot see a file in the \l Projects view, switch to the \uicontrol {File System} view, which shows all the files in the file system. + \if defined(qtcreator) \section1 Projects View Context Menu The \uicontrol Projects view has context menus for managing projects, @@ -65,22 +75,15 @@ projects and subprojects: \list - \if defined(qtcreator) \li Set a project as the active project. - \endif \li Execute \uicontrol Build menu commands. \li Create new files. For more information, see - \if defined(qtdesignstudio) - \l{Adding Files to Projects}. - \else \l{Create files}. - \endif \li Rename existing files. If you change the base name of a file, \QC displays a list of other files with the same base name and offers to rename them as well. If you rename a UI file (.ui), \QC also changes corresponding include statements accordingly. \li Remove existing files. - \if defined(qtcreator) \li Remove existing directories from \l{Import an existing project} {generic projects}. \li Add existing files and directories. @@ -88,16 +91,13 @@ \l{Add libraries to qmake projects}. \li Add and remove subprojects. \li Find unused functions. - \endif \li Search in the selected directory. \li Open a terminal window in the project directory. To specify the terminal to use on Linux and \macos, select \preferences > \uicontrol Environment > \uicontrol System. - \if defined(qtcreator) To use an \l{Terminal}{internal terminal}, select \preferences > \uicontrol Terminal > \uicontrol {Use internal terminal}. - \endif \li Open a terminal window in the project directory that you configured for building or running the project. \li Expand or collapse the tree view to show or hide all files and @@ -114,7 +114,6 @@ the \l {File System} view. To view a project in it, select \uicontrol {Show in File System View}. - \if defined(qtcreator) \section1 Projects View Toolbar The toolbar in the \uicontrol Projects view has additional options. diff --git a/doc/qtcreator/src/user-interface/creator-ui.qdoc b/doc/qtcreator/src/user-interface/creator-ui.qdoc index 9041e6432f..9794667f5b 100644 --- a/doc/qtcreator/src/user-interface/creator-ui.qdoc +++ b/doc/qtcreator/src/user-interface/creator-ui.qdoc @@ -95,7 +95,7 @@ \endif \if defined(qtdesignstudio) - \section1 Customizing the Menu + \section1 Customizing the Menu Bar By default, top-level menu items \uicontrol Build, \uicontrol Debug, and \uicontrol Analyze are not visible. These menu items have options for @@ -113,6 +113,9 @@ You need to restart \QDS to apply changes made to these settings. + \note To show or hide the \uicontrol {Menu Bar}, select \uicontrol View > + \uicontrol {Show Menu Bar}, or use \key {Ctrl+Alt+M}. + \section1 Customizing the UI The following topics describe how to customize the UI: diff --git a/doc/qtcreator/src/vcs/creator-only/creator-vcs-perforce.qdoc b/doc/qtcreator/src/vcs/creator-only/creator-vcs-perforce.qdoc index 443aa40be4..6c9c93ff51 100644 --- a/doc/qtcreator/src/vcs/creator-only/creator-vcs-perforce.qdoc +++ b/doc/qtcreator/src/vcs/creator-only/creator-vcs-perforce.qdoc @@ -35,11 +35,26 @@ Set workspace details in \uicontrol {P4 user}, \uicontrol {P4 client}, and \uicontrol {P4 port}. - To specify the details individually for several projects, use configuration - files instead. Create a \c {p4config.txt} configuration file for each - project in the top level project directory, and run - \c{p4 set P4CONFIG=p4config.txt} once. You must deselect the - \uicontrol {Environment Variables} check box. + \section1 Using Configuration Files + + To specify workspace details individually for several projects, use + configuration files: + + \list 1 + \li Create a \c {p4config.txt} configuration file for each project in the + top level project directory. + \li Go to \preferences > \uicontrol {Version Control} > + \uicontrol Perforce. + \li Clear \uicontrol {Environment Variables}. + \li To set \c P4CONFIG to use the file that you created, run the + following command from the command line once: + \badcode + p4 set P4CONFIG=p4config.txt + \endcode + \endlist + + For more information about using the \c P4CONFIG variable, see + \l{Perforce: P4CONFIG}. \section1 Editing Files diff --git a/doc/qtcreator/src/vcs/creator-vcs-git.qdoc b/doc/qtcreator/src/vcs/creator-vcs-git.qdoc index ea23e53443..e853a86812 100644 --- a/doc/qtcreator/src/vcs/creator-vcs-git.qdoc +++ b/doc/qtcreator/src/vcs/creator-vcs-git.qdoc @@ -30,10 +30,6 @@ You can use the \l{http://code.google.com/p/gerrit/}{Gerrit} code review tool for projects that use Git. - \if defined(qtdesignstudio) - \include creator-vcs-options.qdocinc vcs options - \endif - \if defined(qtcreator) \section1 Using Git for Windows diff --git a/doc/qtcreator/src/webassembly/creator-webassembly.qdoc b/doc/qtcreator/src/webassembly/creator-webassembly.qdoc index 4a459e8cdd..ab757d7add 100644 --- a/doc/qtcreator/src/webassembly/creator-webassembly.qdoc +++ b/doc/qtcreator/src/webassembly/creator-webassembly.qdoc @@ -1,116 +1,71 @@ -// Copyright (C) 2021 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-developing-generic-linux.html \page creator-setup-webassembly.html - \nextpage creator-build-process-customizing.html + \previouspage creator-how-tos.html - \title Building Applications for the Web + \ingroup creator-how-to-webassembly - WebAssembly is a binary format that allows sand-boxed executable code in - web pages. This format is nearly as fast as native machine code, and is - now supported by all major web browsers. + \title Build applications for the Web - \l {Qt for WebAssembly} enables building Qt applications so that they can be - integrated into web pages. It doesn't require any client-side installations - and reduces the use of server-side resources. + WebAssembly is a binary format that allows sand-boxed executable code in + web pages. This format is nearly as fast as native machine code. It is + supported by all major web browsers. - The experimental WebAssembly plugin enables you to build your applications - in WebAssembly format and deploy and run them in the local web browser. - You can change the web browser in the project's \l{Specifying Run Settings} - {run settings}. + Use \l {Qt for WebAssembly} to build your applications in WebAssembly format + and deploy and run them on the local web browser. Change the web browser in + the project's \l{Run applications in a web browser}{run settings}. \note Enable the WebAssembly plugin to use it. - To build applications for the web and run them in a web browser, you need to - install Qt for WebAssembly and the tool chain for compiling to WebAssembly. - - \section1 Requirements - - You need the following software to build Qt applications for the web and run - them in a browser: - - \list - \li Qt for WebAssembly 5.15, or later - \li On Windows: \l{http://wiki.qt.io/MinGW}{\MinGW} 7.3.0, or later - \li \l{https://emscripten.org/docs/introducing_emscripten/index.html} - {emscripten} tool chain for compiling to WebAssembly - \endlist - - \section1 Setting Up the Development Environment + To build applications for the web and run them in a web browser, install + Qt for WebAssembly with \QOI. It automatically adds a build and run kit + to \QC. - You need to install and configure Qt for WebAssembly and the tool chain for - compiling to WebAssembly. \QOI automatically adds a build and - run kit to \QC. + \section1 Set up WebAssembly development environment - \section2 Setting Up Qt for WebAssembly - - To set up Qt for WebAssembly: - - \list 1 - \li Use \QMT to install Qt for WebAssembly and, on - Windows, \MinGW (found in \uicontrol {Developer and Designer Tools}). - \li Check out a known-good Emscripten version supported by the Qt for - WebAssembly version that you installed, and install and activate - \c emscripten, as instructed in - \l {https://doc.qt.io/qt-5/wasm.html#install-emscripten} - {Install Emscripten}. - \endlist - - \section2 Specifying WebAssembly Settings - - To configure \QC for building Qt apps for the web: + To set up the development environment for WebAssembly: \list 1 - \li Select \preferences > \uicontrol Devices > \uicontrol WebAssembly. - \li In the \uicontrol {Emscripten SDK path} field, enter the root - directory where \c emsdk is installed. + \li Go to \preferences > \uicontrol Devices > \uicontrol WebAssembly. + \li In \uicontrol {Emscripten SDK path}, enter the root directory where + you installed \c emsdk. \li \QC configures the \uicontrol {Emscripten SDK environment} for you - if the \c emsdk is supported by the Qt for WebAssembly version that - you will use for developing the application. - \image qtcreator-webassembly-options.png "Qt for WebAssembly device preferences" - \li Select \preferences > \uicontrol Kits. - \image qtcreator-kit-webassembly.png "Qt for WebAssembly kit" - \li In the \uicontrol Compiler group, \uicontrol {Emscripten Compiler} - should have been automatically detected for both C++ and C. If not, - check that emscripten is set up correctly. + if your Qt for WebAssembly version supports the \c emsdk. + \image qtcreator-webassembly-options.png {Qt for WebAssembly device preferences} + \li Go to \preferences > \uicontrol Kits. + \image qtcreator-kit-webassembly.png {Qt for WebAssembly kit} + \li If \uicontrol {Emscripten Compiler} was not automatically set + for both C++ and C, check that emscripten is set up correctly. \endlist - \section2 Adding WebAssembly Kits + \sa {Run applications in a web browser} +*/ - The Qt for Web Assembly installation automatically adds build and run kits - to \QC. To add kits: +/*! + \page creator-how-to-run-webassembly.html + \previouspage creator-how-tos.html - \list 1 - \li Select \preferences > \uicontrol Kits > \uicontrol Add. - \li In the \uicontrol Name field, specify a name for the kit. - \li In the \uicontrol {Run device type} field, select - \uicontrol {WebAssembly Runtime}. - The value of the \uicontrol Device field is automatically - set to \uicontrol {Web Browser}. - \li In the \uicontrol Compiler field, select - \uicontrol {Emscripten Compiler} for both C and C++. - \li Select \uicontrol Apply to add the kit. - \endlist + \ingroup creator-how-to-webassembly - \section1 Running Applications in a Web Browser + \title Run applications in a web browser - To run a project: + To build Qt applications in \l{Qt for WebAssembly}{WebAssembly} format and + run them in a web browser: \list 1 \li Open a project for an application you want to run in a web browser. - \li Select \uicontrol Projects > \uicontrol {Build & Run}, and then + \li Go to \uicontrol Projects > \uicontrol {Build & Run}, and then select the WebAssembly kit as the build and run kit for the project. \li Select \uicontrol Run to specify run settings. - \li In the \uicontrol {Web browser} field, select the browser to run - the application in. - \image qtcreator-settings-run-webassembly.png "Selecting the browser to run in" + \li In \uicontrol {Web browser}, select a browser. + \image qtcreator-settings-run-webassembly.png {Selecting the browser to run in} \endlist - You can now build Qt applications in WebAssembly format and run them in + Build Qt applications in WebAssembly format and run them in a web browser as described in \l {Build for many platforms} and \l{Run on many platforms}. - \sa {Enable and disable plugins} + \sa {Build applications for the Web}, {Enable and disable plugins} */ diff --git a/doc/qtcreator/src/widgets/creator-faq-qtdesigner.qdocinc b/doc/qtcreator/src/widgets/creator-faq-qtdesigner.qdocinc index 93ed060e4a..eb93c69a8c 100644 --- a/doc/qtcreator/src/widgets/creator-faq-qtdesigner.qdocinc +++ b/doc/qtcreator/src/widgets/creator-faq-qtdesigner.qdocinc @@ -4,7 +4,7 @@ /*! //! [qt designer faq] - \section1 Qt Designer Integration Questions + \section1 \QD Integration Questions \b {Why are custom widgets not loaded in the \uicontrol Design mode even though it works in standalone \QD?} @@ -13,7 +13,7 @@ that match its build key. The locations are different for standalone and integrated \QD. - For more information, see \l{Adding Qt Designer Plugins}. + For more information, see \l{Adding \QD Plugins}. //! [qt designer faq] */ diff --git a/doc/qtcreator/src/widgets/qtdesigner-app-tutorial.qdoc b/doc/qtcreator/src/widgets/qtdesigner-app-tutorial.qdoc index f3717ee049..8f744bced0 100644 --- a/doc/qtcreator/src/widgets/qtdesigner-app-tutorial.qdoc +++ b/doc/qtcreator/src/widgets/qtdesigner-app-tutorial.qdoc @@ -197,7 +197,7 @@ \endlist For more information about designing forms with \QD, see the - \l{Qt Designer Manual}. + \l{\QD Manual}. \section2 Completing the Header File diff --git a/doc/qtcreator/src/widgets/qtdesigner-overview.qdoc b/doc/qtcreator/src/widgets/qtdesigner-overview.qdoc index b2357514fa..29d2c7d34b 100644 --- a/doc/qtcreator/src/widgets/qtdesigner-overview.qdoc +++ b/doc/qtcreator/src/widgets/qtdesigner-overview.qdoc @@ -29,7 +29,7 @@ Furthermore, features such as widget promotion and custom plugins allow you to use your own widgets with \QD. - For more information about \QD, see the \l{Qt Designer Manual}. + For more information about \QD, see the \l{\QD Manual}. Generally, the integrated \QD has the same functions as the standalone \QD. The following sections describe the differences. @@ -62,7 +62,7 @@ \uicontrol {Follow Symbol Under Cursor} in the context menu or press \key F2 when the cursor is over a string literal. - \section1 Specifying Settings for Qt Designer + \section1 Specifying Settings for \QD You can drag and drop the views in \QD to new positions on the screen. @@ -102,7 +102,7 @@ \list 1 \li \preferences > \uicontrol Designer. - \image qtdesigner-embedded-design.png "Qt Designer Embedded Design preferences" + \image qtdesigner-embedded-design.png "Qt Widgets Designer Embedded Design preferences" \li In \uicontrol {Embedded Design}, select \inlineimage icons/plus.png to open the \uicontrol {Add Profile} dialog. \image qtdesigner-add-profile.png "Add Profile dialog" @@ -119,5 +119,5 @@ To import device profiles from .qdp files, select \uicontrol Open. To save them as .qdp files, select \uicontrol Save. - \sa {Creating a Qt Widget Based Application}, {Adding Qt Designer Plugins} + \sa {Creating a Qt Widget Based Application}, {Adding \QD Plugins} */ diff --git a/doc/qtcreator/src/widgets/qtdesigner-plugins.qdoc b/doc/qtcreator/src/widgets/qtdesigner-plugins.qdoc index 00f61ab051..3ce3dc02f7 100644 --- a/doc/qtcreator/src/widgets/qtdesigner-plugins.qdoc +++ b/doc/qtcreator/src/widgets/qtdesigner-plugins.qdoc @@ -26,7 +26,7 @@ and to change the default plugin path, see \l{How to Create Qt Plugins}. For more information about how to create plugins for \QD, see - \l{Using Custom Widgets with Qt Designer}. + \l{Using Custom Widgets with \QD}. \section1 Locating \QD Plugins @@ -42,7 +42,7 @@ To check which plugins were loaded successfully and which failed, choose \uicontrol Tools > \uicontrol {Form Editor} > - \uicontrol {About Qt Designer Plugins}. + \uicontrol {About \QD Plugins}. The standalone \QD is part of the Qt library used for building projects, located in \c {<Qt_version>\<compiler>\bin} in the Qt installation diff --git a/doc/qtcreatordev/src/plugin-metadata.qdoc b/doc/qtcreatordev/src/plugin-metadata.qdoc index b233ef60bc..20d4073fd1 100644 --- a/doc/qtcreatordev/src/plugin-metadata.qdoc +++ b/doc/qtcreatordev/src/plugin-metadata.qdoc @@ -323,6 +323,27 @@ } \endcode + \section2 Other Meta Data + + \table + \header + \li Key + \li Value Type + \li Meaning + \row + \li Mimetypes + \li String or array of strings + \li Possibly multiple lines of + \l{https://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec/}{XML MIME-info} + used for registering additional or adapting built-in MIME types. + \row + \li JsonWizardPaths + \li Array of strings + \li A list of paths relative to the plugin location or paths to the + \l{The Qt Resource System}{Qt resource system} that are searched for + \l{http://doc.qt.io/qtcreator/creator-project-wizards.html}{template-based wizards}. + \endtable + \section2 A Note on Plugin Versions Plugin versions are in the form \c{x.y.z_n} where, \c x, \c y, \c z and \c n are diff --git a/doc/qtcreatordev/src/qtcreator-dev.qdoc b/doc/qtcreatordev/src/qtcreator-dev.qdoc index 368298b31f..ae68f3f407 100644 --- a/doc/qtcreatordev/src/qtcreator-dev.qdoc +++ b/doc/qtcreatordev/src/qtcreator-dev.qdoc @@ -138,7 +138,7 @@ Most software projects and development processes require various external tools. Several external tools, such as popular version control systems and - build tool chains are integrated into \QC. However, it is impossible for a + build toolchains are integrated into \QC. However, it is impossible for a single tool to cover all the use cases, and therefore you can integrate additional tools to \QC. diff --git a/doc/qtcreatordev/src/qtcreator-module.qdoc b/doc/qtcreatordev/src/qtcreator-module.qdoc index 83d0b3fe15..652f715133 100644 --- a/doc/qtcreatordev/src/qtcreator-module.qdoc +++ b/doc/qtcreatordev/src/qtcreator-module.qdoc @@ -92,7 +92,7 @@ handling. \row - \li \l{Debugger} + \li \l{Debugging} \li Debugging functionality. \row diff --git a/doc/qtcreatordev/src/qtcreator-ui-text.qdoc b/doc/qtcreatordev/src/qtcreator-ui-text.qdoc index f42c80671a..e76ad238e2 100644 --- a/doc/qtcreatordev/src/qtcreator-ui-text.qdoc +++ b/doc/qtcreatordev/src/qtcreator-ui-text.qdoc @@ -158,11 +158,11 @@ \section3 Writing Tooltips in Design Mode - In Qt Designer, use plain text for tooltips. For extra formatting, write + In \QD, use plain text for tooltips. For extra formatting, write short, canonical HTML in the source tab of the rich text editor: \c {<html><head/><body><b>Note:</b> text.} - Qt Designer has a feature that simplifies the rich text (on by default), + \QD has a feature that simplifies the rich text (on by default), but still, you should verify by looking at the \uicontrol Source tab. \section2 Writing Messages @@ -273,8 +273,36 @@ \section2 Marking UI Text for Translation - Make sure the text strings presented to the user are easy to translate. - The user interface text strings are enclosed in \c tr() calls and + \section3 Translation Context + + Avoid creating many different translation contexts. By default, \c tr() + uses the context of the class, which means that translations break when + code is refactored and UI text is moved to a different class. + + Create a single translation context for each plugin instead. Create a header + \c myplugintr.h + + \code + #pragma once + + #include <QCoreApplication> + + namespace MyPlugin { + + struct Tr + { + Q_DECLARE_TR_FUNCTIONS(QtC::MyPlugin) + }; + + } // namespace MyPlugin + \endcode + + and use that struct as the translation context for UI text by calling + \c {Tr::tr()}. Use disambiguation strings in cases that need it. + + \section3 Translator Comments + + The user interface text strings are enclosed in \c {Tr::tr()} calls and extracted from the source code during the translation process. Therefore, the translator might not know the source code context of the messages. @@ -286,26 +314,24 @@ return tr("Add"); \endcode - If the class is not Q_OBJECT, use \c {QCoreApplication::translate("class - context", "message")} or consider using Q_DECLARE_TR_FUNCTIONS. Do not use - \c {QObject::tr()}, which is confusing because the messages appear grouped - by class context in Qt Linguist and messages tied to QObject do not have a - class context. + \section3 File Paths + + Use \c{FilePath::toUserOutput()} from the \c Utils library for file and directory + names that you pass to \c{Tr::tr().arg()}. - Use \c{QDir::toNativeSeparators()} for file and directory names that you - pass to \c{tr().arg()}. + \section3 Markup - Do not use markup that spans the whole string because that can be confusing + Avoid including markup within the translated text itself because that can be confusing for translators. For example, instead of: \code - tr("<html><head/><body><span>UI Text</span></body></html>") + Tr::tr("<html><head/><body><span>UI Text</span></body></html>") \endcode use \code - QLatin1String("<html><head/><body><span>") + tr("UI Text") + QLatin1String("/span></body></html>") + "<html><head/><body><span>" + Tr::tr("UI Text") + "</span></body></html>" \endcode \section2 Features of Languages or Writing Systems diff --git a/doc/qtdesignstudio/config/qtdesignstudio.qdocconf b/doc/qtdesignstudio/config/qtdesignstudio.qdocconf index 72b38940f7..95d1475cf1 100644 --- a/doc/qtdesignstudio/config/qtdesignstudio.qdocconf +++ b/doc/qtdesignstudio/config/qtdesignstudio.qdocconf @@ -120,4 +120,9 @@ macro.function = "\\fn" macro.QMLD = "Qt Design Studio" navigation.landingpage = "$IDE_DISPLAY_NAME Manual" + +# Auto-generate navigation linking based on "All Topics": +navigation.toctitles = "All Topics" +navigation.toctitles.inclusive = false + buildversion = "$IDE_DISPLAY_NAME Manual $QTC_VERSION" diff --git a/doc/qtdesignstudio/config/style/qt5-sidebar.html b/doc/qtdesignstudio/config/style/qt5-sidebar.html index 0a7c93702a..994ecd3db3 100644 --- a/doc/qtdesignstudio/config/style/qt5-sidebar.html +++ b/doc/qtdesignstudio/config/style/qt5-sidebar.html @@ -1,18 +1,109 @@ <div class="sectionlist normallist"> + <ul> + <li><a href="qtdesignstudio-toc.html">View All Topics</a></li> + </ul> +</div> +<div class="sectionlist normallist"> <div class="heading"> - <a name="reference"></a> - <h2 id="reference">Qt Design Studio Manual</h2> + <h2>Getting Started</h2> </div> <div class="indexboxcont indexboxbar"> <ul> - <li><a href="qtdesignstudio-toc.html">All Topics</a></li> - <li><a href="studio-getting-started.html">Getting Started</a></li> - <li><a href="quick-uis.html">Wireframing</a></li> - <li><a href="qtquick-prototyping.html">Prototyping</a></li> - <li><a href="qtquick-motion-design.html">Motion Design</a></li> - <li><a href="studio-implementing-applications.html">Implementing Applications</a></li> - <li><a href="studio-advanced.html">Advanced Designer Topics</a></li> - <li><a href="studio-developer-topics.html">Developer Topics</a></li> - <li><a href="studio-help.html">Help</a></li> + <li><a href="studio-getting-started.html">Overview</a></li> + <li><a href="studio-installation.html">Installing Qt Design Studio</a></li> + <li><a href="gstutorials.html">Tutorials</a></li> + <li><a href="creator-quick-tour.html">User Interface</a></li> + <li><a href="studio-projects.html">Creating Projects</a></li> + <li><a href="studio-use-cases.html">Use Cases</a></li> + <li><a href="studio-terms.html">Concepts and Terms</a></li> + <li><a href="best-practices.html">Best Practices</a></li> + <li><a href="studioexamples.html">Examples</a></li> </ul> </div> +</div> +<div class="sectionlist normallist"> + <div class="heading"> + <h2>Wireframing</h2> + </div> + <div class="indexboxcont indexboxbar"> + <ul> + <li><a href="quick-uis.html">Overview</a></li> + <li><a href="studio-app-flows.html">Designing Application Flows</a></li> + <li><a href="quick-components.html">Using Components</a></li> + <li><a href="qtquick-properties.html">Specifying Component Properties</a></li> + <li><a href="qtquick-positioning.html">Scalable Layouts</a></li> + <li><a href="qtquick-annotations.html">Annotating Designs</a></li> + </ul> + </div> +</div> +<div class="sectionlist normallist"> + <div class="heading"> + <h2>Prototyping</h2> + </div> + <ul> + <li><a href="qtquick-prototyping.html">Overview</a></li> + <li><a href="qtquick-creating-ui-logic.html">Creating UI Logic</a></li> + <li><a href="studio-simulation-overview.html">Simulating Complex Experiences</a></li> + <li><a href="qtquick-adding-dynamics.html">Dynamic Behaviors</a></li> + <li><a href="creator-live-preview.html">Validating with Target Hardware</a></li> + <li><a href="studio-exporting-and-importing.html">Asset Creation with Other Tools</a></li> + </ul> +</div> +<div class="sectionlist normallist"> + <div class="heading"> + <h2>Motion Design</h2> + </div> + <ul> + <li><a href="qtquick-motion-design.html">Overview</a></li> + <li><a href="quick-animation-overview.html">Introduction to Animation Techniques</a></li> + <li><a href="studio-timeline.html">Creating Timeline Animations</a></li> + <li><a href="qtquick-editing-easing-curves.html">Editing Easing Curves</a></li> + <li><a href="qtquick-production-quality-animation.html">Production Quality</a></li> + <li><a href="qtquick-optimizing-designs.html">Optimizing Designs</a></li> + </ul> +</div> +<div class="sectionlist normallist"> + <div class="heading"> + <h2>Implementing Applications</h2> + </div> + <ul> + <li><a href="studio-implementing-applications.html">Overview</a></li> + <li><a href="studio-designer-developer-workflow.html">Designer-Developer Workflow</a></li> + <li><a href="qtquick-text-editor.html">Coding</a></li> + <li><a href="studio-debugging.html">Debugging and Profiling</a></li> + </ul> +</div> +<div class="sectionlist normallist"> + <div class="heading"> + <h2>Advanced Designer Topics</h2> + </div> + <ul> + <li><a href="studio-advanced.html">Overview</a></li> + <li><a href="creator-quick-ui-forms.html">UI Files</a></li> + <li><a href="creator-telemetry.html">Manage Data Collection</a></li> + <li><a href="studio-packaging.html">Packaging Applications</a></li> + </ul> +</div> +<div class="sectionlist normallist"> + <div class="heading"> + <h2>Developer Topics</h2> + </div> + <ul> + <li><a href="studio-developer-topics.html">Overview</a></li> + <li><a href="creator-vcs-git.html">Using Git</a></li> + <li><a href="studio-porting-projects.html">Converting Qt 5 Projects into Qt 6 Projects</a></li> + <li><a href="quick-converting-ui-projects.html">Converting UI Projects to Applications</a></li> + <li><a href="creator-editor-external.html">Using External Tools</a></li> + <li><a href="studio-on-mcus.html">Qt Design Studio on MCUs</a></li> + </ul> +</div> +<div class="sectionlist normallist"> + <div class="heading"> + <h2>Help</h2> + </div> + <ul> + <li><a href="studio-help.html">Overview</a></li> + <li><a href="creator-how-to-get-help.html">Getting Help</a></li> + <li><a href="studio-platforms.html">Supported Platforms</a></li> + </ul> +</div> diff --git a/doc/qtdesignstudio/examples/doc/FresnelExample.qdoc b/doc/qtdesignstudio/examples/doc/FresnelExample.qdoc new file mode 100644 index 0000000000..8dbc8bcfbf --- /dev/null +++ b/doc/qtdesignstudio/examples/doc/FresnelExample.qdoc @@ -0,0 +1,90 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page fresnel-effect-example.html + \ingroup studioexamples + + \title Fresnel Example + \brief Illustrates how to work with the fresnel effect. + + \image fresnel-example.webp + + The \e{Fresnel} example illustrates how to add and adjust a fresnel effect on + a 3D model. + + The fresnel effect affects how materials reflect light at different viewing angles. Imagine the + water on a lake. If you look down at the water from straight above, you can see through the + water, but if you look from a lower angle, the reflections are stronger. + + \image fresnel-angle.webp + + \section1 Running the Example + + To run the example in \QDS, go to the \uicontrol Welcome screen and select the example + from the \uicontrol Examples tab. + + \section1 The 3D Scene + + The example project consists of a basic 3D scene with the following components: + + \list + \li A 3D model. + \li A directional light. + \li An HDR image used to light the scene (image-based lighting). + \endlist + + \section1 The Material + + The material on the 3D model in this example is a principled material with a + clearcoat. + + \section2 Clearcoat + + A clearcoat is an additional specular layer applied to the surface of a material. The + clearcoating is transparent and doesn't add any color to the material, but it affects + how light interacts with the material. + + You adjust clearcoat properties independently from the base material. + + \section2 Fresnel Properties + + The following properties affect how the fresnel effect renders. These properties are + available both for the base material and the clearcoat layer. Adjusting the settings for the + clearcoat has a bigger visual effect. + + \table + \header + \li Property + \li Description + \row + \li Fresnel power + \li Increasing the fresnel power decreases the head-on reflections (steep viewing angle) + while maintaining the reflections seen from more shallow viewing angles. + \row + \li Enable scale and bias + \li Takes the scale and bias properties into account. + \row + \li Scale + \li Determines the rate of change in reflection intensity as the viewing angle varies. A + large scale value results in a gentler transition between weak and strong reflections, while + a smaller scale creates a more abrupt shift in reflection intensity. + \row + \li Bias + \li Controls the offset for the fresnel power property and determines how quickly the + reflection transitions from weak to strong as the viewing + angle changes. A larger bias value shifts the transition point toward steeper angles. + \endtable + + \section3 Adjusting the Fresnel Settings + + To adjust the settings: + + \list 1 + \li In \uicontrol {Material Browser}, double-click \e {Monkey Material}. + \li In \uicontrol {Material Editor}, find the properties under + \uicontrol {Clearcoat} and \uicontrol {Fresnel} respectively. + \endlist + + \note You see the changes live as you edit them in the \uicontrol 2D view. +*/ diff --git a/doc/qtdesignstudio/examples/doc/images/fresnel-angle.webp b/doc/qtdesignstudio/examples/doc/images/fresnel-angle.webp Binary files differnew file mode 100644 index 0000000000..2fe11380f0 --- /dev/null +++ b/doc/qtdesignstudio/examples/doc/images/fresnel-angle.webp diff --git a/doc/qtdesignstudio/examples/doc/images/fresnel-example.webp b/doc/qtdesignstudio/examples/doc/images/fresnel-example.webp Binary files differnew file mode 100644 index 0000000000..75436595aa --- /dev/null +++ b/doc/qtdesignstudio/examples/doc/images/fresnel-example.webp diff --git a/doc/qtdesignstudio/examples/doc/rainSnowParticles.qdoc b/doc/qtdesignstudio/examples/doc/rainSnowParticles.qdoc index 88dbd5fbdb..5cc040d427 100644 --- a/doc/qtdesignstudio/examples/doc/rainSnowParticles.qdoc +++ b/doc/qtdesignstudio/examples/doc/rainSnowParticles.qdoc @@ -41,7 +41,7 @@ Now you have added a particle system to your scene. - \image rain-snow-tutorial-particle-system + \image rain-snow-tutorial-particle-system.png \section2 Adjusting the Behavior and Apperance of the Particle System Next, you adjust the position, behavior, and apperance of the particle diff --git a/doc/qtdesignstudio/images/3d-view-context-menu.png b/doc/qtdesignstudio/images/3d-view-context-menu.png Binary files differdeleted file mode 100644 index 5b08c568cb..0000000000 --- a/doc/qtdesignstudio/images/3d-view-context-menu.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/3d-view-context-menu.webp b/doc/qtdesignstudio/images/3d-view-context-menu.webp Binary files differnew file mode 100644 index 0000000000..1b58f9bded --- /dev/null +++ b/doc/qtdesignstudio/images/3d-view-context-menu.webp diff --git a/doc/qtdesignstudio/images/bleed-scale-1.webp b/doc/qtdesignstudio/images/bleed-scale-1.webp Binary files differnew file mode 100644 index 0000000000..cfe9d7bd7e --- /dev/null +++ b/doc/qtdesignstudio/images/bleed-scale-1.webp diff --git a/doc/qtdesignstudio/images/bleed-scale-8.webp b/doc/qtdesignstudio/images/bleed-scale-8.webp Binary files differnew file mode 100644 index 0000000000..3d4ef0b783 --- /dev/null +++ b/doc/qtdesignstudio/images/bleed-scale-8.webp diff --git a/doc/qtdesignstudio/images/bleed-scale-no.webp b/doc/qtdesignstudio/images/bleed-scale-no.webp Binary files differnew file mode 100644 index 0000000000..e102ae7501 --- /dev/null +++ b/doc/qtdesignstudio/images/bleed-scale-no.webp diff --git a/doc/qtdesignstudio/images/camera-look-at-node.webp b/doc/qtdesignstudio/images/camera-look-at-node.webp Binary files differnew file mode 100644 index 0000000000..e5a92308a3 --- /dev/null +++ b/doc/qtdesignstudio/images/camera-look-at-node.webp diff --git a/doc/qtdesignstudio/images/edit-list-model-model-editor.webp b/doc/qtdesignstudio/images/edit-list-model-model-editor.webp Binary files differnew file mode 100644 index 0000000000..e7f47c6402 --- /dev/null +++ b/doc/qtdesignstudio/images/edit-list-model-model-editor.webp diff --git a/doc/qtdesignstudio/images/ext-scene-env-navigator.webp b/doc/qtdesignstudio/images/ext-scene-env-navigator.webp Binary files differnew file mode 100644 index 0000000000..675a9aedfc --- /dev/null +++ b/doc/qtdesignstudio/images/ext-scene-env-navigator.webp diff --git a/doc/qtdesignstudio/images/filesystem-view-design.webp b/doc/qtdesignstudio/images/filesystem-view-design.webp Binary files differnew file mode 100644 index 0000000000..8d59b85482 --- /dev/null +++ b/doc/qtdesignstudio/images/filesystem-view-design.webp diff --git a/doc/qtdesignstudio/images/glow-additive-blend.webp b/doc/qtdesignstudio/images/glow-additive-blend.webp Binary files differnew file mode 100644 index 0000000000..418628fc8b --- /dev/null +++ b/doc/qtdesignstudio/images/glow-additive-blend.webp diff --git a/doc/qtdesignstudio/images/glow-bicubic.webp b/doc/qtdesignstudio/images/glow-bicubic.webp Binary files differnew file mode 100644 index 0000000000..216a248708 --- /dev/null +++ b/doc/qtdesignstudio/images/glow-bicubic.webp diff --git a/doc/qtdesignstudio/images/glow-example-project.webp b/doc/qtdesignstudio/images/glow-example-project.webp Binary files differnew file mode 100644 index 0000000000..2163fee2d9 --- /dev/null +++ b/doc/qtdesignstudio/images/glow-example-project.webp diff --git a/doc/qtdesignstudio/images/glow-example.webp b/doc/qtdesignstudio/images/glow-example.webp Binary files differnew file mode 100644 index 0000000000..4de776aa44 --- /dev/null +++ b/doc/qtdesignstudio/images/glow-example.webp diff --git a/doc/qtdesignstudio/images/glow-high-quality.webp b/doc/qtdesignstudio/images/glow-high-quality.webp Binary files differnew file mode 100644 index 0000000000..80434dde67 --- /dev/null +++ b/doc/qtdesignstudio/images/glow-high-quality.webp diff --git a/doc/qtdesignstudio/images/glow-no-enhancment.webp b/doc/qtdesignstudio/images/glow-no-enhancment.webp Binary files differnew file mode 100644 index 0000000000..87d90da35f --- /dev/null +++ b/doc/qtdesignstudio/images/glow-no-enhancment.webp diff --git a/doc/qtdesignstudio/images/glow-properties.webp b/doc/qtdesignstudio/images/glow-properties.webp Binary files differnew file mode 100644 index 0000000000..b2d22736eb --- /dev/null +++ b/doc/qtdesignstudio/images/glow-properties.webp diff --git a/doc/qtdesignstudio/images/glow-replace-blend.webp b/doc/qtdesignstudio/images/glow-replace-blend.webp Binary files differnew file mode 100644 index 0000000000..06c8e8c669 --- /dev/null +++ b/doc/qtdesignstudio/images/glow-replace-blend.webp diff --git a/doc/qtdesignstudio/images/glow-screen-blend.webp b/doc/qtdesignstudio/images/glow-screen-blend.webp Binary files differnew file mode 100644 index 0000000000..6a18367cb9 --- /dev/null +++ b/doc/qtdesignstudio/images/glow-screen-blend.webp diff --git a/doc/qtdesignstudio/images/glow-softlight-blend.webp b/doc/qtdesignstudio/images/glow-softlight-blend.webp Binary files differnew file mode 100644 index 0000000000..3ac9ef2640 --- /dev/null +++ b/doc/qtdesignstudio/images/glow-softlight-blend.webp diff --git a/doc/qtdesignstudio/images/glow_all_blur_levels.webp b/doc/qtdesignstudio/images/glow_all_blur_levels.webp Binary files differnew file mode 100644 index 0000000000..a5cc30d9cc --- /dev/null +++ b/doc/qtdesignstudio/images/glow_all_blur_levels.webp diff --git a/doc/qtdesignstudio/images/glow_high_blur_levels.webp b/doc/qtdesignstudio/images/glow_high_blur_levels.webp Binary files differnew file mode 100644 index 0000000000..7cdf15a5c5 --- /dev/null +++ b/doc/qtdesignstudio/images/glow_high_blur_levels.webp diff --git a/doc/qtdesignstudio/images/glow_low_blur_levels.webp b/doc/qtdesignstudio/images/glow_low_blur_levels.webp Binary files differnew file mode 100644 index 0000000000..a59ed6cd7e --- /dev/null +++ b/doc/qtdesignstudio/images/glow_low_blur_levels.webp diff --git a/doc/qtdesignstudio/images/icons/add_material.png b/doc/qtdesignstudio/images/icons/add_material.png Binary files differnew file mode 100644 index 0000000000..6ecb64a180 --- /dev/null +++ b/doc/qtdesignstudio/images/icons/add_material.png diff --git a/doc/qtdesignstudio/images/icons/add_texture.png b/doc/qtdesignstudio/images/icons/add_texture.png Binary files differnew file mode 100644 index 0000000000..8b94da637d --- /dev/null +++ b/doc/qtdesignstudio/images/icons/add_texture.png diff --git a/doc/qtdesignstudio/images/icons/camera_speed.png b/doc/qtdesignstudio/images/icons/camera_speed.png Binary files differnew file mode 100644 index 0000000000..6fcabb05c8 --- /dev/null +++ b/doc/qtdesignstudio/images/icons/camera_speed.png diff --git a/doc/qtdesignstudio/images/icons/easing-curve-spline.png b/doc/qtdesignstudio/images/icons/easing-curve-spline.png Binary files differnew file mode 100644 index 0000000000..d76bf15f21 --- /dev/null +++ b/doc/qtdesignstudio/images/icons/easing-curve-spline.png diff --git a/doc/qtdesignstudio/images/icons/easing-curve-spline-icon.png b/doc/qtdesignstudio/images/icons/easing-curve-unify.png Binary files differindex c5328bed8a..c5328bed8a 100644 --- a/doc/qtdesignstudio/images/icons/easing-curve-spline-icon.png +++ b/doc/qtdesignstudio/images/icons/easing-curve-unify.png diff --git a/doc/qtdesignstudio/images/icons/export.png b/doc/qtdesignstudio/images/icons/export.png Binary files differnew file mode 100644 index 0000000000..6d6f15bd4a --- /dev/null +++ b/doc/qtdesignstudio/images/icons/export.png diff --git a/doc/qtdesignstudio/images/icons/import.png b/doc/qtdesignstudio/images/icons/import.png Binary files differnew file mode 100644 index 0000000000..b4ca149761 --- /dev/null +++ b/doc/qtdesignstudio/images/icons/import.png diff --git a/doc/qtdesignstudio/images/icons/reverse_order.png b/doc/qtdesignstudio/images/icons/reverse_order.png Binary files differnew file mode 100644 index 0000000000..5e661b29cc --- /dev/null +++ b/doc/qtdesignstudio/images/icons/reverse_order.png diff --git a/doc/qtdesignstudio/images/material-editor-browser.webp b/doc/qtdesignstudio/images/material-editor-browser.webp Binary files differindex 160c96e877..1865bf8a54 100644 --- a/doc/qtdesignstudio/images/material-editor-browser.webp +++ b/doc/qtdesignstudio/images/material-editor-browser.webp diff --git a/doc/qtdesignstudio/images/materials-remove-material.png b/doc/qtdesignstudio/images/materials-remove-material.png Binary files differdeleted file mode 100644 index 9ef0a91e5b..0000000000 --- a/doc/qtdesignstudio/images/materials-remove-material.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/materials-remove-material.webp b/doc/qtdesignstudio/images/materials-remove-material.webp Binary files differnew file mode 100644 index 0000000000..64d1d19891 --- /dev/null +++ b/doc/qtdesignstudio/images/materials-remove-material.webp diff --git a/doc/qtdesignstudio/images/model-editor-new-model.webp b/doc/qtdesignstudio/images/model-editor-new-model.webp Binary files differnew file mode 100644 index 0000000000..6ea705a047 --- /dev/null +++ b/doc/qtdesignstudio/images/model-editor-new-model.webp diff --git a/doc/qtdesignstudio/images/navigator-material-texture.png b/doc/qtdesignstudio/images/navigator-material-texture.png Binary files differdeleted file mode 100644 index 849625e1eb..0000000000 --- a/doc/qtdesignstudio/images/navigator-material-texture.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/navigator-material-texture.webp b/doc/qtdesignstudio/images/navigator-material-texture.webp Binary files differnew file mode 100644 index 0000000000..5ac9152627 --- /dev/null +++ b/doc/qtdesignstudio/images/navigator-material-texture.webp diff --git a/doc/qtdesignstudio/images/open-documents-view.webp b/doc/qtdesignstudio/images/open-documents-view.webp Binary files differnew file mode 100644 index 0000000000..c3080b92b5 --- /dev/null +++ b/doc/qtdesignstudio/images/open-documents-view.webp diff --git a/doc/qtdesignstudio/images/projects-view-design.webp b/doc/qtdesignstudio/images/projects-view-design.webp Binary files differnew file mode 100644 index 0000000000..6fd1e6333c --- /dev/null +++ b/doc/qtdesignstudio/images/projects-view-design.webp diff --git a/doc/qtdesignstudio/images/qmldesigner-canvas-color.png b/doc/qtdesignstudio/images/qmldesigner-canvas-color.png Binary files differdeleted file mode 100644 index 6baef3eb90..0000000000 --- a/doc/qtdesignstudio/images/qmldesigner-canvas-color.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/qmldesigner-canvas-color.webp b/doc/qtdesignstudio/images/qmldesigner-canvas-color.webp Binary files differnew file mode 100644 index 0000000000..3474076844 --- /dev/null +++ b/doc/qtdesignstudio/images/qmldesigner-canvas-color.webp diff --git a/doc/qtdesignstudio/images/qmldesigner-element-properties.png b/doc/qtdesignstudio/images/qmldesigner-element-properties.png Binary files differdeleted file mode 100644 index 0a8c4a1041..0000000000 --- a/doc/qtdesignstudio/images/qmldesigner-element-properties.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/qmldesigner-element-properties.webp b/doc/qtdesignstudio/images/qmldesigner-element-properties.webp Binary files differnew file mode 100644 index 0000000000..a90062d6be --- /dev/null +++ b/doc/qtdesignstudio/images/qmldesigner-element-properties.webp diff --git a/doc/qtdesignstudio/images/qmldesigner-form-editor-move-cursor.png b/doc/qtdesignstudio/images/qmldesigner-form-editor-move-cursor.png Binary files differdeleted file mode 100644 index 018a94c88f..0000000000 --- a/doc/qtdesignstudio/images/qmldesigner-form-editor-move-cursor.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/qmldesigner-form-editor-move-cursor.webp b/doc/qtdesignstudio/images/qmldesigner-form-editor-move-cursor.webp Binary files differnew file mode 100644 index 0000000000..a1b7f83e8d --- /dev/null +++ b/doc/qtdesignstudio/images/qmldesigner-form-editor-move-cursor.webp diff --git a/doc/qtdesignstudio/images/qmldesigner-form-editor.png b/doc/qtdesignstudio/images/qmldesigner-form-editor.png Binary files differdeleted file mode 100644 index f32f6965ba..0000000000 --- a/doc/qtdesignstudio/images/qmldesigner-form-editor.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/qmldesigner-form-editor.webp b/doc/qtdesignstudio/images/qmldesigner-form-editor.webp Binary files differnew file mode 100644 index 0000000000..b360c5c241 --- /dev/null +++ b/doc/qtdesignstudio/images/qmldesigner-form-editor.webp diff --git a/doc/qtdesignstudio/images/qmldesigner-preview-size.png b/doc/qtdesignstudio/images/qmldesigner-preview-size.png Binary files differdeleted file mode 100644 index 1a4a5e01ee..0000000000 --- a/doc/qtdesignstudio/images/qmldesigner-preview-size.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/qmldesigner-preview-size.webp b/doc/qtdesignstudio/images/qmldesigner-preview-size.webp Binary files differnew file mode 100644 index 0000000000..37f0c32ecf --- /dev/null +++ b/doc/qtdesignstudio/images/qmldesigner-preview-size.webp diff --git a/doc/qtdesignstudio/images/qmldesigner-snap-margins.png b/doc/qtdesignstudio/images/qmldesigner-snap-margins.png Binary files differdeleted file mode 100644 index 703ed8cc9a..0000000000 --- a/doc/qtdesignstudio/images/qmldesigner-snap-margins.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/qmldesigner-snap-margins.webp b/doc/qtdesignstudio/images/qmldesigner-snap-margins.webp Binary files differnew file mode 100644 index 0000000000..c6ea462063 --- /dev/null +++ b/doc/qtdesignstudio/images/qmldesigner-snap-margins.webp diff --git a/doc/qtdesignstudio/images/qmldesigner-transition-editor-startup.png b/doc/qtdesignstudio/images/qmldesigner-transition-editor-startup.png Binary files differdeleted file mode 100644 index d269470e0d..0000000000 --- a/doc/qtdesignstudio/images/qmldesigner-transition-editor-startup.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/qmldesigner-transition-editor-startup.webp b/doc/qtdesignstudio/images/qmldesigner-transition-editor-startup.webp Binary files differnew file mode 100644 index 0000000000..a246e48411 --- /dev/null +++ b/doc/qtdesignstudio/images/qmldesigner-transition-editor-startup.webp diff --git a/doc/qtdesignstudio/images/qmldesigner-transitions.webp b/doc/qtdesignstudio/images/qmldesigner-transitions.webp Binary files differnew file mode 100644 index 0000000000..ca4aae53ff --- /dev/null +++ b/doc/qtdesignstudio/images/qmldesigner-transitions.webp diff --git a/doc/qtdesignstudio/images/qmldesigner-zooming.gif b/doc/qtdesignstudio/images/qmldesigner-zooming.gif Binary files differindex d8d5beb6b3..82de8223be 100644 --- a/doc/qtdesignstudio/images/qmldesigner-zooming.gif +++ b/doc/qtdesignstudio/images/qmldesigner-zooming.gif diff --git a/doc/qtdesignstudio/images/qtcreator-qt-design-studio-project.webp b/doc/qtdesignstudio/images/qtcreator-qt-design-studio-project.webp Binary files differnew file mode 100644 index 0000000000..3e98d42ce2 --- /dev/null +++ b/doc/qtdesignstudio/images/qtcreator-qt-design-studio-project.webp diff --git a/doc/qtdesignstudio/images/qtquick-assets-tab.png b/doc/qtdesignstudio/images/qtquick-assets-tab.png Binary files differdeleted file mode 100644 index 11c4fe54b4..0000000000 --- a/doc/qtdesignstudio/images/qtquick-assets-tab.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/qtquick-assets-tab.webp b/doc/qtdesignstudio/images/qtquick-assets-tab.webp Binary files differnew file mode 100644 index 0000000000..2e65a7edd9 --- /dev/null +++ b/doc/qtdesignstudio/images/qtquick-assets-tab.webp diff --git a/doc/qtdesignstudio/images/qtquick-designer-rotating-items.png b/doc/qtdesignstudio/images/qtquick-designer-rotating-items.png Binary files differdeleted file mode 100644 index f20669be4e..0000000000 --- a/doc/qtdesignstudio/images/qtquick-designer-rotating-items.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/qtquick-designer-rotating-items.webp b/doc/qtdesignstudio/images/qtquick-designer-rotating-items.webp Binary files differnew file mode 100644 index 0000000000..17a3a664c0 --- /dev/null +++ b/doc/qtdesignstudio/images/qtquick-designer-rotating-items.webp diff --git a/doc/qtdesignstudio/images/qtquick-designer-scaling-items.png b/doc/qtdesignstudio/images/qtquick-designer-scaling-items.png Binary files differdeleted file mode 100644 index 891915dae8..0000000000 --- a/doc/qtdesignstudio/images/qtquick-designer-scaling-items.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/qtquick-designer-scaling-items.webp b/doc/qtdesignstudio/images/qtquick-designer-scaling-items.webp Binary files differnew file mode 100644 index 0000000000..cabbd7e02a --- /dev/null +++ b/doc/qtdesignstudio/images/qtquick-designer-scaling-items.webp diff --git a/doc/qtdesignstudio/images/qtquick-item-properties-common.png b/doc/qtdesignstudio/images/qtquick-item-properties-common.png Binary files differdeleted file mode 100644 index 6311b1ce58..0000000000 --- a/doc/qtdesignstudio/images/qtquick-item-properties-common.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/qtquick-item-properties-common.webp b/doc/qtdesignstudio/images/qtquick-item-properties-common.webp Binary files differnew file mode 100644 index 0000000000..5177534146 --- /dev/null +++ b/doc/qtdesignstudio/images/qtquick-item-properties-common.webp diff --git a/doc/qtdesignstudio/images/qtquick-library-context-menu.png b/doc/qtdesignstudio/images/qtquick-library-context-menu.png Binary files differdeleted file mode 100644 index f611ea6f1c..0000000000 --- a/doc/qtdesignstudio/images/qtquick-library-context-menu.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/qtquick-library-context-menu.webp b/doc/qtdesignstudio/images/qtquick-library-context-menu.webp Binary files differnew file mode 100644 index 0000000000..32fce38c93 --- /dev/null +++ b/doc/qtdesignstudio/images/qtquick-library-context-menu.webp diff --git a/doc/qtdesignstudio/images/qtquick-transition-editor-settings.png b/doc/qtdesignstudio/images/qtquick-transition-editor-settings.png Binary files differdeleted file mode 100644 index a0fef65a51..0000000000 --- a/doc/qtdesignstudio/images/qtquick-transition-editor-settings.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/qtquick-transition-editor-settings.webp b/doc/qtdesignstudio/images/qtquick-transition-editor-settings.webp Binary files differnew file mode 100644 index 0000000000..71734e3eaa --- /dev/null +++ b/doc/qtdesignstudio/images/qtquick-transition-editor-settings.webp diff --git a/doc/qtdesignstudio/images/qtquick-transition-editor-view.png b/doc/qtdesignstudio/images/qtquick-transition-editor-view.png Binary files differdeleted file mode 100644 index 3d747783af..0000000000 --- a/doc/qtdesignstudio/images/qtquick-transition-editor-view.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/qtquick-transition-editor-view.webp b/doc/qtdesignstudio/images/qtquick-transition-editor-view.webp Binary files differnew file mode 100644 index 0000000000..b409b5d57f --- /dev/null +++ b/doc/qtdesignstudio/images/qtquick-transition-editor-view.webp diff --git a/doc/qtdesignstudio/images/repeater3d-listmodel-navigator.png b/doc/qtdesignstudio/images/repeater3d-listmodel-navigator.png Binary files differindex f4b3093bbb..302d7d397a 100644 --- a/doc/qtdesignstudio/images/repeater3d-listmodel-navigator.png +++ b/doc/qtdesignstudio/images/repeater3d-listmodel-navigator.png diff --git a/doc/qtdesignstudio/images/repeater3d-model-editor.webp b/doc/qtdesignstudio/images/repeater3d-model-editor.webp Binary files differnew file mode 100644 index 0000000000..e0e6087366 --- /dev/null +++ b/doc/qtdesignstudio/images/repeater3d-model-editor.webp diff --git a/doc/qtdesignstudio/images/studio-3d-editor-axis-helper.webp b/doc/qtdesignstudio/images/studio-3d-editor-axis-helper.webp Binary files differindex d0a13907e5..c1388d72ed 100644 --- a/doc/qtdesignstudio/images/studio-3d-editor-axis-helper.webp +++ b/doc/qtdesignstudio/images/studio-3d-editor-axis-helper.webp diff --git a/doc/qtdesignstudio/images/studio-3d-editor-move.webp b/doc/qtdesignstudio/images/studio-3d-editor-move.webp Binary files differindex d2ff9b9aac..ac40c5cf1a 100644 --- a/doc/qtdesignstudio/images/studio-3d-editor-move.webp +++ b/doc/qtdesignstudio/images/studio-3d-editor-move.webp diff --git a/doc/qtdesignstudio/images/studio-3d-editor-rotate.webp b/doc/qtdesignstudio/images/studio-3d-editor-rotate.webp Binary files differindex 7cd8fe1bf6..368a2d57fd 100644 --- a/doc/qtdesignstudio/images/studio-3d-editor-rotate.webp +++ b/doc/qtdesignstudio/images/studio-3d-editor-rotate.webp diff --git a/doc/qtdesignstudio/images/studio-3d-editor-scale.webp b/doc/qtdesignstudio/images/studio-3d-editor-scale.webp Binary files differindex be0270d34b..6523539449 100644 --- a/doc/qtdesignstudio/images/studio-3d-editor-scale.webp +++ b/doc/qtdesignstudio/images/studio-3d-editor-scale.webp diff --git a/doc/qtdesignstudio/images/studio-3d-editor.webp b/doc/qtdesignstudio/images/studio-3d-editor.webp Binary files differindex 903ad69b25..2218505917 100644 --- a/doc/qtdesignstudio/images/studio-3d-editor.webp +++ b/doc/qtdesignstudio/images/studio-3d-editor.webp diff --git a/doc/qtdesignstudio/images/studio-3d-properties-type.png b/doc/qtdesignstudio/images/studio-3d-properties-type.png Binary files differdeleted file mode 100644 index c0363d0233..0000000000 --- a/doc/qtdesignstudio/images/studio-3d-properties-type.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-3d-properties-type.webp b/doc/qtdesignstudio/images/studio-3d-properties-type.webp Binary files differnew file mode 100644 index 0000000000..7f353ff655 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-3d-properties-type.webp diff --git a/doc/qtdesignstudio/images/studio-3d-scene-environment-ambient-occlusion.webp b/doc/qtdesignstudio/images/studio-3d-scene-environment-ambient-occlusion.webp Binary files differnew file mode 100644 index 0000000000..91e01bc809 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-3d-scene-environment-ambient-occlusion.webp diff --git a/doc/qtdesignstudio/images/studio-3d-scene-environment-antialiasing.webp b/doc/qtdesignstudio/images/studio-3d-scene-environment-antialiasing.webp Binary files differnew file mode 100644 index 0000000000..a8cae264d3 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-3d-scene-environment-antialiasing.webp diff --git a/doc/qtdesignstudio/images/studio-3d-scene-environment-image-based-lighting.webp b/doc/qtdesignstudio/images/studio-3d-scene-environment-image-based-lighting.webp Binary files differnew file mode 100644 index 0000000000..d5a9da81fb --- /dev/null +++ b/doc/qtdesignstudio/images/studio-3d-scene-environment-image-based-lighting.webp diff --git a/doc/qtdesignstudio/images/studio-3d-scene-environment-light-probe.png b/doc/qtdesignstudio/images/studio-3d-scene-environment-light-probe.png Binary files differdeleted file mode 100644 index 7a062a2a36..0000000000 --- a/doc/qtdesignstudio/images/studio-3d-scene-environment-light-probe.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-3d-scene-environment-properties.png b/doc/qtdesignstudio/images/studio-3d-scene-environment-properties.png Binary files differdeleted file mode 100644 index 353e0c3584..0000000000 --- a/doc/qtdesignstudio/images/studio-3d-scene-environment-properties.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-3d-scene-environment-properties.webp b/doc/qtdesignstudio/images/studio-3d-scene-environment-properties.webp Binary files differnew file mode 100644 index 0000000000..bb3e62d716 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-3d-scene-environment-properties.webp diff --git a/doc/qtdesignstudio/images/studio-3d-split-view.webp b/doc/qtdesignstudio/images/studio-3d-split-view.webp Binary files differindex 630fdb48fe..aec301c91f 100644 --- a/doc/qtdesignstudio/images/studio-3d-split-view.webp +++ b/doc/qtdesignstudio/images/studio-3d-split-view.webp diff --git a/doc/qtdesignstudio/images/studio-curve-editor.png b/doc/qtdesignstudio/images/studio-curve-editor.png Binary files differdeleted file mode 100644 index 01cd7f5ab4..0000000000 --- a/doc/qtdesignstudio/images/studio-curve-editor.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-curve-editor.webp b/doc/qtdesignstudio/images/studio-curve-editor.webp Binary files differnew file mode 100644 index 0000000000..79624624d1 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-curve-editor.webp diff --git a/doc/qtdesignstudio/images/studio-effects-background-blur.webp b/doc/qtdesignstudio/images/studio-effects-background-blur.webp Binary files differnew file mode 100644 index 0000000000..b1fd217263 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-effects-background-blur.webp diff --git a/doc/qtdesignstudio/images/studio-effects-drop-shadow.webp b/doc/qtdesignstudio/images/studio-effects-drop-shadow.webp Binary files differnew file mode 100644 index 0000000000..7de04ead32 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-effects-drop-shadow.webp diff --git a/doc/qtdesignstudio/images/studio-effects-inner-shadow.webp b/doc/qtdesignstudio/images/studio-effects-inner-shadow.webp Binary files differnew file mode 100644 index 0000000000..3502903551 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-effects-inner-shadow.webp diff --git a/doc/qtdesignstudio/images/studio-effects-layer-blur.webp b/doc/qtdesignstudio/images/studio-effects-layer-blur.webp Binary files differnew file mode 100644 index 0000000000..32c2c66779 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-effects-layer-blur.webp diff --git a/doc/qtdesignstudio/images/studio-effects-show-shadow-behind.webp b/doc/qtdesignstudio/images/studio-effects-show-shadow-behind.webp Binary files differnew file mode 100644 index 0000000000..5b7411bd2c --- /dev/null +++ b/doc/qtdesignstudio/images/studio-effects-show-shadow-behind.webp diff --git a/doc/qtdesignstudio/images/studio-effects.webp b/doc/qtdesignstudio/images/studio-effects.webp Binary files differnew file mode 100644 index 0000000000..1910dc40af --- /dev/null +++ b/doc/qtdesignstudio/images/studio-effects.webp diff --git a/doc/qtdesignstudio/images/studio-ext-scene-environment.webp b/doc/qtdesignstudio/images/studio-ext-scene-environment.webp Binary files differnew file mode 100644 index 0000000000..cc26498c95 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-ext-scene-environment.webp diff --git a/doc/qtdesignstudio/images/studio-flow-action-area-properties.png b/doc/qtdesignstudio/images/studio-flow-action-area-properties.png Binary files differdeleted file mode 100644 index 9e69282fe8..0000000000 --- a/doc/qtdesignstudio/images/studio-flow-action-area-properties.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-flow-action-area-properties.webp b/doc/qtdesignstudio/images/studio-flow-action-area-properties.webp Binary files differnew file mode 100644 index 0000000000..e269557c16 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-flow-action-area-properties.webp diff --git a/doc/qtdesignstudio/images/studio-flow-action-area.png b/doc/qtdesignstudio/images/studio-flow-action-area.png Binary files differdeleted file mode 100644 index 531af8aab5..0000000000 --- a/doc/qtdesignstudio/images/studio-flow-action-area.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-flow-action-area.webp b/doc/qtdesignstudio/images/studio-flow-action-area.webp Binary files differnew file mode 100644 index 0000000000..f6d4c4d5f4 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-flow-action-area.webp diff --git a/doc/qtdesignstudio/images/studio-flow-decision-preview.png b/doc/qtdesignstudio/images/studio-flow-decision-preview.png Binary files differdeleted file mode 100644 index c0c367d143..0000000000 --- a/doc/qtdesignstudio/images/studio-flow-decision-preview.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-flow-decision-preview.webp b/doc/qtdesignstudio/images/studio-flow-decision-preview.webp Binary files differnew file mode 100644 index 0000000000..e3ac10b0b2 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-flow-decision-preview.webp diff --git a/doc/qtdesignstudio/images/studio-flow-decision-properties.png b/doc/qtdesignstudio/images/studio-flow-decision-properties.png Binary files differdeleted file mode 100644 index dbaba5338f..0000000000 --- a/doc/qtdesignstudio/images/studio-flow-decision-properties.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-flow-decision-properties.webp b/doc/qtdesignstudio/images/studio-flow-decision-properties.webp Binary files differnew file mode 100644 index 0000000000..4029d5cd19 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-flow-decision-properties.webp diff --git a/doc/qtdesignstudio/images/studio-flow-decision.png b/doc/qtdesignstudio/images/studio-flow-decision.png Binary files differdeleted file mode 100644 index 0880a14559..0000000000 --- a/doc/qtdesignstudio/images/studio-flow-decision.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-flow-decision.webp b/doc/qtdesignstudio/images/studio-flow-decision.webp Binary files differnew file mode 100644 index 0000000000..df7b18ab93 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-flow-decision.webp diff --git a/doc/qtdesignstudio/images/studio-flow-events-assign.png b/doc/qtdesignstudio/images/studio-flow-events-assign.png Binary files differdeleted file mode 100644 index c585dd8033..0000000000 --- a/doc/qtdesignstudio/images/studio-flow-events-assign.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-flow-events-assign.webp b/doc/qtdesignstudio/images/studio-flow-events-assign.webp Binary files differnew file mode 100644 index 0000000000..53468aca42 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-flow-events-assign.webp diff --git a/doc/qtdesignstudio/images/studio-flow-events-event-list.webp b/doc/qtdesignstudio/images/studio-flow-events-event-list.webp Binary files differnew file mode 100644 index 0000000000..b33b940812 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-flow-events-event-list.webp diff --git a/doc/qtdesignstudio/images/studio-flow-item-component.webp b/doc/qtdesignstudio/images/studio-flow-item-component.webp Binary files differnew file mode 100644 index 0000000000..8c1ea982b1 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-flow-item-component.webp diff --git a/doc/qtdesignstudio/images/studio-flow-item.png b/doc/qtdesignstudio/images/studio-flow-item.png Binary files differdeleted file mode 100644 index 905174d600..0000000000 --- a/doc/qtdesignstudio/images/studio-flow-item.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-flow-item.webp b/doc/qtdesignstudio/images/studio-flow-item.webp Binary files differnew file mode 100644 index 0000000000..1b3c54d818 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-flow-item.webp diff --git a/doc/qtdesignstudio/images/studio-flow-signal-list.png b/doc/qtdesignstudio/images/studio-flow-signal-list.png Binary files differdeleted file mode 100644 index 4af0a0e853..0000000000 --- a/doc/qtdesignstudio/images/studio-flow-signal-list.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-flow-signal-list.webp b/doc/qtdesignstudio/images/studio-flow-signal-list.webp Binary files differnew file mode 100644 index 0000000000..248f4f8590 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-flow-signal-list.webp diff --git a/doc/qtdesignstudio/images/studio-flow-states-item-properties.webp b/doc/qtdesignstudio/images/studio-flow-states-item-properties.webp Binary files differnew file mode 100644 index 0000000000..14e024dab5 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-flow-states-item-properties.webp diff --git a/doc/qtdesignstudio/images/studio-flow-transition-line-properties.png b/doc/qtdesignstudio/images/studio-flow-transition-line-properties.png Binary files differdeleted file mode 100644 index 93c948e7ec..0000000000 --- a/doc/qtdesignstudio/images/studio-flow-transition-line-properties.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-flow-transition-line-properties.webp b/doc/qtdesignstudio/images/studio-flow-transition-line-properties.webp Binary files differnew file mode 100644 index 0000000000..e56dfd218e --- /dev/null +++ b/doc/qtdesignstudio/images/studio-flow-transition-line-properties.webp diff --git a/doc/qtdesignstudio/images/studio-flow-transition-properties-question.png b/doc/qtdesignstudio/images/studio-flow-transition-properties-question.png Binary files differdeleted file mode 100644 index 80cb7ad1a9..0000000000 --- a/doc/qtdesignstudio/images/studio-flow-transition-properties-question.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-flow-transition-properties-question.webp b/doc/qtdesignstudio/images/studio-flow-transition-properties-question.webp Binary files differnew file mode 100644 index 0000000000..26250a17c1 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-flow-transition-properties-question.webp diff --git a/doc/qtdesignstudio/images/studio-flow-transition-properties.png b/doc/qtdesignstudio/images/studio-flow-transition-properties.png Binary files differdeleted file mode 100644 index e754f3012e..0000000000 --- a/doc/qtdesignstudio/images/studio-flow-transition-properties.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-flow-transition-properties.webp b/doc/qtdesignstudio/images/studio-flow-transition-properties.webp Binary files differnew file mode 100644 index 0000000000..a47a8977dd --- /dev/null +++ b/doc/qtdesignstudio/images/studio-flow-transition-properties.webp diff --git a/doc/qtdesignstudio/images/studio-flow-view-properties.png b/doc/qtdesignstudio/images/studio-flow-view-properties.png Binary files differdeleted file mode 100644 index 95fe403b76..0000000000 --- a/doc/qtdesignstudio/images/studio-flow-view-properties.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-flow-view-properties.webp b/doc/qtdesignstudio/images/studio-flow-view-properties.webp Binary files differnew file mode 100644 index 0000000000..7592e57954 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-flow-view-properties.webp diff --git a/doc/qtdesignstudio/images/studio-flow-view.png b/doc/qtdesignstudio/images/studio-flow-view.png Binary files differdeleted file mode 100644 index 1eda708fcb..0000000000 --- a/doc/qtdesignstudio/images/studio-flow-view.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-flow-view.webp b/doc/qtdesignstudio/images/studio-flow-view.webp Binary files differnew file mode 100644 index 0000000000..21db99f043 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-flow-view.webp diff --git a/doc/qtdesignstudio/images/studio-flow-wildcard-properties.png b/doc/qtdesignstudio/images/studio-flow-wildcard-properties.png Binary files differdeleted file mode 100644 index 944fd79431..0000000000 --- a/doc/qtdesignstudio/images/studio-flow-wildcard-properties.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-flow-wildcard-properties.webp b/doc/qtdesignstudio/images/studio-flow-wildcard-properties.webp Binary files differnew file mode 100644 index 0000000000..66ade49942 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-flow-wildcard-properties.webp diff --git a/doc/qtdesignstudio/images/studio-flow-wildcard.webp b/doc/qtdesignstudio/images/studio-flow-wildcard.webp Binary files differnew file mode 100644 index 0000000000..8c0805cedc --- /dev/null +++ b/doc/qtdesignstudio/images/studio-flow-wildcard.webp diff --git a/doc/qtdesignstudio/images/studio-project-cmake-generation.webp b/doc/qtdesignstudio/images/studio-project-cmake-generation.webp Binary files differnew file mode 100644 index 0000000000..18058f785a --- /dev/null +++ b/doc/qtdesignstudio/images/studio-project-cmake-generation.webp diff --git a/doc/qtdesignstudio/images/studio-project-export-advanced-options.webp b/doc/qtdesignstudio/images/studio-project-export-advanced-options.webp Binary files differdeleted file mode 100644 index 33be8549a7..0000000000 --- a/doc/qtdesignstudio/images/studio-project-export-advanced-options.webp +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-project-export-advanced.webp b/doc/qtdesignstudio/images/studio-project-export-advanced.webp Binary files differdeleted file mode 100644 index d6f1189093..0000000000 --- a/doc/qtdesignstudio/images/studio-project-export-advanced.webp +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-project-export.webp b/doc/qtdesignstudio/images/studio-project-export.webp Binary files differindex 8847dd945f..b79ce329ee 100644 --- a/doc/qtdesignstudio/images/studio-project-export.webp +++ b/doc/qtdesignstudio/images/studio-project-export.webp diff --git a/doc/qtdesignstudio/images/studio-project-wizards.png b/doc/qtdesignstudio/images/studio-project-wizards.png Binary files differdeleted file mode 100644 index 3a329bd16e..0000000000 --- a/doc/qtdesignstudio/images/studio-project-wizards.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-project-wizards.webp b/doc/qtdesignstudio/images/studio-project-wizards.webp Binary files differnew file mode 100644 index 0000000000..fcb7c22ff0 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-project-wizards.webp diff --git a/doc/qtdesignstudio/images/studio-qtquick-3d-components.png b/doc/qtdesignstudio/images/studio-qtquick-3d-components.png Binary files differdeleted file mode 100644 index 25974ab326..0000000000 --- a/doc/qtdesignstudio/images/studio-qtquick-3d-components.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-qtquick-3d-components.webp b/doc/qtdesignstudio/images/studio-qtquick-3d-components.webp Binary files differnew file mode 100644 index 0000000000..54be760fd2 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-qtquick-3d-components.webp diff --git a/doc/qtdesignstudio/images/studio-qtquick-3d-view.png b/doc/qtdesignstudio/images/studio-qtquick-3d-view.png Binary files differdeleted file mode 100644 index 9c0e8fc82b..0000000000 --- a/doc/qtdesignstudio/images/studio-qtquick-3d-view.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-qtquick-3d-view.webp b/doc/qtdesignstudio/images/studio-qtquick-3d-view.webp Binary files differnew file mode 100644 index 0000000000..7351317e10 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-qtquick-3d-view.webp diff --git a/doc/qtdesignstudio/images/studio-qtquick-camera-properties.webp b/doc/qtdesignstudio/images/studio-qtquick-camera-properties.webp Binary files differnew file mode 100644 index 0000000000..e54afe807e --- /dev/null +++ b/doc/qtdesignstudio/images/studio-qtquick-camera-properties.webp diff --git a/doc/qtdesignstudio/images/studio-timeline-empty.png b/doc/qtdesignstudio/images/studio-timeline-empty.png Binary files differdeleted file mode 100644 index 861a1021bb..0000000000 --- a/doc/qtdesignstudio/images/studio-timeline-empty.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/studio-timeline-empty.webp b/doc/qtdesignstudio/images/studio-timeline-empty.webp Binary files differnew file mode 100644 index 0000000000..16aa728a52 --- /dev/null +++ b/doc/qtdesignstudio/images/studio-timeline-empty.webp diff --git a/doc/qtdesignstudio/images/texture-editor.png b/doc/qtdesignstudio/images/texture-editor.png Binary files differdeleted file mode 100644 index e8eecbd13b..0000000000 --- a/doc/qtdesignstudio/images/texture-editor.png +++ /dev/null diff --git a/doc/qtdesignstudio/images/texture-editor.webp b/doc/qtdesignstudio/images/texture-editor.webp Binary files differnew file mode 100644 index 0000000000..092a6f0dab --- /dev/null +++ b/doc/qtdesignstudio/images/texture-editor.webp diff --git a/doc/qtdesignstudio/src/best practices/best-practices-glow.qdoc b/doc/qtdesignstudio/src/best practices/best-practices-glow.qdoc new file mode 100644 index 0000000000..22a71ec681 --- /dev/null +++ b/doc/qtdesignstudio/src/best practices/best-practices-glow.qdoc @@ -0,0 +1,200 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \previouspage best-practices.html + \page best-practices-glow.html + \nextpage {Examples} + + \title Creating Glow and Bloom Effects + + In \QDS, you can add a glow and bloom effect to your 3D scene using the + \uicontrol ExtendedSceneEnvironment component (available in Qt 6.5 and later). With this effect, + you can, for example, create glow around illuminated areas (such as material or skyboxes when + using image-based lighting) or add ambient light. Using the glow effect is one way to make your + scene more realistic. + + \image glow-example.webp + + \section1 Creating a Project with ExtendedSceneEnvironment + + To create a project with \uicontrol ExtendedSceneEnvironment as the default + scene environment, use the \uicontrol {3D Extended} project preset. + + For more information about creating projects, see \l{Creating Projects}. + + \section1 Adding ExtendedSceneEnvironment to an Existing Project + + To add \uicontrol {ExtendedSceneEnvironment} to an existing project, drag the + \uicontrol {ExtendedSceneEnvironment} component from \uicontrol Components to + the \uicontrol 2D or \uicontrol Navigator view. + + \image ext-scene-env-navigator.webp + + \section1 Enabling the Glow Effect + + To enable the glow effect, select \e SceneEnvironment in the \uicontrol Navigator view and + then, in the \uicontrol Properties view, select \uicontrol Enabled in the + \uicontrol Glow section. + + \image glow-properties.webp + + \note When setting up or experimenting with the glow effect, use the \l {Blend Modes}{Replace} + blend mode to see the effect more clearly. + + \section1 The Flashlight Example Project + + The flashlight example used in this documentation is available from the \uicontrol Examples + section of the \QDS \uicontrol Welcome page. + + You can use the project to experiment with the \uicontrol Glow properties. When you run the + project, you can control most properties with UI controls. Another way to experiment with + properties is to change them directly in the \uicontrol Properties view in \QDS and see the + changes live in the \uicontrol 2D view. + + \image glow-example-project.webp + + \section1 Basic Properties + + Usually, the best way to achieve a realistic glow effect in your 3D scene is to adjust + the \uicontrol {Strength}, \uicontrol {Intensity}, and \uicontrol {Bloom} + properties together. + + \section2 Strength + + Sets the strength of the glow. If this property has a 0 value, the glow effect is disabled. The + strength is a scale factor (multiplier) applied per level. This means that + with more levels enabled in \l {Blur Levels}, a larger \uicontrol {strength} value has + a more pronounced effect. + + \section2 Intensity + + Sets the intensity of the glow. The intensity is effectively a scale factor (multiplier) for the + accumulated glow color (including all levels). + + \section2 Bloom + + Sets the overall illumination of the whole scene. + + \section2 Lower Threshold + + Sets the minimum level of brightness for the glow. + + \section2 Upper Threshold + + Sets the maximum level of brightness for the glow. + + \section2 HDR Scale + + Sets how much the glow bleeds (or extends) beyond the borders of bright areas + in the scene. The range for this property is 0-8. As seen in the example images below, a high + value gives a very modest bleed, while a low number results in a much more visible bleed. + + \table + \header + \li HDR Scale + \li Example + \row + \li Bloom disabled + \li \image bleed-scale-no.webp + \row + \li 8 + \li \image bleed-scale-8.webp + \row + \li 1 + \li \image bleed-scale-1.webp + \endtable + + \section1 Blur Levels + + Sets which of the blur passes to apply to the glow effect. + + The higher the level is, the more the glow effect spreads around the light source, + and the softer the glow is. + + As seen in the example image below, lower blur levels produce an intense glow within a limited + area, while higher blur levels produce a softer glow in a more extensive area. Combine blur + levels to get the desired result. + + \table + \header + \li Blur level + \li Example + \row + \li 1, 2, 3 + \li \image glow_low_blur_levels.webp + \row + \li 5, 6, 7 + \li \image glow_high_blur_levels.webp + \row + \li 1, 2, 3, 4, 5, 6, 7 + \li \image glow_all_blur_levels.webp + \endtable + + \section2 Blend Modes + + The following blend modes are available: + + \table + \header + \li Blend mode + \li Description + \li Example + \row + \li Additive + \li Often recommended for outdoor scenes with a visible sky or sun. + \li \image glow-additive-blend.webp + \row + \li Screen + \li Similar to \uicontrol {Additive}, but the result is less bright. + \li \image glow-screen-blend.webp + \row + \li SoftLight + \li Often recommended for in-door environments. + \li \image glow-softlight-blend.webp + \row + \li Replace + \li Does not perform any blending, but displays only the contribution + the glow effect would blend with the actual content. In practice, this is useful for + experimenting and troubleshooting when setting up the glow effect. + \li \image glow-replace-blend.webp + \endtable + + \section1 Improvement Properties + + The \uicontrol{High Quality} and \uicontrol{Bicubical Upsampling} + properties improve the quality of the glow blur by upsampling. Using these properties + may slow down the performance of the application. You can also try using the + \uicontrol Dithering property in the \uicontrol sceneEnvironment instead. In some cases, + \uicontrol Dithering renders a similar result but at a lower cost. + + \section2 High Quality + + Increases the samples used for the glow when downsampling to improve the quality of the glow + effect. + + \section2 Bicubical Upsampling + + Reduces the aliasing artifacts and boxing in the glow effect. + + \section2 Examples + + These examples show a zoomed-in image of each effect: + + \table + \header + \li Effect + \li Example + \row + \li No effect + \li \image glow-no-enhancment.webp + \row + \li High Quality + \li \image glow-high-quality.webp + \row + \li Bicubic Upsampling + \li \image glow-bicubic.webp + \endtable + + +*/ diff --git a/doc/qtdesignstudio/src/best-practices.qdoc b/doc/qtdesignstudio/src/best-practices.qdoc new file mode 100644 index 0000000000..4abcc80f6a --- /dev/null +++ b/doc/qtdesignstudio/src/best-practices.qdoc @@ -0,0 +1,38 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \previouspage studio-terms.html + \page best-practices.html + \nextpage best-practices-glow.html + + \title Best Practices + + \section1 Graphics + + \list + \li \l {Creating Glow and Bloom Effects} + \endlist + + \section1 Performance + + \list + \li \l {Optimizing Designs} + \li \l {QML Performance Considerations And Suggestions} + \li \l {Creating Optimized 3D Scenes} + \li \l {Using Components Economically} + \endlist + + \section1 Projects + + \list + \li \l {Converting Qt 5 Projects into Qt 6 Projects} + \li \l {Converting UI Projects to Applications} + \endlist + + \section1 Workflow + + \list + \li \l {Designer-Developer Workflow} + \endlist +*/ diff --git a/doc/qtdesignstudio/src/components/qtquick-component-context-menu.qdocinc b/doc/qtdesignstudio/src/components/qtquick-component-context-menu.qdocinc index 34140b8894..7fb95a9880 100644 --- a/doc/qtdesignstudio/src/components/qtquick-component-context-menu.qdocinc +++ b/doc/qtdesignstudio/src/components/qtquick-component-context-menu.qdocinc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -26,7 +26,7 @@ \li Group \li \l{Organizing Components} \row - \li Position + \li Positioner \li \l{Using Positioners} \row \li Layout @@ -53,8 +53,8 @@ \li Move Component Instances into Separate Files \li \l{Turning Component Instances into Custom Components} \row - \li Add New Signal Handler - \li \l{Adding Signal Handlers} + \li Connecting Components to Signals + \li \l{Connecting Components to Signals in the Connection View} \row \li Go to Implementation \li \l{Using UI Files} diff --git a/doc/qtdesignstudio/src/components/qtquick-data-models.qdoc b/doc/qtdesignstudio/src/components/qtquick-data-models.qdoc index 400e264d02..b93b745bc2 100644 --- a/doc/qtdesignstudio/src/components/qtquick-data-models.qdoc +++ b/doc/qtdesignstudio/src/components/qtquick-data-models.qdoc @@ -142,17 +142,17 @@ To edit list models: \list 1 - \li Drag-and-drop a \uicontrol {Grid View} or \uicontrol {List View} + \li Drag a \uicontrol {Grid View} or \uicontrol {List View} from \uicontrol Components > \uicontrol {Default Components} > \uicontrol Views to the \uicontrol Navigator or \uicontrol {2D} view. \li Right-click the view in \uicontrol Navigator, and select - \uicontrol {Edit List Model} in the context-menu to open - the list model editor: - \image qtquick-designer-edit-list-model.png "List view in model editor" - \li Double-click the column headings and cells to change their values. - \li Use the toolbar buttons to add, remove, or move rows and columns. - In a list, each column represents a property and each row adds a + \uicontrol {Edit Model} in the context-menu to open the + \uicontrol {Model Editor} view. + \image edit-list-model-model-editor.webp "List view in Model Editor" + \li Double-click a cell to edit its value. + \li Use the toolbar buttons to add or remove rows and columns. + In a list, each column represents a property, and each row adds a list item. \endlist diff --git a/doc/qtdesignstudio/src/components/qtquick-images.qdoc b/doc/qtdesignstudio/src/components/qtquick-images.qdoc index 176e4409f8..cbece71a4b 100644 --- a/doc/qtdesignstudio/src/components/qtquick-images.qdoc +++ b/doc/qtdesignstudio/src/components/qtquick-images.qdoc @@ -44,6 +44,9 @@ If you need to display animated images, such as GIFs, use the \l {Animated Image} component. + \note Currently, the supported image formats include JPEG, JPG, PNG, SVG, + HDR, KTX, BMP, TTF, TIFF, WEBP, and GIF. + \section1 Image Size \image qtquick-designer-image-properties.png "Image properties" diff --git a/doc/qtdesignstudio/src/components/qtquick-preset-components.qdoc b/doc/qtdesignstudio/src/components/qtquick-preset-components.qdoc index 19ee8e60dd..267517cb6c 100644 --- a/doc/qtdesignstudio/src/components/qtquick-preset-components.qdoc +++ b/doc/qtdesignstudio/src/components/qtquick-preset-components.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -31,6 +31,7 @@ \li \l {UI Controls} \li \l {Lists and Other Data Models} \li \l {2D Effects} + \li \l {Design Effects} \li \l {Logic Helpers} \li \l Animations \endlist @@ -58,7 +59,7 @@ \li \l {Custom Effects and Materials} \li \l {Lights} \li \l {Cameras} - \li \l {Scene Environment} + \li \l {Scene Environments} \li \l {Morph Target} \li \l {Repeater3D} \li \l {Loader3D} diff --git a/doc/qtdesignstudio/src/developers/studio-designer-developer-workflow.qdoc b/doc/qtdesignstudio/src/developers/studio-designer-developer-workflow.qdoc index 0a6531fe12..e214b7709e 100644 --- a/doc/qtdesignstudio/src/developers/studio-designer-developer-workflow.qdoc +++ b/doc/qtdesignstudio/src/developers/studio-designer-developer-workflow.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -10,7 +10,7 @@ \note In this section, you are using advanced menu items. These are not visible by default. To toggle the visibility of advanced menu items, see - \l{Customizing the Menu}. + \l{Customizing the Menu Bar}. \QDS enables designers and developers to work together on common projects to develop applications. Designers use the \l{Design Views}{views} @@ -19,10 +19,6 @@ other files that are needed to implement the application logic and to prepare the application for production. - Use the \l{Using Git}{Git} version control system to ensure that changes - are not lost when files are passed back and forth between designers and - developers. - \QDS \l{Creating Projects}{projects} come with boilerplate code for a working Qt 6 application that you can build and run in Qt Creator using CMake. Therefore, you can open, build, and run the projects with Qt Creator. @@ -31,58 +27,53 @@ \e CMakeLists.txt file as the project file. This enables you to share your project as a fully working C++ application with developers. - If you use Git, you can clone an example project - \l{https://git.qt.io/public-demos/qtdesign-studio/-/tree/master/playground/AuroraCluster0} - {here}. - - \section1 Exporting a \QDS Project - - \QDS uses a different project format than Qt Creator. \QDS does not build the project, - it uses a pre-compiled \l{QML runtime} to run the project. To export a \QDS project for the - Qt Creator, follow the process: + To export a \QDS project for Qt Creator, you need: - \list 1 - \li Open the project you want to export in \QDS. - \li Select \uicontrol {File} > \uicontrol {Export Project} > \uicontrol {Generate CMake Build Files}. - \image studio-project-export.webp "Export the \QDS project for Qt Creator" + \list + \li Qt Creator 13.0 or above. + \li \QDS 4.5 or above. + \endlist - \li Select \uicontrol {Details} to access the \l {Advanced Options}. - \image studio-project-export-advanced.webp "Access Advanced Options in the project exporter" + \section1 Exporting a \QDS Project - \note The project exporter has default settings selected. This works better if the project - is combined with an existing Qt project. + \list 1 + \li \l {Creating a Project} {Create} or open your \QDS project with \QDS 4.5 or above. - \li Select all the options here. This allows to export the - complete project. So, it can be compiled as a stand-alone application. - \image studio-project-export-advanced-options.webp "Select all the options in the project exporter" + \note If you are creating a new project in \QDS, select the + \uicontrol {Target Qt Version} that is not higher than the Qt version + used in your Qt Creator. - \note If you copy this export on top of the existing Qt Creator project - it overwrites the existing project. Hence, the default selected options in - the exporter only exports the QML-specific items. You get a list of - warnings at the bottom part of the exporter that denotes exactly which parts - of the project gets overwritten. - \endlist + \li Go to \uicontrol {File} > \uicontrol {Export Project} + > \uicontrol {Enable Automatic CMake Generation}. This creates a + \e {CMakeLists.txt} file in your project folder. - \section1 Using the Exported Project in Qt Creator + \note Enabling this option tracks the changes made to the project in Qt Creator + and automatically updates in \QDS. The connection works unless you + deactivate the option. - After exporting the project from the \QDS, you have to open it from Qt Creator. + \image studio-project-export.webp "Exporting Qt Design Studio project" + \endlist - If you have used any version before \QDS 4.0 to create the project, manually include this code - in the \l {CMakeLists.txt} file so the exported project works in Qt Creator. + \section1 Opening the \QDS Project in Qt Creator - \code - set(BUILD_QDS_COMPONENTS ON CACHE BOOL "Build design studio components") + Open the \e {CMakeLists.txt} file in Qt Creator. To open: - set(CMAKE_INCLUDE_CURRENT_DIR ON) + \list 1 + \li In Qt Creator, select \uicontrol File > \uicontrol {Open File or Project}. + \li Browse through your project directory and select the \e {CMakeLists.txt}. + Then select \uicontrol Open. - if (${BUILD_QDS_COMPONENTS}) - include(${CMAKE_CURRENT_SOURCE_DIR}/qmlcomponents) - endif () + \image studio-project-cmake-generation.webp "Project folder after CMake generation" - include(${CMAKE_CURRENT_SOURCE_DIR}/qmlmodules) - \endcode + \li Select the Qt version and then \uicontrol {Configure Project}. - \note If you have created the project with the \QDS version 4.0 or above, you already have this code in - \l {CMakeLists.txt} by default. + \note If your \QDS project was created with a more updated Qt than the one + available in Qt Creator, the import doesn't work. Use + \l {Get and Install Qt with Qt Online Installer} {Qt Online Installer} + to install the latest Qt version. If successfully opened, all the files are + accessible in the \uicontrol Projects view. + \image qtcreator-qt-design-studio-project.webp "Qt Design studio projects in Qt Creator after successful import" + \li To run the project, select \uicontrol Run. + \endlist */ diff --git a/doc/qtcreator/src/qtquick/qtquick-live-preview-desktop.qdoc b/doc/qtdesignstudio/src/how-to/qtdesignstudio-live-preview-desktop.qdoc index 2f939c69cb..0178d7f666 100644 --- a/doc/qtcreator/src/qtquick/qtquick-live-preview-desktop.qdoc +++ b/doc/qtdesignstudio/src/how-to/qtdesignstudio-live-preview-desktop.qdoc @@ -2,8 +2,8 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \previouspage creator-live-preview.html - \page creator-live-preview-desktop.html + \page studio-live-preview-desktop.html + \previouspage studio-live-preview.html \nextpage creator-live-preview-devices.html \title Previewing on Desktop @@ -11,16 +11,9 @@ 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 + \image studio-live-preview.webp \endlist To preview any QML file in the project: @@ -31,9 +24,12 @@ \uicontrol {Preview File}. \endlist - To preview the whole UI, select \uicontrol {Live Preview} + To preview the whole application, select \uicontrol {Live Preview} when viewing the main QML file of the project. + To preview the application in a different zoom level, right-click the \uicontrol {Live Preview} + button and select the zoom level. + \section1 Overriding the Preview Tool By default, the QML runtime is used for previewing. @@ -47,5 +43,4 @@ \li In \uicontrol {Override device QML viewer}, select the folder where the preview tool executable is located. \endlist - \endif */ diff --git a/doc/qtdesignstudio/src/mcus/qtdesignstudio-compatibility-with-mcu-sdks.qdoc b/doc/qtdesignstudio/src/mcus/qtdesignstudio-compatibility-with-mcu-sdks.qdoc index de94f59d80..0e833cead1 100644 --- a/doc/qtdesignstudio/src/mcus/qtdesignstudio-compatibility-with-mcu-sdks.qdoc +++ b/doc/qtdesignstudio/src/mcus/qtdesignstudio-compatibility-with-mcu-sdks.qdoc @@ -16,10 +16,16 @@ \li \QDS Version \li \QMCU SDK Version \row - \li 4.3 or later - \li 2.6 or later + \li 4.5 or later + \li 2.8 or later \row - \li 4.2 or later + \li 4.4 + \li 2.7 + \row + \li 4.3 + \li 2.6 + \row + \li 4.2 \li 2.5 \row \li 4.0 up to 4.1 diff --git a/doc/qtdesignstudio/src/overviews/qtquick-creating-ui-logic.qdoc b/doc/qtdesignstudio/src/overviews/qtquick-creating-ui-logic.qdoc index a5e05f8beb..1ea19bac4b 100644 --- a/doc/qtdesignstudio/src/overviews/qtquick-creating-ui-logic.qdoc +++ b/doc/qtdesignstudio/src/overviews/qtquick-creating-ui-logic.qdoc @@ -84,7 +84,7 @@ \li \l{Connecting Components to Signals} \row \li Formatting connections - \li \l{Adding Actions and Assignments} + \li \l{Actions and Conditions} \row \li Dynamically changing the behavior of a component \li \l{Adding Bindings Between Properties} diff --git a/doc/qtdesignstudio/src/overviews/qtquick-export.qdoc b/doc/qtdesignstudio/src/overviews/qtquick-export.qdoc index f9ae3b8d7b..f083f85f8e 100644 --- a/doc/qtdesignstudio/src/overviews/qtquick-export.qdoc +++ b/doc/qtdesignstudio/src/overviews/qtquick-export.qdoc @@ -10,7 +10,7 @@ \note In this section, you are using advanced menu items. These are not visible by default. To toggle the visibility of advanced menu items, see - \l{Customizing the Menu}. + \l{Customizing the Menu Bar}. \l{glossary-component}{Components} contained in \l{UI Files} {UI files} (.ui.qml) can be exported to JSON metadata format and PNG assets. diff --git a/doc/qtdesignstudio/src/overviews/qtquick-live-preview.qdoc b/doc/qtdesignstudio/src/overviews/qtquick-live-preview.qdoc new file mode 100644 index 0000000000..d286c41c7a --- /dev/null +++ b/doc/qtdesignstudio/src/overviews/qtquick-live-preview.qdoc @@ -0,0 +1,38 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page studio-live-preview.html + \previouspage quick-states.html + \nextpage studio-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. + + \image studio-live-preview.webp + + Or, use \QDV to run applications 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} + + Connect your devices to your computer. + + \li \l{Sharing Applications Online} + + Share applications online and view them in a web browser. + + \li \l{Viewing Applications on Android} + + Preview \QDS projects with \QUV on an Android device. + \endlist +*/ diff --git a/doc/qtdesignstudio/src/overviews/qtquick-optimizing-designs.qdoc b/doc/qtdesignstudio/src/overviews/qtquick-optimizing-designs.qdoc index 3cf0c1336b..937362450b 100644 --- a/doc/qtdesignstudio/src/overviews/qtquick-optimizing-designs.qdoc +++ b/doc/qtdesignstudio/src/overviews/qtquick-optimizing-designs.qdoc @@ -21,7 +21,7 @@ \endlist For more useful information for application developers, see - \l {Performance Considerations And Suggestions}. + \l {QML Performance Considerations And Suggestions}. For more information about optimizing 3D scenes, see \l{Creating Optimized 3D Scenes}. diff --git a/doc/qtdesignstudio/src/overviews/qtquick-production-quality-animation.qdoc b/doc/qtdesignstudio/src/overviews/qtquick-production-quality-animation.qdoc index fcf1a4c455..068a7c140b 100644 --- a/doc/qtdesignstudio/src/overviews/qtquick-production-quality-animation.qdoc +++ b/doc/qtdesignstudio/src/overviews/qtquick-production-quality-animation.qdoc @@ -28,7 +28,7 @@ to upload the draw primitives to the graphics hardware. The frames-per-second (FPS) refresh rate of animations is displayed in the - \uicontrol FPS field on the \l{Summary of Main Toolbar Actions}{toolbar} + \uicontrol FPS field on the toolbar in the \uicontrol Design mode. To improve the FPS rate, application developers should: diff --git a/doc/qtdesignstudio/src/qtbridge/qtbridge-figma-overview.qdoc b/doc/qtdesignstudio/src/qtbridge/qtbridge-figma-overview.qdoc index b721acfa9e..798ca9551c 100644 --- a/doc/qtdesignstudio/src/qtbridge/qtbridge-figma-overview.qdoc +++ b/doc/qtdesignstudio/src/qtbridge/qtbridge-figma-overview.qdoc @@ -1,4 +1,4 @@ -// 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 // Note: The \page value is hard-coded as a link in Qt Bridge for Figma. @@ -29,5 +29,9 @@ To get the best results when you use \QBF to export designs from Figma, you should follow the guidelines for working with Figma and organizing your assets. + \endlist + + \include qtdesignstudio-qt-academy.qdocinc qt-academy-using-qt-bridge-for-figma + */ diff --git a/doc/qtdesignstudio/src/qtbridge/qtbridge-figma-setup.qdoc b/doc/qtdesignstudio/src/qtbridge/qtbridge-figma-setup.qdoc index 33d130f336..00e9586df2 100644 --- a/doc/qtdesignstudio/src/qtbridge/qtbridge-figma-setup.qdoc +++ b/doc/qtdesignstudio/src/qtbridge/qtbridge-figma-setup.qdoc @@ -1,4 +1,4 @@ -// 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 /*! @@ -25,4 +25,6 @@ \endlist You can launch the installed Figma plugin from \uicontrol Plugins > \uicontrol {\QBF} in Figma. + + \include qtdesignstudio-qt-academy.qdocinc qt-academy-using-qt-bridge-for-figma */ diff --git a/doc/qtdesignstudio/src/qtbridge/qtbridge-figma-using.qdoc b/doc/qtdesignstudio/src/qtbridge/qtbridge-figma-using.qdoc index b189500f49..22cc72105e 100644 --- a/doc/qtdesignstudio/src/qtbridge/qtbridge-figma-using.qdoc +++ b/doc/qtdesignstudio/src/qtbridge/qtbridge-figma-using.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -247,4 +247,6 @@ \uicontrol Home tab) to default values. This means that you will lose all your changes to the settings. \endtable + + \include qtdesignstudio-qt-academy.qdocinc qt-academy-using-qt-bridge-for-figma */ diff --git a/doc/qtdesignstudio/src/qtdesignstudio-app-flows.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-app-flows.qdoc index 05906cba86..1be7f14311 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio-app-flows.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio-app-flows.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -8,25 +8,25 @@ \title Designing Application Flows - \image studio-flow-view.png "Application flow in the 2D view" + \image studio-flow-view.webp "Application flow in the 2D view" In \QDS, a \e {flow view} represents a schematic diagram. It consists of \e {flow items} that represent the screens in the UI and \e {transition lines} that connect them, thus illustrating the possible user pathways - through the UI. You use \e {action areas} as starting points for transition - lines. You can attach effects to transition lines, such as fade or push, + through the UI. \e {Action areas} are clickable starting points for transition + lines. Attach effects to transition lines, such as fade or push, to determine what users see when one flow item changes into another. - You can use \e {flow decisions} to set up alternative pathways between - flow items in the UI. For example, if user input determines which flow item - should open next, you can test the different scenarios in the prototype - by having a dialog pop up where you can select which flow item to show next. + Use \e {flow decisions} to set up alternative pathways between flow items in the UI. For + example, if user input determines which flow item should open next, test the different + scenarios in the prototype with the decision dialog where you can select which flow item to + show next. Especially on mobile and embedded platforms, the application might need to react to external events from the platform, such as notifications or other - applications requiring the users' attention. You can use \e {flow wildcards} - to determine the priority of flow items by adding them to positive and - negative lists. + applications requiring the users' attention. Use \e {flow wildcards} + to determine the priority of flow items by adding them to allow and + block lists. To design application flows: @@ -40,14 +40,17 @@ \l{Adding Flow Items}. \li Use context menu commands to add action areas and transitions, as described in \l{Adding Action Areas and Transitions}. + \endlist + + Additionally, to create a more advanced application flow: + + \list \li Use context menu commands to apply effects to transitions, as described in \l{Applying Effects to Transitions}. - \li When you are ready for production, use the event list simulator - to replace transition lines with connections to real signals - from UI controls, as described in \l{Simulating Events}. - \li To set up alternative pathways between flow items, use - \uicontrol {Flow Decision} components from - \uicontrol Components > \uicontrol {Flow View}, as described in + \li Use the event list simulator to replace transition lines with connections to real + signals from UI controls, as described in \l{Simulating Events}. + \li Use \uicontrol {Flow Decision} components from \uicontrol Components > \uicontrol {Flow + View} to set up alternative pathways between flow items, as described in \l{Simulating Conditions}. \li Use \l{Working with States}{states} in flows to modify the appearance of components on screens in response to user interaction, as @@ -66,8 +69,11 @@ \title Adding Flow Views - You can add a flow view to an existing project or create a new project - for it, as described in \l {Creating Projects}. + A flow view is the base component of the flow diagram that you can use to wireframe + the UI of your application. For more information, see \l{Designing Application Flows}. + + Add a flow view to an existing project or create a new project for it, as described in + \l {Creating Projects}. To create the flow view, select \uicontrol File > \uicontrol {New File} > @@ -76,24 +82,18 @@ \image studio-flow-view-create.png "Create Flow View wizard template" - You only need to select the \uicontrol {Use Event Simulator} check box if - you want to add an event simulator to the flow view. The event simulator - needs the project to be imported to the flow view, so you also need - to select the \uicontrol {Use Application Import} check box. You need the + If you want to add an event simulator to the flow view, select the + \uicontrol {Use Event Simulator} checkbox. In this case, select also the + \uicontrol {Use Application Import} checkbox to import the project to the flow view + as the event simulator requires it to work correctly. You need the import also for access to the project \c Constants.qml file that contains - global settings for the project. - - The flow view properties enable you to adjust the appearance of all - the items in the flow: action areas, transition lines, decisions, and - wildcards. You can change the global settings for all items by editing - flow view properties, or you can select an individual action area or - transition line and change the appearance of just that component, including - the color, line thickness, dotted or solid lines, and even the curve of - the line. This enables you to add extra semantics to the design - of the flow diagram itself. + global settings for the project. For more information, see \l {Simulating Events}. - You can \l{Adding Flow Items}{add flow items} to the flow view to design - the UI. + You can adjust the appearance of all the items in the flow: action areas, + transition lines, decisions, and wildcards. Change the global settings for all items + by editing the flow view properties. To add additional semantics to the flow diagram + design, select an individual action area or transition line and change the appearance + of just that component. \section1 Flow View Properties @@ -102,12 +102,12 @@ \l Visibility sections in the \l Properties view. Specify flow view properties in the \uicontrol {Flow View} section. - \image studio-flow-view-properties.png "Flow View component properties" + \image studio-flow-view-properties.webp "Flow View component properties" To specify the \uicontrol {Flow Item} that is currently visible in the flow view, set its index in the \uicontrol {Current index} field. - You can use the \l{Picking Colors}{color picker} to set colors for: + Use the \l{Picking Colors}{color picker} to set colors for: \list \li Transition lines @@ -133,9 +133,6 @@ area or transition line, see \l{Flow Action Area Properties} and \l{Flow Transition Properties}. - In the \uicontrol Layout tab, you can use \l{Setting Anchors and Margins} - {anchors} to position the component. - In the \uicontrol Advanced section, you can manage the more \l{Specifying Developer Properties}{advanced properties} of components. @@ -148,29 +145,26 @@ \title Adding Flow Items - After you create a \l{Adding Flow Views}{Flow View} component, you can - use a project wizard template to add a \uicontrol {Flow Item} component - for each screen in the UI. + After you create a \l{Adding Flow Views}{Flow View} component, use a project wizard + template to add a \uicontrol {Flow Item} component for each screen in the UI. If you \l{Importing 2D Assets}{imported} your screen designs from a design tool as individual \l{glossary-component}{components} - (\e {.ui.qml} files), you can use them as content for flow items. + (\e {.ui.qml} files), you can use them as content for flow items like any other components. The imported components are listed in \uicontrol Components > \uicontrol {My Components}. - If you are building your UI from scratch in \QDS, you must first add - components to the flow items to create the screens as you would any - components. For more information, see \l {Using Components}. The - flow items that you attach the components to are listed under + If you are building your UI from scratch in \QDS, add components to the flow items + first to create the screens as you would any components. For more information, see + \l {Using Components}. The flow items that you attach the components to are listed under \uicontrol {My Components}. - \image studio-flow-item.png "Custom Flow Item in Components" + \image studio-flow-item.webp "Custom Flow Item in Components" \note You must use the wizard to create the flow items. After you create a flow view, the \uicontrol {Flow View} module is added to - \uicontrol Components. It contains a \uicontrol {Flow Item} component that - you can use to \l{Applying States in Flows}{apply states to flow items}, and - that you should use solely for that purpose. + \uicontrol Components. It contains the \uicontrol {Flow Item} component for + \l{Applying States in Flows}{applying states to flow items}, and solely for that purpose. To add flow items: @@ -181,7 +175,7 @@ to create flow items for each screen in the UI. \li Add content to the flow item in one of the following ways: \list - \li Drag-and-drop components from \uicontrol Components to a + \li Drag components from \uicontrol Components to a flow item in the \l {2D} view or \l Navigator. \li Drag a screen from \uicontrol Components > \uicontrol {My Components} to a flow item in @@ -190,10 +184,9 @@ \li In \l Properties, edit the properties of each flow item. \endlist - You can now drag the flow items from \uicontrol Components - > \uicontrol {My Components} to the flow view in the \uicontrol {2D} - or \uicontrol Navigator view. When you have all the flow items in place, you can - \l{Adding Action Areas and Transitions}{add action areas} to them to create + Now, drag the flow items from \uicontrol Components > \uicontrol {My Components} to the + flow view in the \uicontrol {2D} or \uicontrol Navigator view. When you have all the flow + items in place, \l{Adding Action Areas and Transitions}{add action areas} to them to create transitions between them. \section1 Flow Item Properties @@ -209,23 +202,20 @@ properties are used to \l{Applying States in Flows}{apply states} in flows. - To include another flow view into a flow view, select the UI file (.ui.qml) + To include another flow view as a flow item into a flow view, select the UI file (.ui.qml) that specifies the flow view in the \uicontrol {Loader source} field. Usually, a flow item is inactive and invisible when it is not currently selected in the flow. Especially, all events from the flow item are ignored. To make a flow item always active, so that another flow item within it can respond to events and trigger the opening of a dialog, for example, - select the \uicontrol {Force active} check box. + select the \uicontrol {Force active} checkbox. - By default, transitions are drawn from action areas to the target flow item. + In the flow view, transitions are drawn from action areas to the target flow item by default. To draw the transitions from the edges of flow items instead, select the - \uicontrol {Join lines} check box in the \uicontrol {Transition Lines} + \uicontrol {Join lines} checkbox in the \uicontrol {Transition Lines} section. - In the \uicontrol Layout tab, you can use \l{Setting Anchors and Margins} - {anchors} to position the component. - In the \uicontrol Advanced section, you can manage the more \l{Specifying Developer Properties}{advanced properties} of components. */ @@ -237,26 +227,19 @@ \title Adding Action Areas and Transitions - \e {Action areas} can act as clickable areas that initiate transitions - between flow items or they can \l{Connecting and Releasing Signals} - {create connections} to any signal from any component in a + \e {Action areas} are clickable areas that initiate transitions between flow items or + \l{Connecting and Releasing Signals}{create connections} to any signal from any component in a \l{Adding Flow Items}{flow item}. For example, you could connect an action to the \c onPressed signal of a button in your flow item to determine what should happen when users press the button. - \image studio-flow-action-area.png "Flow Action Area in the 2D view" + \image studio-flow-action-area.webp "Flow Action Area in the 2D view" - \note To connect components to \l{Connecting and Releasing Signals} - {signals}, you must first export the components as - \l{Adding Property Aliases}{aliases} in \l Navigator. - To create and release connections, select - \uicontrol {Open Signal Dialog} in the context menu. + Select the type of the mouse or touch input to use for triggering + events, such as click, double-click, flick, pinch, or long press. - You can select the type of the mouse or touch input to use for triggering - events, such as click, double-click, flick, pinch, or press. - - Typically, a flow item can be connected to several other flow items in the - flow with two-way connections. To avoid clutter, you can set an action area + Typically, a flow item is connected to several other flow items in the + flow with two-way connections. To avoid clutter, set an action area as \e {go back} instead of adding explicit transition lines to and from every potentially connected flow item. When the \uicontrol {Go back} option is enabled, the transition will always take the user back to the previous @@ -270,14 +253,15 @@ To create action areas: \list 1 - \li Right-click the flow item in the \l {2D} view and select + \li Select the flow item in the \l {2D} view, then right-click it, and select \uicontrol {Flow} > \uicontrol {Create Flow Action} in the context menu. \li Drag the action area to the UI control that you want to connect to the other flow item. For example, to a button that opens another flow item when clicked. - \li Double-click the action area and drag the transition line to the - flow item you want to connect to. + \li Double-click the action area and drag the transition line to the flow item you want to + connect to. Alternatively, select the action area, right-click it to open the + context-menu, and then select \uicontrol Connect and the flow item from the list. \li In \l Properties, modify the properties of the action area and transition line. \endlist @@ -288,29 +272,29 @@ \section1 Common Properties - You can specify basic properties for \uicontrol {Flow Action Area} + Specify basic properties for \uicontrol {Flow Action Area} and \uicontrol {Flow Transition} components in the \l {Type}{Component}, \l {2D Geometry}{Geometry - 2D}, and \l Visibility sections in the \uicontrol Properties view. - In the \uicontrol Layout tab, you can use \l{Setting Anchors and Margins} - {anchors} to position the component. + Use \l{Setting Anchors and Margins}{anchors} in the \uicontrol Layout tab to position + the component. - In the \uicontrol Advanced section, you can manage the more - \l{Specifying Developer Properties}{advanced properties} of components. + Manage the more \l{Specifying Developer Properties}{advanced properties} of components + in the \uicontrol Advanced section. \section1 Flow Action Area Properties - In the \uicontrol {Flow Action Area} section, you can use the - \l{Picking Colors}{color picker} to set line and fill color. + Use the \l{Picking Colors}{color picker} in the \uicontrol {Flow Action Area} section + to set line and fill color. - \image studio-flow-action-area-properties.png "Flow Action Area properties" + \image studio-flow-action-area-properties.webp "Flow Action Area properties" - In the \uicontrol {Flow Action} and \uicontrol {Action Area} sections, - specify additional properties for action areas: + Specify additional properties for action areas in the \uicontrol {Flow Action} and + \uicontrol {Action Area} sections: \list - \li Select the \uicontrol {Go back} check box to specify that the + \li Select the \uicontrol {Go back} checkbox to specify that the transition will always take the user back to the previous flow item. \li In the \uicontrol {Event IDs} field, specify the IDs of the events to connect to, such as mouse, touch or keyboard events. @@ -318,22 +302,22 @@ mouse or touch input to use for triggering events. \li In the \uicontrol {Line width} field, set the width of the action area outline. - \li Select the \uicontrol {Dashed line} check box to draw a dashed + \li Select the \uicontrol {Dashed line} checkbox to draw a dashed action area outline. - \li Select the \uicontrol Enabled check box to enable interaction + \li Select the \uicontrol Enabled checkbox to enable interaction with the action area during preview. \endlist \section1 Flow Transition Properties - In the \uicontrol Transition section, specify additional properties for - transitions between \l{Adding Flow Items}{flow items}: + Specify additional properties for transitions between \l{Adding Flow Items}{flow items} + in the \uicontrol Transition section: - \image studio-flow-transition-properties.png "Flow Transition properties" + \image studio-flow-transition-properties.webp "Flow Transition properties" \list \li Select the \uicontrol Condition checkbox to activate the - transition. You can select \inlineimage icons/action-icon.png + transition. Select \inlineimage icons/action-icon.png to \l{Adding Bindings Between Properties}{bind} a condition to the transition. \li In the \uicontrol Question field, enter the text that will appear @@ -348,10 +332,10 @@ ends. \endlist - You can specify the following properties to change the appearance of - transition lines in the \uicontrol {2D} view: + Specify the following properties to change the appearance of transition lines in + the \uicontrol {2D} view: - \image studio-flow-transition-line-properties.png "Flow Transition Line properties" + \image studio-flow-transition-line-properties.webp "Flow Transition Line properties" \list \li In the \uicontrol {Line width} field, set the width of the @@ -360,7 +344,7 @@ the start point (\uicontrol Out) or end point (\uicontrol In) of a transition line or a break to the specified offset. This enables you to move them up and down or left and right. - \li Select the \uicontrol {Dashed line} check box to draw a dashed line. + \li Select the \uicontrol {Dashed line} checkbox to draw a dashed line. \li In the \uicontrol Type field, select \uicontrol Bezier to draw transition lines as bezier curves. \li In the \uicontrol Radius field, specify the corner radius for @@ -371,19 +355,19 @@ \li In the \uicontrol {Label position} field, set the position of the value of the \uicontrol Question field in respect to the transition start point. - \li Select the \uicontrol {Label flip side} check box to move the + \li Select the \uicontrol {Label flip side} checkbox to move the \uicontrol Question value to the opposite side of the transition line. \endlist \section1 Connecting and Releasing Signals - To connect a component to a \l{Connecting Components to Signals}{signal}, - select \uicontrol {Open Signal Dialog} in the context menu. The - \uicontrol {Signal List} dialog displays the signals for all components - that you export as \l{Adding Property Aliases}{aliases} in \l Navigator. + To connect components to \l{Connecting Components to Signals}{signals}, export the + components first as \l{Adding Property Aliases}{aliases} in \l Navigator. To create + and release connections, select \uicontrol {Open Signal Dialog} in the context menu. + The \uicontrol {Signal List} dialog displays the signals for all components. - \image studio-flow-signal-list.png "Signal List dialog" + \image studio-flow-signal-list.webp "Signal List dialog" To connect a component to a signal, select \uicontrol Connect next to one in the list. To release a connected signal, select \uicontrol Release. @@ -396,13 +380,13 @@ \title Applying Effects to Transitions - You can apply effects, such as fade, move, or push to + You can apply effects, such as fade, move, or push, to \l{Adding Action Areas and Transitions}{transitions} between \l{Adding Flow Items}{flow items}. A fade effect makes the first flow item appear to fade out, while the next flow item fades in. A move effect makes the second flow item appear to move in over the - first flow item, while the push effect appears to make a flow item - push out the previous one. You can also design and use custom effects. + first flow item. The push effect makes a flow item appear to push out the previous one. + You can also use your own custom effects that you have created with some other tool. The transition direction determines the direction the new flow item appears from: left, right, top, bottom. You can set the duration of the effect and @@ -412,34 +396,42 @@ \list 1 \li Select a transition line in the \l {2D} view. - \li In the context menu, select \uicontrol {Flow} > - \uicontrol {Assign Flow Effects}, and then select the effect - to apply. + \li Right-click the transition line to open the context menu, select \uicontrol {Flow} > + \uicontrol {Flow Effects}, and then select the effect to apply. \li In \l Properties, modify the properties of the effect. \endlist - To edit effect properties later, select a transition, and then select - \uicontrol {Flow} > \uicontrol {Select Effect} in the context menu. + To edit effect properties later, select a transition, open the context menu, and then select + \uicontrol {Flow} > \uicontrol {Select Effect}. + + To use your own custom effects, select a transition, open the context menu, and then select + \uicontrol {Flow} > \uicontrol {Flow Effects} > \uicontrol {Assign Custom FlowEffect}. + Then specify the path to your custom effect file. + + To remove the current effect from a transition, select a transition, open the context menu, + and then select \uicontrol {Flow} > \uicontrol {Flow Effects} > + \uicontrol {Assign FlowEffect None}. \section1 Flow Effect Properties - You can specify basic properties for a \uicontrol {Flow Effect} - component in the \l Type and \l ID fields in the \uicontrol Component - section in the \uicontrol Properties view. + Specify basic properties for a \uicontrol {Flow Effect} component in the \l Type and + \l ID fields in the \uicontrol Component section in the \uicontrol Properties view. \image studio-flow-effect-properties.png "Flow Effect properties" - You can set the duration and easing curve of all flow effects: + Set the duration and easing curve of flow effects in the \uicontrol {Transition Effect} + section: \list \li In the \uicontrol Duration field, specify the duration of the effect. \li Select the \inlineimage icons/curve_editor.png - button to open \uicontrol {Easing Curve Editor} for attaching an + button to open \uicontrol {Easing Curve Editor} to attach an \l{Editing Easing Curves}{easing curve} to the effect. \endlist - For a move or push effect, you can set some additional properties: + Set some additional properties for a move or push effect in the \uicontrol {Push Effect} + or \uicontrol {Move Effect} section: \image studio-flow-effect-push-properties.png "Flow Push Effect properties" @@ -451,7 +443,7 @@ \li In the \uicontrol {Incoming opacity} and \uicontrol {Outgoing opacity} fields, specify the opacity of the effect as a number between 0 and 1. - \li Select the \uicontrol Reveal check box to reveal the + \li Select the \uicontrol Reveal checkbox to reveal the \uicontrol {Flow Item} where the transition starts. \endlist */ @@ -473,7 +465,7 @@ keyboard shortcuts to simulate these events when you preview the UI. When you use the wizard to create a \uicontrol {Flow View} component, select - the \uicontrol {Use event simulator} check box to add an event simulator to + the \uicontrol {Use event simulator} checkbox to add an event simulator to the flow view. You can create an event list where you assign keyboard shortcuts to events, @@ -490,9 +482,8 @@ \li In the \uicontrol {Event List} dialog, select \inlineimage icons/plus.png to add a keyboard shortcut for triggering an event to the list. \image studio-flow-event-list.png "Event List dialog" - \li In the \uicontrol {Event ID} field, enter an identifier for the - event. You can search for existing events by entering search - criteria in the \uicontrol Filter field. + \li In the \uicontrol {Event ID} field, enter an identifier for the event. To search + for existing events, enter search criteria in the \uicontrol Filter field. \li In the \uicontrol Description field, describe the keyboard shortcut. \li In the \uicontrol Shortcut field, press the keyboard key that will trigger the event, and then select \uicontrol R to record the @@ -506,24 +497,22 @@ To assign events to actions: \list 1 + \li Select \uicontrol eventListSimulator in \uicontrol Navigator, and in + \uicontrol Properties > \uicontrol {Exposed Custom Properties}, select the + \uicontrol active checkbox. If \uicontrol eventListSimulator is not visible + in the \uicontrol Navigator, select \inlineimage icons/visibilityon.png. \li In \uicontrol Navigator, select an action area or transition line. \li In the context menu, select \uicontrol {Event List} > \uicontrol {Assign Events to Actions}. - \image studio-flow-events-assign.png "Assign Events to Actions dialog" - \li In the \uicontrol ID field, select a transition or an action area - \inlineimage icons/flow-action-icon.png - . You can search for events by entering search criteria in the - \uicontrol Filter field. + \image studio-flow-events-assign.webp "Assign Events to Actions dialog" \li To connect an event, select \uicontrol Connect next to an event in the list. To release a connected event, select \uicontrol Release. \li Press \key {Alt+P} to preview the UI. \li Select action areas in the preview, double-click events in the event list, or use the keyboard shortcuts to trigger events. - \image studio-flow-decision-preview.png "Event list in preview" + \image studio-flow-events-event-list.webp "Event list in Live Preview" \endlist - If the event triggers a \l{Simulating Conditions}{flow decision}, you - can select the path to take to the next flow item. */ /*! @@ -545,17 +534,17 @@ controls, backend, or sensor data that will be required for the production version. - \image studio-flow-decision.png "Flow Decision in the 2D view" + \image studio-flow-decision.webp "Flow Decision in the 2D view" To simulate conditions: \list 1 \li Drag a \uicontrol {Flow Decision} component from - \uicontrol Components \uicontrol {Flow View} to a + \uicontrol Components > \uicontrol {Flow View} to a \l{Adding Flow Views}{flow view} in the \l Navigator or \l {2D} view. \li Select the flow item where you want the application to start in - the \uicontrol Navigator or \uicontrol {2D} view, and then select - \uicontrol {Flow} > \uicontrol {Set Flow Start} in the context menu. + the \uicontrol Navigator or \uicontrol {2D} view. Then right-click the component + to open the context menu, and select \uicontrol Flow > \uicontrol {Set Flow Start}. \li Create an \l{Adding Action Areas and Transitions}{action area} for the component that will trigger the condition and connect it to the flow decision. @@ -566,10 +555,10 @@ title for the selection dialog that opens when the condition is triggered. \li Select a transition line in the \uicontrol Navigator or - \uicontrol {2D} view and add a descriptive text in the + \uicontrol {2D} view, and add a descriptive text in the \uicontrol {Question} field in \uicontrol Properties to represent a choice in the selection dialog. - \image studio-flow-transition-properties-question.png "Flow Transition properties" + \image studio-flow-transition-properties-question.webp "Flow Transition properties" \li Press \key {Alt+P} to preview the UI. \li Select action areas in the preview, double-click events in the event list, or use the keyboard shortcuts to trigger events. @@ -578,21 +567,21 @@ Flow decisions are listed in a dialog where you can select which condition is met to see the results. - \image studio-flow-decision-preview.png "Selection dialog for flow decision" + \image studio-flow-decision-preview.webp "Selection dialog for flow decision" \section1 Flow Decision Properties - You can specify basic properties for a \uicontrol {Flow Decision} component + Specify basic properties for a \uicontrol {Flow Decision} component in the \l Type and \l ID fields in the \uicontrol Component section in the \uicontrol Properties view. Specify properties for flow decisions in the \uicontrol {Flow Decision} section. - \image studio-flow-decision-properties.png "Flow Decision properties" + \image studio-flow-decision-properties.webp "Flow Decision properties" In the \uicontrol {Dialog title} field, enter a title for the selection dialog that opens when the condition is triggered. - You can specify the following properties to change the appearance of the + Specify the following properties to change the appearance of the flow decision icon \inlineimage icons/flow-decision-icon.png : @@ -602,14 +591,14 @@ component in the \l {2D} view. \li In the \uicontrol {Label position} field, select the corner of the flow decision icon to place the label in. + \li Use the \l{Picking Colors}{color picker} to set \uicontrol {Outline color} and + \uicontrol {Fill color} of the flow decision icon. \li In the \uicontrol Size field, specify the size of the flow decision icon. \li In the \uicontrol Radius field, specify the radius of the flow decision icon corners. \endlist - You can use the \l{Picking Colors}{color picker} to set the outline and - fill color of the flow decision icon. */ /*! @@ -619,32 +608,34 @@ \title Applying States in Flows - You can use \l{Working with States}{states} in flows to modify the appearance - of \l{glossary-component}{components} in flow items in response to user - interaction, for example. For this purpose, you use the - \uicontrol {Flow Item} components available in - \uicontrol Components > \uicontrol {Flow View}. + Use \l{Working with States}{states} in flows to modify how the \l{glossary-component} + {component} properties change in flow items. For this purpose, use the \uicontrol {Flow Item} + component available in \uicontrol Components > \uicontrol {Flow View}. + + To apply states in flows: \list 1 \li Select \uicontrol File > \uicontrol {New File} > \uicontrol {Qt Quick Files} > \uicontrol {Flow Item} to create a flow item. - \li In \l States, add states to the flow item. - \li Open the .ui.qml file that contains the \l{Adding Flow Views} - {flow view} in the \l {2D} view and drag the flow item to the - flow view in the \l Navigator or \l {2D} view. - \li Drag an empty \uicontrol {Flow Item} component from - \uicontrol Components > \uicontrol {Flow View} - to the flow for each state that you added. - \li In \l Properties, in the \uicontrol {State change target} - field, select the flow item that you created using the wizard. - \image studio-flow-item-properties.png "Flow Item properties" - \li In the \uicontrol {Target state} field, select the state to - apply to the flow item. + \li In the \l States view, add states to the flow item. + \li In the \l Projects view, open the .ui.qml file that contains the \l{Adding Flow Views} + {flow view}, and drag the flow item from \uicontrol Components > + \uicontrol {My Components} to the flow view in the \l Navigator or \l 2D view. + \li From \uicontrol Components > \uicontrol {Flow View}, drag an empty + \uicontrol {Flow Item} component (1) to the flow view for each state that you added. + \image studio-flow-item-component.webp "Flow Item in the Components view." + \li In the \uicontrol Navigator or \uicontrol 2D view, select an empty + \uicontrol {Flow Item} to open the \l Properties view. + \li In the \uicontrol {State change target} field, select the flow item that you created + using the wizard. + \li In the \uicontrol {Target state} field, select the state to apply to the flow item. + \image studio-flow-states-item-properties.webp "Flow Item properties" \endlist - You can now add \l{Adding Action Areas and Transitions}{action areas} and - \l{Simulating Conditions}{flow decisions} to apply the different states. + To apply the different states to your application flow, add + \l{Adding Action Areas and Transitions}{action areas} and + \l{Simulating Conditions}{flow decisions} to the flow items. */ /*! @@ -659,11 +650,10 @@ time, based on a conditional event. For example, push notifications appear on mobile devices and incoming call screens on a car's HMI. - You can use the \uicontrol {Flow Wildcard} component to model this type of - screens in your \l{Adding Flow Views}{flow view} using real or simulated - \l{Connecting and Releasing Signals}{signals} and \l{Simulating Conditions} - {conditions}. You can add \l{Adding Flow Items}{flow items} to a positive - list to prioritize them or to a negative list to stop some screens from + Use the \uicontrol {Flow Wildcard} component to model this type of + screens in your \l{Adding Flow Views}{flow view} using real or simulated events. + Add \l{Adding Flow Items}{flow items} to an \uicontrol {Allow + list} to prioritize them or to a \uicontrol {Block list} to stop some screens from appearing on others. For example, you could block the incoming call screen from appearing on a warning screen for the engine if you consider the warning more important. @@ -672,42 +662,46 @@ \list 1 \li Drag a \uicontrol {Flow Wildcard} component from - \uicontrol Components > \uicontrol {Flow View} to an - \l{Adding Action Areas and Transitions}{action area} in - the \l Navigator or \l {2D} view. - \li In \l Properties, select flow items to add them to the - positive and negative list of the action area. + \uicontrol Components > \uicontrol {Flow View} to the \l {2D} view. + \li To connect the wildcard to a flow item with a \l{Adding Action Areas and Transitions} + {transition line}, double-click the wildcard and drag the transition line to the flow + item. + \li To add logic to the \uicontrol {Flow Wildcard} component, use + \l{Simulating Events}{events}, \l{Simulating Conditions}{Flow Decision} components, + or \l{Connecting and Releasing Signals}{signals}. + \li To manage the priority of your flow items, add flow items to + \uicontrol {Allow list} or \uicontrol {Block list} in \l Properties. + \image studio-flow-wildcard.webp "The wildcard component in 2D view." \endlist \section1 Flow Wildcard Properties - You can specify basic properties for a \uicontrol {Flow Wildcard} component + Specify basic properties for a \uicontrol {Flow Wildcard} component in the \l Type and \l ID fields in the \uicontrol Component section in the \uicontrol Properties view. Specify properties for flow wildcards in the \uicontrol {Flow Wildcard} section. - \image studio-flow-wildcard-properties.png "Flow Wildcard properties" + \image studio-flow-wildcard-properties.webp "Flow Wildcard properties" In the \uicontrol {Event IDs} field, specify the IDs of the events to connect to, such as mouse, touch or keyboard events. - Select the \uicontrol {Global wildcard} check box to enable triggering + Select the \uicontrol {Global wildcard} checkbox to enable triggering the wildcard from several flows. To give flow items high priority, select them in the \uicontrol {Allow list} field. To block flow items, select them in the \uicontrol {Block list} field. - You can specify the following properties to change the appearance of the - wildcard icon \inlineimage icons/flow-wildcard-icon.png - : + Specify the following properties to change the appearance of the + wildcard icon \inlineimage icons/flow-wildcard-icon.png: \list + \li To set the outline and fill color of the wildcard icon, use the + \l{Picking Colors}{color picker}. \li In the \uicontrol Size field, specify the size of the wildcard icon. \li In the \uicontrol Radius field, specify the radius of the wildcard icon corners. \endlist - You can use the \l{Picking Colors}{color picker} to set the outline and - fill color of the wildcard icon. */ diff --git a/doc/qtdesignstudio/src/qtdesignstudio-debugging.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-debugging.qdoc index 9d1fa446ae..09cd1d0f58 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio-debugging.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio-debugging.qdoc @@ -22,8 +22,10 @@ \uicontrol Debug mode. \li \l{Profiling QML Applications} - You can use the QML Profiler to find causes for typical performance + You can use QML Profiler to find causes for typical performance problems in your UIs, such as slowness, freezing, and stuttering. - The QML Profiler is installed and configured as part of \QDS. + QML Profiler is installed and configured as part of \QDS. \endlist + + \sa {Profile QML applications} */ diff --git a/doc/qtdesignstudio/src/qtdesignstudio-faq.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-faq.qdoc deleted file mode 100644 index 8f7267e0d3..0000000000 --- a/doc/qtdesignstudio/src/qtdesignstudio-faq.qdoc +++ /dev/null @@ -1,139 +0,0 @@ -// Copyright (C) 2021 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! - \previouspage creator-how-to-get-help.html - \page studio-faq.html - \nextpage studio-platforms.html - - \title Frequently Asked Questions - - This section contains answers to some frequently asked questions about \QDS - grouped by categories. You might also find answers to your questions in the - product documentation by searching or browsing the index in the - \l{Get help}{Help mode}. Many questions are also answered by the - \l{Examples}{examples} and \l{Tutorials}{video tutorials}. - - \list - \li \l {FAQ - \QB}{\QB} - \li \l {FAQ - Assets}{Assets} - \li \l {FAQ - Components}{Components} - \li \l {FAQ - Views}{Views} - \li \l {FAQ - Integration Between \QDS and Qt Creator}{Integration Between \QDS and Qt Creator} - \li \l {FAQ - Performance}{Performance} - \li \l {FAQ - Data Simulation}{Data Simulation} - \endlist - - \section1 FAQ - \QB - - \section2 How does \QBPS differ from \QBSK and \QBF? - - \QBPS, \QBSK, and \QBF are functionally similar. The biggest difference - between the tools is that \QBSK and \QBF can export .svg (vector), .png, and - .jpeg files, while \QBPS only supports .png and .jpeg. Adobe Illustrator - users can port their designs into Photoshop, but they must be rasterized - into \e {smart objects}. - - For more information, see \l {Exporting from Design Tools}. - - \section2 Do I need to copy the .qml files in the resource folder after each design modification? - - No you don't. When you add new or modified .metadata files to your project - from Photoshop, \QBPS, \QBSK, or \QBF, select the \uicontrol {Merge QML} - check box in the \uicontrol {Asset Import} dialog to merge the changes into - existing QML files instead of overwriting them. - - For more information, see \l {Importing 2D Assets}. - - \section2 Where can I find log files generated by \QB while exporting metadata? - - On Windows, the logs are stored inside the temp folder in - \c {C:\Users\<USERNAME>\AppData\Local\Temp}. The log files are named as - \e csxs<versionNumber>-<HostID>.log. Please note that you might have to set - the log level to generate logs. Also note the CEP version while setting the - log level. The CEP version depends on the Photoshop version you are using. - Currently the latest version is version 10. - - \section1 FAQ - Assets - - \section2 Can I import my organization's preferred font in \QDS? - - Yes, you can import your custom fonts, for example, in .ttf or .otf formats. - Fonts installed on your system will be available to use in your imported - designs. If you need to deploy the device, you will have to import the font - into the project. - - For more information, see \l {Using Custom Fonts}. - - \section1 FAQ - Components - - \section2 Can I use custom components? - - Yes, you can create custom components and controls by using wizard templates - or move component instances into separate files to turn them into new - components that you can create instances of. For more information, see - \l {Using Components}. - - \section2 What are the 3D import formats for \QDS? - - You can import files stored in several widely-used formats, such as .fbx, - .obj, .gltf, .glb, .blend, .dae, .uia, and .uip. - - For more information, see \l {Importing 3D Assets}. - - \section2 How can I integrate custom C++ components into QDS? - - You must create your own QML module that contains the components and - provides additional information about your components. For more information, - see \l {Using QML Modules with Plugins}. - - \section1 FAQ - Views - - \section2 What are the keyboard shortcuts for moving around in the \uicontrol{3D} view? - - \list - \li To pan: \key Alt + middle mouse button - \li To orbit (rotate): \key Alt (or \key Option on \macos) + left mouse button - \li To zoom: \key Alt + right mouse button - \endlist - - For more information, see the \l {3D} view. - - \section1 FAQ - Integration Between \QDS and Qt Creator - - \section2 Can I automatically propagate name changes between \QDS and Qt Creator? - - Unfortunately we do not automate renaming files between tools at the moment. - If you decide to change the name of a property, alias, or signal in \QDS, - you need to manually change the name in Qt Creator to maintain the connection. - However, you can rename symbols in all files within a project. To rename a - QML type in a project, select \uicontrol Tools > \uicontrol QML/JS > - \uicontrol {Rename Symbol Under Cursor} or press \key Ctrl+Shift+R. For more - information, see \l {Rename symbols}. - - \section2 How can I add .qml files to my project in Qt Creator? - - Use the project wizard templates to create an application in \QDS and copy - your .qml files to the project folder. Then make some changes to the project - configuration and source files, as instructed in - \l {Converting UI Projects to Applications}. - - \section1 FAQ - Performance - - \section2 Will my application with 3D components run at 60 FPS? - - With the ability to test the full (2D/3D) UI in \QDS on target hardware, - you will quickly be able to determine if a 3D object is causing performance - issues using the \uicontrol FPS field in the \uicontrol Design mode. - \uicontrol FPS displays the frames-per-second (FPS) refresh rate of - previewed animations. - - See \l {Optimizing Your 3D Scene} to learn how you can enhance the - performance by optimizing your scene. - - \section1 FAQ - Data Simulation - - \section2 Can I automatically generate dummy data? - No, this is not supported at the moment. For more information about creating - the data manually, see \l {Loading Placeholder Data}. - */ diff --git a/doc/qtdesignstudio/src/qtdesignstudio-finding-qt-runtime-version.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-finding-qt-runtime-version.qdoc index cb9c7e86e9..5f2bc9bdad 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio-finding-qt-runtime-version.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio-finding-qt-runtime-version.qdoc @@ -34,5 +34,8 @@ \row \li 4.4 \li 6.6.2 + \row + \li 4.5 + \li 6.7.0 (with additional Quick3D features) \endtable */ diff --git a/doc/qtdesignstudio/src/qtdesignstudio-getting-started.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-getting-started.qdoc index 493242254f..a975dfe7fc 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio-getting-started.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio-getting-started.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -56,4 +56,6 @@ If you would rather be shown things than read about them, you can watch our extensive video tutorials. \endlist + + \include qtdesignstudio-qt-academy.qdocinc qt-academy-getting-started-with-qt-design-studio */ diff --git a/doc/qtdesignstudio/src/qtdesignstudio-help-overview.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-help-overview.qdoc index be9e6b4ed5..36fbc8c015 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio-help-overview.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio-help-overview.qdoc @@ -11,8 +11,7 @@ \table \row \li \image qds-front-help.png - \li Learn more about using the \uicontrol Help mode, frequently - asked questions, and supported platforms. + \li Learn more about using the \uicontrol Help mode and supported platforms. \endtable \list @@ -23,9 +22,6 @@ and index functions to find particular topics in the helps, or request context-sensitive help by pressing \key F1 in the Design mode. - \li \l{Frequently Asked Questions} - - Contains answers to some frequently asked questions about \QDS. \li \l{Supported Platforms} You can install and run \QDS on several operating systems to design diff --git a/doc/qtdesignstudio/src/qtdesignstudio-implementing-applications.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-implementing-applications.qdoc index 1f0aa08629..d19ede682f 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio-implementing-applications.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio-implementing-applications.qdoc @@ -41,7 +41,7 @@ you can inspect the state of your UI while debugging. The memory and CPU power available on devices are limited and - you should use them carefully. The QML Profiler enables you to - profile Qt Quick UIs. + you should use them carefully. With QML Profiler, you can find + problems in QML code. \endlist */ diff --git a/doc/qtdesignstudio/src/qtdesignstudio-packaging.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-packaging.qdoc index 1e426f011e..4158a7b545 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio-packaging.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio-packaging.qdoc @@ -10,7 +10,7 @@ \note In this section, you are using advanced menu items. These are not visible by default. To toggle the visibility of advanced menu items, see - \l{Customizing the Menu}. + \l{Customizing the Menu Bar}. When you are ready to deliver your application to users or upload it to app stores, you can use \QDS to create suitable packages that contain all diff --git a/doc/qtdesignstudio/src/qtdesignstudio-platforms.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-platforms.qdoc index 5a50eb2bf4..501e30adc7 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio-platforms.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio-platforms.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -11,20 +11,20 @@ You can install and run \QDS on several operating systems to create applications for multiple desktop, embedded, and mobile device platforms. - \section1 Development Platforms + \section1 Host Platforms \QDS is available in binary packages for the following operating systems: \list - \li \macOS 11.0 - \li Linux: - \list - \li CentOS 8.1 - \li openSUSE Leap 15.1 - \li SUSE Linux Enterprise Server 15 (SLES 15) - \li Ubuntu 20.04 - \endlist - \li Windows 10, version 2004 + \li Windows 11 + \li Windows 10 64-bit + \li \macOS 12, 13 + \list + \li ARM-based Mac + \li Intel Mac + \endlist + \li Linux Ubuntu 22.04 (latest LTS) + \li Linux Ubuntu 20.04 \endlist \note For a good user experience on Windows 10, we recommend the following @@ -36,9 +36,9 @@ \QB is available for the following design tools: \list - \li Adobe Photoshop version 24.0 - \li Adobe XD version 55.0.12 - \li Figma version 116.4 - \li Sketch version 90.0 + \li Adobe Photoshop 25.0 + \li Adobe XD 57.1.12.2 + \li Figma 116.15.15 + \li Sketch 99.1 \endlist */ diff --git a/doc/qtdesignstudio/src/qtdesignstudio-projects.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-projects.qdoc index 3daf6e7089..46b2ac8fbb 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio-projects.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio-projects.qdoc @@ -37,7 +37,7 @@ \li \li Lists your most recently used presets. \row - \li {1,2} General + \li {1,3} General \li Empty \li Creates a project that uses default components such as rectangles, images, and text. You can run the application on all target @@ -47,6 +47,11 @@ \li Creates a project that uses default and 3D components such as cameras, lights, 3D models, and materials. \row + \li 3D Extended + \li Creates a project that uses default and 3D components, such as + camera, light, model and materials. Extended scene environment is + also included to enable various built-in effects. + \row \li \QMCU \li MCU \li Creates an application that uses a subset of default components @@ -77,7 +82,7 @@ \note This tab is not visible if there are no saved custom presets. \endtable - \image studio-project-wizards.png "The Create Project wizard" + \image studio-project-wizards.webp "The Create Project wizard" To test how well your designs work, you can preview the UIs on the desktop, embedded Linux devices, or Android devices. For more diff --git a/doc/qtdesignstudio/src/qtdesignstudio-qt-academy.qdocinc b/doc/qtdesignstudio/src/qtdesignstudio-qt-academy.qdocinc new file mode 100644 index 0000000000..3769ddc5e3 --- /dev/null +++ b/doc/qtdesignstudio/src/qtdesignstudio-qt-academy.qdocinc @@ -0,0 +1,22 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +//! [qt-academy-using-qt-bridge-for-figma] + To learn the basics of \QBF, take the + \l {https://www.qt.io/academy/course-catalog#how-to-use-qt-bridge-for-figma} + {How to Use \QBF} course in \QAC. +//! [qt-academy-using-qt-bridge-for-figma] + +//! [qt-academy-3D-with-qt-design-studio] + To learn the basics of using 3D in \QDS, take the + \l {https://www.qt.io/academy/course-catalog#3d-with-qt-design-studio} + {3D with \QDS} course in \QAC. +//! [qt-academy-3D-with-qt-design-studio] + +//! [qt-academy-getting-started-with-qt-design-studio] + To learn the basics of using \QDS, take the + \l {https://www.qt.io/academy/course-catalog#getting-started-with-qt-design-studio} + {Getting Started with \QDS} course in \QAC. +//! [qt-academy-getting-started-with-qt-design-studio] + +*/ diff --git a/doc/qtdesignstudio/src/qtdesignstudio-terms.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-terms.qdoc index 9c517f9846..00464f7447 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio-terms.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio-terms.qdoc @@ -4,7 +4,7 @@ /*! \page studio-terms.html \previouspage studio-use-cases.html - \nextpage {Examples} + \nextpage best-practices.html \title Concepts and Terms @@ -30,7 +30,7 @@ An \e asset is an image, font file, 3D model, or other supported file that you add to your \l{glossary-project}{project}. - \image qtquick-assets-tab.png "Assets" + \image qtquick-assets-tab.webp "Assets" Assets are packaged with \l{glossary-component}{components} for delivery to users. @@ -170,7 +170,7 @@ example, if you create a 3D project, preset 3D components are added to it. You can add more preset components in \uicontrol {Components}. - \image studio-project-wizards.png "New Project dialog" + \image studio-project-wizards.webp "New Project dialog" Read more about projects: @@ -187,7 +187,7 @@ also be modified by another component, unless a particular component type has explicitly disallowed this for a specific property. - \image qtquick-item-properties-common.png "Properties view" + \image qtquick-item-properties-common.webp "Properties view" Read more about properties: diff --git a/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc index cf00e32419..6b3680de54 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -16,29 +16,30 @@ \list \li \l{2D} \li \l{3D} - \li \l{Material Editor and Browser} - \li \l{Components} \li \l{Assets} - \li \l{Navigator} - \li \l{Properties} - \li \l{Connections} - \li \l{States} - \li \l{Translations} - \li \l{Transitions} - \li \l{Timeline} - \li \l{Curves} \li \l{Code} \generatelist studio-how-to-code \generatelist studio-how-to-refactor-code \generatelist studio-how-to-search \generatelist studio-preferences-code - \li \l{Projects} + \li \l{Components} + \li \l{Connections} + \li \l{Content Library} + \li \l{Curves} + \li \l{Effect Composer} \li \l{File System} + \li \l{Material Editor and Browser} + \li \l{Model Editor} + \li \l{Navigator} \li \l{Open Documents} - \li \l{Content Library} - \li \l{Texture Editor} + \li \l{Projects} + \li \l{Properties} \li \l{Qt Insight} - \li \l{Effect Composer} + \li \l{States} + \li \l{Texture Editor} + \li \l{Timeline} + \li \l{Transitions} + \li \l{Translations} \endlist \li \l{Managing Workspaces} \li \l{Manage sessions} @@ -47,6 +48,7 @@ \li \l{Creating Projects} \li \l{Use Cases} \li \l{Concepts and Terms} + \li \l{Best Practices} \li \l{Examples} \endlist \li \l{Wireframing} @@ -73,8 +75,9 @@ \li \l{UI Controls} \li \l{Lists and Other Data Models} \li \l{2D Effects} + \li \l{Design Effects} \li \l{Logic Helpers} - \li \l Animations + \li \l{Animations} \li \l{3D Views} \li \l{Node} \li \l{Group} @@ -89,7 +92,7 @@ \li \l{Custom Effects and Materials} \li \l{Lights} \li \l{Cameras} - \li \l{Scene Environment} + \li \l{Scene Environments} \li \l{Morph Target} \li \l{Repeater3D} \li \l{Loader3D} @@ -214,6 +217,9 @@ \endlist \li \l{Debugging a Qt Quick Application} \li \l{Profiling QML Applications} + \list + \li \l{Profile QML applications} + \endlist \endlist \endlist \li \l{Advanced Designer Topics} @@ -261,7 +267,6 @@ \li \l {Search from documentation} \li \l {Select the help start page} \endlist - \li \l{Frequently Asked Questions} \li \l{Supported Platforms} \endlist \li \l{Technical Support} diff --git a/doc/qtdesignstudio/src/qtdesignstudio.qdoc b/doc/qtdesignstudio/src/qtdesignstudio.qdoc index 6d84474605..d3a0b007d1 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio.qdoc @@ -31,6 +31,7 @@ \li \l{Creating Projects} \li \l{Use Cases} \li \l{Concepts and Terms} + \li \l{Best Practices} \li \l{Examples} \endlist \li \b {\l{Wireframing}} @@ -86,7 +87,6 @@ \li \b {\l Help} \list \li \l{Get help}{Getting Help} - \li \l{Frequently Asked Questions} \li \l{Supported Platforms} \endlist \row diff --git a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-camera.qdoc b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-camera.qdoc index 202249188d..89da3cbb34 100644 --- a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-camera.qdoc +++ b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-camera.qdoc @@ -8,13 +8,13 @@ \title Cameras - A camera is always necessary to view the content of a 3D scene. A camera + A camera is necessary to view the content of a 3D scene. A camera defines how to project the content of a 3D scene into a 2D coordinate space, which can then be used on a 2D surface. When a camera is present in the scene, it can be used to direct what is displayed in a \l {3D Views} {3D view}. - \image studio-qtquick-3d-components.png "Qt Quick 3D components in Components" + \image studio-qtquick-3d-components.webp "Qt Quick 3D components in Components" To add a camera component to your UI, do one of the following: \list @@ -31,7 +31,7 @@ \uicontrol QtQuick3D module to your project, as described in \l {Adding and Removing Modules}. - You can use the following components in your scenes to determine camera + The following components in your scenes determine the camera projection: \list @@ -65,7 +65,7 @@ You can edit the camera properties in the \uicontrol Properties view. - \image studio-qtquick-camera-properties "Properties view for Perspective Camera" + \image studio-qtquick-camera-properties.webp "Properties view for Perspective Camera" \section1 Setting Camera Field of View @@ -73,6 +73,8 @@ when \l {Creating Projects}{creating your project}, the camera properties will be slightly different. + \note Orthographic cameras don't have the FOV property. + The camera frustum can be obtained by taking a frustum (that is, a truncation with parallel planes) of the cone of vision that a camera or eye would have to the rectangular viewports typically used in computer graphics. @@ -112,10 +114,10 @@ \note The \uicontrol {Horizontal magnification} and \uicontrol {Vertical magnification} properties are not available in Qt 5. - The \uicontrol {Frustum culling enabled} property determines whether the + The \uicontrol {Frustum culling} property determines whether the objects outside the camera frustum will be culled, which means they will not be passed to the renderer. - \note The \uicontrol {Frustum culling enabled} property is not available in + \note The \uicontrol {Frustum culling} property is not available in Qt 5. The default values are intended to cause anything within the view @@ -124,5 +126,22 @@ better results with ambient occlusion or with effects that use the depth buffer of the camera, such as the \e {depth of field} effect. - \note Orthographic cameras don't have the FOV property. + \section1 Setting a Camera to Look at an Object + + Setting the camera to look at a specific object can be useful, for example, + if you want to create a cinematic effect or have the camera follow a user-controlled object. + + To set a camera to look at an object: + + \list 1 + \li In \uicontrol Navigator, select the camera. + \li In \uicontrol Properties > \uicontrol {Look-at-Node}, select the object that + the camera should look at. + \image camera-look-at-node.webp + \endlist + + When you set a camera to look at an object, the camera automatically rotates to + point toward the assigned object, even if the object or the camera moves. The rotation only + happens around the x and y axes. + */ diff --git a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-custom-shaders.qdoc b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-custom-shaders.qdoc index b559fd2230..f053834f0d 100644 --- a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-custom-shaders.qdoc +++ b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-custom-shaders.qdoc @@ -29,7 +29,7 @@ \uicontrol {Custom Material} components, in \uicontrol Components > \uicontrol {Qt Quick3D} > \uicontrol {Qt Quick 3D}. - \image studio-qtquick-3d-components.png "Effect and Custom Material Components in Components" + \image studio-qtquick-3d-components.webp "Effect and Custom Material Components in Components" \note In Qt 5 the \uicontrol Effect component is located in \uicontrol {Qt Quick 3D Effects} > @@ -218,7 +218,7 @@ \row \li \l Blending - \li \inlineimage ok.png + \li \li A pass command that specifies the source blending function. The \uicontrol Source property specifies the source blending diff --git a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-editor.qdoc b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-editor.qdoc index 7111d2db90..ff67fa14a8 100644 --- a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-editor.qdoc +++ b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-editor.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2022 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -6,57 +6,35 @@ \page studio-3d-editor.html \nextpage studio-material-editor.html + \ingroup studio-views + \title 3D + \brief Edit a 3D scene. + When editing a 3D scene, you view the scene in the \uicontrol{3D} - view. You can change the projection of the view by switching between - \e {perspective camera} and \e {orthographic camera} modes. When using the - perspective camera mode, components that are far from the camera appear - smaller than those nearby. In the orthographic camera mode, all components - appear at the same scale irrespective of their distance from the camera. - Both of them are free-form camera modes that you can use to orbit around - the scene. + view. When you import 3D scenes from files that you exported from 3D graphics tools, you also import a \l{Cameras}{scene camera}, - \l{Lights}{light}, \l{3D Models}{model}, and - \l {Materials and Shaders}{materials}. If your scene did not contain - them, you can add the corresponding \l {3D Components}{Qt Quick 3D} + \l{Lights}{light}, \l{3D Models}{model}, and \l {Materials and Shaders}{materials}. + If your scene does not contain them, add the corresponding \l {3D Components}{Qt Quick 3D} components from \uicontrol Components > \inlineimage icons/plus.png > \uicontrol {Qt Quick 3D} > \uicontrol {Qt Quick 3D}. - You can use the \l{Summary of the 3D View Toolbar Buttons}{toolbar buttons} - to \e transform 3D components and manipulate the 3D scene. Transformation - refers to moving, rotating, or scaling of a component. The \e pivot of the - component is used as the origin for transformations. You can set a - \l{Managing 3D Transformations}{local pivot offset} for a component in - \uicontrol Properties to transform the component around a point other than - its local origin. A line is drawn in the \uicontrol{3D} view from the pivot - point to the center of the component to provide a visual connection between - them. Especially when working with complex scenes, it may be useful to use - the \l {Showing and Hiding Components}{showing and hiding} or the - \l {Locking Components}{locking} features in \l Navigator to avoid - transforming components by mistake while editing your scene. - - Toggle between local and global orientation to determine whether the gizmos - affect only the local transformations of the component or whether they - transform with respect to the global space. - - Another helpful feature when editing 3D scenes is the \e {edit light}, - which is a quick way to light the scene. - - Additionally, you can toggle the visibility of the grid, selection boxes, - icon gizmos, and camera frustums in the 3D scene. + Use the \uicontrol 3D toolbar buttons to modify the \uicontrol 3D view, + manipulate the 3D scene, and to access functionalities to \e transform 3D + components. Transformation refers to moving, rotating, or scaling a + component. The \e pivot of the component is used as the origin for + transformations. Set a \l{Managing 3D Transformations}{local pivot offset} + for a component in \uicontrol Properties to transform the component around + a point other than its local origin. A line is drawn in the \uicontrol{3D} + view from the pivot point to the center of the component to provide a visual + connection between them. - There is a context menu in the \uicontrol 3D view. To open it, right-click - in the \uicontrol 3D view. From the context menu you can: - \list - \li Create cameras, lights, and models. - \li Open \uicontrol {Material Editor} and edit materials. - \li Delete components - \endlist - - \image 3d-view-context-menu.png + \note To avoid transforming components by mistake while editing your scene, + use the \l {Showing and Hiding Components}{showing and hiding} or the + \l {Locking Components}{locking} features in \l Navigator. To refresh the contents of the \uicontrol{3D} view, press \key P or select the \inlineimage icons/reset.png @@ -69,66 +47,142 @@ \youtube SsFWyUeAA_4 + \include qtdesignstudio-qt-academy.qdocinc qt-academy-3D-with-qt-design-studio + + \section1 Using the Context Menu in the 3D View + + There is a context menu in the \uicontrol 3D view. To open it, right-click + in the \uicontrol 3D view. From the context menu you can, for example: + \list + \li Create cameras, lights, and models. + \li Open \uicontrol {Material Editor} and edit materials. + \li Delete components. + \li Align camera views. + \endlist + + \image 3d-view-context-menu.webp "The context menu in the 3D view" + \section1 Controlling the 3D View Camera - To switch to perspective camera mode, select - \inlineimage perspective_camera.png - (\uicontrol {Toggle Perspective/Orthographic Edit Camera}). - To switch to orthographic camera mode, select - \inlineimage orthographic_camera.png - . You can also Toggle the camera mode by using the keyboard shortcut \key T. + \section2 Toggling Camera Mode + + Change the projection of the view by switching between \e {perspective camera} + and \e {orthographic camera} modes. When using the perspective camera mode, + components that are far from the camera appear smaller than those nearby. In + the orthographic camera mode, all components appear at the same scale + irrespective of their distance from the camera. Both of them are free-form + camera modes that you can use to orbit around the scene. + + To toggle the camera mode, do one of the following: + \list + \li Select \inlineimage perspective_camera.png + (\uicontrol {Toggle Perspective/Orthographic Camera}) to use the + perspective camera mode. + \li Select \inlineimage orthographic_camera.png to use the orthographic + camera mode. + \endlist + You can also toggle the camera mode by using the keyboard shortcut \key T. + + \section2 Navigating in the 3D Scene - You can navigate the scene by panning, rotating, and zooming the 3D view + Navigate the scene by panning, rotating, and zooming the 3D view camera: \list \li To pan, press \key Alt (or \key Option on \macos) and use the - middle mouse button to click and drag anywhere in the rendered - view to slide the view around. - \note It is not possible to pan using Magic Mouse. - \li To orbit, press \key Alt and click and drag anywhere in the rendered - view to rotate the view. + wheel button to drag anywhere in the \uicontrol 3D view to + slide the view around. Alternatively, press and hold \key + {right mouse button} and \key {left mouse button} and drag + anywhere in the view to pan. + \li To orbit, press \key Alt and and drag anywhere in the + \uicontrol 3D view to rotate the view. \li To zoom, use the mouse wheel or press \key Alt and right-click - anywhere in the rendered view to zoom the view in or out as you drag + anywhere in the \uicontrol 3D view to zoom the view in or out as you drag up or down. \endlist - To zoom and focus the 3D view camera on a selected component, - select \inlineimage fit_selected.png - (\uicontrol {Fit Selected}) or press \key F. + To zoom and focus the 3D view camera on a selected component, select + \inlineimage fit_selected.png (\uicontrol {Fit Selected}) or press \key F. The world axis helper (1) shows the direction of the world axes in the view. - To point the camera at the currently selected component in the direction of + To point the 3D view camera at the currently selected component in the direction of an axis, click the axis. Clicking the dot at the end of the axis will point the camera at the opposite direction of the axis. If no component is - selected, the camera is pointed at the world origin. This does not affect - the camera zoom level. + selected, the camera is pointed at the world origin. + + \image studio-3d-editor-axis-helper.webp "Axis helper in the 3D view" + + Use scene cameras (2) to view the \uicontrol View3D component from a + specific angle in the \l {2D} view while editing scenes. Drag a camera + component to your scene from \uicontrol Components > \uicontrol {Qt Quick 3D} > + \uicontrol {Qt Quick 3D}. For more information about using cameras in the + scene and the available camera types, see \l{Cameras}. + + \section2 Using Split View To view the scene in a split view of four different point of views, select \inlineimage icons/split-view.png. \image studio-3d-split-view.webp "Split view in the 3D view" - To select one of the four panes, click on it. The selected pane is marked with + To select one of the four panes, click the pane. The selected pane is marked with a blue frame. Use the world axis helper to change the point of view for each pane independently. Navigate each split by panning, rotating, and zooming, as described above. - \image studio-3d-editor-axis-helper.webp "Axis helper in the 3D view" + \section2 Using Fly Mode + + Use the fly mode to move around freely in the 3D scene. To navigate the scene with + fly mode, right-click and hold in the \uicontrol 3D view, and use the keyboard shortcuts + to move around the scene: + + \table + \header + \li Key + \li Action + \row + \li \key W or \key {Up arrow} + \li Move forward. + \row + \li \key S or \key {Down arrow} + \li Move backward. + \row + \li \key A or \key {Left arrow} + \li Move left. + \row + \li \key D or \key {Right arrow} + \li Move right. + \row + \li \key E or \key {Page up} + \li Move up. + \row + \li \key Q or \key {Page down} + \li Move down. + \row + \li \key Shift + \li Move faster. + \row + \li \key Alt + \li Move slower. + \row + \li \key Spacebar + \li Move to an object in the crosshairs. + \endtable + + To adjust the movement speed, right-click and hold in the \uicontrol 3D view, and rotate the + mouse wheel. Alternatively, select \inlineimage icons/camera_speed.png in the \uicontrol 3D + view toolbar to open the configuration dialog. - You can use scene cameras (2) to view the \uicontrol View3D component from a - specific angle in the \l {2D} view while editing scenes. Different types of - cameras are available in \uicontrol Components - > \uicontrol {Qt Quick 3D} > \uicontrol {Qt Quick 3D}. For more information - about using cameras in the scene, the available camera types, and their - properties, see \l{Cameras}. + In the configuration dialog, you can: + \list + \li Adjust the movement speed of the camera with a slider. + \li Set a value multiplier for the speed slider. + \endlist \section1 Using Global and Local Orientation - To switch between local and global orientation, select - \inlineimage global.png - (\uicontrol {Toggle Local/Global Orientation}) - or press \key Y. + In \uicontrol 3D view, you view the scene in global or local orientation + mode. In global orientation mode, transformation of a selected component is presented with respect to the global space. For example, while the move tool @@ -142,40 +196,40 @@ the axes of global space. Dragging on the red arrow of the gizmo moves the component in the local x direction in relation to the component. + To switch between local and global orientation, select \inlineimage global.png + (\uicontrol {Toggle Local/Global Orientation}) or press \key Y. + \section1 Using Edit Light The edit light is an extra point light that can be used to illuminate the scene. To toggle the edit light on and off, select \inlineimage edit_light_on.png - or \inlineimage edit_light_off.png - (\uicontrol {Toggle Edit Light}) - or press \key U. + or \inlineimage edit_light_off.png (\uicontrol {Toggle Edit Light}) or + press \key U. - For more information about the available scene light types and their - properties, see \l{Lights}. + For information about the available scene light types and their properties, + see \l{Lights}. \section1 Baking Lights - Bake lights to light static elements in your scene. To bake lights, - select \inlineimage icons/bakelights.png to open the - \uicontrol {Lights Baking Setup} dialog. For more information, see - \l {Baking Lightmaps}. + Bake lights to light static elements in your scene. To bake lights, select + \inlineimage icons/bakelights.png to open the \uicontrol {Lights Baking Setup} + dialog. For more information, see \l {Baking Lightmaps}. \section1 Selecting Components To move, rotate, or scale components in the scene, you need to select them - first. The selection mode buttons determine how components are selected when - you click them in the \uicontrol{3D} view: + first. Toggle the selection mode to determine how components are selected + when you click them in the \uicontrol{3D} view: \list - \li In the \inlineimage select_item.png - (\uicontrol {Single Selection}) mode, a single component is selected. - \li In the \inlineimage select_group.png - (\uicontrol {Group Selection}) mode, the top level parent of the - component is selected. This enables you to move, rotate, or scale a - group of components. + \li Use the \inlineimage select_item.png (\uicontrol {Single Selection}) + mode to select a single component. + \li Use the \inlineimage select_group.png (\uicontrol {Group Selection}) + mode to select the top level parent of the component, so you can move + a group of components simultaneously. \endlist - To toggle the selection mode, press \key Q. + Alternatively, press \key Q to toggle the selection mode. To multiselect, hold \key Ctrl and click the components you wish to select. @@ -192,16 +246,15 @@ y, or z axis or on the top, bottom, left, and right clip planes of the the \uicontrol{3D} view. - To move components, select \inlineimage move_off.png - or press \key W: + To move components, select \inlineimage move_off.png or press \key W: \list \li To move components along the axes of the move gizmo, click the axis, and drag the component along the axis. - \li To move components on a plane, click the plane handle and drag the + \li To move components on a plane, drag the plane handle of the move component on the plane. - \li To move components freely in the 3D view, click and drag the gray - handle at the center of the move gizmo. + \li To move components freely in the 3D view, drag the gray handle at the + center of the move gizmo. \endlist \section1 Rotating Components @@ -212,29 +265,28 @@ or press \key E: \list - \li To rotate a component around its rotation gizmo, click the axis ring - and drag in the direction you want to rotate the component in. - \li To freely rotate the component, click and drag the inner center - circle of the gizmo. + \li To rotate a component around its rotation gizmo, drag the axis ring + in the direction you want to rotate the component in. + \li To freely rotate the component, drag the inner center circle of the + gizmo. \endlist \section1 Scaling Components \image studio-3d-editor-scale.webp "The 3D view in scale mode" - You can use the scale handles to adjust the local x, y, or z scale of a + Úse the scale handles to adjust the local x, y, or z scale of a component. You can adjust the scale across one, two, or three axes, depending on the handle. - To scale components, select \inlineimage scale_off.png - or press \key R: + To scale components, select \inlineimage scale_off.png or press \key R: \list - \li To adjust the scale across one axis, click and drag the scale handle + \li To adjust the scale across one axis, drag the scale handle attached to the axis. - \li To adjust the scale across a plane, click the plane handle and drag - the component on the plane. - \li To uniformly scale a component across all axes, click and drag the + \li To adjust the scale across a plane, drag the plane handle of + the component. + \li To uniformly scale a component across all axes, drag the gray handle at the center of the component. \endlist @@ -243,7 +295,7 @@ With snapping turned on, the objects in the \uicontrol 3D view snap to certain intervals during transformation (move, rotate, scale). - You can toggle snapping in the following ways: + Toggle snapping in the following ways: \list \li Select \inlineimage icons/snapping-3d.png @@ -251,7 +303,7 @@ \li Hold down the \key Ctrl key. \endlist - With snapping turned on, you can press and hold \key Shift to snap objects to one tenth of + With snapping turned on, press and hold \key Shift to snap objects to one tenth of the specified snap interval. \section2 Configuring Snapping @@ -278,78 +330,85 @@ To align a camera to the \uicontrol{3D} view: \list 1 - \li Select a camera in the \uicontrol{3D} or \uicontrol {Navigator} view. + \li Select a scene camera in the \uicontrol{3D} or \uicontrol {Navigator} view. \note If you don't have a camera selected, the most recently selected camera is aligned to the view. - \li In the \uicontrol{3D} view, - select \inlineimage icons/align-camera-on.png - . + \li In the \uicontrol{3D} view, select \inlineimage icons/align-camera-on.png. \endlist - This moves and rotates the camera so that the camera shows the same view - as the current view in the \uicontrol{3D} view. + This moves and rotates the scene camera to show the same view as the current view + in the \uicontrol{3D} view. To align the \uicontrol{3D} view to a camera: - \list 1 - \li Select a camera in the \uicontrol{3D} view or \uicontrol {Navigator}. + \list 1 + \li Select a scene camera in the \uicontrol{3D} view or \uicontrol {Navigator}. \note If you don't have a camera selected, the view is aligned to the most recently - selected camera. - \li In the \uicontrol{3D} view, - select \inlineimage icons/align-view-on.png - . + selected camera. + \li In the \uicontrol{3D} view, select \inlineimage icons/align-view-on.png. \endlist - This copies the position as well as x and y rotation values from the - camera and applies them to the \uicontrol{3D} view. + This moves and rotates the 3D view to show the same view as the selected scene camera. \section1 Toggling Visibility To toggle the visibility of objects in the \uicontrol{3D} view, select - \inlineimage icons/visibilityon.png - in the toolbar. This opens a menu with the following options: + \inlineimage icons/visibilityon.png in the toolbar. This opens a menu with the + following options: \table - \row - \li Show Grid - \li Toggles the visibility of the helper grid. - \row - \li Show Selection Boxes - \li Toggles the visibility of selection boxes for selected 3D objects. - \row - \li Show Icon Gizmos - \li Toggles the visibility of icon gizmos for object such as cameras, - lights, and particle systems. - \row - \li Always Show Camera Frustums - \li Toggles between always showing the camera frustum and showing it - only for cameras selected in the \uicontrol{3D} view. - \row - \li Always Show Particle Emitters and Attractors - \li Toggle between always showing the particle emitter and attractor - visualizations and only showing them when the emitter or attractor is - selected in the \uicontrol{3D} view. + \header + \li Action + \li Description + \li Keyboard Shortcut + \row + \li Show Grid + \li Toggles the visibility of the helper grid. + \li \key G + \row + \li Show Selection Boxes + \li Toggles the visibility of selection boxes for selected 3D objects. + \li \key B + \row + \li Show Icon Gizmos + \li Toggles the visibility of icon gizmos for object such as cameras, + lights, and particle systems. + \li \key I + \row + \li Always Show Camera Frustums + \li Toggles between always showing the camera frustum and showing it + only for cameras selected in the \uicontrol{3D} view. + \li \key C + \row + \li Always Show Particle Emitters and Attractors + \li Toggles between always showing the particle emitter and attractor + visualizations and only showing them when the emitter or attractor + is selected in the \uicontrol{3D} view. + \li \key M \endtable \section1 Changing Colors To change the \uicontrol 3D view background or grid color, select - \inlineimage icons/3d-background-color.png - in the toolbar. This opens a menu with the following options: + \inlineimage icons/3d-background-color.png in the toolbar. This opens a menu + with the following options: \table + \header + \li Action + \li Decription + \row + \li Select Background Color + \li Select a color for the background. \row - \li Select Background Color - \li Select a color for the background. - \row - \li Select Grid Color - \li Select a color for the grid. + \li Select Grid Color + \li Select a color for the grid. \row - \li Use Scene Environment Color - \li Sets the 3D view to use the scene environment color as background - color. + \li Use Scene Environment Color + \li Sets the 3D view to use the scene environment color as background + color. \row - \li Reset Colors - \li Resets the background and grid colors to the default colors. + \li Reset Colors + \li Resets the background and grid colors to the default colors. \endtable \section1 Particle Editor @@ -364,16 +423,14 @@ \li Select a particle system in the \uicontrol Navigator or \uicontrol{3D} view. \li In the \uicontrol{3D} view, select - \inlineimage icons/particle-animation-on.png - to activate particle animation. Now you can see the particle animation in - the \uicontrol{3D} view. + \inlineimage icons/particle-animation-on.png to activate particle animation. + Now you can see the particle animation in the \uicontrol{3D} view. \endlist You can pause the particle animation by selecting - \inlineimage icons/particle-pause.png - . When the animation is paused, you can use - \inlineimage icons/particles-seek.png - to manually seek forward or backward in the particle animation. + \inlineimage icons/particle-pause.png. When the animation is paused, use + \inlineimage icons/particles-seek.png to manually seek forward or backward in + the particle animation. \section1 Using Viewport Shading @@ -423,120 +480,4 @@ Select \uicontrol{Reset All Viewports} to reset the shading of the scene in all of the splits. - \section1 Summary of the 3D View Toolbar Buttons - - The \uicontrol{3D} view toolbar contains the following buttons: - - \table - \header - \li Button - \li Tooltip - \li Keyboard Shortcut - \li Read More - \row - \li \inlineimage icons/select_group.png - \inlineimage icons/select_item.png - \li Toggle Group/Single Selection Mode - \li \key Q - \li \l{Selecting Components} - \row - \li \inlineimage icons/move_off.png - \li Activate the Move Tool - \li \key W - \li \l{moving components 3d view}{Moving Components} - \row - \li \inlineimage icons/rotate_off.png - \li Activate Rotate Tool - \li \key E - \li \l{Rotating Components} - \row - \li \inlineimage icons/scale_off.png - \li Activate Scale Tool - \li \key R - \li \l{Scaling Components} - \row - \li \inlineimage icons/fit_selected.png - \li Fit Selected Object to View - \li \key F - \li \l{Controlling the 3D View Camera} - \row - \li \inlineimage icons/perspective_camera.png - \inlineimage icons/orthographic_camera.png - \li Toggle Perspective/Orthographic Edit Camera - \li \key T - \li \l{Controlling the 3D View Camera} - \row - \li \inlineimage icons/global.png - \li Toggle Global/Local Orientation - \li \key Y - \li \l{Using Global and Local Orientation} - \row - \li \inlineimage icons/edit_light_off.png - \inlineimage icons/edit_light_on.png - \li Toggle Edit Light On/Off - \li \key U - \li \l{Using Edit Light} - \row - \li \inlineimage icons/snapping-3d.png - \li Toggle Snapping During Node Drag - \li \key Shift + \key Tab - \li \l{Snapping} - \row - \li \inlineimage icons/snapping-3d-conf.png - \li Open Snap Configuration Dialog - \li - \li \l{Configuring Snapping} - \row - \li \inlineimage icons/align-camera-on.png - \li Align Selected Cameras to View - \li - \li\l{Aligning Views and Cameras} - \row - \li \inlineimage icons/align-view-on.png - \li Align View to Selected Camera - \li - \li \l{Aligning Views and Cameras} - \row - \li \inlineimage icons/visibilityon.png - \li Visibility Toggles - \li - \li \l{Toggling Visibility} - \row - \li \inlineimage icons/3d-background-color.png - \li Background Color Actions - \li - \li \l{Changing Colors} - \row - \li \inlineimage icons/split-view.png - \li Toggle Split View On/Off - \li \key Ctrl + \key Alt + \key Q - \li \l{Using Split View} - \row - \li \inlineimage icons/particles-seek.png - \li Seek Particle System Time - \li - \li \l{Particle Editor} - \row - \li \inlineimage icons/particle-animation-on.png - \li Toggle Particle Animation - \li \key V - \li \l{Particle Editor} - \row - \li \inlineimage icons/particle-play.png - \inlineimage icons/particle-pause.png - \li Play/Pause Particles - \li \key , - \li \l{Particle Editor} - \row - \li \inlineimage icons/particle-restart.png - \li Restart Particles - \li \key / - \li \l{Particle Editor} - \row - \li \inlineimage icons/reset.png - \li Reset View - \li \key P - \li - \endtable - */ diff --git a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-effects.qdoc b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-effects.qdoc index 158932dff8..95eb3232d7 100644 --- a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-effects.qdoc +++ b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-effects.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -263,7 +263,7 @@ be transparent in the \uicontrol {Background Mode} field of the \uicontrol {Scene Environment} component. Otherwise, the clear color of the background hides the blur. For more information, see - \l {Scene Environment}. + \l {Scene Environments}. The \uicontrol {Fade Amount} property defines the fade speed of the trail. diff --git a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-lights.qdoc b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-lights.qdoc index af994d5877..c7ae1e955e 100644 --- a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-lights.qdoc +++ b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-lights.qdoc @@ -9,7 +9,7 @@ \title Lights Light components are the primary source of lighting in a \QDS scene. - As a secondary light source, you can use \l{Setting the Light Probe} + As a secondary light source, you can use \l{Setting Image Based Lighting} {image-based lighting}. To add a light component to your UI, do one of the following: diff --git a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-model.qdoc b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-model.qdoc index 4159269bc7..e1f6edd8de 100644 --- a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-model.qdoc +++ b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-model.qdoc @@ -27,11 +27,14 @@ \note You can not create \uicontrol Empty models this way. \endlist + Double-clicking a 3D model in \uicontrol 2D view opens the \uicontrol 3D view with + the 3D model selected. + If you cannot find the model components in \uicontrol {Components}, add the \uicontrol QtQuick3D module to your project, as described in \l {Adding and Removing Modules}. - \image studio-qtquick-3d-components.png "The Qt Quick 3D section in Components" + \image studio-qtquick-3d-components.webp "The Qt Quick 3D section in Components" \section1 Model Properties diff --git a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-repeater-3d.qdoc b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-repeater-3d.qdoc index 9e181a8aae..5cf2370cc9 100644 --- a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-repeater-3d.qdoc +++ b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-repeater-3d.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -8,10 +8,6 @@ \title Repeater3D - \note The \uicontrol Repeater3D component is released as a tech preview - feature in \QDS 2.2, and its functionality will be improved in future - releases. - The \uicontrol Repeater3D component is used to create multiple similar items. Like other view types, \uicontrol Repeater3D needs a model and a delegate. The delegate sets the item to use and the model sets the @@ -100,90 +96,58 @@ \endlist \image repeater3d-numeric-model.webp - \section1 Adding a Repeater3D Component with a List Model + \section1 Adding a Repeater3D Component with a Model This section explains how to add a \uicontrol Repeater3D component with - a ListModel to your \QDS project: + a model to your \QDS project: To add a \uicontrol Repeater3D component: \list 1 \li Drag a \uicontrol Repeater3D component from \uicontrol Components to \e scene in \uicontrol Navigator. - \li You need to enter the QML code for the \uicontrol ListModel manually. - Go to the \uicontrol {Code} view and enter the following code somewhere - inside the root object: - \code qml - ListModel { - id: planetModel - ListElement { - name: "Mars" - radius: 3.39 - } - ListElement { - name: "Earth" - radius: 6.37 - } - ListElement { - name: "Venus" - radius: 6.05 - } - } - \endcode - The default root object for a \QDS project is \uicontrol Rectangle, so - you can paste the \uicontrol ListModel code, for example, like this: - \code qml - Rectangle { - width: Constants.width - height: Constants.height - color: Constants.backgroundColor - - ListModel { - id: planetModel - ListElement { - name: "Mars" - radius: 3.39 - } - ListElement { - name: "Earth" - radius: 6.37 - } - ListElement { - name: "Venus" - radius: 6.05 - } - } - - View3D { - id: view3D - anchors.fill: parent - ... - \endcode - \li In the \uicontrol {Code} view, add \c {model: planetModel} to the - \uicontrol Repeater3D object to tell that you want to use your - \uicontrol ListModel as the model for the \uicontrol Repeater3D object. - \code qml - Repeater3D { - id: repeater3D - model: planetModel - } - \endcode + \li Go to \uicontrol {Model Editor} and create a new model with the name + \e planetModel. + \li Add the following columns and data to the model. + \raw HTML + <table> + <tr> + <th>name (<i>String</i>)</th> + <th>radius (<i>Real</i>)</th> + </tr> + <tr> + <td>Mars</td> + <td>3.39</td> + </tr> + <tr> + <td>Earth</td> + <td>6.37</td> + </tr> + <tr> + <td>Venus</td> + <td>6.05</td> + </tr> + </table> + \endraw + \note You can also import a model in JSON or CSV format. See \l {Importing a Data Model}. + \image repeater3d-model-editor.webp + \li In \uicontrol Navigator, select \e{_3DRepeater}. + \li In \uicontrol Properties, set \uicontrol Model to \e {DataStore.planetModel}. \endlist - Now, you have set up the \uicontrol Repeater3D component to use a \uicontrol ListModel to draw the items. Next, you need to add the - item to draw. In this example we are using a \uicontrol Sphere. + item to draw. In this example, you are using a \uicontrol Sphere. \list 1 - \li From \uicontrol Components, drag a \uicontrol Sphere to \e repeater3D + \li From \uicontrol Components, drag a \uicontrol Sphere to \e _3DRepeater in \uicontrol Navigator. \image repeater3d-listmodel-navigator.png - \li Select \e sphere in \uicontrol Navigator and select + \li Select \e sphere in \uicontrol Navigator and in the \uicontrol Properties view, select \inlineimage icons/action-icon.png next to \uicontrol Scale > \uicontrol X. \li Select \uicontrol {Set binding} to open \uicontrol {Binding Editor}. \li In the binding editor, enter \c{radius}. This sets the X - scale to the radius value defined in the ListModel for each of the sphere + scale to the radius value defined in the model for each of the sphere instances. \image repeater3d-radius-binding.png \li Select \uicontrol OK. @@ -195,7 +159,7 @@ position so you need to change the position to see all spheres. \list 1 - \li Select \e sphere in \uicontrol Navigator and select + \li Select \e sphere in \uicontrol Navigator and in the \uicontrol Properties view, select \inlineimage icons/action-icon.png next to \uicontrol Translation > \uicontrol X. \li Select \uicontrol {Set binding} to open \uicontrol {Binding Editor}. diff --git a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-scene-environment.qdoc b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-scene-environment.qdoc index 6e9db7012c..5d18f39a83 100644 --- a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-scene-environment.qdoc +++ b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-scene-environment.qdoc @@ -1,4 +1,4 @@ -// 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 /*! @@ -6,31 +6,43 @@ \previouspage studio-3d-camera.html \nextpage studio-3d-morph-target.html - \title Scene Environment + \title Scene Environments - You can use the \uicontrol {Scene Environment} component to specify - how a scene is rendered globally. You can specify settings for antialiasing, - scene background, ambient occlusion, and image-based lighting in the - \l Properties view. The \uicontrol {Scene Environment} component is available - in \uicontrol Components > \uicontrol {Qt Quick 3D}. It is - automatically included under the 3D view component in \l{Creating Projects} - {projects created} using the \uicontrol {Qt Quick 3D Application} wizard - template. + The \uicontrol {Scene Environment} and the \uicontrol {Extended Scene Environment} + components define how a scene is rendered globally. - \note If you select \uicontrol {Qt 5} as the \uicontrol {Target Qt Version} - when \l {Creating Projects}{creating your project}, the available properties - for this component will be slightly different. The properties may also be - situated differently in the \uicontrol Properties view. + \note The available properties for the scene environments and their location in the + \uicontrol Properties view vary according to \uicontrol {Target Qt Version} that + you select when \l {Creating Projects}{creating your project}. + + \note \uicontrol {Extended Scene Environment} is available in projects created with + Qt 6.5 or higher as the \uicontrol {Target Qt Version}. + + \section1 Adding Scene Environments to Projects + + Add the scene environment components to projects by selecting a suitable preset when + \l{Creating Projects}{creating your project}. + + Use the \uicontrol {3D} preset to create a project with a \uicontrol View3D + component that includes a scene environment. If you need to add it manually, it is + available in \uicontrol Components > \uicontrol {Qt Quick 3D}. + + Use the \uicontrol {Extended 3D} preset to create a project with a 3D view + component that includes an extended scene environment. It is also + available in \uicontrol Components > \uicontrol {Qt Quick 3D Helpers}. \section1 Setting the Scene Environment - In the \uicontrol {Scene Environment} section of the \uicontrol Properties - view, you can specify whether and how the background of the scene should be - cleared, specify whether you wish to perform depth-tests on the scene, - apply post-processing effects to the scene, and define how colors are - tonemapped before the scene is rendered. + To define properties for the scene environment, select \uicontrol {Scene Environment} + in \uicontrol Navigator and specify its properties in the \uicontrol Properties view. - \image studio-3d-scene-environment-properties.png "The Scene Environment properties" + Set the properties in the \uicontrol {Scene Environment} section of the + \uicontrol Properties view to specify whether and how the background + of the scene should be cleared, to apply post-processing effects to the scene, + to define how colors are tonemapped before the scene is rendered, and to + specify fog settings. + + \image studio-3d-scene-environment-properties.webp "The Scene Environment properties" The \uicontrol {Clear color} property specifies which color will be used to clear the background of the scene if \uicontrol {Background mode} is defined @@ -64,23 +76,22 @@ image as a \uicontrol SkyBox using the \uicontrol Image property in the \uicontrol {Light probe} section (In Qt 5, the \uicontrol {Light Probe} property in - the \uicontrol {Image-Based Lighting} group. + the \uicontrol {Image-Based Lighting} group). + \row + \li SkyBoxCubeMap + \li The scene will not be cleared, but instead a + \uicontrol SkyBox or Skydome that uses a \uicontrol CubeMapTexture + will be rendered. A cube map texture has six faces + (X+, X-, Y+, Y-, Z+, and Z-), where each face is an individual + 2D image. Selecting this mode allows custom materials and post-processing + effects to work with cube map textures in their shaders. \endtable To leave the scene uncleared, select \uicontrol {Unspecified} as the \uicontrol {Background mode}. - You can perform depth tests to optimize the scene environment. To skip the - depth tests, deselect the \uicontrol {Enable depth test} checkbox. Note that - skipping the tests can cause rendering errors. - - To have the renderer write to the depth buffer as part of the color pass, - deselect the \uicontrol {Enable depth prepass} checkbox. Deselecting the - checkbox disables the depth prepass on any GPU that uses tiled rendering - architecture. - - The \uicontrol Effect property defines a post-processing effect to the - scene. Use the dropdown menu to select one of the effects that will be + The \uicontrol Effects property defines post-processing effects applied + to the scene. Use the dropdown menu to select one of the effects that will be applied to the entire scene. The order of the effects is significant since the result of each effect is fed to the next. @@ -92,14 +103,21 @@ tonemapping, or \uicontrol ToneMapModeFilmic to apply filmic tonemapping. \note The \uicontrol {Tonemap mode} property is not available in Qt 5. + The \uicontrol Fog property defines settings for fog applied to the + scene. When the \uicontrol Fog property of a scene environment is set to a + valid \uicontrol Fog object, the properties are used to configure the + rendering of fog. The simple fog provided by this type is implemented by + the materials. Use the dropdown menu to select a \uicontrol Fog object for + your scene. + \section1 Applying Antialiasing - Antialiasing is used to make curved lines smoother on the screen. In the + Use antialiasing to make curved lines smoother on the screen. In the \uicontrol Antialiasing section of the \uicontrol Properties view, you can specify the mode and quality of antialiasing and also enable temporal antialiasing and define its strength. - \image studio-3d-scene-environment-antialiasing.png "The Antialiasing properties" + \image studio-3d-scene-environment-antialiasing.webp "The antialiasing properties" The \uicontrol {Antialiasing mode} property specifies the mode of antialiasing applied when the scene is rendered. Select one of the following @@ -174,11 +192,12 @@ animations stop. The \uicontrol {Temporal AA strength} property modifies the amount of - temporal movement in antialiasing. This property only has an effect when + temporal movement in antialiasing. This property is only available when the \uicontrol {Temporal AA} property is set to true. - \note In Qt 5, the antialiasing properties are located in - \uicontrol Properties > \uicontrol {Scene Environment}. + The \uicontrol {Specular AA} property enables specular antialiasing. Specular + aliasing is often visible in form of bright dots and flickering when moving the + camera around. \section1 Applying Ambient Occlusion @@ -188,14 +207,17 @@ \uicontrol {Sample rate}, and \uicontrol Bias properties in the \uicontrol {Ambient Occlusion} section of the \uicontrol Properties view. - \image studio-3d-scene-environment-ambient-occlusion.png "The Ambient Occlusion properties" + \image studio-3d-scene-environment-ambient-occlusion.webp "The ambient occlusion properties" + + In \uicontrol Properties > \uicontrol {Ambient Occlusion}, select the + \uicontrol Enabled checkbox to define settings for ambient occlusion. - You can set the strength of the shadows using the \uicontrol Strength - property, which defines the amount of ambient occlusion applied. A value of - 100 causes full darkness shadows, while lower values cause the shadowing to - appear lighter. A value of 0 disables ambient occlusion entirely, thus - improving performance at a cost to the visual realism of 3D objects rendered - in the scene. All values other than 0 have the same impact on performance. + Set the strength of the shadows using the \uicontrol Strength property, + which defines the amount of ambient occlusion applied. A value of 100 causes + full darkness shadows, while lower values cause the shadowing to appear lighter. + A value of 0 disables ambient occlusion entirely, thus improving performance at + a cost to the visual realism of 3D objects rendered in the scene. All values other + than 0 have the same impact on performance. The \uicontrol Distance property defines roughly how far the ambient occlusion shadows spread away from objects. Greater distances cause increasing impact @@ -213,7 +235,7 @@ occlusion, try adjusting the value in the \uicontrol {Clip far} field in the \l{Cameras}{scene camera} properties. - The \uicontrol {Sample rate} property specifies the number of shades of gray, + The \uicontrol {Sample Rate} property specifies the number of shades of gray, thus defining the quality of ambient occlusion at the expense of performance. The \uicontrol Bias property defines a cutoff distance preventing objects @@ -227,15 +249,15 @@ differently: \uicontrol {AO strength}, \uicontrol {AO distance}, \uicontrol {AO softness}, \uicontrol {AO dither}, and \uicontrol {AO bias}. - \section1 Setting the Light Probe + \section1 Setting Image Based Lighting - In the \uicontrol {Light Probe} section of the \uicontrol Properties view, - you can set the \uicontrol Image, \uicontrol Exposure, \uicontrol Horizon, + In the \uicontrol {Image Based Lighting} section of the \uicontrol Properties view, + you can set the \uicontrol {HDR Image}, \uicontrol Exposure, \uicontrol Horizon, and \uicontrol Orientation properties for image-based lighting. - \image studio-3d-scene-environment-light-probe.png "The Light Probe properties" + \image studio-3d-scene-environment-image-based-lighting.webp "Image based lighting properties" - The \uicontrol Image property defines an image used to light the scene + The \uicontrol {HDR Image} property defines an image used to light the scene instead of or in addition to standard lights. The image is preferably a high-dynamic range image or a pre-generated cubemap. Pre-baking provides significant performance improvements at run time because no time is spent on @@ -286,4 +308,45 @@ The value of the \uicontrol {Probe FOV} property sets the angle of the image source field of view when using a camera source as the IBL probe. + + \section2 Advanced Scene Environment settings + + You can perform depth tests to optimize the scene environment. To skip the + depth tests, clear the \uicontrol {Enable depth test} checkbox. Note that + skipping the tests can cause rendering errors. + + To have the renderer write to the depth buffer as part of the color pass, + clear the \uicontrol {Enable depth prepass} checkbox. Clearing the + checkbox disables the depth prepass on any GPU that uses tiled rendering + architecture. + + To specify additional render settings for debugging scenes, define + \uicontrol {Debug Settings}. + + To define lightmap baking settings for direct and indirect lighting, use + the \uicontrol {Light Mapper} property to specify a lightmapper object. + These settings are not relevant at other times, such as when using already + generated lightmaps to render a scene. + + \section1 Setting the Extended Scene Environment + + In addition to properties described above, in the extended scene environment + you can apply effects to your scene by defining them as properties. When enabling + one or more of these effects, the result is similar to manually adding + \l {3D Effects}{effects} to \uicontrol {Scene Environment}. + + Use \uicontrol {Extended Scene Environment} instead of \uicontrol {Scene Environment} + to add multiple and complex effects to your scene. Because the \uicontrol + {Extended Scene Environment} combines the effects that are enabled, the number of + render passes is reduced, which results in significantly better performance + than applying individual post-processing effects to the scene. + + For the extended scene environment, you can also define \uicontrol {Local Custom Properties}. + + \image studio-ext-scene-environment.webp "Properties of Extended Scene Environment" + + \note If additional post-processing effects are manually added to + \uicontrol {Scene Environment}, those effects will be applied before the effects + defined in the properties of \uicontrol {Extended Scene Environment}. + */ diff --git a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-view.qdoc b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-view.qdoc index 5f2f53ca96..db9961e31d 100644 --- a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-view.qdoc +++ b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-view.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -8,42 +8,61 @@ \title 3D Views - To create a Qt Quick 3D UI project, we recommend using a \uicontrol - {Qt Quick 3D Application} wizard template that adds the + To create a Qt Quick 3D UI project, use the \uicontrol {3D} preset that adds the \l {3D Components}{Qt Quick 3D} components to \uicontrol Components - and contains a 3D view. A 3D view component includes a - \l {Scene Environment}{scene environment} as well as a scene - \l {Lights}{light}, \l {Cameras}{camera}, and - \l {3D Models}{model}. A default \l {Materials and Shaders}{material} - is attached to the model. You can attach \l {Textures}{textures} - to materials. For more information about creating projects, see \l{Creating Projects}. - - To add a 3D view to some other kind of a project, you first need to add the + and contains a 3D view component. The \uicontrol {View3D} component + includes a \l {Scene Environments}{scene environment} as well as a scene \l {Lights}{light}, + \l {Cameras}{camera}, and \l {3D Models}{model}. A default \l {Materials and Shaders}{material} + is attached to the model. You can attach \l {Textures}{textures} to materials. + + To create a project with many complex effects, use the \uicontrol {Extended 3D} preset + that creates a project with an \uicontrol {Extended View3D} component. + The extended 3D view includes an \uicontrol{Extended Scene Environment} + component that enables using various effects by defining them as properties. + + \note The extended 3D view is available in projects created with Qt 6.5 + or higher set as the target version. + + For more information about creating projects, see \l{Creating Projects}. + + To manually add a 3D view to your project, you first need to add the \uicontrol {Qt Quick 3D} module to \uicontrol {Components}, as described in \l {Adding and Removing Modules}. - \image studio-qtquick-3d-components.png "Qt Quick 3D components in Components" + \note \uicontrol {The Qt Quick 3D} module is not available in projects created + with Qt 5 set as the target version. - You can now drag-and-drop a \uicontrol View3D component to the \l Navigator - or \l {2D} view. + \image studio-qtquick-3d-components.webp "QtQuick3D components" - \image studio-navigator-view3d.png "A View 3D component in the Navigator" + You can now drag a \uicontrol View3D or an \uicontrol {Extended View3D} component from + \l Components > \uicontrol QtQuick3D > \uicontrol Items to \l Navigator or to the + \l {2D} view. - By default, a directional light and a perspective camera are used in a 3D - scene created by using the wizard template mentioned above. To use other - light and camera types, select the component in the \uicontrol{3D} or - \uicontrol Navigator view and change the type of the component in the \uicontrol - Type field in \l Properties. For example, to use a point light, enter - \e {PointLight}. + To switch to the \uicontrol 3D view while maintaining the camera orientation of the + \uicontrol View3D, right-click a \uicontrol View3D or an \uicontrol {Extended View3D} + component in the \uicontrol Navigator or \uicontrol 2D view and select + \uicontrol {Edit in 3D View}. Alternatively, you can double-click a \uicontrol View3D + or an \uicontrol {Extended View3D} component in the \uicontrol 2D view to open the + \uicontrol 3D view. Double-clicking a 3D model in the \uicontrol 2D view opens the + \uicontrol 3D view with the 3D model selected. - \image studio-3d-properties-type.png "Type field in Properties view" + \image studio-navigator-view3d.png "A View 3D component in Navigator" - Similarly to other components, you can select a 3D view in \uicontrol - Navigator or the \uicontrol{3D} view and modify its property values in the - \uicontrol Properties view. Use the properties in the \uicontrol View3D - tab to set properties specific to a 3D view component. + By default, a directional light and a perspective camera are used in 3D + scenes created by using the \uicontrol 3D and \uicontrol {Extended 3D} + presets. To use other light and camera types, select the component in + the \uicontrol {3D} or \uicontrol Navigator view and change the type of + the component in the \uicontrol Type field in \l Properties. For example, + to use a point light, enter \c {PointLight}. - \image studio-qtquick-3d-view.png "View 3D component properties" + \image studio-3d-properties-type.webp "Type field in the Properties view" + + Select a 3D view in \uicontrol Navigator or in \uicontrol{3D} to modify + its property values in the \uicontrol Properties view. Use the properties + in the \uicontrol View3D tab to set properties specific to a 3D view + component. + + \image studio-qtquick-3d-view.webp "View 3D component properties" The \uicontrol Camera property defines which camera is used to render the scene to the \uicontrol {2D} view. If this property is not defined, the @@ -63,4 +82,7 @@ \note The \uicontrol {Import Scene} property can only be set once. Subsequent changes will have no effect. + + The \uicontrol {Render Format} property defines the format of the backing + texture. */ diff --git a/doc/qtdesignstudio/src/qtquickdesigner-components/qtdesignstudio-logic-helpers.qdoc b/doc/qtdesignstudio/src/qtquickdesigner-components/qtdesignstudio-logic-helpers.qdoc index c928fff58c..72f57f0c17 100644 --- a/doc/qtdesignstudio/src/qtquickdesigner-components/qtdesignstudio-logic-helpers.qdoc +++ b/doc/qtdesignstudio/src/qtquickdesigner-components/qtdesignstudio-logic-helpers.qdoc @@ -3,7 +3,7 @@ /*! \page quick-logic-helpers.html - \previouspage quick-2d-effects.html + \previouspage quick-design-effects.html \nextpage quick-animations.html \title Logic Helpers diff --git a/doc/qtdesignstudio/src/qtquickdesigner-components/qtdesignstudio-property-visual-effects.qdoc b/doc/qtdesignstudio/src/qtquickdesigner-components/qtdesignstudio-property-visual-effects.qdoc new file mode 100644 index 0000000000..3530d4da64 --- /dev/null +++ b/doc/qtdesignstudio/src/qtquickdesigner-components/qtdesignstudio-property-visual-effects.qdoc @@ -0,0 +1,136 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page quick-design-effects.html + \previouspage quick-2d-effects.html + \nextpage quick-logic-helpers.html + + \title Design Effects + + \QDS provides a set of effects in the \uicontrol Properties view that you can apply + to the components. + + \image studio-effects.webp "Design Effects in the Properties view" + + \note This feature is a \e Beta release. + + The available set of Design Effects applies to the \QDS components: + \list + \li \l {Applying Layer Blur on a Component} {Layer Blur} + \li \l {Applying Background Blur on a Component} {Background Blur} + \li \l {Applying Drop Shadow on a Component} {Drop Shadow} + \li \l {Applying Inner Shadow on a Component} {Inner Shadow} + \endlist + + \section1 Applying Layer Blur on a Component + + Use \uicontrol {Layer Blur} to make a component blurry. To apply \uicontrol {Layer Blur} + to a component, follow these steps: + \list 1 + \li Select the component in the \uicontrol 2D or \uicontrol Navigator view. + \li Go to the \uicontrol {Properties} view > \uicontrol Effects + and select \uicontrol {Add Effects}. + \li Go to \uicontrol {Layer Blur} and enter the level of blurring you need + in \uicontrol {Blur}. + + \image studio-effects-layer-blur.webp "Layer Blur Effects in Properties view" + \endlist + \note The level of \uicontrol {Layer Blur} is adjustable between zero and one hundred. \br + To remove the applied \uicontrol {Layer Blur}, select the component, + then go to \uicontrol {Properties} view > \uicontrol {Layer Blur} + > \uicontrol {Remove Effects}. This also removes all the other effects + applied to the component. + + \section1 Applying Background Blur on a Component + + Apply \uicontrol {Background Blur} to a component when you want to blur a selected + component behind it. There are a few essential conditions you should consider. + \list + \li Make the component partially transparent. With solid color, + the background component is not visible. + \li Use a solid color on the background component. On + a transparent background component the \uicontrol {Background Blur} does not + function properly. + \note Currently, the \uicontrol {Background Blur} functions on top of only one selected + background component. All the other components ignore the blurring. + \endlist + + After fulfilling the above conditions, follow the next steps to apply the + \uicontrol {Background Blur} on a component. + + \list 1 + \li Select the component in the \uicontrol 2D or \uicontrol Navigator view. + \li Go to the \uicontrol {Properties} view > \uicontrol Effects + and select \uicontrol {Add Effects}. + \li Go to \uicontrol {Background Blur} and enter the level of blurring you need + in \uicontrol {Blur}. + \li In the \uicontrol Background dropdown menu, select another + components as the background component. + \li Drag the component on top of the background component. The area from the + component covering the component selected as \uicontrol Background gets + blurred. However, any other component behind the component doesn't blur. + \endlist + + \image studio-effects-background-blur.webp "Applying Background Blur" + + \section1 Applying Drop Shadow on a Component + + Shadows can either fall outside or inside the component. + The shadow that falls outside is a drop shadow. To apply + a \uicontrol {Drop Shadow} to a component, follow the instructions below. + + \list 1 + \li Select the component in the \uicontrol 2D or \uicontrol Navigator view. + \li Go to the \uicontrol {Properties} view > \uicontrol Effects + and select \uicontrol {Add Effects}. + \endlist + + This adds the default drop shadow to the component. To adjust this shadow, + follow these instructions. + + \list 1 + \li Select the component and go to the \uicontrol Properties view > \uicontrol Effects. + Then, select \inlineimage icons/particle-play.png next to the shadow type + selector dropdown menu. + \li Adjust \uicontrol Blur, \uicontrol Offset, \uicontrol Spread, and \uicontrol Color + to shape the shadow. + \endlist + + \image studio-effects-drop-shadow.webp "Drop Shadow Effects in Properties view" + + \note To stack multiple shadows, select \uicontrol {Add Shadow Effect} from the + \uicontrol Properties view. After adding multiple shadows, you can adjust them + separately from their expandable menu. + + The \uicontrol {Show behind} feature in \uicontrol {Drop Shadow} only works when + the component is transparent. To use it: + + \list 1 + \li Select the component with a drop shadow. + \li Go to the \uicontrol Properties view > \uicontrol Effects. + Then, select \inlineimage icons/particle-play.png next to the shadow type + selector dropdown menu. + \li Select \uicontrol {Show Behind}. + + \image studio-effects-show-shadow-behind.webp "Show drop shadow behind the component" + \endlist + + \section1 Applying Inner Shadow on a Component + + \uicontrol {Inner shadow} works inside a component. To apply \uicontrol {Inner Shadow}, + do the following: + + \list 1 + \li Select the component in the \uicontrol 2D or \uicontrol Navigator view. + \li Go to the \uicontrol {Properties} view > \uicontrol Effects + and select \uicontrol {Add Effects}. + \li From the dropdown menu, select \uicontrol {Inner Shadow}. + \li Adjust \uicontrol Blur, \uicontrol Offset, \uicontrol Spread, and \uicontrol Color + to shape the shadow. + + \image studio-effects-inner-shadow.webp "Inner shadow of the component" + \endlist + + +*/ diff --git a/doc/qtdesignstudio/src/qtquickdesigner-components/qtdesignstudio-visual-effects.qdoc b/doc/qtdesignstudio/src/qtquickdesigner-components/qtdesignstudio-visual-effects.qdoc index 9cff12750c..52ef110a62 100644 --- a/doc/qtdesignstudio/src/qtquickdesigner-components/qtdesignstudio-visual-effects.qdoc +++ b/doc/qtdesignstudio/src/qtquickdesigner-components/qtdesignstudio-visual-effects.qdoc @@ -4,7 +4,7 @@ /*! \page quick-2d-effects.html \previouspage quick-data-models.html - \nextpage quick-logic-helpers.html + \nextpage quick-property-effects.html \title 2D Effects diff --git a/doc/qtdesignstudio/src/reference/qtdesignstudio-keyboard-shortcuts.qdoc b/doc/qtdesignstudio/src/reference/qtdesignstudio-keyboard-shortcuts.qdoc index ac6354ca90..21b195b522 100644 --- a/doc/qtdesignstudio/src/reference/qtdesignstudio-keyboard-shortcuts.qdoc +++ b/doc/qtdesignstudio/src/reference/qtdesignstudio-keyboard-shortcuts.qdoc @@ -112,6 +112,9 @@ \li Previous open document in history \li \key{Ctrl+Tab} \row + \li Toggle \uicontrol {Menu Bar} visibility + \li \key{Ctrl+Alt+M} + \row \li Switch to \uicontrol Welcome mode \li \key{Ctrl+1} \row @@ -201,7 +204,10 @@ \li Action \li Keyboard shortcut \row - \li Open the QML file that defines the selected component + \li Open the project with \uicontrol {Live Preview}. + \li \key{Alt+P} (\key{Opt+P} on \macos) + \row + \li Open the QML file that defines the selected component. \li \key{F2} \row \li Jump to the \uicontrol {Code} view. diff --git a/doc/qtdesignstudio/src/views/qtquick-assets.qdoc b/doc/qtdesignstudio/src/views/qtquick-assets.qdoc index b95bf1e889..fad871debd 100644 --- a/doc/qtdesignstudio/src/views/qtquick-assets.qdoc +++ b/doc/qtdesignstudio/src/views/qtquick-assets.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2022 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -6,43 +6,31 @@ \previouspage quick-components-view.html \nextpage qtquick-navigator.html + \ingroup studio-views + \title Assets + \brief Select assets such as images and fonts to use in your application. + The \uicontrol Assets view lists available assets. \uicontrol {Assets} displays the images and other files - that you add to the project folder by dragging-and-dropping external asset + that you add to the project folder by dragging external asset files to \QDS or by selecting \inlineimage icons/plus.png . For more information about importing assets to \QDS, see \l {Importing 2D Assets} and \l {Importing 3D Assets}. - To add assets to your UI, drag-and-drop them from + To add assets to your UI, drag them from \uicontrol Assets to the \l Navigator, \l {2D}, or \l {3D} view. To add multiple assets to your UI simultaneously, multiselect them first by holding \key Ctrl and clicking the asset files you wish to select. - \image qtquick-assets-tab.png "Assets view" + \image qtquick-assets-tab.webp "Assets view" - When you drag-and-drop assets from \uicontrol Assets to the \l Navigator + When you drag assets from \uicontrol Assets to the \l Navigator or \l {2D} view, component instances with a suitable type are automatically created for you. For example, instances of the \l{Images}{Image} component will be created for graphics files. - \section1 Context Menu Commands - - \image qtquick-library-context-menu.png "Context menu commands in Assets" - - To use the context menu commands in \uicontrol Assets, right-click the - name of a folder and select one of the following commands: - - \list - \li \uicontrol {Expand All}: expands all folders. - \li \uicontrol {Collapse All}: collapses all folders. - \li \uicontrol {Rename Folder}: prompts you to enter a new name - for the folder. - \li \uicontrol {New Folder}: creates a new folder. - \li \uicontrol {Delete Folder}: deletes the folder. - \endlist - */ diff --git a/doc/qtdesignstudio/src/views/qtquick-components-view.qdoc b/doc/qtdesignstudio/src/views/qtquick-components-view.qdoc index 1e2786bfbc..5933e4be70 100644 --- a/doc/qtdesignstudio/src/views/qtquick-components-view.qdoc +++ b/doc/qtdesignstudio/src/views/qtquick-components-view.qdoc @@ -1,13 +1,18 @@ -// Copyright (C) 2021 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 quick-components-view.html \previouspage studio-material-editor.html \nextpage quick-assets.html + \sa {Using Components} + + \ingroup studio-views \title Components + \brief Select preset components and your own components to use in your application. + The \uicontrol Component view lists the available components. \image qtquick-components-tab.png "Components view" @@ -52,7 +57,7 @@ \li \l{Custom Shaders} \li \l{Lights} \li \l{Cameras} - \li \l{Scene Environment} + \li \l{Scene Environments} \li \l{Morph Target} \li \l{Repeater3D} \li \l{Particles} @@ -86,27 +91,4 @@ final application package, it is recommended that you select \uicontrol {Remove Module} to remove the ones you don't use in the project. - \section1 Context Menu Commands - - \image qtquick-components-context-menu.png "Context menu commands in Components" - \image qtquick-components-context-menu-hide.png "Context menu command Hide Category" - - To use the context menu commands in \uicontrol Components, right-click the - name of a module or category and select one of the following commands: - - \list - \li \uicontrol {Remove Module}: removes the module and all of its - components from \uicontrol Components. - \li \uicontrol {Expand All}: expands all the modules. - \li \uicontrol {Collapse All}: collapses all the modules. - \li \uicontrol {Hide Category}: hides the category from the module. - \li \uicontrol {Show Module Hidden Categories}: shows the hidden - categories of the module. - \li \uicontrol {Show All Hidden Categories}: shows the hidden - categories in all of the modules. - \endlist - - \note The context menu commands for the \uicontrol Components categories do - not function if you have entered something into the \uicontrol Search field. - Clear the \uicontrol Search field to resume using the context menu commands. */ diff --git a/doc/qtdesignstudio/src/views/qtquick-connection-view.qdoc b/doc/qtdesignstudio/src/views/qtquick-connection-view.qdoc index 5cc2c4a667..066ff1c9dc 100644 --- a/doc/qtdesignstudio/src/views/qtquick-connection-view.qdoc +++ b/doc/qtdesignstudio/src/views/qtquick-connection-view.qdoc @@ -1,13 +1,19 @@ -// Copyright (C) 2021 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 qtquick-connection-view.html \previouspage qtquick-properties-view.html \nextpage qtquick-states-view.html + \sa {Working with Connections} + + \ingroup studio-views \title Connections + \brief Add functionality to the UI by creating connections between components, + signals, and component properties. + The \uicontrol {Connections} view is a collection of views that enable you to create connections between components and the application, to bind component properties together, and to add custom properties for components. @@ -36,29 +42,4 @@ {preset properties} that you can specify values for. You can add custom properties that would not otherwise exist for a particular \l{Component Types}{component type}. - - \section1 Summary of the Connections View Tabs - - \table - \header - \li Tab - \li Purpose - \li Read More - \row - \li \uicontrol Connections - \li Create connections between components and the application logic - by accessing signals outside of the components that emit them. - \li \l{Connecting Components to Signals} - \row - \li \uicontrol Bindings - \li Dynamically change the behavior of a component by creating a - binding between the properties of two components. - \li \l{Adding Bindings Between Properties} - \row - \li \uicontrol Properties - \li Add custom properties that would not otherwise exist for a - particular preset component or your own custom component. - \li \l{Specifying Custom Properties} - - \endtable */ diff --git a/doc/qtdesignstudio/src/views/qtquick-curve-editor.qdoc b/doc/qtdesignstudio/src/views/qtquick-curve-editor.qdoc index 88ba762f53..52e1ba5963 100644 --- a/doc/qtdesignstudio/src/views/qtquick-curve-editor.qdoc +++ b/doc/qtdesignstudio/src/views/qtquick-curve-editor.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -6,12 +6,16 @@ \previouspage qtquick-timeline-view.html \nextpage qtquick-text-editor.html + \ingroup studio-views + \title Curves + \brief View and modify the animation curve. + The \uicontrol {Curves} view shows the interpolated values of an animated property over the animation range. - \image studio-curve-editor.png "Curves" + \image studio-curve-editor.webp "Curves" When you edit an animation curve, you implicitly edit the \l{Editing Easing Curves}{easing curves} that the underlying system uses @@ -20,11 +24,22 @@ simultaneously. You can use the toolbar buttons to add \uicontrol Linear, \uicontrol Step, - or \uicontrol Spline interpolation between two keyframes. + or \uicontrol Spline interpolation between keyframes. + + To apply interpolation between keyframes: + \list 1 + \li Select the keyframes. To select multiple keyframes, press and hold + \key Ctrl, and then select them. + \li Select \inlineimage icons/easing-curve-linear-icon.png (\uicontrol Linear), + \inlineimage icons/easing-curve-step-icon.png (\uicontrol Step) or + \inlineimage icons/easing-curve-spline.png (\uicontrol Spline) depending on + which interpolation method you want to use. + \endlist When you set interpolation to \uicontrol Spline, handles appear in \uicontrol {Curves} that you can use to modify the curve. Select - \uicontrol Unify to lock the handle on the left of a keyframe to the one + \inlineimage icons/easing-curve-unify.png (\uicontrol Unify) to lock the handle on the + left of a keyframe to the one on the right of it so that moving the left handle also moves the right handle. @@ -32,53 +47,14 @@ in \l Navigator, you can select \inlineimage icons/lockon.png to unlock it. You can also lock individual easing curves for editing. - To lock an animation curve, hover the mouse over the keyframe in the list, + To lock an animation curve, hover the mouse over the property in the list, and then select \inlineimage icons/lockoff.png . - To pin an animation curve, hover the mouse over the keyframe in the list, + To pin an animation curve, hover the mouse over the property in the list, and then select \inlineimage icons/pin.png . - \section1 Curves Toolbar - - The \uicontrol {Curves} toolbar contains the following buttons and - fields. - - \table - \header - \li Button/Field - \li Action - \row - \li \inlineimage icons/easing-curve-linear-icon.png - \li \uicontrol Linear specifies that the interpolation between - keyframes is linear. - \row - \li \inlineimage icons/easing-curve-step-icon.png - \li \uicontrol Step uses steps for interpolation between keyframes. - \row - \li \inlineimage icons/easing-curve-spline-icon.png - \li \uicontrol Spline uses bezier spline curves for interpolation - between keyframes and displays handles for managing them. - \row - \li \uicontrol {Set Default} - \li Currently not used. - \row - \li \uicontrol Unify - \li For \uicontrol Spline curves, locks the handle on the left of a - keyframe to the one on the right. - \row - \li Start Frame - \li Specifies the first frame of the curve. - \row - \li End Frame - \li Specifies the last frame of the curve. - \row - \li Current Frame - \li Displays the frame that the playhead is currently on. Enter a - number in the field to move the playhead to the respective frame. - \endtable - \section1 Editing Animation Curves To edit animation curves: @@ -90,14 +66,14 @@ \uicontrol {Curves} to open the animation curve editor. \li Right-click in \uicontrol {Curves}, and select \uicontrol {Insert Keyframe} to add a keyframe. - \li Select keyframes to display the easing curves attached to them. - To select multiple keyframes, press and hold \key Ctrl. + \li Select properties in the list to display the easing curves attached to them. + To select multiple properties, press and hold \key Ctrl, and then select them. \endlist Your changes are automatically saved when you close the view. \section1 Deleting Keyframes in Curves - To delete the selected keyframe, select \uicontrol {Delete All Keyframes} + To delete the selected keyframe, select \uicontrol {Delete Selected Keyframes} in the context menu. */ diff --git a/doc/qtdesignstudio/src/views/qtquick-designer.qdoc b/doc/qtdesignstudio/src/views/qtquick-designer.qdoc index 3ca0149437..d4fb09efc6 100644 --- a/doc/qtdesignstudio/src/views/qtquick-designer.qdoc +++ b/doc/qtdesignstudio/src/views/qtquick-designer.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // ********************************************************************** @@ -27,218 +27,8 @@ \section1 Summary of Design Views - In addition to the summary of design views, the table below includes an MCU - column that indicates the views which are fully supported on MCU projects. - For more information, see \l {\QDS Features on MCU Projects}. + The following table provides a summary of the design views. For information on + MCU support, see \l {\QDS Features on MCU Projects}. - \table - \header - \li View - \li Purpose - \li MCU - \li Read More - \row - \li \l {2D} - \li Provides a working area for designing 2D UIs. - When you are editing 3D scenes, the \uicontrol {2D} view is - used as a canvas for the 3D scene projected by the camera. - \li \image ok.png - \li \l {2D} - \row - \li \l {3D} - \li Provides an editor for files you created using 3D graphics - applications and stored in one of the supported formats. - \li - \li \l {3D} - \row - \li \l {Material Editor and Browser} - \li In the \uicontrol {Material Editor} and - \uicontrol {Material Browser} views, you create and manage materials and - textures. - \li - \li \l {Material Editor and Browser} - \row - \li \l Components - \li Contains preset components and your own components, that you can use - to design you application. - \li \image ok.png - \li \l{Using Components} - \row - \li \l Assets - \li Contains assets such as images and fonts that you can use in your - application. - \li \image ok.png - \li \l Assets - \row - \li \l Navigator - \li Displays the composition of the current component file as - a tree structure. A component file can contain references - to other components and assets. - \li \image ok.png - \li \l Navigator - \row - \li \l Properties - \li Enables you to modify the properties of the selected component. - \li \image ok.png - \li \l {Specifying Component Properties} - \row - \li \l{Connections} - \li Enables you to add functionality to the UI by creating - connections between components, signals, and component properties. - \li \image ok.png - \li \l{Working with Connections} - \row - \li \l States - \li Displays the different states that can be applied to a component. - Typically, states describe UI configurations, such as the - visibility and behavior of components and the available user - actions. - \li \image ok.png - \li \l{Working with States} - \row - \li \l{Transitions} - \li Enables you to make movement between states smooth by animating - the changes between states. - \li \image ok.png - \li \l{Animating Transitions Between States} - \row - \li \l Translations - \li Provides functionality to add multi-language support to your - project. - \li - \li \l{Translations} - \row - \li \l Timeline - \li Provides a timeline and keyframe based editor for animating - the properties of components. - \li \image ok.png - \li \l{Creating Timeline Animations} - \row - \li \l{Curves} - \li Enables you to view and modify the whole animation curve by - inserting keyframes to the curve and dragging them and the point - handlers to modify the curve. - \li - \li \l {Editing Animation Curves} - \row - \li \l{Code} - \li Provides a code editor for viewing and modifying the code - generated by the visual editors. - \li \image ok.png - \li \l {Code} - \row - \li \l Projects - \li Shows a list of open projects and the files they contain. - \li \image ok.png - \li \l Projects - \row - \li \l{File System} - \li Shows all files in the currently selected directory. - \li \image ok.png - \li \l{File System} - \row - \li \l{Open Documents} - \li Shows currently open files. - \li \image ok.png - \li \l{Open Documents} - \row - \li \l{Content Library} - \li The \uicontrol {Content Library} view contains material, texture, - and environment bundles with assets that you can use in your project. - \li - \li \l{Content Library} - \row - \li \l{Texture Editor} - \li In the \uicontrol {Texture Editor} view, you create and manage - textures. - \li - \li \l{Texture Editor} - \row - \li \l{Effect Composer} - \li Use \uicontrol {Effect Composer} to compose custom effects. - \li - \li \l{Effect Composer} - \endtable - - \section1 Summary of Main Toolbar Actions - - The top level toolbar in the \uicontrol Design mode contains shortcuts to - widely used actions. - - \table - \header - \li Button/Field - \li Action - \li Keyboard Shortcut - \li Read More - - \row - \li \inlineimage icons/home.png - \li \uicontrol {Home}: opens the welcome page. - \li - \li - \row - \li \inlineimage icons/start_playback.png - \li \uicontrol {Play}: runs the application. - \li - \li - \row - \li \uicontrol {Live Preview} - \li Shows a preview of the current file or the entire UI. The changes you - make to the UI are instantly visible to you in the preview. - \li \key Alt+P (\key Opt+P on \macos) - \li \l{Validating with Target Hardware} - - \row - \li Currently open file - \li Displays the location and filename of the currently open file. You - can select another file in the list of open files to view it in - the \uicontrol {2D} and \uicontrol Navigator views. - \li - \li \l{Open Documents} - \row - \li \inlineimage icons/prev.png - \li \uicontrol {Go Back}: moves a step backwards in your location history. - That is, returns the focus to the last location in the last file it - was on. - \li \key Alt+< (\key Opt+Cmd+< on \macos) - \li - \row - \li \inlineimage icons/next.png - \li \uicontrol {Go Forward}: moves a step forward in your location history. - \li \key Alt+> (\key Opt+Cmd+> on \macos) - \li - \row - \li \inlineimage icons/close.png - \li \uicontrol {Close Document}: closes the current file. - \li \key Ctrl+W (\key Cmd+W on \macos) - \li - \row - \li \inlineimage icons/create_component.png - \li Creates a custom component from the selected item. - \li - \li \l{Creating Custom Components} - \row - \li \inlineimage icons/edit_component.png - \li Edits the selected custom component. - \li - \li \l{Creating Custom Components} - \row - \li Workspace - \li Displays the currently selected workspace. To switch to another - workspace, select it in the list. - \li - \li \l{Managing Workspaces} - \row - \li \inlineimage icons/lockoff.png - / \inlineimage icons/lockon.png - \li Toggles the views to locked or movable in \QDS. - \li - \li \l{Managing Workspaces} - \row - \li \uicontrol Share - \li Shares the application online using Qt Design Viewer. - \li - \li \l{Sharing Applications Online} - \endtable + \annotatedlist studio-views */ diff --git a/doc/qtdesignstudio/src/views/qtquick-easing-curve-editor.qdoc b/doc/qtdesignstudio/src/views/qtquick-easing-curve-editor.qdoc index ef518989ce..66b54c0d55 100644 --- a/doc/qtdesignstudio/src/views/qtquick-easing-curve-editor.qdoc +++ b/doc/qtdesignstudio/src/views/qtquick-easing-curve-editor.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -79,7 +79,7 @@ \endlist When you attach easing curves to keyframes, the shape of the - \l{keyframe_marker}{keyframe marker} on a keyframe track in + keyframe marker on a keyframe track in \l Timeline changes from \inlineimage icons/keyframe_linear_active.png to a marker that describes the type of the selected easing curve. diff --git a/doc/qtdesignstudio/src/views/qtquick-effect-maker-view.qdoc b/doc/qtdesignstudio/src/views/qtquick-effect-maker-view.qdoc index 3d7e046d85..f0de1a3522 100644 --- a/doc/qtdesignstudio/src/views/qtquick-effect-maker-view.qdoc +++ b/doc/qtdesignstudio/src/views/qtquick-effect-maker-view.qdoc @@ -4,10 +4,14 @@ /*! \page qtquick-effect-composer-view.html \previouspage studio-qt-insight.html - \nextpage creator-project-managing-workspaces.html + \nextpage studio-model-editor.html + + \ingroup studio-views \title Effect Composer + \brief Compose custom effects. + Use \uicontrol {Effect Composer} to create post-processing effects that can be applied to 2D or 3D components. The effects created with \uicontrol {Effect Composer} are shader effects, which can be used in any \QDS projects. @@ -86,4 +90,4 @@ \uicontrol Navigator, and in \uicontrol Properties > \uicontrol {Exposed Custom Properties}, select or clear the \uicontrol timeRunning checkbox. - +*/ diff --git a/doc/qtdesignstudio/src/views/qtquick-form-editor.qdoc b/doc/qtdesignstudio/src/views/qtquick-form-editor.qdoc index 3ac3027392..7ecd0a77db 100644 --- a/doc/qtdesignstudio/src/views/qtquick-form-editor.qdoc +++ b/doc/qtdesignstudio/src/views/qtquick-form-editor.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -6,13 +6,17 @@ \previouspage creator-using-qt-quick-designer.html \nextpage studio-3d-editor.html + \ingroup studio-views + \title 2D + \brief Design 2D UIs. + You design applications in the \uicontrol {2D} view by opening component files and placing instances of \l{Component Types}{2D components} and \l{Assets}{assets} into them. - \image qmldesigner-form-editor.png "The 2D view" + \image qmldesigner-form-editor.webp "The 2D view" When you select component instances in the \uicontrol {2D} view, markers appear around their edges and in their corners. Depending on the shape of @@ -25,60 +29,12 @@ \li \l{Rotating 2D Components}{Rotate} \endlist - \section1 Summary of 2D View Buttons - - The \uicontrol {2D} view toolbar contains the following buttons and - fields. - - \table - \header - \li Button/Field - \li Tooltip - \li Read More - \row - \li \uicontrol {Override Width} - \li Shows a preview of the component using the specified width. - \li \l{Previewing Component Size} - \row - \li \uicontrol {Override Height} - \li Shows a preview of the component using the specified height. - \li \l{Previewing Component Size} - \row - \li \inlineimage icons/canvas-color.png - \li Sets the color of the \uicontrol {2D} view working area. - \li \l{Setting Canvas Color} - \row - \li \inlineimage icons/zoomIn.png - \li Zooms in. - \li \l{Zooming} - \row - \li \inlineimage icons/zoomOut.png - \li Zooms out. - \li \l{Zooming} - \row - \li Zoom level - \li Sets the zoom level that you select from the list. - \li \l{Zooming} - \row - \li \inlineimage icons/zoomAll.png - \li Zooms to fit all content. - \li \l{Zooming} - \row - \li \inlineimage icons/zoomSelection.png - \li Zooms to fit the current selection. - \li \l{Zooming} - \row - \li \inlineimage icons/reset.png - \li Refreshes the contents of the \uicontrol {2D} view. - \li \l{Refreshing 2D View Contents} - \endtable - \section1 Moving Components When the move cursor is displayed, you can move the selected component instance to any position in the \uicontrol {2D} view. - \image qmldesigner-form-editor-move-cursor.png "Move cursor in the 2D view" + \image qmldesigner-form-editor-move-cursor.webp "Move cursor in the 2D view" For more information about alternative ways of positioning component instances in UIs, see \l{Scalable Layouts}. @@ -88,7 +44,7 @@ When the resize cursor is displayed, you can drag the markers to resize component instances. - \image qtquick-designer-scaling-items.png "The 2D view" + \image qtquick-designer-scaling-items.webp "The 2D view" To have the resizing done from the center of the selected component instance rather than from its edges, press \key Alt (or \key Opt on \macos). @@ -110,7 +66,7 @@ clockwise or counter-clockwise to freely rotate the component instance around its origin. - \image qtquick-designer-rotating-items.png "2D rotation tool" + \image qtquick-designer-rotating-items.webp "2D rotation tool" Additionally, press \key Shift or \key Alt (or \key Opt on \macos) to rotate component instances in steps of 5 or 45 degrees, respectively. @@ -152,9 +108,9 @@ \image qtquick-designer-options.png "Qt Quick Designer preferences" The following image shows the snapping lines (1) when - \uicontrol {Parent component padding} is set to 5 pixels. + \uicontrol {Parent component padding} is set to 10 pixels. - \image qmldesigner-snap-margins.png "Snapping lines on canvas" + \image qmldesigner-snap-margins.webp "Snapping lines on canvas" For alternative ways of aligning and distributing component instances by using the \l Properties view, see \l{Aligning and Distributing Components}. @@ -181,7 +137,7 @@ values are not changed permanently in the UI file. You can permanently change the property values in the \uicontrol Properties view (4). - \image qmldesigner-preview-size.png "Component width and height" + \image qmldesigner-preview-size.webp "Component width and height" To set the initial size of the root component, select \uicontrol Edit > \uicontrol Preferences > \uicontrol {Qt Quick} > \uicontrol {Qt Quick Designer} @@ -204,7 +160,7 @@ not affect the background color of your root component or component instances in any way. - \image qmldesigner-canvas-color.png "Transparent canvas color for a transparent component instance" + \image qmldesigner-canvas-color.webp "Transparent canvas color for a transparent component instance" \section1 Refreshing 2D View Contents @@ -219,6 +175,4 @@ To refresh the contents of the \uicontrol {2D} view, press \key R or select the \inlineimage icons/reset.png (\uicontrol {Reset View}) button. - - \include qtquick-component-context-menu.qdocinc context-menu */ diff --git a/doc/qtdesignstudio/src/views/qtquick-navigator.qdoc b/doc/qtdesignstudio/src/views/qtquick-navigator.qdoc index f0cd1fe235..cfba22dc60 100644 --- a/doc/qtdesignstudio/src/views/qtquick-navigator.qdoc +++ b/doc/qtdesignstudio/src/views/qtquick-navigator.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -6,8 +6,12 @@ \previouspage quick-assets.html \nextpage qtquick-properties-view.html + \ingroup studio-views + \title Navigator + \brief View the composition of the current component file as a tree structure. + The \uicontrol Navigator view displays the components in the current component file and their relationships. \l{glossary-component}{Components} (1) are listed in a tree structure, below their parent (2). You can preview @@ -36,57 +40,11 @@ you can change the source of an Image component by selecting \uicontrol {Change Source URL} in the context menu. - \section1 Summary of Navigator Buttons - - The following table lists the \uicontrol Navigator buttons: - - \table - \header - \li Icon - \li Tooltip - \li Read More - \row - \li \inlineimage icons/arrowleft.png - \li Moves the component one level up in the component tree, so that - it becomes the last sibling of its current parent. - \li \l{Arranging Components} - \row - \li \inlineimage icons/arrowright.png - \li Moves the component one level down in the component tree, so that it - becomes the child of its last sibling. - \li \l{Arranging Components} - \row - \li \inlineimage icons/navigator-arrowdown.png - \li Moves the component down within its parent. - \li \l{Arranging Components} - \row - \li \inlineimage icons/navigator-arrowup.png - \li Moves the component up within its parent. - \li \l{Arranging Components} - \row - \li \inlineimage icons/filtericon.png - \li Shows and hides invisible components in \uicontrol Navigator. - \li \l{Showing and Hiding Components} - \row - \li \inlineimage icons/alias.png - \li Adds a property alias that you can use from outside of the - component. - \li \l{Adding Property Aliases} - \row - \li \inlineimage icons/visibilityon.png - \li Shows and hides components in the \uicontrol {2D} view. - \li \l{Showing and Hiding Components} - \row - \li \inlineimage icons/lockon.png - \li Locks components in all views. - \li \l{Locking Components} - \endtable - \section1 Showing and Hiding Components To show and hide components in the \uicontrol {2D} view when focusing on - specific parts of the application, click \inlineimage icons/visibilityon.png - in \uicontrol Navigator. + specific parts of the application, select \inlineimage icons/eye_open.png and + \inlineimage icons/visibility-off.png in \uicontrol Navigator. To change the visibility of a component in the application code, select the \uicontrol Visibility check box in the \uicontrol Properties view or select @@ -99,10 +57,8 @@ component. To hide or show child components, edit the properties of the parent component. - To hide invisible components in \uicontrol Navigator, click - \inlineimage icons/filtericon.png - (\uicontrol {Filter Tree}) and select - \uicontrol {Show Only Visible Components}. + To show and hide invisible components in \uicontrol Navigator, select + \inlineimage {icons/visibilityon.png}. \section1 Locking Components @@ -141,9 +97,8 @@ By default, components that are located at the top of the file are listed at the bottom of the \uicontrol Navigator tree and behind overlapping components in the \uicontrol {2D} view. To list the components in the order - in which they appear in the file, as some other tools do, click - \inlineimage icons/filtericon.png - (\uicontrol {Filter Tree}), and select \uicontrol {Reverse Component Order}. + in which they appear in the file, as some other tools do, select + \inlineimage {icons/reverse_order.png}. To move a component to the top or bottom of the tree within its parent, right-click it in the \uicontrol Navigator or \uicontrol {2D} view @@ -156,20 +111,18 @@ \image qtquick-designer-navigator-arrange.gif "Reversing component order" - You can also drag-and-drop the component to another position in the tree or - use the arrow buttons to move the component in the tree. You can use the - left and right arrow buttons to change the parent of the component. + You can also drag the component to another position in the tree or use the + \inlineimage {icons/navigator-arrowup.png} and \inlineimage {icons/navigator-arrowdown.png} + buttons to move the component in the tree. You can use the \inlineimage {icons/arrowleft.png} + and \inlineimage {icons/arrowright.png} buttons to change the parent of the component. \image qmldesigner-navigator-arrows.png "Navigator buttons" - When you drag-and-drop instances of components to the \uicontrol {2D} view, + When you drag instances of components to the \uicontrol {2D} view, the new component is added as a child of the component beneath it. When you move the components, it is not possible to determine whether you want to adjust their position or attach them to a new parent component. - Therefore, the parent component is not automatically changed. To change the - parent of the component, press down the \key Shift key before you drag-and-drop - the component into a new position. The topmost component under the cursor becomes the - new parent of the component. + Therefore, the parent component is not automatically changed. \section1 Adding Property Aliases @@ -236,5 +189,4 @@ \image qmldesigner-breadcrumbs.png "Component hierarchy" - \include qtquick-component-context-menu.qdocinc context-menu */ diff --git a/doc/qtdesignstudio/src/views/qtquick-properties-view.qdoc b/doc/qtdesignstudio/src/views/qtquick-properties-view.qdoc index acde01a951..2d660c9951 100644 --- a/doc/qtdesignstudio/src/views/qtquick-properties-view.qdoc +++ b/doc/qtdesignstudio/src/views/qtquick-properties-view.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -6,21 +6,25 @@ \previouspage qtquick-navigator.html \nextpage qtquick-connection-view.html + \ingroup studio-views + \title Properties + \brief Modify the properties of the selected component. + The \uicontrol Properties view displays all the properties of the selected \l{glossary-component}{component}. The properties are grouped by type. The top part of the view displays properties that are common to all components, such as component type, ID, name, geometry, and visibility. - \image qtquick-item-properties-common.png "Basic component properties" + \image qtquick-item-properties-common.webp "Basic component properties" The bottom part of the view displays properties that have been defined for the component type. For example, the following image displays the predefined properties you can set for \l{basic-rectangle}{Rectangle} and \l Text components. - \image qmldesigner-element-properties.png "Rectangle and Text properties" + \image qmldesigner-element-properties.webp "Rectangle and Text properties" \section1 Custom Properties @@ -42,46 +46,6 @@ \image custom-properties.png - \section1 Summary of Properties View Buttons - - The following table lists the \uicontrol Properties view buttons: - - \table - \header - \li Icon - \li Tooltip - \li Read More - \row - \li \inlineimage icons/alias.png - \li Adds a property alias that you can use from outside of the - component for the root component. You can use a menu item - in the actions menu to add property aliases for property - values of child components. - \li \l{Adding Property Aliases} - \row - \li \inlineimage icons/action-icon.png - \li Opens a menu with actions for: - \list - \li Resetting property values to their default values - \li Setting property bindings - \li Creating property aliases - \li Inserting keyframes for timeline animations - \endlist - \li - \list - \li \l{Viewing Changes in Properties} - \li \l{Adding Bindings Between Properties} - \li \l{Adding Property Aliases} - \li \l{Setting Keyframe Values} - \endlist - \row - \li \inlineimage icons/action-icon-binding.png - \li Indicates that the value of the property is bound to the value - of another property. Opens the same menu as the action icon. - \li \l{Adding Bindings Between Properties} - - \endtable - \section1 Viewing Changes in Properties The default values of properties are displayed in white color, while the diff --git a/doc/qtdesignstudio/src/views/qtquick-properties.qdoc b/doc/qtdesignstudio/src/views/qtquick-properties.qdoc index fc8ba92e93..87dfd7a341 100644 --- a/doc/qtdesignstudio/src/views/qtquick-properties.qdoc +++ b/doc/qtdesignstudio/src/views/qtquick-properties.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -17,7 +17,7 @@ All components share a set of properties that you can specify in the \uicontrol Properties view. - \image qtquick-item-properties-common.png "Basic component properties" + \image qtquick-item-properties-common.webp "Basic component properties" \section2 Type diff --git a/doc/qtdesignstudio/src/views/qtquick-states-view.qdoc b/doc/qtdesignstudio/src/views/qtquick-states-view.qdoc index 407e2f5769..5270df5b06 100644 --- a/doc/qtdesignstudio/src/views/qtquick-states-view.qdoc +++ b/doc/qtdesignstudio/src/views/qtquick-states-view.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -7,12 +7,16 @@ \nextpage studio-translations.html \sa {Working with States} + \ingroup studio-views + \title States + \brief Apply states to a component. + The \uicontrol States view displays the different \l{Working with States}{states} of a UI. - \image qmldesigner-transitions.png "States view" + \image qmldesigner-transitions.webp "States view" To open the \uicontrol States view, select \uicontrol View > \uicontrol Views > \uicontrol States. diff --git a/doc/qtdesignstudio/src/views/qtquick-states.qdoc b/doc/qtdesignstudio/src/views/qtquick-states.qdoc index 9f91c52f46..ab31c93f46 100644 --- a/doc/qtdesignstudio/src/views/qtquick-states.qdoc +++ b/doc/qtdesignstudio/src/views/qtquick-states.qdoc @@ -4,7 +4,7 @@ /*! \page quick-states.html \previouspage quick-json-data-properties.html - \nextpage creator-live-preview.html + \nextpage studio-live-preview.html \title Working with States diff --git a/doc/qtdesignstudio/src/views/qtquick-text-editor.qdoc b/doc/qtdesignstudio/src/views/qtquick-text-editor.qdoc index f202df3c37..6941a1c2ec 100644 --- a/doc/qtdesignstudio/src/views/qtquick-text-editor.qdoc +++ b/doc/qtdesignstudio/src/views/qtquick-text-editor.qdoc @@ -6,8 +6,12 @@ \previouspage qtquick-curve-editor.html \nextpage creator-projects-view.html + \ingroup studio-views + \title Code + \brief View and modify the code generated by the visual editors. + To view and modify the code in a \l{UI Files}{UI file} (.ui.qml) or component file (.qml), go to \uicontrol View and select \uicontrol Views > \uicontrol Code. \QDS generates the code when you create components in the diff --git a/doc/qtdesignstudio/src/views/qtquick-timeline-view.qdoc b/doc/qtdesignstudio/src/views/qtquick-timeline-view.qdoc index 8194726184..2e34d70dc4 100644 --- a/doc/qtdesignstudio/src/views/qtquick-timeline-view.qdoc +++ b/doc/qtdesignstudio/src/views/qtquick-timeline-view.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -6,14 +6,18 @@ \previouspage qtquick-transition-editor.html \nextpage qtquick-curve-editor.html + \ingroup studio-views + \title Timeline + \brief Animate the properties of components. + You can use the timeline and keyframe based editor in the \uicontrol Timeline view to animate the properties of \l{glossary_component}{components}. The view is empty until you create a timeline. - \image studio-timeline-empty.png "Empty Timeline view" + \image studio-timeline-empty.webp "Empty Timeline view" Select the \inlineimage icons/plus.png (\uicontrol {Add Timeline}) button to @@ -23,7 +27,7 @@ \image studio-timeline-settings.png "Timeline Settings dialog" When you select \uicontrol Close, the \uicontrol Timeline view appears. - It now displays a \l{Timeline Toolbar}{toolbar} and a ruler but no + It now displays a toolbar and a ruler but no keyframe tracks. \image studio-timeline-no-tracks.webp "Timeline view without keyframe tracks" @@ -86,171 +90,4 @@ \image studio-timeline-keyframe-track-colors.webp "Keyframe track colors in Timeline" - \section1 Timeline Toolbar - - The \uicontrol Timeline toolbar contains the following buttons and fields. - - \table - \header - \li Button/Field - \li Action - \li Read More - \row - \li \inlineimage icons/settings.png - \li Opens the \uicontrol {Timeline Settings} dialog for editing - timeline settings. - \li \l{Creating a Timeline} - \row - \li Timeline ID - \li Displays the ID of the current timeline. - \li \l{Creating a Timeline} - \row - \li \inlineimage icons/to_first_frame.png - \li \uicontrol {To Start (Home)} moves to the first frame on the - timeline. - \li \l{Navigating in Timeline} - \row - \li \inlineimage icons/back_one_frame.png - \li \uicontrol {Previous (,)} moves to the previous frame on the - timeline. - \li \l{Navigating in Timeline} - \row - \li \inlineimage icons/start_playback.png - \li \uicontrol {Play (Space)} previews the animation. - \li \l{Viewing the Animation} - \row - \li \inlineimage icons/forward_one_frame.png - \li \uicontrol {Next (.)} moves to the next frame on the timeline. - \li \l{Navigating in Timeline} - \row - \li \inlineimage icons/to_last_frame.png - \li \uicontrol {To End (End)} moves to the last frame on the timeline. - \li \l{Navigating in Timeline} - \row - \li Current Keyframe - \li Displays the frame that the playhead is currently on. Enter a - number in the field to move the playhead to the respective frame. - \li \l{Navigating in Timeline} - \row - \li \inlineimage icons/global_record_keyframes.png - \li Records changes in keyframe values. - \li \l {Setting Keyframe Values} - \row - \li \inlineimage icons/curve_editor.png - \li Opens \uicontrol {Easing Curve Editor} for attaching an easing - curve to the selected transition. - \li \l{Editing Easing Curves} - \row - \li Start Frame - \li Specifies the first frame of the timeline. Negative values are - allowed. The difference between the start frame and the end frame - determines the duration of the animation. - \li \l{Creating a Timeline} - \row - \li \inlineimage icons/zoomOut.png - \li \uicontrol {Zoom Out} (\key Ctrl+-) zooms out of the view. - \li \l{Zooming in Timeline} - \row - \li Slider - \li Sets the zooming level. - \li \l{Zooming in Timeline} - \row - \li \inlineimage icons/zoomIn.png - \li \uicontrol {Zoom In} (\key Ctrl++) zooms into the view. - \li \l{Zooming in Timeline} - \row - \li End Frame - \li Specifies the last frame of the timeline. The difference between - the start frame and the end frame determines the duration of the - animation, so if the start frame is 0, the end frame equals the - duration. - \li \l{Creating a Timeline} - \row - \li State Name - \li Displays the name of the current state. - \li \l{Binding Animations to States} - \endtable - - \section1 Keyframe Track Icons - - Each keyframe track can contain the following buttons and markers. - - \table - \header - \li Button/Icon - \li Action - \li Read More - \row - \li \inlineimage icons/previous_keyframe.png - \li Jumps to the previous frame on the timeline. - \li \l{Setting Keyframe Values} - \row - \li \inlineimage icons/next_keyframe.png - \li Jumps to the next frame on the timeline. - \li \l{Setting Keyframe Values} - \row - \li \inlineimage icons/local_record_keyframes.png - \li Records changes in keyframe values for a particular property. - \li \l {Setting Keyframe Values} - \target keyframe_marker - \row - \li \inlineimage icons/keyframe.png - \li Indicates the type of easing curve attached to the keyframe. - When a keyframe track is selected, the keyframe markers on it turn - gray, and when a keyframe itself is selected, its marker turns - brown: - \list - \li \inlineimage icons/keyframe_linear_active.png - - linear easing curve - \li \inlineimage icons/keyframe_manualbezier_active.png - - manually set Bezier curve - \li \inlineimage icons/keyframe_autobezier_active.png - - automatically set Bezier curve - \li \inlineimage icons/keyframe_lineartobezier_active.png - - linear-to-Bezier curve - \endlist - \li \l {Editing Easing Curves} - \endtable - - \section1 Timeline Context Menu - - The following table summarizes the context menu items available for each - keyframe track for a component, property, or keyframe marker and provides - links to more information about them. - - \table - \header - \li To Learn About - \li Go To - \row - \li Delete All Keyframes - \li \l{Deleting Keyframes} - \row - \li Add Keyframes at Current Frame - \li \l{Setting Keyframe Values} - \row - \li Copy All Keyframes - \li \l{Copying Keyframes} - \row - \li Paste Keyframes - \li \l{Copying Keyframes} - \row - \li Remove Property - \li \l{Setting Keyframe Values} - \row - \li Delete Keyframe - \li \l{Deleting Keyframes} - \row - \li Edit Easing Curve - \li \l{Editing Easing Curves} - \row - \li Edit Keyframe - \li \l{Editing Keyframe Values} - \row - \li Override Color - \li \l{Setting Keyframe Track Color} - \row - \li Reset Color - \li \l{Setting Keyframe Track Color} - \endtable */ diff --git a/doc/qtdesignstudio/src/views/qtquick-timeline.qdoc b/doc/qtdesignstudio/src/views/qtquick-timeline.qdoc index c6a33f62c7..b599932ed0 100644 --- a/doc/qtdesignstudio/src/views/qtquick-timeline.qdoc +++ b/doc/qtdesignstudio/src/views/qtquick-timeline.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -191,7 +191,7 @@ position of the playhead, right-click the component name on the timeline and select \uicontrol {Add Keyframes at Current Frame}. - Keyframes are marked on the timeline by using \l{keyframe_marker}{markers} + Keyframes are marked on the timeline by using markers of different colors and shapes, depending on whether they are active or inactive or whether you have applied \l{Editing Easing Curves} {easing curves} to them. diff --git a/doc/qtdesignstudio/src/views/qtquick-transition-editor.qdoc b/doc/qtdesignstudio/src/views/qtquick-transition-editor.qdoc index b21207259e..7f73e0ceca 100644 --- a/doc/qtdesignstudio/src/views/qtquick-transition-editor.qdoc +++ b/doc/qtdesignstudio/src/views/qtquick-transition-editor.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -6,8 +6,12 @@ \previouspage studio-translations.html \nextpage qtquick-timeline-view.html + \ingroup studio-views + \title Transitions + \brief Make movement between states smooth. + To make movement between states smooth, you can use \uicontrol {Transitions} to animate the changes between states. @@ -17,7 +21,7 @@ animated, such as colors or numbers, in the \l Properties view. For example, you can animate the changes in the position of a component. - \image qtquick-transition-editor-view.png "Transitions view" + \image qtquick-transition-editor-view.webp "Transitions view" In \uicontrol {Transitions}, you can set the start frame, end frame, and duration for the transition of each property. You can also @@ -31,46 +35,6 @@ and \inlineimage icons/zoom_big.png buttons to zoom out of or into the view. - \section1 Summary of Transitions Toolbar Actions - - \table - \header - \li Button/Field - \li Action - \li Read More - \row - \li \inlineimage icons/settings.png - \li Opens \uicontrol {Transition Settings} dialog for editing - transition settings. - \li \l{Specifying Transition Settings} - \row - \li Transition ID - \li Displays a list of transitions that you can open in - \uicontrol {Transitions}. - \li \l{Animating Transitions Between States} - \row - \li \inlineimage icons/curve_editor.png - \li Opens \uicontrol {Easing Curve Editor} for attaching an easing - curve to the selected transition. - \li \l{Editing Easing Curves} - \row - \li \inlineimage icons/zoomOut.png - \li \uicontrol {Zoom Out} (\key Ctrl+-): zooms out of the view. - \li \l{Zooming in Transitions} - \row - \li Slider - \li Sets the zooming level. - \li \l{Zooming in Transitions} - \row - \li \inlineimage icons/zoomIn.png - \li \uicontrol {Zoom In} (\key Ctrl++): zooms into the view. - \li \l{Zooming in Transitions} - \row - \li Maximum Duration - \li Specifies the maximum duration of the transition. - \li - \endtable - \section1 Animating Transitions Between States To animate transitions: @@ -78,12 +42,12 @@ \list 1 \li Select \uicontrol View > \uicontrol Views > \uicontrol {Transition Editor}. - \image qmldesigner-transition-editor-startup.png "Empty Transitions view" + \image qmldesigner-transition-editor-startup.webp "Empty Transitions view" \li Select the \inlineimage icons/plus.png (\uicontrol {Add Transition}) button to add a transition. This works only if you have added at least one state and modified at least one property in it. - \image qtquick-transition-editor-view.png "Transitions view" + \image qtquick-transition-editor-view.webp "Transitions view" \li Move the blue bar next to the component or property name to set the start and end frame of the animation of the property. Pull its left and right edges to set the duration of the animation. @@ -98,7 +62,7 @@ (\uicontrol {Transition Settings (S)}) button in \uicontrol {Transition Editor}. - \image qtquick-transition-editor-settings.png "Transitions settings" + \image qtquick-transition-editor-settings.webp "Transitions settings" To add transitions: diff --git a/doc/qtdesignstudio/src/views/studio-content-library.qdoc b/doc/qtdesignstudio/src/views/studio-content-library.qdoc index e2785149e1..b3dbb28065 100644 --- a/doc/qtdesignstudio/src/views/studio-content-library.qdoc +++ b/doc/qtdesignstudio/src/views/studio-content-library.qdoc @@ -6,8 +6,13 @@ \previouspage creator-open-documents-view.html \nextpage studio-texture-editor.html + \ingroup studio-views + \title Content Library + \brief Select material, texture, and environment bundles with assets to + use in your application. + \note The \uicontrol {Content Library} view is included in the \l{https://www.qt.io/pricing}{Qt Design Studio Enterprise license}. diff --git a/doc/qtdesignstudio/src/views/studio-material-editor.qdoc b/doc/qtdesignstudio/src/views/studio-material-editor.qdoc index bb2923a7ab..44cea9504a 100644 --- a/doc/qtdesignstudio/src/views/studio-material-editor.qdoc +++ b/doc/qtdesignstudio/src/views/studio-material-editor.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2022 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -6,9 +6,12 @@ \previouspage studio-3d-editor.html \nextpage quick-components-view.html + \ingroup studio-views \title Material Editor and Browser + \brief Create and manage materials and textures. + In the \uicontrol {Material Editor} and \uicontrol {Material Browser} views, you create and manage materials and textures. @@ -21,7 +24,8 @@ To create a new material, do one of the following: \list - \li In \uicontrol {Material Browser}, select \inlineimage icons/plus.png + \li In \uicontrol {Material Browser}, select \inlineimage icons/add_material.png + \inlineimage icons/plus.png . \li In \uicontrol {Material Editor}, select \inlineimage icons/plus.png . @@ -67,7 +71,7 @@ \li In \uicontrol{Properties}, select \inlineimage icons/close.png next to the material. - \image materials-remove-material.png + \image materials-remove-material.webp "Remove a material in model properties" \endlist \section2 Copying and Pasting Material Properties @@ -82,7 +86,7 @@ want to copy properties from. \li Select \uicontrol {Copy properties} and then \uicontrol All or a property group. - \image material-copy-properties.png + \image material-copy-properties.png "Copy material properties in Material Browser" \li Right-click the material that you want to copy the properties to. \li Select \uicontrol {Paste properties}. \endlist @@ -114,11 +118,10 @@ \li From \uicontrol{Assets}, drag an image to \uicontrol{Reflection Map}. \li In \uicontrol {Navigator}, select - \inlineimage icons/filtericon.png - and then clear \uicontrol {Show Only Visible Components}. Now the + \inlineimage {icons/visibilityon.png}. Now the texture you just added to the material is visible in \uicontrol {Navigator}. - \image navigator-material-texture.png + \image navigator-material-texture.webp "Materials visible in Navigator" \li In \uicontrol {Navigator}, select the texture. \li In \uicontrol {Properties}, set \uicontrol {Texture Mapping} to \uicontrol {Environment}. @@ -276,8 +279,8 @@ To create a new texture, do one of the following in \uicontrol {Material Browser}: \list - \li Select \inlineimage icons/plus.png - in the \uicontrol Textures section. + \li Select \inlineimage icons/add_texture.png \inlineimage icons/plus.png + . \li Right-click anywhere in the \uicontrol Textures section and select \uicontrol {Create new texture}. \endlist diff --git a/doc/qtdesignstudio/src/views/studio-model-editor.qdoc b/doc/qtdesignstudio/src/views/studio-model-editor.qdoc new file mode 100644 index 0000000000..0caebcfb49 --- /dev/null +++ b/doc/qtdesignstudio/src/views/studio-model-editor.qdoc @@ -0,0 +1,62 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page studio-model-editor.html + \previouspage qtquick-effect-composer-view.html + \nextpage creator-project-managing-workspaces.html + + \ingroup studio-views + + \title Model Editor + + \brief Create, manage, import, and export data models. + + In the \uicontrol {Model Editor} view, you can create, manage, import, and export + data models. With data models, you can, for example, populate views with data. + + \image edit-list-model-model-editor.webp + + For examples of how to use data models, see + \l {Adding a Repeater3D Component with a Model}. + + \section1 Creating a Data Model + + To create a data model: + \list 1 + \li In \uicontrol {Model Editor}, select \inlineimage {icons/zoomIn.png}. + \li Enter a name and select \uicontrol {Create}. + \endlist + + This creates a single-cell table. + + \image model-editor-new-model.webp + + Next, add columns, rows, and data to the model. + + \note You must manually save the table after you have made changes. To do this, + select \inlineimage {icons/save-effect-composer.png}. + + \section1 Editing a Data Model + + Edit a data model in one of the following ways: + \list + \li Right-click a column name to edit its name and type, delete, or sort it. + \li Double-click a cell to edit its content. + \li Use the toolbar to add and remove columns and rows. + \endlist + + \note You must manually save the table after you have made changes. To do this, + select \inlineimage {icons/save-effect-composer.png}. + + \section1 Importing a Data Model + + Import data models from JSON or CSV files. To do this, select \inlineimage {icons/import.png} + in \uicontrol {Model Editor}. + + \section1 Exporting a Data Model + + Export data models to JSON or CSV files. To do this, select \inlineimage {icons/export.png} + in \uicontrol {Model Editor}. + +*/ diff --git a/doc/qtdesignstudio/src/views/studio-qtinsight.qdoc b/doc/qtdesignstudio/src/views/studio-qtinsight.qdoc index 6af9b071e1..6f420e1cb7 100644 --- a/doc/qtdesignstudio/src/views/studio-qtinsight.qdoc +++ b/doc/qtdesignstudio/src/views/studio-qtinsight.qdoc @@ -6,8 +6,12 @@ \previouspage studio-texture-editor.html \nextpage qtquick-effect-composer-view.html + \ingroup studio-views + \title Qt Insight + \brief Manage your Qt Insight. + In the \uicontrol {Qt Insight} view, you manage your Qt Insight. Qt Insight is an analytics solution that provides real user insights on the usage of Qt diff --git a/doc/qtdesignstudio/src/views/studio-texture-editor.qdoc b/doc/qtdesignstudio/src/views/studio-texture-editor.qdoc index ef45d8efdf..62b0eb147c 100644 --- a/doc/qtdesignstudio/src/views/studio-texture-editor.qdoc +++ b/doc/qtdesignstudio/src/views/studio-texture-editor.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2022 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -6,11 +6,15 @@ \previouspage studio-content-library.html \nextpage studio-qt-insight.html + \ingroup studio-views + \title Texture Editor + \brief Create and manage textures. + In the \uicontrol {Texture Editor} view, you create and manage textures. - \image texture-editor.png + \image texture-editor.webp "Texture Editor" \section1 Creating a Texture @@ -38,7 +42,7 @@ \li Select \inlineimage icons/apply.png . \li Select the material and property that you want to add the texture to. - \image select-material-property.png + \image select-material-property.png "Select a material property" \endlist \note You can also apply textures to materials in the diff --git a/doc/qtdesignstudio/src/views/studio-translations.qdoc b/doc/qtdesignstudio/src/views/studio-translations.qdoc index a2a610b313..ecf43369a4 100644 --- a/doc/qtdesignstudio/src/views/studio-translations.qdoc +++ b/doc/qtdesignstudio/src/views/studio-translations.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -6,8 +6,12 @@ \previouspage qtquick-states-view.html \nextpage qtquick-timeline-view.html + \ingroup studio-views + \title Translations + \brief Handle translations and multi-language support. + The \uicontrol Translations view is included in the \l{https://www.qt.io/pricing}{Qt Design Studio Enterprise license}. @@ -16,49 +20,6 @@ \image studio-translations-view.png "Translations view" - \section1 Summary of Translations View Buttons - - The \uicontrol {Translations} view contains the following buttons. - - \table - \header - \li Button - \li Function - \li Read More - \row - \li \inlineimage icons/select-languages.png - \li Select which languages you want your project to support. - \li - \row - \li \inlineimage icons/export-json-translations.png - \li Export all your translations to a JSON file. - \li \l{Importing and Exporting Translations} - \row - \li \inlineimage icons/import-json-translations.png - \li Import translations from a JSON file. - \li \l{Importing and Exporting Translations} - \row - \li \inlineimage icons/generate-translation-files.png - \li Generate Qt compiled translation source files (\e{.qm}) - and Qt translation source files (\e{.ts}). - \li \l{Generating Qt Translation Source Files} - \row - \li \inlineimage icons/project-translation-test.png - \li Run translation test for several documents and create a test report. - \li \l{Running Translation Test for Several Documents} - \row - \li \inlineimage icons/qml-translation-test.png - \li Run translation test for the currently open document. This test - shows translation warnings in the \uicontrol{2D} view and creates a - test report. - \li \l{Running Translation Test for a Single Document} - \row - \li \inlineimage icons/export-translations.png - \li Export all translations used in your project or all translations - currently visible in your UI. - \li \l{Exporting Translations in Other Ways} - \endtable - \section1 Importing and Exporting Translations You can import and export translations using JSON files. diff --git a/doc/qtdesignstudio/src/views/studio-workspaces.qdoc b/doc/qtdesignstudio/src/views/studio-workspaces.qdoc index 407513c40f..ed79be99d1 100644 --- a/doc/qtdesignstudio/src/views/studio-workspaces.qdoc +++ b/doc/qtdesignstudio/src/views/studio-workspaces.qdoc @@ -3,7 +3,7 @@ /*! \page creator-project-managing-workspaces.html - \previouspage qtquick-effect-composer-view.html + \previouspage studio-model-editor.html \nextpage creator-project-managing-sessions.html \title Managing Workspaces |
