Doc

4 files changed, 639 insertions, 0 deletions

diff --git a/doc/src/declarative/extending-examples.qdoc b/doc/src/declarative/extending-examples.qdoc
new file mode 100644
index 0000000..09239c1
--- /dev/null
+++ b/doc/src/declarative/extending-examples.qdoc
@@ -0,0 +1,258 @@
+/****************************************************************************
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+\example declarative/extending/adding
+\title Extending QML - Adding Types Example
+
+The Adding Types Example shows how to add a new element type, \c Person, to QML.
+The \c Person type can be used from QML like this:
+
+\snippet examples/declarative/extending/adding/example.qml 0
+
+\section1 Declare the Person class
+
+All QML elements map to C++ types.  Here we declare a basic C++ Person class 
+with the two properties we want accessible on the QML type - name and shoeSize.
+Although in this example we use the same name for the C++ class as the QML 
+element, the C++ class can be named differently, or appear in a namespace.
+
+\snippet examples/declarative/extending/adding/person.h 0
+
+Following the class declaration, we include the QML_DECLARE_TYPE() macro.  This
+is necessary to declare the type to QML.  It also includes the logic necessary
+to expose the class to Qt's meta system - that is, it includes the 
+Q_DECLARE_METATYPE() functionality.
+
+\section1 Define the Person class
+
+\snippet examples/declarative/extending/adding/person.cpp 0
+
+The Person class implementation is quite basic.  The property accessors simply
+return members of the object instance.
+
+The implementation must also include the QML_DEFINE_TYPE() macro.  This macro
+registers the Person class with QML, and defines the mapping between the C++
+and QML class names.
+
+\section1 Running the example
+
+The main.cpp file in the example includes a simple shell application that 
+loads and runs the QML snippet shown at the beginning of this page.  
+*/
+
+/*!
+\example declarative/extending/properties
+\title Extending QML - Object and List Property Types Example
+
+This example builds on:
+\list
+\o \l {Extending QML - Adding Types Example}
+\endlist
+
+The Object and List Property Types example shows how to add object and list
+properties in QML.  This example adds a BirthdayParty element that specifies
+a birthday party, consisting of a celebrant and a list of guests.  People are
+specified using the People QML type built in the previous example.
+
+\snippet examples/declarative/extending/properties/example.qml 0
+
+\section1 Declare the BirthdayParty
+
+The BirthdayParty class is declared like this:
+
+\snippet examples/declarative/extending/properties/birthdayparty.h 0
+\snippet examples/declarative/extending/properties/birthdayparty.h 1
+\snippet examples/declarative/extending/properties/birthdayparty.h 2
+\snippet examples/declarative/extending/properties/birthdayparty.h 3
+
+The class contains a member to store the celebrant object, and also a 
+QmlConcreteList<Person *> member.  
+
+In QML, the type of a list properties - and the guests property is a list of 
+people - are all of type QmlList<T *>*.  QmlList is an abstract list interface
+that allows a developer to react to QML accessing and modifying the contents of
+the list.  This is useful for implementing "virtual lists" or other advanced
+scenarios, but can't be used directly for the common case of just wanting a
+regular list of things.  For this a concrete implementation, QmlConcreteList, is
+provided and that is used here.
+
+\section2 Define the BirthdayParty
+
+The implementation of BirthdayParty property accessors is straight forward.
+
+\snippet examples/declarative/extending/properties/birthdayparty.cpp 0
+
+\section1 Running the example
+
+The main.cpp file in the example includes a simple shell application that 
+loads and runs the QML snippet shown at the beginning of this page.  
+*/
+
+/*!
+\example declarative/extending/coercion
+\title Extending QML - Inheritance and Coercion Example
+
+This example builds on:
+\list
+\o \l {Extending QML - Object and List Property Types Example}
+\o \l {Extending QML - Adding Types Example}
+\endlist
+
+The Inheritance and Coercion Example shows how to use base classes to assign
+elements of more than one type to a property.  It specializes the Person element
+developed in the previous examples into two elements - a \c Boy and a \c Girl.
+
+\snippet examples/declarative/extending/coercion/example.qml 0
+
+\section1 Declare Boy and Girl
+
+\snippet examples/declarative/extending/coercion/person.h 0
+
+The Person class remains unaltered in this example and the Boy and Girl C++ 
+classes are trivial extensions of it.  As an example, the inheritance used here
+is a little contrived, but in real applications it is likely that the two
+extensions would add additional properties or modify the Person classes 
+behavior.
+
+\section2 Define People as a base class
+
+The implementation of the People class itself has not changed since the the 
+previous example.  However, as we have repurposed the People class as a common
+base for Boy and Girl, we want to prevent it from being instantiated from QML
+directly - an explicit Boy or Girl should be instantiated instead.
+
+\snippet examples/declarative/extending/coercion/person.cpp 0
+
+While we want to disallow instantiating Person from within QML, it still needs
+to be registered with the QML engine, so that it can be used as a property type
+and other types can be coerced to it.  To register a type, without defining a
+named mapping into QML, we use the QML_DEFINE_NOCREATE_TYPE() macro instead of
+the QML_DEFINE_TYPE() macro used previously.
+
+\section2 Define Boy and Girl
+
+The implementation of Boy and Girl are trivial.
+
+\snippet examples/declarative/extending/coercion/person.cpp 1
+
+All that is necessary is to implement the constructor, and to register the types
+and their QML name with the QML engine.
+
+\section1 Running the example
+
+The BirthdayParty element has not changed since the previous example.  The 
+celebrant and guests property still use the People type.  
+
+\snippet examples/declarative/extending/coercion/birthdayparty.h 0
+
+However, as all three types, Person, Boy and Girl, have been registered with the
+QML system, on assignment QML automatically (and type-safely) converts the Boy
+and Girl objects into a Person.
+
+The main.cpp file in the example includes a simple shell application that 
+loads and runs the QML snippet shown at the beginning of this page.  
+*/
+
+/*!
+\example declarative/extending/default
+\title Extending QML - Default Property Example
+
+This example builds on:
+\list
+\o \l {Extending QML - Inheritance and Coercion Example}
+\o \l {Extending QML - Object and List Property Types Example}
+\o \l {Extending QML - Adding Types Example}
+\endlist
+
+The Default Property Example is a minor modification of the 
+\l {Extending QML - Inheritance and Coercion Example} that simplifies the 
+specification of a BirthdayParty through the use of a default property.
+
+\snippet examples/declarative/extending/default/example.qml 0
+
+\section1 Declaring the BirthdayParty class
+
+The only difference between this example and the last, is the addition of the
+\c DefaultProperty class info annotation.  
+
+\snippet examples/declarative/extending/default/birthdayparty.h 0
+
+The default property specifies the property to assign to whenever an explicit 
+property is not specified, in the case of the BirthdayParty element the guest
+property.  It is purely a syntactic simplification, the behavior is identical 
+to specifying the property by name, but it can add a more natural feel in many
+situations.  The default property must be either an object or list property.
+
+\section1 Running the example
+
+The main.cpp file in the example includes a simple shell application that 
+loads and runs the QML snippet shown at the beginning of this page.  
+*/
+
+/*!
+\example declarative/extending/grouped
+\title Extending QML - Grouped Properties Example
+
+This example builds on:
+\list
+\o \l {Extending QML - Default Property Example}
+\o \l {Extending QML - Inheritance and Coercion Example}
+\o \l {Extending QML - Object and List Property Types Example}
+\o \l {Extending QML - Adding Types Example}
+\endlist
+
+*/
+
+/*!
+\example declarative/extending/grouped
+\title Extending QML - Attached Properties Example
+
+This example builds on:
+\list
+\o \l {Extending QML - Grouped Properties Example}
+\o \l {Extending QML - Default Property Example}
+\o \l {Extending QML - Inheritance and Coercion Example}
+\o \l {Extending QML - Object and List Property Types Example}
+\o \l {Extending QML - Adding Types Example}
+\endlist
+
+*/
diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc
index 7163a93..138ccb2 100644
--- a/doc/src/declarative/extending.qdoc
+++ b/doc/src/declarative/extending.qdoc
@@ -1,3 +1,376 @@
+/****************************************************************************
+**
+** 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 qml-extending.html
+\title Extending QML
+
+The QML syntax declaratively describes how to construct an in memory object 
+tree.  In Qt, QML is mainly used to describe a visual scene graph, but it is 
+not conceptually limited to this: the QML format is an abstract description of
+any object tree.  All the QML element types included in Qt are implemented using
+the C++ extension mechanisms describe on this page.  Programmers can use these
+APIs to add new types that interact with the existing Qt types, or to repurpose
+QML for their own independent use.
+
+\tableofcontents
+
+\section1 Adding Types
+
+\snippet examples/declarative/extending/adding/example.qml 0
+
+The QML snippet shown above instantiates one \c Person instance and sets 
+the name and shoeSize properties on it.  Everything in QML ultimately comes down
+to either instantiating an object instance, or assigning a property a value.  
+QML relies heavily on Qt's meta object system and can only instantiate classes
+that derive from QObject.
+
+The QML engine has no intrinsic knowledge of any class types.  Instead the 
+programmer must define the C++ types, and their corresponding QML name.  
+
+Custom C++ types are made available to QML using these two macros:
+
+\quotation
+\code
+#define QML_DECLARE_TYPE(T)
+#define QML_DEFINE_TYPE(T,QmlName)
+\endcode
+
+Register the C++ type \a T with the QML system, and make it available in QML
+under the name \a QmlName.  \a T and \a QmlName may be the same.
+
+Generally the QML_DECLARE_TYPE() macro should be included immediately following
+the type declaration (usually in its header file), and the QML_DEFINE_TYPE() 
+macro in the implementation file.  QML_DEFINE_TYPE() must not be present in
+a header file.
+
+Type \a T must be a concrete type that inherits QObject and has a default 
+constructor.
+\endquotation
+
+Once registered, all of the \l {Qt's Property System}{properties} of a supported
+type are available for use within QML.  QML has intrinsic support for properties
+of these types:
+
+\list
+\o bool
+\o unsigned int, int
+\o float, double, qreal
+\o QString
+\o QUrl
+\o QColor
+\o QDate, QTime, QDateTime
+\o QPoint, QPointF
+\o QSize, QSizeF
+\o QRect, QRectF
+\o QVariant
+\endlist
+
+QML is typesafe.  Attempting to assign an invalid value to a property will
+generate an error.  For example, assuming the name property of the \c Person 
+element had a type of QString, this would cause an error:
+
+\code
+Person {
+    // Will NOT work
+    name: 12
+}
+\endcode
+
+\l {Extending QML - Adding Types Example} shows the complete code used to create
+the \c Person type.
+
+\section1 Object and List Property Types
+
+\snippet examples/declarative/extending/properties/example.qml 0
+
+The QML snippet shown above assigns a \c Person object to the \c BirthdayParty's
+celebrant property, and assigns three \c Person objects to the guests property.
+
+QML can set properties of types that are more complex than basic intrinsics like
+integers and strings.  Properties can also be object pointers, Qt interface 
+pointers,  lists of object points, and lists of Qt interface pointers.  As QML 
+is typesafe it ensures that only valid types are assigned to these properties, 
+just like it does for primitive types.
+
+Properties that are pointers to objects or Qt interfaces are declared with the
+Q_PROPERTY() macro, just like other properties.  The celebrant property 
+declaration looks like this:
+
+\snippet examples/declarative/extending/properties/birthdayparty.h 1
+
+As long as the property type, in this case Person, is registered with QML the
+property can be assigned.
+
+QML also supports assigning Qt interfaces.  To assign to a property whose type
+is a Qt interface pointer, the interface must also be registered with QML.  As
+they cannot be instantiated directly, registering a Qt interface is different 
+from registering a new QML type.  The following macros are used instead:
+
+\quotation
+\code
+    #define QML_DECLARE_INTERFACE(T)
+    #define QML_DEFINE_INTERFACE(T)
+\endcode
+
+Register the C++ interface \a T with the QML system.
+
+Generally the QML_DECLARE_INTERFACE() macro should be included immediately 
+following the interface declaration (usually in its header file), and the 
+QML_DEFINE_INTERFACE() macro in an implementation file.  QML_DEFINE_INTERFACE()
+must not be present in a header file.
+
+Following registration, QML can coerce objects that implement this interface
+for assignment to appropriately typed properties.
+\endquotation
+
+The guests property is a list of \c Person objects.  Properties that are lists 
+of objects or Qt interfaces are also declared with the Q_PROPERTY() macro, just
+like other properties.  List properties must have the type \c {QmlList<T *>*}.
+As with object properties, the type \a T must be registered with QML.
+
+The guest property declaration looks like this:
+
+\snippet examples/declarative/extending/properties/birthdayparty.h 2
+
+\l {Extending QML - Object and List Property Types Example} shows the complete 
+code used to create the \c BirthdayParty type.
+
+\section1 Inheritance and Coercion
+
+\snippet examples/declarative/extending/coercion/example.qml 0
+
+The QML snippet shown above assigns a \c Boy object to the \c BirthdayParty's
+celebrant property, and assigns three other objects to the guests property.
+
+QML supports C++ inheritance heirarchies and can freely coerce between known, 
+valid object types.  This enables the creation of common base classes that allow
+the assignment of specialized classes to object or list properties.  In the
+snippet shown, both the celebrant and the guests properties retain the Person
+type used in the previous section, but the assignment is valid as both the Boy 
+and Girl objects inherit from Person.
+
+To assign to a property, the property's type must have been registered with QML.
+Both the QML_DEFINE_TYPE() and QML_DEFINE_INTERFACE() macros already shown can
+be used to register a type with QML.  Additionally, if a type that acts purely
+as a base class that cannot be instantiated from QML needs to be 
+registered these macros can be used:
+
+\quotation
+\code
+    #define QML_DECLARE_TYPE(T)
+    #define QML_DEFINE_NOCREATE_TYPE(T)
+\endcode
+
+Register the C++ type \a T with the QML system. QML_DEFINE_NOCREATE_TYPE() 
+differs from QML_DEFINE_TYPE() in that it does not define a mapping between the
+C++ class and a QML element name, so the type is not instantiable from QML, but
+it is available for type coercion.
+
+Generally the QML_DECLARE_TYPE() macro should be included immediately following
+the type declaration (usually in its header file), and the 
+QML_DEFINE_NOCREATE_TYPE() macro in the implementation file.  
+QML_DEFINE_NOCREATE_TYPE() must not be present in a header file.
+
+Type \a T must inherit QObject, but there are no restrictions on whether it is
+concrete or the signature of its constructor.
+\endquotation
+
+QML will automatically coerce C++ types when assigning to either an object
+property, or to a list property.  Only if coercion fails does an assignment 
+error occur.
+
+\l {Extending QML - Inheritance and Coercion Example} shows the complete 
+code used to create the \c Boy and \c Girl types.
+
+\section1 Default Property
+
+\snippet examples/declarative/extending/default/example.qml 0
+
+The QML snippet shown above assigns a collection of objects to the 
+\c BirthdayParty's default property.
+
+The default property is a syntactic convenience that allows a type designer to
+specify a single property as the type's default.  The default property is 
+assigned to whenever no explicit property is specified.  As a convenience, it is
+behaviorally identical to assigning the default property explicitly by name.
+
+From C++, type designers mark the default property using a Q_CLASSINFO() 
+annotation:
+
+\quotation
+\code
+Q_CLASSINFO("DefaultProperty", "property")
+\endcode
+
+Mark \a property as the class's default property.  \a property must be either
+an object property, or a list property.
+
+A default property is optional.  A derived class inherits its base class's 
+default property, but may override it in its own declaration.  \a property can
+refer to a property declared in the class itself, or a property inherited from a
+base class.
+\endquotation
+
+\l {Extending QML - Default Property Example} shows the complete code used to
+specify a default property.
+
+\section1 Grouped Properties
+
+\snippet examples/declarative/extending/grouped/example.qml 1
+
+The QML snippet shown above assigns a number properties to the \c Boy object,
+including four properties using the grouped property syntax.
+
+Grouped properties collect similar properties together into a single named 
+block.  Grouped properties can be used to present a nicer API to developers, and
+may also simplify the implementation of common property collections across 
+different types through implementation reuse.
+
+A grouped property block is implemented as a read-only object property.  The
+shoe property shown is declared like this:
+
+\snippet examples/declarative/extending/grouped/person.h 1
+
+The ShoeDescription type declares the properties available to the grouped 
+property block - in this case the size, color, brand and price properties.
+
+Grouped property blocks may declared and accessed be recusively. 
+
+\l {Extending QML - Grouped Properties Example} shows the complete code used to 
+implement the \c shoe property grouping.
+
+\section1 Attached Properties
+
+\snippet examples/declarative/extending/attached/example.qml 1
+
+The QML snippet shown above assigns the rsvp property using the attached 
+property syntax.
+
+Attached properties allow unrelated types to annotate other types with some
+additional properties, generally for their own use.  Attached properties are 
+identified through the use of the attacher type name, in the case shown 
+\c BirthdayParty, as a suffix to the property name.  
+
+In the example shown, \c BirthdayParty is called the attaching type, and the
+Box instance the attachee object instance.  
+
+For the attaching type, an attached property block is implemented as a new
+QObject derived type, called the attachment object.  The properties on the
+attachment object are those that become available for use as the attached 
+property block.
+
+Any QML type can become an attaching type by declaring the 
+\c qmlAttachedProperties() public function:
+
+\quotation
+\code
+static AttachedPropertiesType *qmlAttachedProperties(QObject *object)
+\endcode
+Return an attachment object, of type \a AttachedPropertiesType, for the
+attachee \a object instance.  It is customary, though not strictly required, for
+the attachment object to be parented to \a object to prevent memory leaks.
+
+\a AttachedPropertiesType must be a QObject derived type.  The properties on 
+this type will be accessible through the attached properties syntax.
+
+This method will be called at most once for each attachee object instance.  The
+QML engine will cache the returned instance pointer for subsequent attached 
+property accesses.  Consequently the attachment object may not be deleted until
+\a object is destroyed.
+\endquotation
+
+Conceptually, attached properties are a \e type exporting a set of additional 
+properties that can be set on \e any other object instance.  Attached properties
+cannot be limited to only attaching to a sub-set of object instances, although
+their effect may be so limited.
+
+For example, a common usage scenario is for a type to enhance the properties 
+available to its children in order to gather instance specific data.  Here we
+add a rsvp field to all the guests coming to a birthday party:
+\code
+BirthdayParty {
+    Boy { BirthdayParty.rsvp: "2009-06-01" }
+}
+\endcode
+However, as a type cannot limit the instances to which the attachment object 
+must attach, the following is also allowed, even though adding a birthday party
+rsvp in this context will have no effect.
+\code
+GraduationParty {
+    Boy { BirthdayParty.rsvp: "2009-06-01" }
+}
+\endcode
+
+From C++, including the attaching type implementation, the attachment object for
+an instance can be accessed using the following method:
+
+\quotation
+\code
+template<typename T>
+QObject *qmlAttachedPropertiesObject<T>(QObject *attachee, bool create = true);
+\endcode
+Returns the attachment object attached to \a attachee by the attaching type 
+\a T.  If type \a T is not a valid attaching type, this method always returns 0.
+
+If \a create is true, a valid attachment object will always be returned, 
+creating it if it does not already exist.  If \a create is false, the attachment
+object will only be returned if it has previously been created.
+\endquotation
+
+\l {Extending QML - Attached Properties Example} shows the complete code used to
+implement the rsvp attached property.
+
+\section1 Property Binding
+
+\section1 Signal support
+
+\section1 Extension Objects
+
+\section1 Parser Status
+
+\section1 Property Value Sources
+*/
+
+
 /*!
 \page qml-extending-types.html
 \title Extending types from QML
diff --git a/doc/src/declarative/qmlformat.qdoc b/doc/src/declarative/qmlformat.qdoc
new file mode 100644
index 0000000..fd22ab5
--- /dev/null
+++ b/doc/src/declarative/qmlformat.qdoc
@@ -0,0 +1,6 @@
+/*!
+    \page qmlformat.html
+    \title QML Format
+
+    Format reference here...
+*/
diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc
index c945b24..c5d32fe 100644
--- a/doc/src/declarative/qtdeclarative.qdoc
+++ b/doc/src/declarative/qtdeclarative.qdoc
@@ -81,11 +81,13 @@
 
     QML Reference:
     \list
+    \o \l {QML Format}
     \o \l {elements}{Qml Elements}
     \endlist
 
     C++ Reference:
     \list
+    \o \l {Extending QML}
     \o \l {qtbinding}{C++ Data Binding}
     \o \l {cppitem}{C++ Components}
     \endlist