From ad5ae0d751e42a9ca6def5d98b2db740f195c16f Mon Sep 17 00:00:00 2001 From: Topi Reinio Date: Mon, 29 Apr 2013 15:01:32 +0200 Subject: 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 Reviewed-by: Sze Howe Koh Reviewed-by: Alan Alpert --- examples/qml/doc/src/qml-extending.qdoc | 322 ++++++++++++++++++++++++++++++++ 1 file changed, 322 insertions(+) create mode 100644 examples/qml/doc/src/qml-extending.qdoc (limited to 'examples/qml/doc/src/qml-extending.qdoc') 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 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 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 + +*/ -- cgit v1.2.3