From 14cc3a81ec910a6ecc7ede3c0e51566c712bf819 Mon Sep 17 00:00:00 2001 From: Bea Lam Date: Thu, 20 May 2010 10:50:27 +1000 Subject: Create overview page for examples for Extending QML in C++ Task-number: QT-3365 QT-3366 --- doc/src/declarative/examples.qdoc | 2 +- doc/src/declarative/extending-examples.qdoc | 302 ---------------------------- doc/src/examples/qml-examples.qdoc | 27 ++- doc/src/examples/qml-extending.qdoc | 302 ++++++++++++++++++++++++++++ 4 files changed, 328 insertions(+), 305 deletions(-) delete mode 100644 doc/src/declarative/extending-examples.qdoc create mode 100644 doc/src/examples/qml-extending.qdoc diff --git a/doc/src/declarative/examples.qdoc b/doc/src/declarative/examples.qdoc index 5b8c937..72c585b 100644 --- a/doc/src/declarative/examples.qdoc +++ b/doc/src/declarative/examples.qdoc @@ -136,7 +136,7 @@ For example, from your build directory, run: \section2 C++ Extensions \list -\o \l{declarative/cppextensions/referenceexamples}{Reference examples} (discussed in \l {Extending QML in C++}) +\o \l{declarative-cppextensions-reference.html}{Reference examples} (discussed in \l {Extending QML in C++}) \o \l{declarative/cppextensions/plugins}{Plugins} \o \l{declarative/cppextensions/qgraphicslayouts}{QGraphicsLayouts} \o \l{declarative/cppextensions/qwidgets}{QWidgets} diff --git a/doc/src/declarative/extending-examples.qdoc b/doc/src/declarative/extending-examples.qdoc deleted file mode 100644 index 577ab78..0000000 --- a/doc/src/declarative/extending-examples.qdoc +++ /dev/null @@ -1,302 +0,0 @@ -/**************************************************************************** -** -** 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 member. - -In QML, the type of a list properties - and the guests property is a list of -people - are all of type QDeclarativeListProperty. 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/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/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 - -*/ 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 member. + +In QML, the type of a list properties - and the guests property is a list of +people - are all of type QDeclarativeListProperty. 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 + +*/ -- cgit v0.12