path: root/doc/src/declarative/extending-examples.qdoc

/****************************************************************************
**
** 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/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 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/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

*/

/*!
\example declarative/extending/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/extending/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/extending/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

*/