From 2b469742848c6cb26daab9d5c72e512473dede2b Mon Sep 17 00:00:00 2001 From: Aaron Kennedy Date: Wed, 21 Oct 2009 12:37:19 +1000 Subject: Doc --- doc/src/declarative/qmlformat.qdoc | 350 --------------------------------- doc/src/declarative/qtdeclarative.qdoc | 11 +- 2 files changed, 3 insertions(+), 358 deletions(-) delete mode 100644 doc/src/declarative/qmlformat.qdoc diff --git a/doc/src/declarative/qmlformat.qdoc b/doc/src/declarative/qmlformat.qdoc deleted file mode 100644 index 72bbe40..0000000 --- a/doc/src/declarative/qmlformat.qdoc +++ /dev/null @@ -1,350 +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 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 - -*/ diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc index ebf7880..e01b02d 100644 --- a/doc/src/declarative/qtdeclarative.qdoc +++ b/doc/src/declarative/qtdeclarative.qdoc @@ -93,20 +93,15 @@ completely new applications. QML is fully \l {Extending QML}{extensible from C+ \o \l {Extending types from QML} \endlist -\section1 QML Reference: +\section1 Reference: \list -\o \l {QML Format Reference} \o \l {QML Elements} -\endlist - -\section1 C++ Reference: -\list \o \l {Extending QML} -\o \l {qtbinding}{QML/C++ Data Binding} \endlist \section1 Deprecated - +\list \o \l {tutorials-declarative-contacts.html}{Tutorial: 'Introduction to QML'} +\endlist */ -- cgit v0.12