diff options
Diffstat (limited to 'src/qml/doc/src/qmldocument.qdoc')
-rw-r--r-- | src/qml/doc/src/qmldocument.qdoc | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/src/qml/doc/src/qmldocument.qdoc b/src/qml/doc/src/qmldocument.qdoc new file mode 100644 index 0000000000..89a5bbd57b --- /dev/null +++ b/src/qml/doc/src/qmldocument.qdoc @@ -0,0 +1,151 @@ +/**************************************************************************** +** +** 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 qml-documents.html +\title QML Documents +\brief a description of QML documents and the kind of content they contain + +A QML document is a block of QML source code. QML documents generally correspond to files +stored on a disk or at a location on a network, but they can also be constructed directly +from text data. + +Here is a simple QML document: + +\snippet doc/snippets/qml/qml-documents/non-trivial.qml document + +QML documents are always encoded in UTF-8 format. + +A QML document always begins with one or more import statements. To prevent elements +introduced in later versions from affecting existing QML programs, the element types +available within a document are controlled by the imported QML \l {Modules} with +a corresponding \e version. + +QML does \e not have a preprocessor that modifies the document prior to +presentation to the \l{The QML Engine}{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 in QML}{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}. + +Each \c id value in a QML document must be unique within that document. They do +not need to be unique across different documents as id values are resolved +according to the document scope. + +\section1 Documents as Component Definitions + +A QML document defines a single, top-level \l {QML Components}{QML component}. A +QML component is a template that is interpreted by the QML engine to +create an object with some predefined behaviour. As it is a template, a single +QML component can be "run" multiple times to produce several objects, each of +which are said to be \e instances of the component. + +Once created, instances are not dependent on the component that created them, so +they can operate on independent data. Here is an example of a simple "Button" +component (defined in a \c Button.qml file) that is instantiated four times by +\c application.qml. Each instance is created with a different value for its \c +text property: + +\table +\row +\li Button.qml +\li application.qml + +\row +\li \snippet doc/snippets/qml/qml-documents/qmldocuments.qml document +\li +\qml +import QtQuick 2.0 + +Column { + spacing: 10 + + Button { text: "Apple" } + Button { text: "Orange" } + Button { text: "Pear" } + Button { text: "Grape" } +} +\endqml + +\image anatomy-component.png + +\endtable + +Any snippet of QML code can become a component, just by placing it in the file +"<Name>.qml" where <Name> is the component name, and begins with an \b +uppercase letter. Note that the case of all characters in the <Name> are +significant on some filesystems, notably UNIX filesystems. It is recommended +that the case of the filename matches the case of the component name in QML +exactly, regardless of the platform the QML will be deployed to. These QML +component files automatically become available as new QML element types to other +QML components and applications in the same directory. + +The \l{QML Components} article details the creation of components and how to +load them in other components. + +\section1 Inline Components + +In addition to the top-level component that all QML documents define, and any +reusable components placed in separate files, documents may also include \e +inline components. Inline components are declared using the \l Component +element, as can be seen in the first example above. Inline components share all +the characteristics of regular top-level components and use the same \c import +list as their containing QML document. Components are one of the most basic +building blocks in QML, and are frequently used as "factories" by other +elements. For example, the \l ListView element uses the \c delegate component as +the template for instantiating list items - each list item is just a new +instance of the component with the item specific data set appropriately. + +Like other \l {QML Elements}, the \l Component element is an object and must be +assigned to a property. \l Component objects may also have an object id. In the +first example on this page, the inline component is added to the \l Rectangle's +\c resources list, and then \l {Property Binding} is used to assign the \l +Component to the \l ListView's \c delegate property. The QML language even +contains a syntactic optimization when assigning directly to a component +property for this case where it will automatically insert the \l Component tag. +This means that by enclosing components in a \c Component element, we can +assign an id to the component and use the component elsewhere + +These final two examples perform identically to the original document. + +\table +\row +\li +\snippet doc/snippets/qml/qml-documents/inline-component.qml document +\li +\snippet doc/snippets/qml/qml-documents/inline-text-component.qml document +\endtable + + +For information about components, the \l{QML Components} article details the +creation of components and how to load them in other components. + +\sa QQmlComponent +*/ |