diff options
Diffstat (limited to 'src/qml/doc/src/qtqml.qdoc')
| -rw-r--r-- | src/qml/doc/src/qtqml.qdoc | 182 |
1 files changed, 53 insertions, 129 deletions
diff --git a/src/qml/doc/src/qtqml.qdoc b/src/qml/doc/src/qtqml.qdoc index e1ff693195..51a638bf4d 100644 --- a/src/qml/doc/src/qtqml.qdoc +++ b/src/qml/doc/src/qtqml.qdoc @@ -1,148 +1,92 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-index.html -\title Qt QML -\brief The Qt QML module defines and implements the QML language +\title Qt Qml +\brief The Qt Qml module implements the QML language and offers APIs to register + types for it. -The Qt QML module provides a framework for developing applications and libraries -with the \l{QML Applications}{QML language}. It defines and implements the +The Qt Qml module provides a framework for developing applications and libraries +with the \l{The QML Reference}{QML language}. It defines and implements the language and engine infrastructure, and provides an API to enable application -developers to extend the QML language with custom types and integrate QML code -with JavaScript and C++. The Qt QML module provides both a \l{Qt QML QML Types} -{QML API} and a \l{Qt QML C++ Classes}{C++ API}. - -Note that while the Qt QML module provides the language and infrastructure -for QML applications, the \l{Qt Quick} module provides many visual components, -model-view support, an animation framework, and much more for building user -interfaces. - -For those new to QML and Qt Quick, please see -\l{QML Applications} -for an introduction to writing QML applications. +developers to \l{Registering QML Types and QML Modules}{register} custom QML types +and modules and integrate QML code with JavaScript and C++. The Qt Qml module +provides both a \l{Qt QML QML Types}{QML API} and a +\l{Qt Qml C++ Classes}{C++ API}. \section1 Using the Module \section2 QML API -The QML types in Qt QML are available through the \c QtQml import. To use the -types, add the following import statement to your .qml file: +\include {module-use.qdocinc} {using the qml api} {QtQml} + +The Qt QML module contains the QML framework and important QML types used in +applications. The constructs of QML are described in the \l{The QML Reference}. -\qml -import QtQml -\endqml +The \l{Qt QML QML Types}{QML API} of the Qt QML module provides a number of +\l{qtqml-typesystem-objecttypes.html}{QML Object Types}, +\l{qtqml-typesystem-valuetypes.html}{QML Value Types} and namespaces. \section2 C++ API -Using the \l{Qt QML C++ Classes}{C++ API} requires linking against the module library, -either directly or through other dependencies. -Several build tools have dedicated support for this, including CMake and qmake. +\include {module-use.qdocinc} {using the c++ api} + +The C++ API contains some +\l{Important C++ Classes Provided By The Qt QML Module}{important classes} +you should get familiar with. It also provides +\l{Integrating with JavaScript values from C++}{types} to hold JavaScript +values. \section3 Building with CMake -Use the \c find_package() command to locate the needed module components in the Qt6 package: +\include {module-use.qdocinc} {building with cmake} {Qml} -\snippet code/doc_src_qtqml.cmake 0 +To provide foreign QML type support for a non-QML library, locate +the \c QmlIntegration module as follows: -See also the \l{Build with CMake} overview. +\snippet code/doc_src_qtqml.cmake 1 -\section3 Building with qmake +See \l{qt6_generate_foreign_qml_types} for details. -To configure the module for building with qmake, add the module as a value of the QT variable in the project's .pro file: +\section3 Building with qmake -\badcode -QT += qml -\endcode +\include {module-use.qdocinc} {building_with_qmake} {qml} -\section1 QML and QML Types +\section1 Registering QML Types and QML Modules -The Qt QML module contains the QML framework and important QML types used in -applications. The constructs of QML are described in the \l{The QML Reference}. +In order to register types for usage with QML you first need to define a +\l{Writing QML Modules}{QML module}, preferably using \l{qt_add_qml_module} in CMake. +Then, you can add C++ headers to your new module, and +\l{Defining QML Types from C++}{define types} to be +\l{Exposing Attributes of C++ Types to QML}{exposed to QML} in them. -In addition to the \l{QML Basic Types}, the module comes with -the following QML object types: -\list -\li \l Component -\li \l QtObject -\li \l Binding -\li \l Connections -\li \l Timer -\endlist +\section1 Tweaking the engine -The \l{QtQml::Qt}{Qt} global object provides useful enums and functions -for various QML types. +There are a number of knobs you can turn to customize the behavior of the QML engine. +The page on \l{Configuring the JavaScript Engine}{configuring the JavaScript engine} +lists the environment variables you may use to this effect. The description of the +\l{The QML Disk Cache}{QML Disk Cache} describes the options related to how your QML +components are compiled and loaded. -\section2 Lists and Models +\section1 Articles and Guides -New in Qt 5.1, the model types are moved to a submodule, \c QtQml.Models. The -\l{Qt QML Models QML Types}{Qt QML Models} page has more information. +These articles contain information about Qt Qml. \list -\li \l DelegateModel -\li \l DelegateModelGroup -\li \l ListElement -\li \l ListModel -\li \l ObjectModel + \li \l{The QML Reference} + \li \l{Qt Qml Tooling} + \li \l{Writing QML Modules} + \li \l{Singletons in QML} \endlist -\section1 JavaScript Environment for QML Applications - -JavaScript expressions allow QML code to contain application logic. Qt QML -provides the framework for running JavaScript expressions in QML and from C++. - -These sections are from \l{The QML Reference}. - \list - \li \l{qtqml-javascript-topic.html}{Integrating QML and JavaScript} - \li \l{qtqml-javascript-expressions.html}{Using JavaScript Expressions with QML} - \li \l{qtqml-javascript-dynamicobjectcreation.html}{Dynamic QML Object Creation from JavaScript} - \li \l{qtqml-javascript-resources.html}{Defining JavaScript Resources In QML} - \li \l{qtqml-javascript-imports.html}{Importing JavaScript Resources In QML} - \li \l{qtqml-javascript-hostenvironment.html}{JavaScript Host Environment} - \endlist - -\section1 Integrating QML with C++ Applications - -The module also provides the framework for running QML applications. -The QML framework allows QML code to contain JavaScript expressions and for -the QML code to interact with C++ code. +\section1 Reference \list -\li \l{Important C++ Classes Provided By The Qt QML Module} -\li \l{Integrating QML and C++} + \li \l {Qt QML C++ Classes} {C++ Classes} + \li \l {Qt QML QML Types} {QML Types} \endlist -\omit - \section1 Additional Frameworks - \list - \li \l{The Declarative State Machine Framework} - \endlist -\endomit - \section1 Licenses and Attributions Qt QML is available under commercial licenses from \l{The Qt Company}. @@ -157,24 +101,4 @@ modules under following permissive licenses: \generatelist{groupsbymodule attributions-qtqml} -\section1 Guides and Other Information - -Further information for writing QML applications: -\list -\li \l{The QML Reference} -\li \l{QML Applications} - - essential information for application development with QML and Qt Quick -\li \l{Qt Quick} - a module which provides a set of QML types and C++ classes - for building user interfaces and applications with QML -\li \l{The QML Disk Cache} - - how to fine tune if and where the QML engine caches compilation results. -\endlist - -\section2 Reference -\list -\li \l{Qt QML C++ Classes}{C++ Classes} -\li \l{Qt QML QML Types}{QML Types} -\li \l{Qt QML Examples}{Examples} -\endlist - */ |