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, 95 insertions, 0 deletions

diff --git a/src/qml/doc/src/cppintegration/contextproperties.qdoc b/src/qml/doc/src/cppintegration/contextproperties.qdoc
new file mode 100644
index 0000000000..4a3501944e
--- /dev/null
+++ b/src/qml/doc/src/cppintegration/contextproperties.qdoc
@@ -0,0 +1,95 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** 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.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+\page qtqml-cppintegration-contextproperties.html
+\title Embedding C++ Objects into QML with Context Properties
+\brief Description of how to embed C++ data into QML using context properties
+
+When loading a QML object into a C++ application, it can be useful to directly embed some C++ data
+that can be used from within th QML code. This makes it possible, for example, to invoke a C++
+method on the embedded object, or use a C++ object instance as a data model for a QML view.
+
+The ability to inject C++ data into a QML object is made possible by the QQmlContext class. This
+class exposes data to the context of a QML object so that the data can be referred to directly from
+within the scope of the QML code.
+
+
+\section1 Setting a Simple Context Property
+
+For example, here is a QML item that refers to a \c currentDateTime value that does not exist in
+the current scope:
+
+\snippet qml/qtbinding/context/MyItem.qml 0
+
+This \c currentDateTime value can be set directly by the C++ application that loads the QML
+component, using QQmlContext::setContextProperty():
+
+\snippet qml/qtbinding/context/main.cpp 0
+
+\note Since all expressions evaluated in QML are evaluated in a particular context, if the context
+is modified, all bindings in that context will be re-evaluated. Thus, context properties should be
+used with care outside of application initialization, as this may lead to decreased application
+performance.
+
+
+\section1 Setting an Object as a Context Property
+
+Context properties can hold either QVariant or QObject* values. This means custom C++ objects can
+also be injected using this approach, and these objects can be modified and read directly in QML.
+Here, we modify the above example to embed a QObject instance instead of a QDateTime value, and the
+QML code invokes a method on the object instance:
+
+\table
+\row
+\li
+\snippet qml/qtbinding/context-advanced/applicationdata.h 0
+\codeline
+\snippet qml/qtbinding/context-advanced/main.cpp 0
+\li
+\snippet qml/qtbinding/context-advanced/MyItem.qml 0
+\endtable
+
+(Note that date/time values returned from C++ to QML can be formatted through
+\l{QML:Qt::formatDateTime}{Qt.formatDateTime()} and associated functions.)
+
+If the QML item needs to receive signals from the context property, it can connect to them using the
+\l Connections element. For example, if \c ApplicationData has a signal named \c
+dataChanged(), this signal can be connected to using an \c onDataChanged handler within
+a \l Connections object:
+
+\snippet qml/qtbinding/context-advanced/connections.qml 0
+
+Context properties can be useful for using C++ based data models in a QML view. See the
+\l {quick/modelviews/stringlistmodel}{String ListModel},
+\l {quick/modelviews/objectlistmodel}{Object ListModel} and
+\l {quick/modelviews/abstractitemmodel}{AbstractItemModel} models for
+respective examples on using QStringListModel, QObjectList-based models and QAbstractItemModel
+in QML views.
+
+Also see the QQmlContext documentation for more information.
+
+*/