diff options
Diffstat (limited to 'src/qml/doc/src/qmllanguageref/documents/structure.qdoc')
-rw-r--r-- | src/qml/doc/src/qmllanguageref/documents/structure.qdoc | 88 |
1 files changed, 88 insertions, 0 deletions
diff --git a/src/qml/doc/src/qmllanguageref/documents/structure.qdoc b/src/qml/doc/src/qmllanguageref/documents/structure.qdoc new file mode 100644 index 0000000000..c8176f7e0f --- /dev/null +++ b/src/qml/doc/src/qmllanguageref/documents/structure.qdoc @@ -0,0 +1,88 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html. +** $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 or type namespaces 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 type namespace into which those types have +been registered. + +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}. + +*/ |