-** 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

-

-\tableofcontents

-

-\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

-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.

-

-\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

-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

-exist. It must exist before any of these structures can be created. If the engine is removed,

-existing documents, contexts and objects are invalidated, but not destroyed. An invalid

-

-\list

-\i \e {QML document} can no longer be used to create QML objects.

-\i \e {QML context} can no longer host QML objects, new context properties cannot be added

-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

-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

-exclusively on the import statements present in the document.

-

-A simple QML document looks like this:

-

-\table

-\row

-\o

-\code

-import Qt 4.6

-

-Rectangle {

- id: myRect

- width: 100; height: 100

- color: background

-}

-\endcode

-\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

-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.

-

-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

-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

-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

-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

-document.

-

-\image qml-context-object.png

-

-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

-involved when resolving a variable name in a binding. The following pseudo code describes the

-algorithm used:

-

-\table

-\row

-\o

-\code

-if (scopeObject.hasProperty(name))

- return scopeObject.property(name)

-

-foreach (context in contextChain) {

- if (context.hasContextProperty(name)

- return context.contextProperty(name)

-

- if (context.defaultObject.hasProperty(name))

- return context.defaultObject.property(name)

-}

-\endcode

-\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

-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

-\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

-property that sets both the width and the height.

-

-\table

-\row

-\o

-\code

-import Qt 4.6

-Image {

- property int 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

-\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

-different property bindings.

-

-\image qml-context.png

-

-\section1 Syntax

-

-\section2 Encoding

-

-QML files are always encoded in UTF-8 format.

-

-\section2 Commenting

-

-The commenting rules in QML are the same as for ECMAScript. Both \e {MultiLineComment} blocks and \e {SingleLineComment}'s are supported.

-

-\section2 QML Document

-

-\section3 Syntax

-

-\e {QMLDocument} \bold {:}

-

-\quotation

-\e {QMLImportList} \sub {opt} \e {QMLObjectDefinition}

-\endquotation

-

-\e {QMLImportList} \bold {:}

-\quotation

-\e {QMLImportStatement} \e {QMLImportList} \sub {opt}

-\endquotation

-

-\e {QMLImportStatement} \bold {:}

-

-\quotation

-\bold {import} \e {StringLiteral}

-

-\bold {import} \e {StringLiteral} \e {QMLVersionNumber}

-

-\bold {import} \e {QMLNamespaceName} \e {QMLVersionNumber}

-

-\bold {import} \e {StringLiteral} \bold {as} \e {QMLNamespacePrefix}

-

-\bold {import} \e {StringLiteral} \e {QMLVersionNumber} \bold {as} \e {QMLNamespacePrefix}

-

-\bold {import} \e {QMLNamespaceName} \e {QMLVersionNumber} \bold {as} \e {QMLNamespacePrefix}

-\endquotation

-

-\e {QMLNamespaceName} \bold {:}

-\quotation

-\e {QMLQualifiedId}

-\endquotation

-

-\e {QMLVersionNumber} \bold {:}

-\quotation

-\e {DecimalLiteral} \bold {but not} with \e {ExponentPart}

-\endquotation

-

-\section3 Semantics

-

-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.

-

-\section2 Object Definition

-

-\section3 Syntax

-

-\e {QMLObjectDefinition} \bold {:}

-\quotation

-\e {QMLQualifiedId} \bold {\{} \e {QMLObjectMemberList} \bold {\}}

-\endquotation

-

-\e {QMLObjectMemberList} \bold {:}

-\quotation

-\e {QMLObjectMember} \e {QMLObjectMemberList} \sub {opt}

-\endquotation

-

-\e {QMLObjectMember} \bold {:}

-\quotation

-\e {QMLMemberAssignment}

-

-\e {QMLObjectDefinition}

-

-\e {QMLObjectExtensionDefinition}

-\endquotation

-

-\e {QMLMemberAssignmentList} \bold {:}

-\quotation

-\e {QMLMemberAssignment} \e {QMLMemberAssignmentList} \sub {opt}

-\endquotation

-

-\e {QMLMemberAssignment} \bold {:}

-\quotation

-

-\e {QMLQualifiedId} \bold {:} \e {Literal} \bold {but not} \e {NullLiteral}

-

-\e {QMLQualifiedId} \bold {:} \e {QMLObjectDefinition}

-

-\e {QMLQualifiedId} \bold {:} \e {QMLObjectDefinitionArray}

-

-\e {QMLQualifiedId} \bold {:} \e {QMLBindingExpression}

-

-\e {QMLQualifiedId} \bold {\{} \e {QMLMemberAssignmentList} \bold {\}}

-

-\endquotation

-

-\section3 Semantics

-

-\section2 Object Extension

-

-\section3 Syntax

-

-\e {QMLObjectExtensionDefinition} \bold {:}

-\quotation

-\e {QMLObjectPropertyDefinition}

-

-\e {QMLObjectSignalDefinition}

-

-\e {QMLObjectMethodDefinition}

-\endquotation

-

-\e {QMLObjectPropertyDefinition} \bold {:}

-\quotation

-\bold {property} \e {QmlObjectPropertyType} \e {QMLMemberIdentifier}

-

-\bold {default} \bold {property} \e {QmlObjectPropertyType} \e {QMLMemberIdentifier}

-

-\bold {property} \e {QmlObjectPropertyType} \e {QMLMemberIdentifier} \bold {:} \e {Literal} \bold {but not} \e {NullLiteral}

-

-\bold {property} \e {QmlObjectPropertyType} \e {QMLMemberIdentifier} \bold {:} \e {QmlBindingExpression}

-

-\bold {default} \bold {property} \e {QmlObjectPropertyType} \e {QMLMemberIdentifier} \bold {:} \e {Literal} \bold {but not} \e {NullLiteral}

-

-\bold {default} \bold {property} \e {QmlObjectPropertyType} \e {QMLMemberIdentifier} \bold {:} \e {QmlBindingExpression}

-\endquotation

-

-\e {QMLObjectPropertyType} \bold {:: one of}

-\quotation

-\bold {int} \bold {bool} \bold {double} \bold {real} \bold {string} \bold {url} \bold {color} \bold {date} \bold {var} \bold {variant} \bold {alias}

-\endquotation

-

-\e {QMLObjectSignalDefinition} \bold {:}

-\quotation

-\bold {signal} \e {QMLMemberIdentifier}

-

-\bold {signal} \e {QMLMemberIdentifier} \bold {(} QMLMemberTypedParameterList \bold {)}

-\endquotation

-

-\e {QMLObjectMethodDefinition} \bold {:}

-\quotation

-\e {FunctionDeclaration} \bold {but not} \e {Identifier} \sub {opt}

-\endquotation

-\section3 Semantics

-

-\section2 Binding Expression

-

-\section3 Syntax

-

-\e {QMLBindingExpression} \bold {:}

-

-\section3 Semantics

-

-*/