diff options
Diffstat (limited to 'doc/src/declarative/qmlformat.qdoc')
| -rw-r--r-- | doc/src/declarative/qmlformat.qdoc | 117 |
1 files changed, 79 insertions, 38 deletions
diff --git a/doc/src/declarative/qmlformat.qdoc b/doc/src/declarative/qmlformat.qdoc index f16adca..be1afa4 100644 --- a/doc/src/declarative/qmlformat.qdoc +++ b/doc/src/declarative/qmlformat.qdoc @@ -1,3 +1,44 @@ +/**************************************************************************** +** +** 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 qmlformat.html \title QML Format Reference @@ -7,20 +48,20 @@ \section1 Overview QML is an extension to \l {http://www.ecma-international.org/publications/standards/Ecma-262.htm} -{ECMAScript}. QML adds a mechanism for declaratively building a tree of objects, improved -integration between ECMAScript and Qt's existing QObject based type system, and support for -transparently maintained property value bindings between ECMAScript expressions and QObject +{ECMAScript}. QML adds a mechanism for declaratively building a tree of objects, improved +integration between ECMAScript and Qt's existing QObject based type system, and support for +transparently maintained property value bindings between ECMAScript expressions and QObject properties. Much of a QML file consists of valid ECMAScript \e {Statement}s. Except where constraints imposed by ECMAScript, C++ or QObject prevented it, the syntactic extensions introduced by QML are designed -to look similar and fit well with existing ECMAScript syntax and concepts. +to look similar and fit well with existing ECMAScript syntax and concepts. \section1 QML engine -The \l {QmlEngine}{QML engine} executes a \l {QmlComponent}{QML document} in a -\l {QmlContext}{QML context} to produce a \l {QObject}{QML object}. A single QML -document may be executed in one or many contexts to produce many QML objects. A single +The \l {QmlEngine}{QML engine} executes a \l {QmlComponent}{QML document} in a +\l {QmlContext}{QML context} to produce a \l {QObject}{QML object}. A single QML +document may be executed in one or many contexts to produce many QML objects. A single QML document may be executed many times in the same context to produce many QML objects. The QML engine provides the environment in which QML documents, contexts and objects @@ -34,10 +75,10 @@ and existing context properties cannot be modified. \i \e {QML object} will no longer evaluate bindings or scripts. \endlist -A QML document is a block of QML source code. QML documents generally correspond to files stored +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 \bold {not} have a preprocessor that modifies the document -before presentation to the compiler. Type references within a QML document are resolved based +document is self contained; QML does \bold {not} have a preprocessor that modifies the document +before presentation to the compiler. Type references within a QML document are resolved based exclusively on the import statements present in the document. A simple QML document looks like this: @@ -49,7 +90,7 @@ A simple QML document looks like this: import Qt 4.6 Rectangle { - id: MyRect + id: myRect width: 100; height: 100 color: background } @@ -57,40 +98,40 @@ Rectangle { \endtable To instantiate a QML object, a QML document is executed in a QML context. QML contexts are used by -programmers to pass data to a QML document. QML documents may include property bindings or -ECMAScript blocks that can contain variable references that need to be resolved. Each property +programmers to pass data to a QML document. QML documents may include property bindings or +ECMAScript blocks that can contain variable references that need to be resolved. Each property binding and ECMAScript block has an associated QML context that is used to resolve these references that is determined by the QML context in which the document is executed. The example document above -contains one variable reference, \c background. +contains one variable reference, \c background. Each QML context defines a scope for variable resolution and each may define local, named context -properties. A QML context may also have a \l {QmlContext::addDefaultObject()}{default object}, -which is an object whose properties are searched \e after the context properties when resolving a -variable name. QML contexts form a tree, starting from a root context that is provided by the QML +properties. A QML context may also have a \l {QmlContext::addDefaultObject()}{default object}, +which is an object whose properties are searched \e after the context properties when resolving a +variable name. QML contexts form a tree, starting from a root context that is provided by the QML engine. When resolving variable references, the QML contexts are searched starting from the QML objects containing context upwards towards the root context. -Consider the following QML context tree. If the example QML document is executed in \c Context1, -the \c background variable will resolve to \c Context1's context property. If the document is -executed in \c Context2, the \c background variable will resolve to the root context's context +Consider the following QML context tree. If the example QML document is executed in \c Context1, +the \c background variable will resolve to \c Context1's context property. If the document is +executed in \c Context2, the \c background variable will resolve to the root context's context property. \image qml-context-tree.png While QML contexts can be created explicitly by the programmer to pass data into QML objects, the QML engine also creates a new implicit QML context for every object it instantiates. -Property bindings and ECMAScript blocks in the document are associated with this QML engine -created context. Object ids that are defined in the document are added as context properties, and +Property bindings and ECMAScript blocks in the document are associated with this QML engine +created context. Object ids that are defined in the document are added as context properties, and their value is set to reference the appropriate object, and the instantiated QML object is set as -the context's default object. The following diagram shows the result of executing a simple QML +the context's default object. The following diagram shows the result of executing a simple QML document. \image qml-context-object.png -The blue rectangle in the diagram represents a property binding. Associated with each property +The blue rectangle in the diagram represents a property binding. Associated with each property binding is the QML context to which it belongs, the object property to which it is bound and a -\e {scope object}. The scope object is usually, but not always, the object to which the bound -property belongs. The context properties, context default objects and the scope object are all +\e {scope object}. The scope object is usually, but not always, the object to which the bound +property belongs. The context properties, context default objects and the scope object are all involved when resolving a variable name in a binding. The following pseudo code describes the algorithm used: @@ -112,14 +153,14 @@ foreach (context in contextChain) { \endtable QML supports two categories of types: \e builtin types and \e composite types. Builtin types are -those written in C++ and registered with the QML engine. Builtin types form the most basic -building blocks of QML. Composite types are constructed by composing other builtin or composite -types, property bindings and ECMAScript blocks together into a brand new type using the QML +those written in C++ and registered with the QML engine. Builtin types form the most basic +building blocks of QML. Composite types are constructed by composing other builtin or composite +types, property bindings and ECMAScript blocks together into a brand new type using the QML language. Using a composite type is identical to using a builtin type. -For example, Qt 4.6 includes a builtin type called \c Image that shows a bitmap image. The +For example, Qt 4.6 includes a builtin type called \c Image that shows a bitmap image. The \c Image type has \c width and \c height properties that control the size of the displayed image. -A simple composite type, that will be called \c SquareImage can be built that adds a \c size +A simple composite type, that will be called \c SquareImage can be built that adds a \c size property that sets both the width and the height. \table @@ -129,22 +170,22 @@ property that sets both the width and the height. import Qt 4.6 Image { property int size - width: size - height: size + width: size + height: size } \endcode \endtable To the QML engine, a composite type is just another QML document. When a composite type is used the engine instantiates it just as it would any other document - by creating a new implicit -QML context and the object tree described by the document. The diagram below shows the +QML context and the object tree described by the document. The diagram below shows the \c SquareImage composite type used from within another QML document. When instantiated, the \c SquareImage object is created in its own QML context. Any property bindings specified in the \c SquareImage composite type document are associated with this context. Property bindings created in the outer document, however, are associated with its context, even those that are applied to the created \c SquareImage object. That is, the \c size, \c source, \c width and \c height property bindings all share a common \e {scope object}, but are owned by two different QML contexts. The -difference in containing context results in the \c Root variable resolving differently in the +difference in containing context results in the \c Root variable resolving differently in the different property bindings. \image qml-context.png @@ -173,7 +214,7 @@ The commenting rules in QML are the same as for ECMAScript. Both \e {MultiLineC \e {QMLImportStatement} \bold {:} \quotation -\bold {import} \e {StringLiteral} +\bold {import} \e {StringLiteral} \bold {import} \e {StringLiteral} \e {QMLVersionNumber} @@ -198,8 +239,8 @@ The commenting rules in QML are the same as for ECMAScript. Both \e {MultiLineC \section3 Semantics -The \e {QMLImportList} is used to statically resolve type references used within the enclosing -QML document. +The \e {QMLImportList} is used to statically resolve type references used within the enclosing +QML document. An import statement is used to bring a set of types into scope for a QML document. |