Create overview page for examples for Extending QML in C++

Task-number: QT-3365 QT-3366

2 files changed, 327 insertions, 2 deletions

diff --git a/doc/src/examples/qml-examples.qdoc b/doc/src/examples/qml-examples.qdoc
index 7a0fcca..fa17c6a 100644
--- a/doc/src/examples/qml-examples.qdoc
+++ b/doc/src/examples/qml-examples.qdoc
@@ -71,8 +71,31 @@
 */
 
 /*!
-    \title Reference examples
-    \example declarative/cppextensions/referenceexamples
+    \page declarative-cppextensions-reference.html
+    \title C++ Extensions - Reference examples
+
+    These examples show how QML can be extended from C++ in various ways. 
+    
+    The code for these examples is used throughout the \l {Extending QML in C++} reference
+    documentation, which highlights the main principles demonstrated in each example.
+
+    Furthermore, here are additional pages that discuss each example in detail:
+
+    \list
+    \o \l {declarative/cppextensions/referenceexamples/adding}{Adding Types}
+    \o \l {declarative/cppextensions/referenceexamples/properties}{Object and List Property Types}
+    \o \l {declarative/cppextensions/referenceexamples/coercion}{Inheritance and Coercion}
+    \o \l {declarative/cppextensions/referenceexamples/default}{Default Property}
+    \o \l {declarative/cppextensions/referenceexamples/grouped}{Grouped Properties}
+    \o \l {declarative/cppextensions/referenceexamples/attached}{Attached Properties}
+    \o \l {declarative/cppextensions/referenceexamples/signal}{Signal Support}
+    \o \l {declarative/cppextensions/referenceexamples/valuesource}{Property Value Source}
+    \o \l {declarative/cppextensions/referenceexamples/binding}{Binding}
+    \endlist
+
+    \note These examples all print information to the console to demonstrate the concepts presented.
+    Ensure that you are able to view the application output when running these examples.
+    For example, the dbgView tool on Windows can be used to display application output.
 */
 
 /*!
diff --git a/doc/src/examples/qml-extending.qdoc b/doc/src/examples/qml-extending.qdoc
new file mode 100644
index 0000000..09108d6
--- /dev/null
+++ b/doc/src/examples/qml-extending.qdoc
@@ -0,0 +1,302 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (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 Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\example declarative/cppextensions/referenceexamples/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/cppextensions/referenceexamples/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/cppextensions/referenceexamples/adding/person.h 0
+
+\section1 Define the Person class
+
+\snippet examples/declarative/cppextensions/referenceexamples/adding/person.cpp 0
+
+The Person class implementation is quite basic.  The property accessors simply
+return members of the object instance.
+
+The \c main.cpp file also calls the \c qmlRegisterType() function to
+register the \c Person type with QML as a type in the People library version 1.0,
+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/cppextensions/referenceexamples/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/cppextensions/referenceexamples/properties/example.qml 0
+
+\section1 Declare the BirthdayParty
+
+The BirthdayParty class is declared like this:
+
+\snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 0
+\snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 1
+\snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 2
+\snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 3
+
+The class contains a member to store the celebrant object, and also a 
+QList<Person *> member.  
+
+In QML, the type of a list properties - and the guests property is a list of 
+people - are all of type QDeclarativeListProperty<T>.  QDeclarativeListProperty is simple value
+type that contains a set of function pointers.  QML calls these function 
+pointers whenever it needs to read from, write to or otherwise interact with
+the list.  In addition to concrete lists like the people list used in this
+example, the use of QDeclarativeListProperty allows for "virtual lists" and other advanced
+scenarios.
+
+\section2 Define the BirthdayParty
+
+The implementation of BirthdayParty property accessors is straight forward.
+
+\snippet examples/declarative/cppextensions/referenceexamples/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/cppextensions/referenceexamples/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/cppextensions/referenceexamples/coercion/example.qml 0
+
+\section1 Declare Boy and Girl
+
+\snippet examples/declarative/cppextensions/referenceexamples/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/cppextensions/referenceexamples/coercion/main.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.
+
+\section2 Define Boy and Girl
+
+The implementation of Boy and Girl are trivial.
+
+\snippet examples/declarative/cppextensions/referenceexamples/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/cppextensions/referenceexamples/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/cppextensions/referenceexamples/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/cppextensions/referenceexamples/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/cppextensions/referenceexamples/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/cppextensions/referenceexamples/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/cppextensions/referenceexamples/attached
+\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
+
+*/
+
+/*!
+\example declarative/cppextensions/referenceexamples/signal
+\title Extending QML - Signal Support Example
+
+This example builds on:
+\list
+\o \l {Extending QML - Attached Properties Example}
+\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
+
+*/
+
+/*!
+\example declarative/cppextensions/referenceexamples/valuesource
+\title Extending QML - Property Value Source Example
+
+This example builds on:
+\list
+\o \l {Extending QML - Signal Support Example}
+\o \l {Extending QML - Attached Properties Example}
+\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
+
+*/
+
+/*!
+\example declarative/cppextensions/referenceexamples/binding
+\title Extending QML - Binding Example
+
+This example builds on:
+\list
+\o \l {Extending QML - Property Value Source Example}
+\o \l {Extending QML - Signal Support Example}
+\o \l {Extending QML - Attached Properties Example}
+\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
+
+*/