topic.qdoc

Go to the documentation of this file.

// Copyright (C) 2017 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page qtqml-cppclasses-topic.html
\title Important C++ Classes Provided By The Qt Qml Module
\brief Overview of the C++ classes provided by the Qt Qml module.
 
The \l{Qt Qml} module provides C++ classes which implement the QML framework.
Clients can use these classes to interact with the QML run-time (for example,
by injecting data or invoking methods on objects), and to instantiate a
hierarchy of objects from a QML document.  The Qt Qml module provides more
C++ API than just the classes listed here, however the classes listed here
provide the foundations of the QML runtime and the core concepts of QML.
 
\section1 QML Runtime
 
A typical QML application with a C++ entry-point will instantiate a QQmlEngine
and then use a QQmlComponent to load a QML document.  The engine provides a
default QQmlContext which will be the top-level evaluation context used for
evaluating functions and expressions defined in the QML document.
The object hierarchy defined in the QML document will be instantiated by
calling the \l{QQmlComponent::create()}{create()} function of the QQmlComponent
instance, assuming that no errors were encountered during document loading.
 
The client may wish to modify the QQmlContext provided by the engine, by
injecting properties or objects into the context.  They can call the
\l{QQmlEngine::rootContext()} function to access the top-level context.
 
After instantiating the object, the client will usually pass control to the
application event loop so that user input events (like mouse-clicks) can be
delivered and handled by the application.
 
\note The Qt Quick module provides a convenience class, QQuickView, which
provides a QML runtime and visual window for displaying a QML application.
 
\section2 The QQmlEngine Class
 
The QQmlEngine class provides an engine which can manage a hierarchy of objects
which is defined in a QML document.  It provides a root QML context within
which expressions are evaluated, and ensures that properties of objects are
updated correctly when required.
 
A QQmlEngine allows the configuration of global settings that apply to all of
the objects it manages; for example, the QNetworkAccessManager to be used for
network communications, and the file path to be used for persistent storage.
 
See the \l{QQmlEngine} class documentation for in-depth information about what
the QQmlEngine class provides, and how it can be used in an application.
 
\section2 The QQmlContext Class
 
The QQmlContext class provides a context for object instantiation and
expression evaluation.  All objects are instantiated in a particular context,
and all of the expressions which are evaluated while an application is running
are evaluated within a particular context.  This context defines how symbols
are resolved, and thus which values the expression operates on.
 
See the \l{QQmlContext} class documentation for in-depth information about
how to modify the evaluation context of an object by adding or removing
properties of a QQmlContext, and how to access the context for an object.
 
\section1 Dynamic Object Instantiation and Expression Evaluation
 
Dynamic object instantiation and dynamic expression evaluation are both core
concepts in QML.  QML documents define object types which can be instantiated
at run-time using a QQmlComponent.  An instance of the QQmlComponent class can
be created in C++ directly, or via the \l{QtQml::Qt::createComponent()}
{Qt.createComponent()} function in imperative QML code.  Arbitrary expressions
can be calculated in C++ via the QQmlExpression class, and such expressions
can interact directly with the QML context.
 
\section2 The QQmlComponent Class
 
The QQmlComponent class can be used to load a QML document.  It requires a
QQmlEngine in order to instantiate the hierarchy of objects defined in the QML
document.
 
See the \l{QQmlComponent} class documentation for in-depth information about
how to use QQmlComponent.
 
\section2 The QQmlExpression Class
 
The QQmlExpression class provides a way for clients to evaluate JavaScript
expressions from C++, using a particular QML evaluation context.  This allows
clients to access QML objects by id, for example.  The result of the evaluation
is returned as a QVariant, and the conversion rules are defined by the QML
engine.
 
See the \l{QQmlExpression} class documentation for in depth information about
how to use QQmlExpression in an application.
 
\section1 Usage of the Classes within QML Applications
 
These pages describe how to create QML applications which interact with the
C++ classes:
 
\list
\li \l{Overview - QML and C++ Integration}
    \list
    \li \l{qtqml-cppintegration-exposecppattributes.html}{Exposing Attributes of C++ Classes to QML}
    \li \l{qtqml-cppintegration-definetypes.html}{Defining QML Types from C++}
    \li \l{qtqml-cppintegration-contextproperties.html}{Embedding C++ Objects into QML with Context Properties}
    \li \l{qtqml-cppintegration-interactqmlfromcpp.html}{Interacting with QML Objects from C++}
    \li \l{qtqml-cppintegration-data.html}{Data Type Conversion Between QML and C++}
    \endlist
\endlist
 
*/