Doc: Move example docs related to QtQml under the correct module

This change moves 'Extending QML' qdoc file and the tutorials
from examples/quick to examples/qml, which is the correct
location for them.

Change-Id: I24bd9dfa75baaab7bc8efe08489f09a7b65d98a6
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>
Reviewed-by: Sze Howe Koh <szehowe.koh@gmail.com>
Reviewed-by: Alan Alpert <aalpert@blackberry.com>

1 files changed, 322 insertions, 0 deletions

diff --git a/examples/qml/doc/src/qml-extending.qdoc b/examples/qml/doc/src/qml-extending.qdoc
new file mode 100644
index 0000000000..9823a29b65
--- /dev/null
+++ b/examples/qml/doc/src/qml-extending.qdoc
@@ -0,0 +1,322 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\example referenceexamples/adding
+\title Extending QML - Adding Types Example
+\brief Exporting C++ Classes
+\ingroup qmlextendingexamples
+
+The Adding Types Example shows how to add a new object type, \c Person, to QML.
+The \c Person type can be used from QML like this:
+
+\snippet referenceexamples/adding/example.qml 0
+
+\section1 Declare the Person class
+
+All QML types 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
+type, the C++ class can be named differently, or appear in a namespace.
+
+\snippet referenceexamples/adding/person.h 0
+
+\section1 Define the Person class
+
+\snippet 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 referenceexamples/properties
+\title Extending QML - Object and List Property Types Example
+\brief Exporting C++ Properties
+\ingroup qmlextendingexamples
+
+This example builds on:
+\list
+\li \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 type 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 referenceexamples/properties/example.qml 0
+
+\section1 Declare the BirthdayParty
+
+The BirthdayParty class is declared like this:
+
+\snippet referenceexamples/properties/birthdayparty.h 0
+\snippet referenceexamples/properties/birthdayparty.h 1
+\snippet referenceexamples/properties/birthdayparty.h 2
+\snippet 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 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 referenceexamples/coercion
+\title Extending QML - Inheritance and Coercion Example
+\brief C++ Inheritance and Coercion
+\ingroup qmlextendingexamples
+
+This example builds on:
+\list
+\li \l {Extending QML - Object and List Property Types Example}
+\li \l {Extending QML - Adding Types Example}
+\endlist
+
+The Inheritance and Coercion Example shows how to use base classes to assign
+types of more than one type to a property.  It specializes the Person type
+developed in the previous examples into two types - a \c Boy and a \c Girl.
+
+\snippet referenceexamples/coercion/example.qml 0
+
+\section1 Declare Boy and Girl
+
+\snippet 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
+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 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 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 type has not changed since the previous example.  The
+celebrant and guests property still use the People type.
+
+\snippet 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 referenceexamples/default
+\title Extending QML - Default Property Example
+\brief Default Property
+\ingroup qmlextendingexamples
+
+This example builds on:
+\list
+\li \l {Extending QML - Inheritance and Coercion Example}
+\li \l {Extending QML - Object and List Property Types Example}
+\li \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 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 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 type 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 referenceexamples/grouped
+\title Extending QML - Grouped Properties Example
+\brief Grouped Properties
+\ingroup qmlextendingexamples
+
+This example builds on:
+\list
+\li \l {Extending QML - Default Property Example}
+\li \l {Extending QML - Inheritance and Coercion Example}
+\li \l {Extending QML - Object and List Property Types Example}
+\li \l {Extending QML - Adding Types Example}
+\endlist
+
+*/
+
+/*!
+\example referenceexamples/attached
+\title Extending QML - Attached Properties Example
+\brief Attached Properties
+\ingroup qmlextendingexamples
+
+This example builds on:
+\list
+\li \l {Extending QML - Grouped Properties Example}
+\li \l {Extending QML - Default Property Example}
+\li \l {Extending QML - Inheritance and Coercion Example}
+\li \l {Extending QML - Object and List Property Types Example}
+\li \l {Extending QML - Adding Types Example}
+\endlist
+
+*/
+
+/*!
+\example referenceexamples/signal
+\title Extending QML - Signal Support Example
+\brief Signal Support
+\ingroup qmlextendingexamples
+
+This example builds on:
+\list
+\li \l {Extending QML - Attached Properties Example}
+\li \l {Extending QML - Grouped Properties Example}
+\li \l {Extending QML - Default Property Example}
+\li \l {Extending QML - Inheritance and Coercion Example}
+\li \l {Extending QML - Object and List Property Types Example}
+\li \l {Extending QML - Adding Types Example}
+\endlist
+
+*/
+
+/*!
+\example referenceexamples/methods
+\title Extending QML - Methods Example
+\brief Methods Support
+\ingroup qmlextendingexamples
+
+This example builds on:
+\list
+\li \l {Extending QML - Default Property Example}
+\li \l {Extending QML - Inheritance and Coercion Example}
+\li \l {Extending QML - Object and List Property Types Example}
+\li \l {Extending QML - Adding Types Example}
+\endlist
+
+*/
+
+/*!
+\example referenceexamples/valuesource
+\title Extending QML - Property Value Source Example
+\brief Property Value Source
+\ingroup qmlextendingexamples
+
+This example builds on:
+\list
+\li \l {Extending QML - Signal Support Example}
+\li \l {Extending QML - Attached Properties Example}
+\li \l {Extending QML - Grouped Properties Example}
+\li \l {Extending QML - Default Property Example}
+\li \l {Extending QML - Inheritance and Coercion Example}
+\li \l {Extending QML - Object and List Property Types Example}
+\li \l {Extending QML - Adding Types Example}
+\endlist
+
+*/
+
+/*!
+\example referenceexamples/binding
+\title Extending QML - Binding Example
+\brief Binding
+\ingroup qmlextendingexamples
+
+This example builds on:
+\list
+\li \l {Extending QML - Property Value Source Example}
+\li \l {Extending QML - Signal Support Example}
+\li \l {Extending QML - Attached Properties Example}
+\li \l {Extending QML - Grouped Properties Example}
+\li \l {Extending QML - Default Property Example}
+\li \l {Extending QML - Inheritance and Coercion Example}
+\li \l {Extending QML - Object and List Property Types Example}
+\li \l {Extending QML - Adding Types Example}
+\endlist
+
+*/