source: trunk/doc/src/examples/qml-extending.qdoc@ 846

/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** GNU Free Documentation License
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $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