From 3fd624b77669fb503d2762926c3153596cfb284b Mon Sep 17 00:00:00 2001 From: Aaron Kennedy Date: Tue, 13 Oct 2009 11:42:07 +1000 Subject: Doc --- .../flickr/mobile/images/toolbutton.png | Bin 2619 -> 2550 bytes doc/src/declarative/anatomy.qdoc | 74 -------- doc/src/declarative/pics/anatomy-component.png | Bin 0 -> 16117 bytes doc/src/declarative/qmldocument.qdoc | 188 +++++++++++++++++++++ doc/src/declarative/qtdeclarative.qdoc | 2 +- 5 files changed, 189 insertions(+), 75 deletions(-) delete mode 100644 doc/src/declarative/anatomy.qdoc create mode 100644 doc/src/declarative/pics/anatomy-component.png create mode 100644 doc/src/declarative/qmldocument.qdoc diff --git a/demos/declarative/flickr/mobile/images/toolbutton.png b/demos/declarative/flickr/mobile/images/toolbutton.png index 8862898..1131001 100644 Binary files a/demos/declarative/flickr/mobile/images/toolbutton.png and b/demos/declarative/flickr/mobile/images/toolbutton.png differ diff --git a/doc/src/declarative/anatomy.qdoc b/doc/src/declarative/anatomy.qdoc deleted file mode 100644 index f816464..0000000 --- a/doc/src/declarative/anatomy.qdoc +++ /dev/null @@ -1,74 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Qt Software Information (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 either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** 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.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at qt-sales@nokia.com. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qmldocumentanatomy.html -\title Anatomy of a QML Document - -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 be constructed directly from text data. - -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. Type references made within -a QML document, including within a \l {ECMAScript Block} contained by the document, are -resolved based exclusively on the import statements present in the document. - -A simple QML document looks like this: - -\code -import Qt 4.6 - -Rectangle { - Component { - id: contactDelegate - Text { - text: modelData.firstName + " " + modelData.lastName - } - } - - ListView { - model: contactModel - delegate: contactDelegate - } -} -\endcode - -*/ diff --git a/doc/src/declarative/pics/anatomy-component.png b/doc/src/declarative/pics/anatomy-component.png new file mode 100644 index 0000000..70ed983 Binary files /dev/null and b/doc/src/declarative/pics/anatomy-component.png differ diff --git a/doc/src/declarative/qmldocument.qdoc b/doc/src/declarative/qmldocument.qdoc new file mode 100644 index 0000000..84e7926 --- /dev/null +++ b/doc/src/declarative/qmldocument.qdoc @@ -0,0 +1,188 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (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 either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** 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.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qmldocuments.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 be constructed directly from text data. + +A simple QML document looks like this: + +\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 + +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 {ECMAScript 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 {QmlComponent}{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 +
+\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 + +\endraw +\image anatomy-component.png +\raw HTML +
+\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 QmlComponent +*/ diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc index 56f3252..bd50034 100644 --- a/doc/src/declarative/qtdeclarative.qdoc +++ b/doc/src/declarative/qtdeclarative.qdoc @@ -81,7 +81,7 @@ completely new applications. QML is fully \l {Extending QML}{extensible from C+ \section1 Core QML Features: \list -\o \l {Anatomy of a QML Document} +\o \l {QML Documents} \o \l {Property Binding} \o \l {ECMAScript Blocks} \o \l {Network Transparency} -- cgit v0.12