1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
|
/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** 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.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qtqml-documents-structure.html
\title Structure of a QML Document
\brief Description of the structure of QML documents
A QML document is a self contained piece of QML source code that consists of two parts:
\list
\li Its \e import statements
\li A single root object declaration
\endlist
By convention, a single empty line separates the imports from the object hierarchy definition.
QML documents are always encoded in UTF-8 format.
\section1 Imports
A document must import the necessary modules to enable the engine to load the QML object types referenced within the document. By default, a document can access any QML object types that have been defined through \c .qml files in the same directory; if a document needs to refer to any other object types, it must import the module that exports those types.
QML does \e not have a preprocessor that modifies the document prior to
presentation to the \l{QQmlEngine}{QML engine}, unlike C or C++.
The \c import statements do not copy and prepend the code in the document, but
instead instruct the QML engine on how to resolve type references found
in the document. Any type reference present in a QML document - such as \c
Rectangle and \c ListView - including those made within an \l {Inline
JavaScript}{JavaScript block} or \l {Property Binding}{property
bindings}, are \e resolved based exclusively on the import statements. At least
one \c import statement must be present such as \c{import QtQuick 2.0}.
Please see the \l{qtqml-syntax-imports.html}{QML Syntax - Import Statements}
documentation for in-depth information about QML imports.
\section1 The Root Object Declaration
A QML document describes a hierarchy of objects which can be instantiated.
Each object definition has a certain structure; it has a type, it can have an
id and an object name, it can have properties, it can have methods, it can have
signals and it can have signal handlers.
A QML file must only contain \b {a single root object definition}. The following is invalid and will generate an error:
\code
// MyQmlFile.qml
import QtQuick 2.0
Rectangle { width: 200; height: 200; color: "red" }
Rectangle { width: 200; height: 200; color: "blue" } // invalid!
\endcode
This is because a .qml file automatically defines a QML type, which encapsulates a \e single QML object definition. This is discussed further in \l{qtqml-documents-definetypes.html}{Documents as QML object type definitions}.
*/
|
