Doc

1 files changed, 258 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
+
+*/