diff options
Diffstat (limited to 'doc/src/declarative/qdeclarativedocument.qdoc')
| -rw-r--r-- | doc/src/declarative/qdeclarativedocument.qdoc | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/doc/src/declarative/qdeclarativedocument.qdoc b/doc/src/declarative/qdeclarativedocument.qdoc new file mode 100644 index 0000000..a210c98 --- /dev/null +++ b/doc/src/declarative/qdeclarativedocument.qdoc @@ -0,0 +1,190 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qdeclarativedocuments.html +\title QML Documents + +A QML document is a block of QML source code. QML documents generally correspond to files +stored on a disk or network resource, but can also be constructed directly from text data. + +Here is a simple QML document: + +\code +import Qt 4.6 + +Rectangle { + width: 240; height: 320; + + resources: [ + Component { + id: contactDelegate + Text { + text: modelData.firstName + " " + modelData.lastName + } + } + ] + + ListView { + anchors.fill: parent + model: contactModel + delegate: contactDelegate + } +} +\endcode + +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}. That is, +QML is a \e versioned language. + +Syntactically a QML document is self contained; QML does \e not have a preprocessor that +modifies the document prior to presentation to the QML runtime. \c import statements +do not "include" code in the document, but instead instruct the QML runtime 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 {JavaScript Block} or \l {Property Binding}s, are \e resolved based exclusively on the +import statements. QML does not import any modules by default, so at least one \c import +statement must be present or no elements will be available! + +A QML document defines a single, top-level \l {QDeclarativeComponent}{QML component}. A QML component +is a template that is interpreted by the QML runtime 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 that is +instantiated four times, each with a different value for its \c text property. + +\table +\row +\o +\raw HTML +<table><tr><td> +\endraw +\code +import Qt 4.6 + +BorderImage { + property alias text: textElement.text + width: 100; height: 30; source: "images/toolbutton.sci" + + Text { + id: textElement + anchors.centerIn: parent + font.pointSize: 20 + style: Text.Raised + color: "white" + } +} +\endcode +\raw HTML +</td> <td> +\endraw +\image anatomy-component.png +\raw HTML +</td> </tr> </table> +\endraw +\endtable + +In addition to the top-level component that all QML documents define, documents may also +include additional \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. While using property binding allows the \l Component object to be shared (for example, +if the QML document contained multiple \l ListView's with the same delegate), in this case the +\l Component could have been assigned directly to the \l ListView's \c delegate. 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. + +These final two examples are behaviorally identical to the original document. + +\table +\row +\o +\code +import Qt 4.6 + +Rectangle { + width: 240; height: 320; + + ListView { + anchors.fill: parent + model: contactModel + delegate: Component { + Text { + text: modelData.firstName + " " + modelData.lastName + } + } + } +} +\endcode +\o +\code +import Qt 4.6 + +Rectangle { + width: 240; height: 320; + + ListView { + anchors.fill: parent + model: contactModel + delegate: Text { + text: modelData.firstName + " " + modelData.lastName + } + } +} +\endcode +\endtable + +\sa QDeclarativeComponent +*/ |