Revise the restructured "Integrating QML and C++" docs

These docs were yet to be cleaned up following the recent doc
restructure. This changes most of the the content in these sections
and includes some new docs and examples.

Currently all the code snippets are included inline. In a later patch,
these should be moved into the snippets/ directories and be included
using the \snippet command instead. Alternatively they can be moved
into examples/ to replace the BirthdayParty examples which are no
longer referenced in these docs as of this patch.

Task-number: QTBUG-26381

Change-Id: I94e3654e61476fad11fe81042d1bbe94fc649d06
Reviewed-by: Chris Adams <christopher.adams@nokia.com>

1 files changed, 93 insertions, 56 deletions

diff --git a/src/qml/doc/src/cppintegration/topic.qdoc b/src/qml/doc/src/cppintegration/topic.qdoc
index 3b88c50099..49b1aa0e0c 100644
--- a/src/qml/doc/src/cppintegration/topic.qdoc
+++ b/src/qml/doc/src/cppintegration/topic.qdoc
@@ -1,4 +1,4 @@
-/****************************************************************************
+/****************************************************************************
 **
 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/
@@ -29,81 +29,118 @@
 \title Integrating QML and C++
 \brief Description of how to integrate QML and C++ code
 
-QML was designed to allow tight integration with C++ code.  This allows hybrid
-applications to be developed where the user-interface (and perhaps some small
-amount of application logic) is specified in QML documents with QML and
-JavaScript, but the bulk of the application logic is implemented in C++.
+QML is designed to be easily extensible through C++ code. The classes in the QtQml C++ module
+enables QML objects to be loaded and manipulated from C++, and the nature of QML engine's
+integration with Qt's \l{Meta Object System}{meta object system} enables C++ functionality to be
+invoked directly from QML. This allows the development of hybrid applications which are implemented
+with a mixture of QML, JavaScript and C++ code.
 
-Applications with a C++ entry-point can instantiate a QQmlEngine directly,
-can use the QML type registration functions, and access the properties of the
-root QQmlContext directly.  Applications which utilize a QML entry point (that
-is, they are loaded via \l{qtquick-qmlscene.html}{qmlscene} or some other tool)
-can provide \l{qtqml-modules-cppplugins.html}{C++ plugins} which can register
-types and provide functionality.
-
-You may want to mix QML and C++ for a number of reasons. For example:
+Integrating QML and C++ provides a variety of opportunities, including the ability to:
 
 \list
-\li To use functionality defined in a C++ source (for example, when using a C++ Qt-based data model, or
-calling functions in a third-party C++ library)
-\li To access functionality in the QtQml or QtQuick modules (for example, to dynamically generate
+\li Separate the user interface code from the application logic code, by implementing the former
+with QML and JavaScript within \l{qtqml-documents-topic.html}{QML documents}, and the latter with
+C++
+\li Use and invoke some C++ functionality from QML (for example, to invoke your application logic,
+use a data model implemented in C++, or call some functions in a third-party C++ library)
+\li Access functionality in the QtQml or QtQuick C++ API (for example, to dynamically generate
 images using QQuickImageProvider)
-\li To write your own QML object types (whether for your applications, or for distribution to others)
+\li Implement your own \l{qtqml-typesystem-objecttypes.html}{QML object types} from C++
+\unicode{0x2014} whether for use within your own specific application, or for distribution to others
 \endlist
 
-There are a number of ways to extend your QML application through C++. For example, you could:
+To provide some C++ data or functionality to QML, it must be made available from a QObject-derived
+class. Due to the QML engine's integration with the meta object system, the properties, methods and
+signals of any QObject-derived class are accessible from QML, as described in
+\l{qtqml-cppintegration-exposecppattributes.html}{Exposing Attributes of C++ Types to QML}. Once the
+required functionality is provided by such a class, it can be exposed to QML in a variety of ways:
 
 \list
-\li Load a QML component and manipulate it (or its children) from C++
-\li Embed a C++ object and its properties directly into a QML component (for example, to make a
-particular C++ object callable from QML, or to replace a dummy list model with a real data set)
-\li Define new QML object types (through QObject-based C++ classes) and create them directly from your
-QML code
+\li The class can be
+\l{qtqml-cppintegration-definetypes.html#registering-an-instantiable-object-type}{
+registered as an instantiable QML type}, so that it can be instantiated and used like any ordinary
+\l{qtqml-typesystem-objecttypes.html}{QML object type} from QML code
+\li The class can be registered as a
+\l{qtqml-cppintegration-definetypes.html#registering-singleton-objects-with-a-module-api}
+{Module API} so that a single instance of the class may be imported from QML code, allowing the
+instance's properties, methods and signals to be accessed from QML
+\li An instance of the class can be \l{qtqml-cppintegration-contextproperties.html}{embedded into
+QML code} as a \e {context property} or \e {context object}, allowing the instance's properties,
+methods and signals to be accessed from QML
 \endlist
 
+These are the most common methods of accessing C++ functionality from QML code; for more options and
+details, see the main documentation pages that are described in the sections further below.
+Additionally, aside from the ability to access C++ functionality from QML, the Qt QML module also
+provides ways to do the reverse and manipulate QML objects from C++ code. See
+\l{qtqml-cppintegration-interactqmlfromcpp.html}{Interacting with QML Objects from C++} for more
+details.
+
+Finally, the C++ code may be integrated into either a C++ application or a C++ plugin depending on
+whether it is to be distributed as a standalone application or a library. A plugin can be integrated
+with a QML module that can then be imported and used by QML code in other applications; see
+\l{qtqml-modules-cppplugins.html}{Providing Types and Functionality in a C++ Plugin} for more
+information.
+
+
+\section1 Exposing Attributes of C++ Classes to QML
+
+QML can easily be extended from C++ due to the QML engine's integration with the Qt meta object
+system. This integration allows the properties, methods and signals of any QObject-derived class to
+be accessible from QML: properties can be read and modified, methods can be invoked from JavaScript
+expressions and signal handlers are automatically created for signals as necessary. Additionally,
+enumeration values of a QObject-derived class are accessible from QML.
+
+See \l{qtqml-cppintegration-exposecppattributes.html}{Exposing Attributes of C++ Types to QML} for
+more information.
+
+
+\section1 Defining QML Types from C++
+
+QML types can be defined in C++ and then registered with the \l{qtqml-typesystem-topic.html}{QML
+type system}. This allows a C++ class to be instantiated as a \l {QML object type}, enabling custom
+object types to be implemented in C++ and integrated into existing QML code. A C++ class may be also
+registered for other purposes: for example, it could be registered as a \e {Module API} to enable a
+single class instance to be imported by QML code, or it could be registered to enable the
+enumeration values of a non-instantiable class to be accessible from QML.
+
+Additionally, the QtQml module provides mechanisms to define QML types that integrate with QML
+concepts like attached properties and default properties.
+
+For more information on registering and creating custom QML types from C++, see the \l
+{qtqml-cppintegration-definetypes.html}{Defining QML Types from C++} documentation.
+
 
-\section1 Exposing C++ Types to QML
+\section1 Embedding C++ Objects into QML with Context Properties
 
-QML types may be implemented in C++ and then exposed to the QML type system via
-plugins or type registration.  This is covered in more detail elsewhere in the
-documentation; see the documentation regarding
-\l{qtqml-cppintegration-registercpptypes.html}
-{Registering C++ Types with the QML Type System} for more information on that
-topic.
+C++ objects and values can be embedded directly into the context (or \e scope) of loaded QML objects
+using \e {context properties} and \e {context objects}. This is achieved through the QQmlContext
+class provided by the QtQml module, which exposes data to the context of a QML component, allowing
+data to be injected from C++ into QML.
 
-For more information on the specifics of how to define C++ types for use in QML
-(not merely how to expose types to the QML type system), see the documentation
-about defining \l{qtqml-modules-cppplugins.html#creating-a-plugin}
-{C++ types for use in QML}.
+See \l{qtqml-cppintegration-contextproperties.html}{Embedding C++ Objects into QML with Context
+Properties} for more information.
 
-\section1 Exposing C++ Data to QML
 
-Data from C++ may be exposed to QML via context properties, instance
-properties, or by returning data from Q_INVOKABLE methods.  For more
-information about each of these approaches, and the ownership semantics
-applicable to each, see the documentation on \l{qtqml-cppintegration-data.html}
-{Exposing C++ Data to QML}.
+\section1 Interacting with QML Objects from C++
 
-\section1 Exposing C++ Functions to QML
+QML object types can be instantiated from C++ and inspected in order to access their properties,
+invoke their methods and receive their signal notifications. This is possible due to the fact that
+all QML object types are implemented using QObject-derived classes, enabling the QML engine to
+dynamically load and introspect objects through the Qt meta object system.
 
-Functions from C++ may be exposed to QML via signals and slots, by tagging a
-function declaration with the Q_INVOKABLE macro, or by registering the C++ type
-as a module API and installing that module API into a particular namespace.
-For more information about these approaches, see the documentation on
-\l{qtqml-cppintegration-functions.html}{Exposing C++ Functionality to QML}.
+For more information on accessing QML objects from C++, see the documentation on
+\l{qtqml-cppintegration-interactqmlfromcpp.html}{Interacting with QML Objects from C++}.
 
-\section1 Interacting with Objects Defined in QML from C++
 
-Most properties of an object defined in QML may be accessed via
-QQmlProperty::read() or QObject::property().  If the property is a list
-property, QQmlListReference may be used instead.
+\section1 Data Type Conversion Between QML and C++
 
-All methods of an object defined in QML may be invoked using the
-QMetaObject::invokeMethod() function.  This includes dynamic methods and signal
-handlers.
+When data values are exchanged between QML and C++, they are converted by the QML engine to have the
+correct data types as appropriate for use from QML or C++, providing the data types involved are
+known to the engine.
 
-For more information about accessing QML objects from C++, see the
-documentation on \l{qtqml-cppintegration-reverse.html}
-{Interacting with Objects Defined in QML from C++}.
+See \l{qtqml-cppintegration-data.html}{Data Type Conversion Between QML and C++} for information on
+the built-in types supported by the engine and how these types are converted for use when exchanged
+between QML and C++.
 
 */