Create new documentation structure

The documentation currently has no clear separation between Qt QML
and Qt Quick.  With recent commits like:
6c8378eaf1edbbefe6aaa3672b0127816a004fd7
and
ab1e510121c8a679fdaca12ccd30e0f7ac12a26b
the separation between the language definition and implementation,
provided by Qt QML, and the standard library for the QML language,
provided by Qt Quick, is clear.

This commit creates a new documentation structure that is more
navigable and separates concepts into logical categories, with
clear separation between QtQML and QtQuick.  It also provides a more
generic QML Application Developer Resources page which contains links
to information for QML application developers.

Change-Id: Ia807ccfbfd24ffa0e1c7f0a51ed9d2ed3aa6a733
Reviewed-by: Martin Jones <martin.jones@nokia.com>

4 files changed, 311 insertions, 0 deletions

diff --git a/src/qml/doc/src/cppclasses/component.qdoc b/src/qml/doc/src/cppclasses/component.qdoc
new file mode 100644
index 0000000000..cc4f6b5f1c
--- /dev/null
+++ b/src/qml/doc/src/cppclasses/component.qdoc
@@ -0,0 +1,85 @@
+/****************************************************************************
+**
+** 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-cppclasses-component.html
+\title Qt QML Module C++ Classes - QQmlComponent
+\brief Description of QQmlComponent
+
+    \section2 Loading QML Components from C++
+
+    A QML document can be loaded with QQmlComponent or QQuickView.
+    QQmlComponent loads a QML component as a C++ QObject;
+    QQuickView also does this, but additionally loads the QML component
+    directly into a QQuickCanvas which displays visual QML object types
+    provided by Qt Quick, or object types derived from those.
+    It is convenient for loading a displayable
+    QML component as a root QWindow.
+
+    For example, suppose there is a \c MyItem.qml file that looks like this:
+
+    \snippet qml/qtbinding/loading/MyItem.qml start
+    \snippet qml/qtbinding/loading/MyItem.qml end
+
+    This QML document can be loaded with QQmlComponent or
+    QQuickView with the following C++ code. Using a QQmlComponent
+    requires calling QQmlComponent::create() to create a new instance of
+    the component, while a QQuickView automatically creates an instance of
+    the component, which is accessible via QQuickView::rootObject():
+
+    \table
+    \row
+    \li
+    \snippet qml/qtbinding/loading/main.cpp QQmlComponent-a
+    \dots 0
+    \snippet qml/qtbinding/loading/main.cpp QQmlComponent-b
+    \li
+    \snippet qml/qtbinding/loading/main.cpp QQuickView
+    \endtable
+
+    This \c object is the instance of the \c MyItem.qml component that has been
+    created. You can now modify the item's properties using
+    QObject::setProperty() or QQmlProperty:
+
+    \snippet qml/qtbinding/loading/main.cpp properties
+
+    Alternatively, you can cast the object to its actual type and call functions
+    with compile-time safety. In this case the base object of \c MyItem.qml is
+    an \l Item, which is defined by the QQuickItem class:
+
+    \snippet qml/qtbinding/loading/main.cpp cast
+
+    You can also connect to any signals or call functions defined in the
+    component using QMetaObject::invokeMethod() and QObject::connect(). See \l
+    {Interacting with Objects defined in QML from C++} for further details.
+
+
+
+
+
+
+
+*/
diff --git a/src/qml/doc/src/cppclasses/context.qdoc b/src/qml/doc/src/cppclasses/context.qdoc
new file mode 100644
index 0000000000..0745da3737
--- /dev/null
+++ b/src/qml/doc/src/cppclasses/context.qdoc
@@ -0,0 +1,96 @@
+/****************************************************************************
+**
+** 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-cppclasses-context.html
+\title Qt QML Module C++ Classes - QQmlContext
+\brief Description of QQmlContext
+
+
+
+
+    \section2 Embedding C++ Objects into QML Components
+
+    When loading a QML scene into a C++ application, it can be useful to
+    directly embed C++ data into the QML object. QQmlContext enables
+    this by exposing data to the context of a QML component, allowing data to be
+    injected from C++ into QML.
+
+    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
+
+    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.
+
+
+
+
+
+
+
+
+*/
diff --git a/src/qml/doc/src/cppclasses/engine.qdoc b/src/qml/doc/src/cppclasses/engine.qdoc
new file mode 100644
index 0000000000..7bb40f7b64
--- /dev/null
+++ b/src/qml/doc/src/cppclasses/engine.qdoc
@@ -0,0 +1,62 @@
+/****************************************************************************
+**
+** 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-cppclasses-engine.html
+\title Qt QML Module C++ Classes - QQmlEngine
+\brief Description of QQmlEngine
+
+
+The QML engine runs and executes QML
+applications. The engine loads, instantiates, and executes the QML context as
+specified in QML files, plugins, or applications.
+
+
+    A QQmlEngine allows the configuration of global settings that
+    apply to all of its QML component instances: for example, the
+    QNetworkAccessManager to be used for network communications, and the
+    file path to be used for persistent storage.
+
+    QQmlComponent is used to load QML documents. Each
+    QQmlComponent instance represents a single document. A component
+    can be created from the URL or file path of a QML document, or the raw
+    QML code of the document. Component instances are instatiated through
+    the QQmlComponent::create() method, like this:
+
+    \code
+    QQmlEngine engine;
+    QQmlComponent component(&engine, QUrl::fromLocalFile("MyRectangle.qml"));
+    QObject *rectangleInstance = component.create();
+
+    // ...
+    delete rectangleInstance;
+    \endcode
+
+    QML documents can also be loaded using QQuickView.
+
+
+
+*/
diff --git a/src/qml/doc/src/cppclasses/topic.qdoc b/src/qml/doc/src/cppclasses/topic.qdoc
new file mode 100644
index 0000000000..24d0674f2b
--- /dev/null
+++ b/src/qml/doc/src/cppclasses/topic.qdoc
@@ -0,0 +1,68 @@
+/****************************************************************************
+**
+** 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-cppclasses-topic.html
+\title C++ Classes Provided By The Qt QML Module
+\brief Overview of the C++ classes provided by the Qt QML module
+
+The Qt QML module provides C++ classes which implement the QML framework.
+Clients can use these classes to interact with the QML run-time (for example,
+by injecting data or invoking methods on objects), and to instantiate a
+hierarchy of objects from a QML document.
+
+\section1 The QQmlEngine Class
+
+The QQmlEngine class provides an engine which can manage a hierarchy of objects
+which is defined in a QML document.  It provides a root QML context within
+which expressions are evaluated, and ensures that properties of objects are
+updated correctly when required.
+
+See \l{qtqml-cppclasses-engine.html}{Qt QML Module C++ Classes - QQmlEngine}
+for in-depth information about QQmlEngine.
+
+\section1 The QQmlComponent Class
+
+The QQmlComponent class is used to load a QML document.  It requires a
+QQmlEngine in order to instantiate the hierarchy of objects defined in the QML
+document.
+
+See
+\l{qtqml-cppclasses-component.html}{Qt QML Module C++ Classes - QQmlComponent}
+for in-depth information about QQmlComponent.
+
+\section1 The QQmlContext Class
+
+The QQmlContext class provides a context for object instantiation and
+expression evaluation.  All objects are instantiated in a particular context,
+and all of the expressions which are evaluated while an application is running
+are evaluated within a particular context.  This context defines how symbols
+are resolved, and thus which values the expression operates on.
+
+See \l{qtqml-cppclasses-context.html}{Qt QML Module C++ Classes - QQmlContext}
+for in-depth information about QQmlContext.
+
+*/