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-documents-topic.html
\title QML Documents
\brief Description of QML documents
 
A QML document is a string which conforms to QML document syntax.  A document
defines a QML object type.  A document is generally loaded from a \c ".qml"
file stored either locally or remotely, but can be constructed manually in
code.  An instance of the object type defined by a document may be created
using a \l Component in QML code, or a \l QQmlComponent in C++.
Alternatively, if the object type is explicitly exposed to the QML type system
with a particular type name, the type may be used directly in object
declarations in other documents.
 
The ability to define re-usable QML object types in documents is an important
enabler to allow clients to write modular, highly readable and maintainable
code.
 
Since Qt 5.4, a document can also have the file extension \c ".ui.qml". The QML
engine handles these files like standard .qml files and ignores the \c .ui part
of the extension. Qt Design Studio handles those files as
\l{Qt Design Studio: UI Files}{UI files}. The files can contain only a subset
of the QML language features.
 
\section1 Structure of a QML Document
 
A QML document consists of two sections: the imports section, and the object
declaration section.  The imports section in a document contains import
statements that define which QML object types and JavaScript resources the
document is able to use.  The object declaration section defines the object
tree to be created when instantiating the object type defined by the document.
 
An example of a simple document is as follows:
 
\qml
import QtQuick 2.0
 
Rectangle {
    width: 300
    height: 200
    color: "blue"
}
\endqml
 
See the \l {qtqml-documents-structure.html}{Structure of a QML Document}
for more information on the topic.
 
\section2 Syntax of the QML Language
 
The object declaration section of the document must specify a valid object
hierarchy with appropriate \l {qtqml-syntax-basics.html}{QML syntax}.  An
object declaration may include the specification of custom
\l{qtqml-syntax-objectattributes.html}{object attributes}.  Object method
attributes may be specified as JavaScript functions, and object property
attributes may be assigned \l{qtqml-syntax-propertybinding.html}
{property binding expressions}.
 
Please see the documentation about the \l{qtqml-syntax-basics.html}
{syntax of QML} for more information about valid syntax, and see the
documentation about \l{qtqml-javascript-topic.html}
{integrating QML and JavaScript} for in-depth information on that topic.
 
\section1 Defining Object Types Through QML Documents
 
As described briefly in the previous section, a document implicitly defines
a QML object type.  One of the core principles of QML is the ability to define
and then re-use object types.  This improves the maintainability of QML code,
increases the readability of object hierarchy declarations, and promotes
separation between UI definition and logic implementation.
 
In the following example, the client developer defines a \c Button type with
a document in a file:
 
\snippet ../quick/doc/snippets/qml/qml-extending-types/components/Button.qml 0
 
The \c Button type can then be used in an application:
 
\table
\row
\li \snippet ../quick/doc/snippets/qml/qml-extending-types/components/application.qml 0
\li \image button-types.png
\endtable
 
Please see the documentation about \l{qtqml-documents-definetypes.html}
{defining object types in documents} for in-depth information on the
topic.
 
\section1 Resource Loading and Network Transparency
 
It is important to note that QML is network-transparent.  Applications can
import documents from remote paths just as simply as documents from local
paths.  In fact, any \c url property may be assigned a remote or local URL,
and the QML engine will handle any network communication involved.
 
Please see the \l{qtqml-documents-networktransparency.html}
{Network Transparency} documentation for more information about network
transparency in imports.
 
\section1 Scope and Naming Resolution
 
Expressions in documents usually involve objects or properties of objects,
and since multiple objects may be defined and since different objects may have
properties with the same name, some predefined symbol resolution semantics must
be defined by QML.  Please see the page on \l{qtqml-documents-scope.html}
{scope and symbol resolution} for in-depth information about the topic.
 
*/