diff options
Diffstat (limited to 'src/qml/doc/src/tools')
12 files changed, 1180 insertions, 0 deletions
diff --git a/src/qml/doc/src/tools/qtqml-tooling-qml.qdoc b/src/qml/doc/src/tools/qtqml-tooling-qml.qdoc new file mode 100644 index 0000000000..6a0a335839 --- /dev/null +++ b/src/qml/doc/src/tools/qtqml-tooling-qml.qdoc @@ -0,0 +1,107 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-tooling-qml.html +\title qml +\brief Overview of the qml command line utility. +\ingroup qtqml-tooling + +\section1 The qml utility +\c The qml utility tool loads QML documents and creates a window to show the scene +if your QML document includes a visual item. You can also evaluate non-visual QML +documents with it. +It is mainly meant for testing your QML applications or components quickly +as described in \l {Prototyping with the QML Runtime Tool}{here}. + +\table +\header + \li Usage: +\row + \li qml [\l{options}] files... [-- args...] +\endtable + +\section2 options + +\table +\header + \li Option + \li Description +\row + \li -h, --help + \li Displays help on commandline options. +\row + \li --help-all + \li Displays help, including generic Qt options. +\row + \li -v, --version + \li Displays version information. +\row + \li -a, --apptype <core|gui|widget> + \li Select which application class to use. Default is gui. +\row + \li -I <path> + \li Prepend the given path to the import paths. +\row + \li -f <file> + \li Load the given file as a QML file. +\row + \li -c, --config <file> + \li Load the given built-in configuration or configuration file. +\row + \li --list-conf + \li List the built-in configurations. +\row + \li --translation <file> + \li Load the given file as the translations file. +\row + \li --dummy-data <file> + \li Load QML files from the given directory as context properties. (deprecated) +\row + \li --desktop + \li Force use of desktop OpenGL (AA_UseDesktopOpenGL). +\row + \li --gles + \li Force use of GLES (AA_UseOpenGLES). +\row + \li --software + \li Force use of software rendering (AA_UseSoftwareOpenGL). +\row + \li --core-profile + \li Force use of OpenGL Core Profile. +\row + \li --disable-context-sharing + \li Disable the use of a shared GL context for QtQuick Windows +\row + \li --enable-shader-cache + \li Enable persistent caching of generated shaders +\row + \li --transparent + \li Requests an alpha channel in order to enable semi-transparent windows. +\row + \li --multisample + \li Requests 4x multisample antialiasing. +\row + \li --quiet + \li Suppress all output. +\row + \li --verbose + \li Print information about what qml is doing, like specific file URLs being loaded. +\row + \li --slow-animations + \li Run all animations in slow motion. +\row + \li --fixed-animations + \li Run animations off animation tick rather than wall time. +\row + \li -r, --rhi <backend> + \li Set the backend for the Qt graphics abstraction (RHI). Backend is one of: + default, vulkan, metal, d3d11, gl +\row + \li -S <selector> + \li Add selector to the list of QQmlFileSelectors. + +\endtable + + +*/ diff --git a/src/qml/doc/src/tools/qtqml-tooling-qmlformat.qdoc b/src/qml/doc/src/tools/qtqml-tooling-qmlformat.qdoc new file mode 100644 index 0000000000..b516104f66 --- /dev/null +++ b/src/qml/doc/src/tools/qtqml-tooling-qmlformat.qdoc @@ -0,0 +1,146 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-tooling-qmlformat.html +\title qmlformat +\brief Overview of the qmlformat tool. +\ingroup qtqml-tooling + +\section1 qmlformat +\e qmlformat is a tool that automatically formats QML files in accordance +with the \l{QML Coding Conventions}. \l{Details}{More...} + +\table +\header + \li Usage: +\row + \li qmlformat [\l{options}] \l{arguments} +\endtable + +\section2 Options +\target options +The following options are available: + +\table +\header + \li Option + \li Default Value + \li Description +\row + \li -h, --help + \li + \li Displays help on commandline options. +\row + \li --help-all + \li + \li Displays help, including generic Qt options. + +\row + \li -v, --version + \li + \li Displays version information. +\row + \li -V, --verbose + \li + \li Verbose mode. Outputs more detailed information. +\row + \li --write-defaults + \li + \li Writes defaults settings to .qmlformat.ini and exits + (Warning: This will overwrite any existing settings and comments!) +\row + \li --ignore-settings + \li + \li Ignores all settings files and only takes command line options into consideration +\row + \li -i, --inplace + \li + \li Edit file in-place instead of outputting to stdout. +\row + \li -f, --force + \li + \li Continue even if an error has occurred. +\row + \li -t, --tabs + \li + \li Use tabs instead of spaces. +\row + \li -w, --indent-width <width> + \li 4 + \li How many spaces are used when indenting. +\row + \li -n, --normalize + \li + \li Reorders the attributes of the objects according to the QML Coding Guidelines. +\row + \li -F, --files <file> + \li + \li Format all files listed in file, in-place +\row + \li -l, --newline <newline> + \li + \li Override the new line format to use (native macos unix windows). +\row + \li --objects-spacing + \li + \li Ensure spaces between objects (only works with normalize option). +\row + \li --functions-spacing + \li + \li Ensure spaces between functions (only works with normalize option). + +\endtable + +\section2 Arguments +\target arguments +\table +\header + \li Arguments: +\row + \li filenames +\endtable + +\section2 Details +\e qmlformat is flexible and can be configured according to your needs. + +\section3 Output +qmlformat writes the formatted version of the file to stdout. +If you wish to have your file updated in-place specify the \c{-i} flag. + +\section3 Grouping Properties, Functions, and Signals Together +With \c{-n} or \c{--normalize} flag, \e qmlformat groups all properties, functions, +and signals together, instead of retaining the order you specified. + +\section3 Settings File +You can configure \e qmlformat by including a settings file \c{.qmlformat.ini} in your +project source or in the parent directories of your project source folder. A default +settings file can be obtained by passing the \c{--write-defaults} flag. This generates the +\c{.qmlformat.ini} file in the current working directory. + +\warning \c{--write-defaults} will overwrite any existing settings and comments! + +\section3 Formatting a List of Files +While you can pass a list of files to be formatted as arguments, qmlformat provides +\c {-F} option to format a set of files stored in a file. In this case, formatting will happen +inplace. + +\code + // FileList.txt + main.qml + mycomponent.qml +\endcode + +Then, use it like +\code + qmlformat -F FileList.txt +\endcode + +\note If the file contains an invalid entry, for example, a file path that +doesn't exist or a valid file path but the content is an invalid qml document, +then \c qmlformat will error out for that particular entry. It will still format +the valid file entries in place. + +\warning If you provide -F option, qmlformat will ignore the positional arguments. + +*/ diff --git a/src/qml/doc/src/tools/qtqml-tooling-qmlimportscanner.qdoc b/src/qml/doc/src/tools/qtqml-tooling-qmlimportscanner.qdoc new file mode 100644 index 0000000000..7a4047cf7d --- /dev/null +++ b/src/qml/doc/src/tools/qtqml-tooling-qmlimportscanner.qdoc @@ -0,0 +1,15 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-tooling-qmlimportscanner.html +\title qmlimportscanner +\brief Overview of the qmlimportscanner utility. +\ingroup qtqml-tooling + +\section1 qmlimportscanner +\c qmlimportscanner is an internal tool shipped with Qt Qml to scan QML files +inside the directory for QML import dependencies. It is meant to be invoked by +the build system only, users shouldn't need to execute it directly. + +*/ diff --git a/src/qml/doc/src/tools/qtqml-tooling-qmllint.qdoc b/src/qml/doc/src/tools/qtqml-tooling-qmllint.qdoc new file mode 100644 index 0000000000..7dfde85f2a --- /dev/null +++ b/src/qml/doc/src/tools/qtqml-tooling-qmllint.qdoc @@ -0,0 +1,142 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-tooling-qmllint.html +\title qmllint Reference +\ingroup qtqml-tooling +\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. If there +are more warnings than a limit which can be configured with \c{--max-warnings}, +the exit code will be non-zero. +Minor issues however (such as unused imports) are just informational messages +by default and will never 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 warnings 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} +\sa {Qt Quick Tools and Utilities} +*/ diff --git a/src/qml/doc/src/tools/qtqml-tooling-qmlls.qdoc b/src/qml/doc/src/tools/qtqml-tooling-qmlls.qdoc new file mode 100644 index 0000000000..e9c737c036 --- /dev/null +++ b/src/qml/doc/src/tools/qtqml-tooling-qmlls.qdoc @@ -0,0 +1,168 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-tooling-qmlls.html +\title \QMLLS Reference +\brief Overview of \QMLLS (qmlls). +\ingroup qtqml-tooling + +\QMLLS is a tool shipped with Qt that helps you write code +in your favorite (LSP-supporting) editor. +See \l{https://microsoft.github.io/language-server-protocol/}{Language Server Protocol} +for more information. + +Currently, it enables your editor to: +\list + \li Autocomplete your code + \li Display qmllint warnings + \li Navigate to definitions in QML files + \li Find usages of JavaScript variables and QML objects + \li Rename JavaScript variables and QML objects + \li Format QML files +\endlist + +\note qmlls is currently in development, see \l{Known Limitations} for +more details. + +\section1 Supported Features + +\section2 Linting + +\QMLLS can automatically lint opened QML files +and display warnings or errors straight in the editor. See +\l{qmllint Reference}{qmllint} for more information about the linting process. + +\section2 Formatting + +\QMLLS can format entire files from inside +the editor. See \l{qmlformat} for more information about the +formatting process. + + +\section2 Finding Definitions + +\QMLLS can find definitions of JavaScript variables, +functions, QML object id's and QML properties from their usages. + +\QMLLS can also find the definition of types used in +type annotations for JavaScript functions, QML object properties, +and QML object instantiation. + +\section2 Finding Usages + +\QMLLS can find usages of JavaScript variables, +QML object properties, JavaScript functions, QML object methods, +and QML object id's. + +\section2 Renaming + +\QMLLS can rename JavaScript variables and functions, +as well as QML object properties, methods, and id's, as long as +they are defined in a QML file. + +\section2 Suggesting Autocompletion Items + +\QMLLS provides autocompletion suggestions for +JavaScript variables, expressions, and statements, as well as +QML object properties, methods, and id's. + +\section2 Tracking Changes in C++ Files + +\QMLLS can track changes in C++ files defining QML +types. It automatically rebuilds CMake QML modules to provide +accurate and up-to-date warnings and completion items for C++ +defined QML types. + +You can +\l{Disabling automatic CMake builds}{disable this feature}. + +\section1 Setting up the \QMLLS in Your Editor + +\note You can find the \QMLLS binary under +\c{<Qt installation folder>/bin/qmlls} in installations of Qt +made with \QOI. + +\section2 Setting up the Build Directory + +\QMLLS needs to know the location of your build +folder. You can pass it the following ways: +\list + \li The \c{--build-dir} command line option. In this case +your editor should invoke \c{qmlls} as following: +\badcode +<path/to/qmlls> --build-dir <path/to/build-directory> +\endcode + \li The \c{QMLLS_BUILD_DIRS} environment variable. + \li The \c{.qmlls.ini} settings file, see \l {Configuration File}. +\endlist + +\note When the build directory is specified in multiple ways, the +command line option takes preference over the environment variable +that takes precedence over the setting file. + +\section2 Disabling Automatic CMake Builds + +\c{qmlls} will try to trigger a CMake rebuild when it detects that the +source code of a C++ defined QML type has been modified. + +To disable this feature, use the following ways: +\list + \li The \c{--no-cmake-calls} command line option. In this case +your editor should invoke \c{qmlls} as follows: +\badcode +<path/to/qmlls> --build-dir <path/to/build-directory> --no-cmake-calls +\endcode + \li The \c{QMLLS_NO_CMAKE_CALLS} environment variable. + \li The \c{.qmlls.ini} settings file, see \l {Configuration File}. +\endlist + +\section1 Configuration File + +\QMLLS can be configured via a configuration file \c{.qmlls.ini}. +This file should be in the root source directory of the project. +It should be a text file in the ini-format. + +\note \c{.qmlls.ini} files can be generated automatically via +\l{QT_QML_GENERATE_QMLLS_INI}. + +The configuration file should look like this: +\code +// .qmlls.ini +[General] +buildDir=<path/to/build-directory> +no-cmake-calls=<true-or-false> +\endcode + +Currently, the configuration file can be used to set the build +directory of the current project and optionally disable the automatic +CMake rebuild functionality for C++ defined QML types. + +\note \QMLLS can create default configuration files +using the \c{--write-defaults} option. This will overwrite an +already existing .qmlls.ini file in the current directory. + +\section1 Known Limitations + +\QMLLS might emit false positive warnings on projects +that were not built, as it needs the build information to find +QML modules defined in the same project, for example. + +Despite covering many common QML features, +the \QMLLS is still in development with some features +yet to be supported: + +\list + \li Renaming QML types. + \li Suggesting autocompletions on invalid QML files. + \li Navigating to definitions of objects defined in C++. + \li Supporting all QML and JavaScript language constructs for all features. +\endlist + +The QML code model in the \QMLLS does not yet +support all of the JavaScript language constructs, which means that +some features like navigating to definition and finding usages might not +work on these language constructs. + + +*/ diff --git a/src/qml/doc/src/tools/qtqml-tooling-qmlpreview.qdoc b/src/qml/doc/src/tools/qtqml-tooling-qmlpreview.qdoc new file mode 100644 index 0000000000..5e9da3d2f4 --- /dev/null +++ b/src/qml/doc/src/tools/qtqml-tooling-qmlpreview.qdoc @@ -0,0 +1,74 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-tooling-qmlpreview.html +\title qmlpreview +\brief Overview of the qmlpreview utility. +\ingroup qtqml-tooling + +\section1 The Qml Preview +The QML Preview tool watches QML and JavaScript files on disk and updates +the application live with any changes. The application to be previewed +has to have QML debugging enabled. \l {details}{More...} + +\table +\header + \li Usage +\row + \li qmlpreview [\l{options}] executable [parameters...] +\endtable + +\section2 options + +\table +\header + \li Option + \li Description +\row + \li --verbose + \li Print debugging output. +\row + \li -h, --help + \li Displays help on commandline options. +\row + \li --help-all + \li Displays help, including generic Qt options. +\row + \li -v, --version + \li Displays version information. +\endtable + +\section2 Arguments + +\table + \header + \li Argument + \li Description + \row + \li executable + \li The path of the executable file that loads a QML document. + \row + \li parameters + \li Arguments of the executable + +\endtable + +\section2 Details +\target details + +\section3 Enable QML Debugging +To enable QML debugging, make sure you build your application with appropriate +configuration parameters. When using qmake, you should add \c {CONFIG+=qml_debug} +in the \c {.pro} file. If you use another build system, then \c {QT_QML_DEBUG} +variable should be defined. + +\badcode + qt_add_executable(MyApp + ... + ) + + target_compile_definitions(MyApp PRIVATE QT_QML_DEBUG) +\endcode + +*/ diff --git a/src/qml/doc/src/tools/qtqml-tooling-qmlprofiler.qdoc b/src/qml/doc/src/tools/qtqml-tooling-qmlprofiler.qdoc new file mode 100644 index 0000000000..6bce0417b7 --- /dev/null +++ b/src/qml/doc/src/tools/qtqml-tooling-qmlprofiler.qdoc @@ -0,0 +1,10 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-tooling-qmlprofiler.html +\title qmlprofiler +\brief Overview of the qml profiler tool. +\ingroup qtqml-tooling + +*/ diff --git a/src/qml/doc/src/tools/qtqml-tooling-qmltyperegistrar.qdoc b/src/qml/doc/src/tools/qtqml-tooling-qmltyperegistrar.qdoc new file mode 100644 index 0000000000..1f2103d1b1 --- /dev/null +++ b/src/qml/doc/src/tools/qtqml-tooling-qmltyperegistrar.qdoc @@ -0,0 +1,10 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-tooling-qmltyperegistrar.html +\title qmltyperegistrar +\brief Overview of the qmltyperegistrar utility. +\ingroup qtqml-tooling + +*/ diff --git a/src/qml/doc/src/tools/qtqml-tooling-svgtoqml.qdoc b/src/qml/doc/src/tools/qtqml-tooling-svgtoqml.qdoc new file mode 100644 index 0000000000..836acc3f6a --- /dev/null +++ b/src/qml/doc/src/tools/qtqml-tooling-svgtoqml.qdoc @@ -0,0 +1,92 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-tooling-svgtoqml.html +\title svgtoqml +\brief The SVG to QML converter tool +\ingroup qtqml-tooling + +\c svgtoqml is a command line tool shipped with Qt that converts an SVG document +to a QML file. This QML file can then be used as a component in Qt Quick +applications. The \l{Weather Forecast Example} includes multiple QML files that have been generated +using this tool. + +\section1 Overview +The \c svgtoqml will convert an SVG file to a QML file which uses Qt Quick primitives. Since +Qt Quick supports scalable vector graphics, the resulting item will be smoothly transformable as far +as this is possible. As a baseline, the tool supports most of the static features of the SVG Tiny 1.2 +profile. Certain additional features are supported, determined on a case-by-case basis. Interactive +features and animations are not supported. + +\section1 Usage +The basic usage of \c svgtoqml is to provide an input file and an output file: +\c{svgtoqml input.svg output.qml}. This will read the \c{input.svg} file and convert it into the +corresponding Qt Quick scene in \c{output.qml}, which can then be used as part of a Qt Quick +application. + +In addition, it supports the following options: + +\table +\header + \li Option + \li Description +\row + \li --copyright-statement <string> + \li Adds <string> as a comment at the beginning of the generated file. +\row + \li --curve-renderer + \li Enables the curve renderer backend for \l{Qt Quick Shapes}. This enables smooth, antialiased + shapes in the scene without multi-sampling, but at some extra cost. +\row + \li --optimize-paths + \li Enables optimization of paths before committing them to the QML file, potentially making + them faster to load and render later. +\row + \li --outline-stroke-mode + \li Stroke the outline (contour) of the filled shape instead of the original path. +\row + \li -t, --type-name <string> + \li In place of \l{Shape}, the output will use the type name <string> instead. This is + enables using a custom item to override the default behavior of \l{Shape} items. +\row + \li -v, --view + \li Display a preview of the Qt Quick item as it will be generated. +\endtable + +\section1 Comparison to other options +There are multiple options for including SVG content in Qt Quick. The following will give an +overview of where \c svgtoqml fits into the story. + +\section2 Comparison to Qt Svg +\l{Qt Svg} is a module which provides a parser and software renderer for SVG files. In addition, it +includes an image loader plugin, so that SVG files can be loaded directly by the \l{Image} element +in Qt Quick. The SVG will then be rasterized and cached at a specified size and redrawing it will +be quite cheap. But zooming into the image without pixelation will involve reloading it at a +different size, which in turn can be expensive. + +\c svgtoqml (and the \l{VectorImage} component) are alternative ways of rendering the same content. +Once loaded into Qt Quick, transforms can be changed while retaining the geometry data needed to +render the scene in GPU memory. Thus, the vector image can be redrawn at different scales with very +little overhead. + +If the image size will not change during the life time of the application, however, loading the +SVG as an \l{Image} will be more efficient. In this case, if the SVG is always rendered at a +small subset of possible sizes, consider pre-rasterizing it to an image format which is more +efficient to load, such as \c PNG. + +\section2 Comparison to VectorImage +The \l{VectorImage} component provides the same basic functionality as \c svgtoqml, but instead of +pregenerating the Qt Quick scene as a QML file, it creates the scene at runtime. This allows loading +SVG files that are not provided at build time and thus allows for more flexibility. Pregenerating +the scenes with \c svgtoqml allows optimizing the scene before it is loaded. Thus, for files that +are available at build time, \c svgtoqml is the preferred option. + +\section2 Comparison to PathSvg +The \l{PathSvg} component is part of the \l{Qt Quick Shapes} module. It provides a way to define +paths with the syntax used by SVG, where the control points of a path are specified as a string. It +does not support loading SVG files, so it is not a direct alternative to \c svgtoqml. If a complex +SVG contains a specific shape needed by the application, then copying this path description into +\l{PathSvg} may be more convenient than generating the full file. + +*/ diff --git a/src/qml/doc/src/tools/qtquickcompiler/qtqml-qml-script-compiler.qdoc b/src/qml/doc/src/tools/qtquickcompiler/qtqml-qml-script-compiler.qdoc new file mode 100644 index 0000000000..302c71882a --- /dev/null +++ b/src/qml/doc/src/tools/qtquickcompiler/qtqml-qml-script-compiler.qdoc @@ -0,0 +1,120 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-qml-script-compiler.html +\title QML script compiler +\brief A tool to compile functions and expressions in QML. +\keyword qmlsc +\ingroup qtqml-tooling + +The QML script compiler compiles functions and expressions in QML and JavaScript +files to a byte code that can be interpreted or Just-in-time compiled by the +QML engine. + +In addition, it compiles some functions and expressions in QML files into C++ +code, within limitations set by the nature of JavaScript. It generates C++ code +for functions that can be exhaustively analyzed. The following flow chart +explains the compilation workflow. + +\image qmlsc-compilation-scheme.png + +QML script compiler is available in two versions. One is \e qmlcachegen, which +is a part of the \l{Qt Quick Compiler}. Another one is \e qmlsc, which is a part +of the commercial-only add-on \e{Qt Quick Compiler Extensions}. + +\section1 qmlcachegen +\e qmlcachegen uses the meta-object system and generates lookups and stores them in a +central place, a compilation unit. The compilation unit contains a representation of +document structure, compact byte code representation for each function and expression, +and native code for functions and bindings that compiler fully understands. +The byte code in a compilation unit can be used by the QML engine to avoid re-compilation +and to speed up execution. + +\section1 qmlsc +\e qmlsc, on the flip side, extends the base functionality of qmlcachegen by providing +two extra modes. + +\list +\li \l {static mode} +\li \l {direct mode} +\endlist + +\section2 static mode +In static mode, qmlsc assumes that no properties of any types exposed to C++ can be +shadowed by derived types. It eliminates the shadow checking mechanism and allows more +JavaScript code to be compiled to C++ and eventually generates faster code. + +To enable static mode in qmlsc, you should pass \c{--static} via \c{QT_QMLCACHEGEN_ARGUMENTS} to \l{qt_add_qml_module}. +\badcode + qt_add_qml_module(someTarget + ... + ) + + set_target_properties(someTarget PROPERTIES + QT_QMLCACHEGEN_ARGUMENTS "--static" + ) +\endcode + +\warning qmlsc static-mode generates invalid code if any properties are shadowed in +the QML document. + +\section2 direct mode +In direct mode, qmlsc assumes that all C++ types used in your QML code are available +and can be included as C++ headers to the generated code. Then the generated code +accesses or modifies properties by directly calling getters, setters and invokable +functions in those headers which makes the execution even faster. This means you have to +link to private Qt APIs in CMake. + +\warning Private Qt APIs change often. You will need to recompile Qt for each new version. + +\warning If a type is only defined in a plugin or has no header, you can’t use it in direct mode. + +To enable direct mode, you should consider the followings: + +\list + \li you should pass \c{--direct-calls} via \c{QT_QMLCACHEGEN_ARGUMENTS} to \l{qt_add_qml_module}. + +\badcode + qt_add_qml_module(someTarget + ... + ) + + set_target_properties(someTarget PROPERTIES + QT_QMLCACHEGEN_ARGUMENTS "--direct-calls" + ) +\endcode + + \li Link all the relavant private Qt modules instead of their public counterparts. +\badcode + qt_add_qml_module(someTarget + ... + ) + + target_link_libraries(someTarget PRIVATE + Qt::QmlPrivate + Qt::QuickPrivate + ... + ) +\endcode + + \li Do not set the \c{PLUGIN_TARGET} to be the same as the backing library target. +\badcode + # direct mode will not function in this setup. + qt_add_qml_module(someTarget + PLUGIN_TARGET someTarget + ... + ) +\endcode +\endlist + +\section1 Limitations when compiling JavaScript to C++ + +Many JavaScript constructs cannot be efficiently represented in C++. The QML +script compiler skips the C++ code generation for functions that contain such +constructs and only generates byte code to be interpreted or run through the +Just-in-time compiler. Most common QML expressions are rather simple: value +lookups on QObjects, arithmetics, simple if/else or loop constructs. Those can +easily be expressed in C++, and doing so makes your application run faster. + +*/ diff --git a/src/qml/doc/src/tools/qtquickcompiler/qtqml-qml-type-compiler.qdoc b/src/qml/doc/src/tools/qtquickcompiler/qtqml-qml-type-compiler.qdoc new file mode 100644 index 0000000000..38f8fe039b --- /dev/null +++ b/src/qml/doc/src/tools/qtquickcompiler/qtqml-qml-type-compiler.qdoc @@ -0,0 +1,283 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-qml-type-compiler.html +\title QML type compiler +\brief A tool to compile QML types to C++ ahead of time. +\keyword qmltc +\ingroup qtqml-tooling + +The QML type compiler, \c qmltc, is a tool shipped with Qt to translate QML +types into C++ types that are \e{ahead-of-time} compiled as part of the user +code. Using qmltc can lead to better run-time performance due to more +optimization opportunities available to the compiler compared to a +QQmlComponent-based object creation. The qmltc is part of the \l{Qt Quick Compiler} +toolchain. + +By design, qmltc outputs user-facing code. That code is supposed to be utilized +by the C++ application directly, otherwise you won't see any benefit. This +generated code essentially replaces QQmlComponent and its APIs to create objects +from QML documents. You can find more information under \l{Using qmltc in a QML +application} and \l{Generated Output Basics}. + +In order to enable qmltc: + +\list + \li Create a \l{qt_add_qml_module}{proper QML module} for your application. + + \li Invoke qmltc, for example, through the \l{qmltc-cmake}{CMake API}. + + \li \c{#include} the generated header file(s) in the application source + code. + + \li Instantiate an object of the generated type. +\endlist + +In this workflow qmltc usually runs during the build process. Thus, when qmltc +rejects a QML document (whether due to errors or warnings, or because of +constructs qmltc doesn't yet support), the build process will fail. This is +similar to how you receive qmllint errors when you enable the automatic +generation of linting targets during \l{qt_add_qml_module}{QML module creation} +and then attempt to "build" them to run the qmllint. + +\warning qmltc is currently in a Tech Preview stage and might not compile an +arbitrary QML program (see \l{Known Limitations} for more details). When qmltc +fails, nothing is generated as your application cannot sensibly use the qmltc +output. If your program contains errors (or unsolvable warnings), they should be +fixed to enable the compilation. The general rule is to adhere to the best +practices and follow \l{qmllint Reference}{qmllint} advice. + +\note \c qmltc does not guarantee that the generated C++ stays API-, source- or +binary-compatible between past or future versions, even patch versions. +Furthermore, qmltc-compiled apps using Qt's QML modules will require linking +against private Qt API. This is because Qt's QML modules do not usually provide +a public C++ API since their primary usage is through QML. + + +\section2 Using qmltc in a QML application + +From the build system perspective, adding qmltc compilation is not much +different from adding qml cache generation. Naively, the build process could be +described as: + +\image qmltc-compilation-scheme.png + +While the real compilation process is much trickier, this diagram captures the +core components that qmltc uses: the QML files themselves and qmldir with +qmltypes information. Simpler applications typically have rather primitive +qmldir yet, in general, qmldir could be complex, providing essential, nicely +packed type information that qmltc relies on to perform correct QML-to-C++ +translation. + +Nevertheless, adding an extra build step is not enough in qmltc case. The +application code must also be modified to use qmltc-generated classes instead of +QQmlComponent or its higher-level alternatives. + +\section3 Compiling QML code with qmltc + +Qt, starting from Qt 6, uses CMake to build its various components. User +projects can - and are encouraged to - also use CMake to build their components +using Qt. Adding out-of-the-box qmltc compilation support to your project would +require a CMake-driven build flow as well since this flow is centered around +proper QML modules and their infrastructure. + +The easy way to add qmltc compilation is by using the dedicated +\l{qmltc-cmake}{CMake API} as part of a QML module creation for the application. +Consider a simple application directory structure: + +\badcode +. +├── CMakeLists.txt +├── myspecialtype.h // C++ type exposed to QML +├── myspecialtype.cpp +├── myApp.qml // main QML page +├── MyButton.qml // custom UI button +├── MySlider.qml // custom UI slider +└── main.cpp // main C++ application file +\endcode + +Then the CMake code would usually look similar to the following: + +\snippet qmltc/CMakeLists.txt qmltc-app-name +\codeline +\snippet qmltc/CMakeLists.txt qmltc-qml-files +\codeline +\snippet qmltc/CMakeLists.txt qmltc-add-qml-module +\codeline +\snippet qmltc/CMakeLists.txt qmltc-compile-to-cpp + +\section3 Using the Generated C++ + +Unlike in the case of QQmlComponent instantiation, the output of qmltc, being +C++ code, is used directly by the application. Generally, constructing a new +object in C++ is equivalent to creating a new object through +QQmlComponent::create(). Once created, the object could be manipulated from C++ +or, for example, combined with QQuickWindow to be drawn on screen. + +If a compiled type exposes some required properties, `qmltc` will +require an initial value for those properties in the constructor for +the generated object. + +Additionally, the constructor for a qmltc object can be provided with +with a callback to set up initial values for the component's +properties. + +Given a \c{myApp.qml} file, the application code (in both cases) would +typically look like this: + +\if defined(onlinedocs) + \tab {generated-c++}{tab-qqmlcomponent}{Using QQmlComponent}{checked} + \tab {generated-c++}{tab-qmltc}{Using qmltc-generated class}{} + \tabcontent {tab-qqmlcomponent} +\else + \section4 Using QQmlComponent +\endif +\snippet qmltc/tst_qmltc_examples.cpp qqmlcomponent-include +\codeline +\snippet qmltc/tst_qmltc_examples.cpp qqmlcomponent-app-code-0 +\codeline +\snippet qmltc/tst_qmltc_examples.cpp qqmlcomponent-app-code-1 +\codeline +\snippet qmltc/tst_qmltc_examples.cpp qqmlcomponent-app-code-2 +\codeline +\snippet qmltc/tst_qmltc_examples.cpp qmltc-app-exec +\if defined(onlinedocs) + \endtabcontent + \tabcontent {tab-qmltc} +\else + \section4 Using qmltc-generated class +\endif +\snippet qmltc/tst_qmltc_examples.cpp qmltc-include +\codeline +\snippet qmltc/tst_qmltc_examples.cpp qmltc-app-code +\codeline +\snippet qmltc/tst_qmltc_examples.cpp qmltc-app-exec +\if defined(onlinedocs) + \endtabcontent +\endif + +\section2 QML engine + +The generated code uses QQmlEngine to interact with dynamic parts of a QML +document - mainly the JavaScript code. For this to work, no special arrangements +are needed. Any QQmlEngine instance passed to the constructor of a +qmltc-generated class object should work correctly as does +\c{QQmlComponent(engine)}. This also means that you can use +\l{QQmlEngine}{QQmlEngine methods} that affect QML behavior. However, there are +caveats. Unlike QQmlComponent-based object creation, qmltc itself \e{does not} +rely on QQmlEngine when compiling the code to C++. For instance, +\c{QQmlEngine::addImportPath("/foo/bar/")} - normally resulting in an additional +import path to scan for - would be completely ignored by the ahead-of-time qmltc +procedure. + +\note To add import paths to the qmltc compilation, consider using a relevant +argument of the \l{qmltc-cmake}{CMake command} instead. + +Generally, you can think of it this way: QQmlEngine involves the application +process to run, while qmltc does not as it operates \e{before} your application +is even compiled. Since qmltc makes no attempt to introspect your application's +C++ source code, there is no way for it to know about certain kinds of QML +manipulations you, as a user, do. Instead of using QQmlEngine and related +run-time routines to expose types to QML, adding import paths, etc. you are, +practically, required to create \l{qt_add_qml_module}{well-behaving QML modules} +and use \l{Defining QML Types from C++}{declarative QML type registration}. + +\warning Despite qmltc working closely with QQmlEngine and creating C++ code, +the generated classes cannot be further exposed to QML and used through +QQmlComponent. + +\section2 Generated Output Basics + +\c qmltc aims to be compatible with the existing QML execution model. This +implies that the generated code is roughly equivalent to the internal +QQmlComponent setup logic and thus you should be able to understand your QML +type's behavior, semantics and API the same way you do currently - by visually +inspecting the corresponding QML document. + +However, the generated code is still somewhat confusing, especially given that +your application should use the qmltc output on the C++ side directly. There are +two parts of the generated code: CMake build files structure and the generated +C++ format. The former is covered in the \l{qmltc-cmake}{CMake API of qmltc} and +the latter is covered here. + +Consider a simple HelloWorld type, that has a \c hello property, a function to +print that property, and a signal emitted when the object of that type is +created: + +\snippet qmltc/special/HelloWorld.qml qmltc-hello-world-qml + +When providing a C++ alternative of this QML type, the C++ class would need a +\l{Overview - QML and C++ Integration}{QML-specific meta-object system macro}, +Q_PROPERTY decoration for the \c hello property, \c{Q_INVOKABLE} C++ printing +function and a regular Qt signal definition. Similarly, qmltc would translate +the given HelloWorld type into roughly the following: + +\snippet qmltc/special/HelloWorld.qml.cpp qmltc-hello-world-generated + +Even though specific details of the generated type could differ, the universal +aspects remain. For instance: + +\list + \li QML types within a document are translated into C++ types, according to + the compiler-visible information. + \li Properties are translated into C++ properties with Q_PROPERTY + declarations. + \li JavaScript functions become \c{Q_INVOKABLE} C++ functions. + \li QML signals are transformed into C++ Qt signals. + \li QML enumerations are converted into C++ enumerations with \c{Q_ENUM} + declarations. +\endlist + +An additional detail is the way \c qmltc generates class names. A class name for +a given QML type is automatically deduced from the QML document defining that +type: the QML file name without extensions (up to and excluding the first \c{.}, +also known as the base name) becomes a class name. The file name case is +preserved. Thus, \c{HelloWorld.qml} would result in a \c{class HelloWorld} and +\c{helloWoRlD.qml} in a \c{class helloWoRlD}. Following the QML convention, if a +QML document file name starts with a lower-case letter, the generated C++ class +is assumed to be anonymous and marked with \l{QML_ANONYMOUS}. + +For now, although the generated code is ready to be used from the C++ +application side, you should generally limit calls to the generated APIs. +Instead, prefer implementing the application logic in QML/JavaScript and +hand-written C++ types exposed to QML, using the qmltc-created classes for +simple object instantiation. While generated C++ gives you direct (and usually +faster) access to QML-defined elements of the type, understanding such code +could be a challenge. + +\section2 Known Limitations + +Despite covering many common QML features, qmltc is still in the early stage of +development with some things yet to be supported. + +Imported QML modules that consist of QML-defined types (such as +\c{QtQuick.Controls}) might not get compiled correctly, even if those QML-defined +types were compiled by qmltc.. +At present, you can reliably use \c{QtQml} and \c{QtQuick} modules as well as any +other QML module that \b{only} contains C++ classes exposed to QML. + +On top of this, there are some more fundamental peculiarities to consider: + +\list + \li Qt's QML modules usually rely on C++ libraries to do the heavy lifting. + Often enough, these libraries do not provide public C++ API (since their + primary usage is through QML). For the users of qmltc, this means that their + apps need to link against private Qt libraries. + + \li Due to the nature of qmltc code generation, QML plugins are unusable for + compilation purposes. Instead, QML modules - that use a plugin - have to + ensure that the plugin data is accessible at compile time. Such QML modules + would then have \e optional plugins. In most cases, the compile-time + information can be provided through a header file (with C++ declarations) + and linkable library (with C++ definitions). The user code is responsible + (usually through CMake) for including a path to the header file and linking + against the QML module library. +\endlist + +\note +Given the tech preview status of the compiler, you might also encounter bugs in +qmltc, in the generated code, or some other related part. We encourage you to +\l{https://bugreports.qt.io/}{submit a bug report} in this case. + +*/ diff --git a/src/qml/doc/src/tools/qtquickcompiler/qtqml-tool-qmlcachegen.qdoc b/src/qml/doc/src/tools/qtquickcompiler/qtqml-tool-qmlcachegen.qdoc new file mode 100644 index 0000000000..b7f6d56705 --- /dev/null +++ b/src/qml/doc/src/tools/qtquickcompiler/qtqml-tool-qmlcachegen.qdoc @@ -0,0 +1,13 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-tool-qmlcachegen.html +\title qmlcachegen +\brief A tool to compile QML documents ahead of time +\ingroup qtqml-tooling + +\e qmlcachegen is an internal build tool, invoked by the build system +when using \l qt_add_qml_module in CMake or CONFIG+=qtquickcompiler in +qmake. Users should not invoke it manually. +*/ |