diff options
Diffstat (limited to 'src/quick/doc/src/guidelines')
3 files changed, 59 insertions, 147 deletions
diff --git a/src/quick/doc/src/guidelines/qtquick-bestpractices.qdoc b/src/quick/doc/src/guidelines/qtquick-bestpractices.qdoc index 2e2fc05aac..1934be6f26 100644 --- a/src/quick/doc/src/guidelines/qtquick-bestpractices.qdoc +++ b/src/quick/doc/src/guidelines/qtquick-bestpractices.qdoc @@ -6,6 +6,7 @@ \title Best Practices for QML and Qt Quick \brief Lists best practices for working with QML and Qt Quick. \ingroup best-practices +\ingroup explanations-programminglanguages Despite all of the benefits that QML and Qt Quick offer, they can be challenging in certain situations. The following sections elaborate on some of @@ -28,11 +29,16 @@ options that align with the latest UI design trends. If these UI controls do not satisfy your application's needs, only then it is recommended to create a custom control. +You can use the controls when you design UIs in Qt Design Studio. In addition, +it provides timeline-based animations, visual effects, layouts, and a +live-preview for prototyping applications. \section2 Related Information \list \li \l{Qt Quick Controls} +\li \l{Customizing Qt Quick Controls} \li \l{Qt Quick} +\li \l{Qt Design Studio Manual} \endlist \omit @@ -88,12 +94,17 @@ qt_add_qml_module(my_module All QML files listed under \c {QML_FILES} will automatically get compiled \l {Ahead-of-Time Compilation}{ahead of time}. +You should keep the QML files in the same directory as the CMakeLists.txt with +the qt_add_qml_module. Otherwise their \l{The Implicit Import}{implicit imports} +will be different from the \l{QML Modules} they belong to. This is a frequent +source of mistakes. + \section2 Related Information \list \li \l{The Qt Resource System} \endlist -\section1 Separate UI from Logic +\section1 Separate UI from Business Logic One of the key goals that most application developers want to achieve is to create a maintainable application. One of the ways to achieve this goal is @@ -109,8 +120,8 @@ reasons why an application's UI should be written in QML: \li JavaScript can easily be used in QML to respond to events. \endlist -Being a strongly typed language, C++ is best suited for an application's logic. -Typically, such code performs tasks such as complex calculations +Being a strongly typed language, C++ is best suited for an application's +business logic. Typically, such code performs tasks such as complex calculations or data processing, which are faster in C++ than QML. Qt offers various approaches to integrate QML and C++ code in an application. @@ -154,6 +165,22 @@ see \l {Choosing the Correct Integration Method Between C++ and QML}. \li \l{Qt Quick Controls - Chat Tutorial}{Chat application tutorial} \endlist +\section1 Using Qt Design Studio + +Qt Design Studio uses UI files that have the filename extension \e {.ui.qml} +to separate the visual parts of the UI from the UI logic you implement in +\e {.qml} files. You should edit UI files only in the \uicontrol {2D} view in +Qt Design Studio. If you use some other tool to add code that Qt Design Studio +does not support, it displays error messages. Fix the errors to enable visual +editing of the UI files again. Typically, you should move the unsupported code +to a \e {.qml} file. + +\section2 Related Information + +\list + \li \l{Qt Design Studio: UI Files} +\endlist + \section1 Using Qt Quick Layouts Qt offers Qt Quick Layouts to arrange Qt Quick items visually in a layout. @@ -228,7 +255,7 @@ property MyMenu optionsMenu \section1 Performance For information on performance in QML and Qt Quick, -see \l {Performance Considerations And Suggestions}. +see \l {QML Performance Considerations And Suggestions}. \section1 Prefer Declarative Bindings Over Imperative Assignments diff --git a/src/quick/doc/src/guidelines/qtquick-tool-qmllint.qdoc b/src/quick/doc/src/guidelines/qtquick-tool-qmllint.qdoc deleted file mode 100644 index 0a9d6dbc58..0000000000 --- a/src/quick/doc/src/guidelines/qtquick-tool-qmllint.qdoc +++ /dev/null @@ -1,140 +0,0 @@ -// Copyright (C) 2021 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! -\page qtquick-tool-qmllint.html -\title qmllint -\brief A tool for verifying the syntax of QML files and warning about -anti-patterns. - -\e qmllint is a tool shipped with Qt, that verifies the syntatic validity of -QML files. -It also warns about some QML anti-patterns. If you want to disable a specific -warning type, you can find the appropriate flag for doing so by passing -\c{--help} on the command line. - -By default, some issues will result in warnings that will be printed and result -in a non-zero exit code. -Minor issues however (such as unused imports) are just informational messages -by default and will not affect the exit code. -qmllint is very configurable and allows for disabling warnings or changing how -they are treated. -Users may freely turn any issue into a warning, informational message, or -disable them outright. - -qmllint warns about: -\list - \li Unqualified accesses of properties - \li Usage of signal handlers without a matching signal - \li Usage of with statements in QML - \li Issues related to compiling QML code - \li Unused imports - \li Deprecated components and properties - \li And many other things -\endlist - -\note In order for qmllint to work properly, it requires type information. -That information is provided by QML modules in the import paths. -The current directory, as well as the import paths for Qt's built-in types, -are used as import paths by default. -To add more import paths not included in the default, -add them via the \c{-I} flag. - -To get an overview and explanation of all available command line options, run \c{qmllint --help}. - -\section2 Compiler warnings - -qmllint can warn you about code that cannot be compiled by \l{qmlsc}. - -These warnigs are not enabled by default. In order to enable them specify -\c{--compiler warning} or adjust your settings file accordingly. - -\section2 Marking components and properties as deprecated - -qmllint allows you to mark both properties and components as deprecated: - -\code -@Deprecated { reason: "Use NewCustomText instead" } -Text { - @Deprecated { reason: "Use newProperty instead" } - property int oldProperty - property int newProperty - Component.onCompleted: console.log(oldProperty); // Warning: XY.qml:8:40: Property "oldProperty" is deprecated (Reason: Use newProperty instead) -} -\endcode - -Deprecation warnings for components will be shown every time the component is created. - -\section2 Disabling warnings inline - -You may at any point disable warnings temporarily in a file using \c{// qmllint -disable}. - -You can do this at the end of a line when a single line produces warnings: - -\code -Item { - property string foo - Item { - property string bar: foo // qmllint disable unqualified - } -} -\endcode - -Alternatively you can disable comments for a block of lines by putting the -comment in a line only containing \c{// qmllint disable}, ending the block with -\c{// qmllint enable}: - -\code -Item { - property string foo - Item { - // qmllint disable unqualified - property string bar: foo - property string bar2: foo - // qmllint enable unqualified - } -} -\endcode - -qmllint interprets all single line comments starting with \c {qmllint} as -directives. Thus you may not start a comment that way unless you wish to enable -or disable warnings. - -\note As done in the examples above it is preferable to explicitly specify the -warning or a list of warnings you want to disable instead of disabling all -warnings. This can be done by simply listing warning categories after \c{qmllint disable} (the names are -the same as the options listed in \c{--help}). - -\section2 Settings - -In addition to passing command-line options, you can also -configure qmllint via a settings file. -The command line \c{--write-defaults} will generate one for you. - -Setting files are named \c{.qmllint.ini} and look like this: - -\quotefile qmllint/config.ini - -Warning levels may be set to \c{info}, \c{warning} or \c{disable} just as with -command line options. - -qmllint will automatically look for a settings file at the location of the qml -file that is being linted. -It also looks through all parent directories to find this file and -automatically applies the settings therein. You can disable this behavior by -using \c{--ignore-settings}. -You may always override these defaults by specifying command line parameters -that take precedence over the warning levels in settings. - -\section2 Scripting - -qmllint can write or output JSON via the \c{--json <file>} option which will return valid JSON -with warning messages, file and line location of warnings, and their severity -level. Use the special filename '-' to write to stdout instead of a file. -This can be used to more easily integrate qmllint in your pre-commit hooks or -CI testing. - -\sa {Type Description Files}{qmltypes} -\sa {QtQuick Tools and Utilities}{qtquick-tools-and-utilities} -*/ diff --git a/src/quick/doc/src/guidelines/qtquick-toolsnutilities.qdoc b/src/quick/doc/src/guidelines/qtquick-toolsnutilities.qdoc index 50b929e0ed..f87397f413 100644 --- a/src/quick/doc/src/guidelines/qtquick-toolsnutilities.qdoc +++ b/src/quick/doc/src/guidelines/qtquick-toolsnutilities.qdoc @@ -24,6 +24,12 @@ UIs using simple drag-n-drop gestures that most designers are familiar with. It offers UI elements from the Qt Quick and Qt Quick Controls modules, as well as integration for custom UI elements. +\section1 Qt Quick Effect Maker (QQEM) + +\l{\QQEM} is a tool for creating shader effects for Qt Quick with +high productivity and performance. You can run Qt Quick Effect Maker as a +standalone tool. + \section1 QML Debugger The \l{Qt Creator: QML Debugger}{QML Debugger} is a very useful utility that @@ -52,6 +58,15 @@ capable of rendering changes to the code in realtime. It avoids the need to rebuild the application after every code change and install it on the target device. You can also extend it to build a custom runtime that suits your needs. +\section1 Felgo QML Hot Reload + +\l{Felgo QML Hot Reload Tool}{Felgo QML Hot Reload} is a third-party tool that +updates QML and JavaScript code in your running application without recompiling +and redeploying after each change. Unlike Live Reload, it preserves the +application's current state after a reload and can run on multiple devices +simultaneously to test and iterate code. Felgo Hot Reload supports all Qt +target platforms and architectures. + \section1 GammaRay \l{GammaRay Manual}{GammaRay} is a useful utility that provides diagnostic @@ -69,7 +84,7 @@ tests are setup, UI tests are a lot easier to run. \section1 qmllint -\l{qtquick-tool-qmllint.html}{qmllint} is a tool shipped with Qt, that verifies +\l{qmllint Reference}{qmllint} is a tool shipped with Qt, that verifies the syntatic validity of QML files. It also warns about some QML anti-patterns. If you want to disable a specific warning type, you can find the appropriate flag for doing so by passing \c{--help} on the command line. @@ -98,7 +113,17 @@ all the available options. The Qt Quick Compiler consist of two components: \list - \li \l {QML Type Compiler} - \li \l {QML Script Compiler} + \li \l {QML type compiler} + \li \l {QML script compiler} \endlist + +\section1 \QMLLS + +\l{\QMLLS Reference}{\QMLLS} is a tool shipped with Qt that helps you edit +QML code in your favorite (LSP-compatible) editor. + +\section1 SVG to QML converter [tech preview] + +The \l{svgtoqml} tool converts an SVG document to a QML file that can be used as a component. + */ |