Merge branch '4.7' of scm.dev.nokia.troll.no:qt/qt-qml into 4.7

4 files changed, 575 insertions, 170 deletions

diff --git a/doc/src/declarative/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc
index 6abe96f..8ab06ab 100644
--- a/doc/src/declarative/basictypes.qdoc
+++ b/doc/src/declarative/basictypes.qdoc
@@ -355,9 +355,11 @@
 
     \brief A list of objects.
 
-    A list of objects. While not technically a basic type, QML also
-    supports lists of object types. When used from QML, the engine
-    automatically appends each value to the list.
+    A list type contains a list of objects. While not technically
+    a basic type, QML supports lists of object types. When used
+    from QML, the engine automatically appends each value to the list.
+    Items in the list can be accessed by index using the usual
+    \c listName[index] syntax.
 
     For example, the \l Item class contains a list property named
     children that can be used like this:
@@ -366,14 +368,87 @@
     Item {
         children: [
             Item { id: child1 },
-            Rectangle { id: child2 },
+            Rectangle { id: child2; width: 200 },
             Text { id: child3 }
         ]
+
+        Component.onCompleted: {
+            console.log("Width of child rectangle:", children[1].width)
+        }
     }
     \endqml
-    \c child1, \c child2 and \c child3 will all be added to the children list
+    \c child1, \c child2 and \c child3 will be added to the children list
     in the order in which they appear.
 
+    List \l {Adding new properties}{properties} can be created as a
+    \c variant type, or as a \c list<Type> type, where \c Type is the
+    type of the object in the list:
+
+    \qml
+    Item {
+        property variant values: [ 10, 20, 'abc', 'xyz' ]
+
+        property list<Rectangle> rects: [
+            Rectangle { width: 100; height: 100},
+            Rectangle { width: 200; height: 200}
+        ]
+    }
+    \endqml
+
+    A \c variant list can contain values of any of the \l {QML Basic Types}{basic QML types}
+    such as numbers, strings, etc. while a \c list<Type> list can only contain values
+    that match (or are derived from) the specified \c Type.
+
+    A list property can be cleared by setting it to an empty list:
+
+    \qml
+    Item {
+        children: []
+    }
+    \endqml
+
+    A list property cannot be modified in any other way. Items cannot be dynamically added to
+    or removed from the list through JavaScript operations; any \c push() operations on the
+    list only modify a \e copy of the list and not the actual list. (These current limitations
+    are due to restrictions on \l {Property Binding} where lists are involved.)
+
+    To create a modifiable list, create an array object from within a \c .js JavaScript file,
+    or implement a custom list element in C++. Here is a QML element that modifies the list in a
+    JavaScript file:
+
+    \table
+    \row
+    \o
+    \qml
+    // QML
+    import "script.js" as Script
+
+    Item {
+        Component.onCompleted: {
+            Script.addItem('abc')
+            console.log("Added:", Script.getList()[0])
+        }
+    }
+    \endqml
+
+    \o
+    \code
+    // script.js
+    var myArray = new Array()
+
+    function getList() {
+        return myArray
+    }
+
+    function addItem(item) {
+        myArray.push(item)
+    }
+    \endcode
+    \endtable
+
+    However, note that a JavaScript list should not be used as a QML \c property value,
+    as the property is not updated when the list changes.
+
     \sa {QML Basic Types}
 */
 
diff --git a/doc/src/declarative/extending-tutorial.qdoc b/doc/src/declarative/extending-tutorial.qdoc
index 3b2fe3b..2bfe62e 100644
--- a/doc/src/declarative/extending-tutorial.qdoc
+++ b/doc/src/declarative/extending-tutorial.qdoc
@@ -260,32 +260,28 @@ custom QML types may see unexpected behavior if bindings are not implemented.
 
 The \c PieChart type currently has a string-type property and a color-type property.
 It could have many other types of properties. For example, it could have an
-enum-type property to store a display mode for each chart:
+int-type property to store an identifier for each chart:
 
 \code
     // C++
     class PieChart : public QDeclarativeItem
     {
-        Q_ENUMS(DisplayMode)
-        Q_PROPERTY(DisplayMode displayMode READ displayMode WRITE setDisplayMode)
+        Q_PROPERTY(int chartId READ chartId WRITE setChartId NOTIFY chartIdChanged)
         ...
 
     public:
-        enum DisplayMode {
-            MultiLevel,
-            Exploded,
-            ThreeDimensional
-        };
-
-        void setDisplayMode(DisplayMode mode);
-        DisplayMode displayMode() const;
+        void setChartId(int chartId);
+        int chartId() const;
         ...
+
+    signals:
+        void chartIdChanged();
     };
 
     // QML
     PieChart {
         ...
-        displayMode: PieChart.Exploded
+        chartId: 100
     }
 \endcode
 
diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc
index 18887c7..5c1b977 100644
--- a/doc/src/declarative/extending.qdoc
+++ b/doc/src/declarative/extending.qdoc
@@ -647,7 +647,8 @@ language.
 
 \section1 Adding new properties
 
-New properties can be added to an existing type.  These new properties are
+New properties can be added to an existing type using the \c property keyword.
+These new properties are
 available for use within QML, and also appear as regular Qt properties on the
 C++ object, accessible through the regular property access mechanisms.
 
@@ -679,8 +680,12 @@ like this:
     property list<Item> listOfItemsProperty
 \endcode
 
+Custom types must be registered with qmlRegisterType() to be usable as a property
+type. Also note that list properties cannot be modified like ordinary JavaScript
+arrays; see the \l {list}{list type documentation} for details.
+
 QML supports two methods for adding a new property to a type: a new property
-definition, and a property alias.
+definition, and a property alias. These are shown below.
 
 \section2 Property definitions
 
diff --git a/doc/src/declarative/qtbinding.qdoc b/doc/src/declarative/qtbinding.qdoc
index 58d53de..8a969eb 100644
--- a/doc/src/declarative/qtbinding.qdoc
+++ b/doc/src/declarative/qtbinding.qdoc
@@ -30,126 +30,389 @@
 \target qtbinding
 \title Using QML in C++ Applications
 
-\tableofcontents
+QML is designed to be easily extensible from C++. The classes in the
+QtDeclarative module allow QML components to be loaded and manipulated from C++, and through
+Qt's \l{The Meta-Object System}{meta-object system}, QML and C++ objects can easily
+communicate through Qt signals and slots. In addition, QML plugins can be written to create
+reusable QML components for distribution.
 
-The QML API is split into three main classes - QDeclarativeEngine, QDeclarativeComponent and QDeclarativeContext.  
-QDeclarativeEngine provides the environment in which QML is run, QDeclarativeComponent encapsulates 
-\l {QML Documents}, and QDeclarativeContext allows applications to expose data to QML component instances.
+You may want to mix QML and C++ for a number of reasons. For example:
 
-QML also includes a convenience API, QDeclarativeView, for applications that simply want to embed QML
-components into a new QGraphicsView.  QDeclarativeView covers up many of the details discussed below.  
-While QDeclarativeView is mainly intended for rapid prototyping it can have uses in production applications.
+\list
+\o 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)
+\o To access functionality in the QtDeclarative module (for example, to dynamically generate
+images using QDeclarativeImageProvider)
+\o To write your own QML elements (whether for your applications, or for distribution to others)
+\endlist
+
+To use the QtDeclarative module, you must include and link to the module appropriately, as shown on
+the \l {QtDeclarative}{module index page}. The \l {Qt Declarative UI Runtime} documentation
+shows how to build a basic C++ application that uses this module.
+
+
+\section1 Core module classes
 
-If you are looking at retrofitting an existing Qt application with QML,
-read \l{Integrating QML with existing Qt UI code}.
-\section1 Basic Usage
+The QtDeclarative module provides a set of C++ APIs for extending your QML applications from C++ and
+embedding QML into C++ applications. There are several core classes in the QtDeclarative module
+that provide the essential capabilities for doing this. These are:
 
-Every application requires at least one QDeclarativeEngine.  A QDeclarativeEngine allows the configuration of
-global settings that apply to all the QML component instances - such as the QNetworkAccessManager
-that is used for network communications, and the path used for persistent storage.  
-Multiple QDeclarativeEngine's are only needed if the application requires these settings to differ 
-between QML component instances.
+\list
+\o QDeclarativeEngine: A QML engine provides the environment for executing QML code. Every
+application requires at least one engine instance.
+\o QDeclarativeComponent: A component encapsulates a \l{QML Documents}{QML document}.
+\o QDeclarativeContext: A context allows an application to expose data to the QML components
+created by an engine.
+\endlist
 
-\l {QML Documents} are loaded using the QDeclarativeComponent class.  Each QDeclarativeComponent instance 
-represents a single QML document.  A QDeclarativeComponent can be passed a document URL, or raw text
-representing the content of the document.  The document URL can be a local filesystem URL, or
-any network URL supported by QNetworkAccessManager.
+A QDeclarativeEngine 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.
 
-QML component instances can then be created by calling the QDeclarativeComponent::create() method.  Here's
-an example of loading a QML document, and creating an object from it.
+QDeclarativeComponent is used to load QML documents. Each QDeclarativeComponent 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
+QDeclarativeComponent::create() method, like this:
 
 \code
-    QDeclarativeEngine *engine = new QDeclarativeEngine(parent);
-    QDeclarativeComponent component(engine, QUrl::fromLocalFile("main.qml"));
-    QObject *myObject = component.create();
+QDeclarativeEngine engine;
+QDeclarativeComponent component(&engine, QUrl::fromLocalFile("MyRectangle.qml"));
+QObject *rectangleInstance = component.create();
+
+// ...
+delete rectangleInstance;
 \endcode
 
-\section1 Exposing Data
+QML documents can also be loaded using QDeclarativeView. This class provides a convenient
+QWidget-based view for embedding QML components into QGraphicsView-based applications. (For other
+methods of integrating QML into QWidget-based applications, see \l {Integrating QML with existing Qt
+UI code}.)
+
+
+\section1 Approaches to using QML with C++
+
+There are a number of ways to extend your QML application through C++. For example, you could:
+
+\list
+\o Load a QML component and manipulate it (or its children) from C++
+\o 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 data with a real data set)
+\o Define new QML elements (through QObject-based C++ classes) and create them directly from your
+QML code
+\endlist
+
+These methods are shown below. Naturally these approaches are not exclusive; you can mix any of
+these methods throughout your application as appropriate.
+
+
+\section2 Loading QML components from C++
+
+A QML document can be loaded with QDeclarativeComponent or QDeclarativeView. QDeclarativeComponent
+loads a QML component as a C++ object; QDeclarativeView also does this,
+but additionally loads the QML component directly into a QGraphicsView. It is convenient for loading
+a displayable QML component into a QWidget-based application.
+
+For example, suppose there is a \c MyItem.qml file that looks like this:
+
+\snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml start
+\snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml end
+
+This QML document can be loaded with QDeclarativeComponent or QDeclarativeView with the following
+C++ code. Using a QDeclarativeComponent requires calling QDeclarativeComponent::create() to create
+a new instance of the component, while a QDeclarativeView automatically creates an instance of the
+component, which is accessible via QDeclarativeView::rootObject():
+
+\table
+\row
+\o
+\snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp QDeclarativeComponent-a
+\dots 0
+\snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp QDeclarativeComponent-b
+\o
+\snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp QDeclarativeView
+\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 QDeclarativeProperty:
+
+\snippet doc/src/snippets/declarative/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
+QDeclarativeItem class:
+
+\snippet doc/src/snippets/declarative/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 {Exchanging data between QML and C++}
+below for further details.
+
+\section3 Locating child objects
+
+QML components are essentially object trees with children that have siblings and their own children.
+Child objects of QML components can be located using the QObject::objectName property with
+QObject::findChild(). For example, if the root item in \c MyItem.qml had a child \l Rectangle item:
+
+\snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml start
+\codeline
+\snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml child
+\snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml end
+
+The child could be located like this:
+
+\snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp findChild
+
+If \c objectName is used inside a delegate of a ListView, \l Repeater or some other
+element that creates multiple instances of its delegates, there will be multiple children with
+the same \c objectName. In this case, QObject::findChildren() can be used to find all children
+with a matching \c objectName.
+
+\warning While it is possible to use C++ to access and manipulate QML objects deep into the
+object tree, we recommend that you do not take this approach outside of application
+testing and prototyping. One strength of QML and C++ integration is the ability to implement the
+QML user interface separately from the C++ logic and dataset backend, and this strategy breaks if the
+C++ side reaches deep into the QML components to manipulate them directly. This would make it difficult
+to, for example, swap a QML view component for another view, if the new component was missing a
+required \c objectName. It is better for the C++ implementation to know as little as possible about
+the QML user interface implementation and the composition of the QML object tree.
+
+
+\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. QDeclarativeContext 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 doc/src/snippets/declarative/qtbinding/context/MyItem.qml 0
+
+This \c currentDateTime value can be set directly by the C++ application that loads the QML
+component, using QDeclarativeContext::setContextProperty():
+
+\snippet doc/src/snippets/declarative/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
+\o
+\snippet doc/src/snippets/declarative/qtbinding/context-advanced/applicationdata.h 0
+\codeline
+\snippet doc/src/snippets/declarative/qtbinding/context-advanced/main.cpp 0
+\o
+\snippet doc/src/snippets/declarative/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 doc/src/snippets/declarative/qtbinding/context-advanced/connections.qml 0
+
+Context properties can be useful for using C++ based data models in a QML view. See the
+\l {declarative/modelviews/stringlistmodel}{String ListModel},
+\l {declarative/modelviews/objectlistmodel}{Object ListModel} and
+\l {declarative/modelviews/abstractitemmodel}{AbstractItemModel} models for
+respective examples on using QStringListModel, QObjectList-based models and QAbstractItemModel
+in QML views.
+
+Also see the QDeclarativeContext documentation for more information.
+
+
+\section2 Defining new QML elements
+
+While new QML elements can be \l {Defining new Components}{defined in QML}, they can also be
+defined by C++ classes; in fact, many of the core \l {QML Elements} are implemented through
+C++ classes. When you create a QML object using one of these elements, you are simply creating an
+instance of a QObject-based C++ class and setting its properties.
+
+For example, here is an \c ImageViewer class with an \c image URL property:
+
+\snippet doc/src/snippets/declarative/qtbinding/newelements/imageviewer.h 0
+
+Aside from the fact that it inherits QDeclarativeItem, this is an ordinary class that could
+exist outside of QML. However, once it is registered with the QML engine using qmlRegisterType():
+
+\snippet doc/src/snippets/declarative/qtbinding/newelements/main.cpp register
+
+Then, any QML code loaded by your C++ application or \l{QDeclarativeExtensionPlugin}{plugin} can create and manipulate
+\c ImageViewer objects:
+
+\snippet doc/src/snippets/declarative/qtbinding/newelements/standalone.qml 0
+
+Note that custom C++ types do not have to inherit from QDeclarativeItem; this is only necessary if it is
+a displayable item. If the item is not displayable, it can simply inherit from QObject.
+
+For more information on defining new QML elements, see the \l {Tutorial: Writing QML extensions with C++}
+{Writing QML extensions with C++} tutorial and the \l {Extending QML in C++} reference
+documentation.
+
+
+
+\section1 Exchanging data between QML and C++
+
+QML and C++ objects can communicate with one another through signals, slots and property
+modifications. For a C++ object, any data that is exposed to Qt's \l{The Meta-Object System}{Meta-Object System}
+- that is, properties, signals, slots and Q_INVOKABLE methods - become available to QML. On
+the QML side, all QML object data is automatically made available to the meta-object system and can
+be accessed from C++.
+
+
+\section2 Calling functions
 
-QML components are instantiated in a QDeclarativeContext.  A context allows the application to expose data
-to the QML component instance.  A single QDeclarativeContext can be used to instantiate all the objects
-used by an application, or several QDeclarativeContext can be created for more fine grained control over
-the data exposed to each instance.  If a context is not passed to the QDeclarativeComponent::create()
-method, the QDeclarativeEngine's \l {QDeclarativeEngine::rootContext()}{root context} is used.  Data exposed through
-the root context is available to all object instances.
+QML functions can be called from C++ and vice-versa.
 
-\section1 Simple Data
+All QML functions are exposed to the meta-object system and can be called using
+QMetaObject::invokeMethod(). Here is a C++ application that uses this to call a QML function:
 
-To expose data to a QML component instance, applications set \l {QDeclarativeContext::setContextProperty()}
-{context properties} which are then accessible by name from QML  \l {Property Binding}s and JavaScript.
-The following example shows how to expose a background color to a QML file through QDeclarativeView:
+\table
+\row
+\o \snippet doc/src/snippets/declarative/qtbinding/functions-qml/MyItem.qml 0
+\o \snippet doc/src/snippets/declarative/qtbinding/functions-qml/main.cpp 0
+\endtable
+
+Notice the Q_RETURN_ARG() and Q_ARG() arguments for QMetaObject::invokeMethod() must be specified as
+QVariant types, as this is the generic data type used for QML functions and return values.
+
+To call a C++ function from QML, the function must be either a Qt slot, or a function marked with
+the Q_INVOKABLE macro, to be available to QML. In the following example, the QML code invokes
+methods on the \c myObject object, which has been set using QDeclarativeContext::setContextProperty():
+
+\table
+\row
+\o
+\snippet doc/src/snippets/declarative/qtbinding/functions-cpp/MyItem.qml 0
+\o
+\snippet doc/src/snippets/declarative/qtbinding/functions-cpp/myclass.h 0
+\codeline
+\snippet doc/src/snippets/declarative/qtbinding/functions-cpp/main.cpp 0
+\endtable
+
+Note that QML does not support overloaded functions. If a C++ has more than one function with the
+same name, there is no guarantee which overloaded function will be called from QML.
+
+
+\section2 Receiving signals
+
+All QML signals are automatically available to C++, and can be connected to using QObject::connect()
+like any ordinary Qt C++ signal.
+
+Here is a QML component with a signal named \c qmlSignal. This signal is connected to a C++ object's
+slot using QObject::connect():
+
+\table
+\row
+\o
+\snippet doc/src/snippets/declarative/qtbinding/signals-qml/MyItem.qml 0
+\o
+\snippet doc/src/snippets/declarative/qtbinding/signals-qml/myclass.h 0
+\codeline
+\snippet doc/src/snippets/declarative/qtbinding/signals-qml/main.cpp 0
+\endtable
+
+To connect to Qt C++ signals from within QML, use a signal handler with the \c on<SignalName> syntax.
+If the C++ object is directly creatable from within QML (see \l {Defining new QML elements} above)
+then the signal handler can be defined within the object declaration. In the following example, the
+QML code creates a \c ImageViewer object, and the \c imageChanged and \c loadingError signals of the
+C++ object are connected to through \c onImagedChanged and \c onLoadingError signal handlers in QML:
 
 \table
 \row
 \o
-\c {// main.cpp}
-\snippet doc/src/snippets/declarative/qtbinding/contextproperties/main.cpp 0
+
+\snippet doc/src/snippets/declarative/qtbinding/signals-cpp/imageviewer.h start
+\dots 4
+\snippet doc/src/snippets/declarative/qtbinding/signals-cpp/imageviewer.h end
 
 \o
-\c {// main.qml}
-\snippet doc/src/snippets/declarative/qtbinding/contextproperties/main.qml 0
+\snippet doc/src/snippets/declarative/qtbinding/signals-cpp/standalone.qml 0
+\endtable
+
+(Note that if a signal has been declared as the NOTIFY signal for a property, QML allows it to be
+received with an \c on<Property>Changed handler even if the signal's name does not follow the \c
+<Property>Changed naming convention. In the above example, if the "imageChanged" signal was named
+"imageModified" instead, the \c onImageChanged signal handler would still be called.)
+
+If, however, the object with the signal is not created from within the QML code, and the QML item only has a
+reference to the created object - for example, if the object was set using
+QDeclarativeContext::setContextProperty() - then the \l Connections element can be used
+instead to create the signal handler:
 
+\table
+\row
+\o \snippet doc/src/snippets/declarative/qtbinding/signals-cpp/main.cpp connections
+\o \snippet doc/src/snippets/declarative/qtbinding/signals-cpp/MyItem.qml 0
 \endtable
 
-Or, if you want \c main.cpp to create the component without showing it in a QDeclarativeView, you could create an instance of QDeclarativeContext using QDeclarativeEngine::rootContext() instead:
 
-\snippet doc/src/snippets/declarative/qtbinding/contextproperties/main.cpp 1
+\section2 Modifying properties
 
-Context properties work just like normal properties in QML bindings - if the \c backgroundColor
-context property in this example was changed to red, the component object instances would
-all be automatically updated.  Note that it is the responsibility of the creator to delete any
-QDeclarativeContext it constructs.  If the \c windowContext is no longer needed when
-the \c window component instantiation is destroyed, the \c windowContext must be destroyed
-explicitly.  The simplest way to ensure this is to set \c window as \c windowContext's parent.
+Any properties declared in a QML object are automatically accessible from C++. Given a QML item
+like this:
 
-QDeclarativeContexts form a tree - each QDeclarativeContext except for the root context has a parent.  Child 
-QDeclarativeContexts effectively inherit the context properties present in their parents.  This gives
-applications more freedom in partitioning the data exposed to different QML object instances.  
-If a QDeclarativeContext sets a context property that is also set in one of its parents, the new context
-property shadows that in the parent.  In The following example, the \c background context property
-in \c {Context 1} shadows the \c background context property in the root context.
+\snippet doc/src/snippets/declarative/qtbinding/properties-qml/MyItem.qml 0
 
-\image qml-context-tree.png
+The value of the \c someNumber property can be set and read using QDeclarativeProperty, or
+QObject::setProperty() and QObject::property():
 
-\section2 Structured Data
+\snippet doc/src/snippets/declarative/qtbinding/properties-qml/main.cpp 0
 
-Context properties can also be used to expose structured and writable data to QML objects.  In 
-addition to all the types already supported by QVariant, QObject derived types can be assigned to
-context properties.  QObject context properties allow the data exposed to be more structured, and
-allow QML to set values.
+You should always use QObject::setProperty(), QDeclarativeProperty or QMetaProperty::write() to
+change a QML property value, to ensure the QML engine is made aware of the property change. For example,
+say you have a custom element \c PushButton with a \c buttonText property that internally reflects
+the value of a \c m_buttonText member variable. Modifying the member variable directly like this is
+not a good idea:
 
-The following example creates a \c CustomPalette object, and sets it as the \c palette context
-property.
+\badcode
+// BAD!
+QDeclarativeComponent component(engine, "MyButton.qml");
+PushButton *button = qobject_cast<PushButton*>(component.create());
+button->m_buttonText = "Click me";
+\endcode
 
-\snippet doc/src/snippets/declarative/qtbinding/custompalette/custompalette.h 0
+Since the value is changed directly, this bypasses Qt's \l{The Meta-Object System}{meta-object system}
+and the QML engine is not made aware of the property change. This means property bindings to
+\c buttonText would not be updated, and any \c onButtonTextChanged handlers would not be called.
 
-\snippet doc/src/snippets/declarative/qtbinding/custompalette/main.cpp 0
 
-The QML that follows references the palette object, and its properties, to set the appropriate
-background and text colors.  When the window is clicked, the palette's text color is changed, and
-the window text will update accordingly.
+\target properties-cpp
 
-\snippet doc/src/snippets/declarative/qtbinding/custompalette/main.qml 0
+Any \l {The Property System}{Qt properties} - that is, those declared with the Q_PROPERTY()
+macro - are accessible from QML. Here is a modified version of the \l {Embedding C++ objects into
+QML components}{earlier example} on this page; here, the \c ApplicationData class has a \c backgroundColor
+property. This property can be written to and read from QML:
 
-To detect when a C++ property value - in this case the \c CustomPalette's \c text property - 
-changes, the property must have a corresponding NOTIFY signal.  The NOTIFY signal specifies a signal
-that is emitted whenever the property changes value.  Implementers should take care to only emit the
-signal if the value \e changes to prevent loops from occurring.  Accessing a property from a
-binding that does not have a NOTIFY signal will cause QML to issue a warning at runtime.
+\table
+\row
+\o \snippet doc/src/snippets/declarative/qtbinding/properties-cpp/applicationdata.h 0
+\o \snippet doc/src/snippets/declarative/qtbinding/properties-cpp/MyItem.qml 0
+\endtable
 
-\section2 Dynamic Structured Data
+Notice the \c backgroundColorChanged signal is declared as the NOTIFY signal for the
+\c backgroundColor property. If a Qt property does not have an associated NOTIFY signal,
+the property cannot be used for \l {Property Binding} in QML, as the QML engine would not be
+notified when the value changes. If you are using custom types in QML, make sure their
+properties have NOTIFY signals so that they can be used in property bindings.
 
-If an application is too dynamic to structure data as compile-time QObject types, dynamically
-structured data can be constructed at runtime using the QDeclarativePropertyMap class.
+See \l {Tutorial: Writing QML extensions with C++} for further details and examples
+on using Qt properties with QML.
 
 
-\section1 Calling C++ methods from QML
+\section1 Supported data types
 
-It is possible to call methods of QObject derived types by either exposing the
-methods as public slots, or by marking the methods Q_INVOKABLE.
+Any C++ data that is used from QML - whether as custom properties, or parameters for signals or
+functions - must be of a type that is recognizable by QML.
 
-The C++ methods can also have parameters and return values.  QML has support for
-the following types:
+By default, QML recognizes the following data types:
 
 \list
 \o bool
@@ -163,102 +426,168 @@ the following types:
 \o QSize, QSizeF
 \o QRect, QRectF
 \o QVariant
+\o QObject*
+\o Enumerations declared with Q_ENUMS()
 \endlist
 
-This example toggles the "Stopwatch" object on/off when the MouseArea is clicked:
+To allow a custom C++ type to be created or used in QML, the C++ class must be registered as a QML
+type using qmlRegisterType(), as shown in the \l {Defining new QML elements} section above.
 
-\table
-\row
-\o
-\c {// main.cpp}
-\snippet doc/src/snippets/declarative/qtbinding/stopwatch/stopwatch.h 0
-\snippet doc/src/snippets/declarative/qtbinding/stopwatch/main.cpp 0
 
-\o
-\c {// main.qml}
-\snippet doc/src/snippets/declarative/qtbinding/stopwatch/main.qml 0
+\section2 Using enumerations of a custom type
 
-\endtable
+To use an enumeration from a custom C++ component, the enumeration must be declared with Q_ENUMS() to
+register it with Qt's meta object system. For example, the following C++ type has a \c Status enum:
 
-Note that in this particular example a better way to achieve the same result
-is to have a "running" property in \c main.qml.  This leads to much nicer QML code:
+\snippet doc/src/snippets/declarative/qtbinding/enums/imageviewer.h start
+\snippet doc/src/snippets/declarative/qtbinding/enums/imageviewer.h end
+
+Providing the \c ImageViewer class has been registered using qmlRegisterType(), its \c Status enum can
+now be used from QML:
+
+\snippet doc/src/snippets/declarative/qtbinding/enums/standalone.qml 0
+
+The C++ type must be registered with QML to use its enums. If your C++ type is not instantiable, it
+can be registered using qmlRegisterUncreatableType().
+
+See the \l {Tutorial: Writing QML extensions with C++}{Writing QML extensions with C++} tutorial and
+the \l {Extending QML in C++} reference documentation for more information.
+
+
+\section2 Automatic type conversion
+
+As a convenience, some basic types can be specified in QML using format strings to make it easier to
+pass simple values from QML to C++.
 
 \table
+\header
+\o Type
+\o String format
+\o Example
 \row
-\o
-\code
-// main.qml
-import QtQuick 1.0
-
-Rectangle {
-    MouseArea {
-        anchors.fill: parent
-        onClicked: stopwatch.running = !stopwatch.running
-    }
-}
-\endcode
+\o QColor
+\o Color name, "#RRGGBB", "#RRGGBBAA"
+\o "red", "#ff0000", "#ff000000"
+\row
+\o QDate
+\o "YYYY-MM-DD"
+\o "2010-05-31"
+\row
+\o QPoint
+\o "x,y"
+\o "10,20"
+\row
+\o QRect
+\o "x,y,WidthxHeight"
+\o "50,50,100x100"
+\row
+\o QSize
+\o "WidthxHeight"
+\o "100x200"
+\row
+\o QTime
+\o "hh:mm:ss"
+\o "14:22:55"
+\row
+\o QUrl
+\o URL string
+\o "http://www.example.com"
+\row
+\o QVector3D
+\o "x,y,z"
+\o "0,1,0"
+\row
+\o Enumeration value
+\o Enum value name
+\o "AlignRight"
 \endtable
 
-Of course, it is also possible to call \l {Adding new methods}{functions declared in QML from C++}.
+(More details on these string formats and types can be found in the
+\l {QML Basic Types}{basic type documentation}.)
+
+These string formats can be used to set QML \c property values and pass arguments to C++
+functions. This is demonstrated by various examples on this page; in the above
+\l{#properties-cpp}{Qt properties example}, the \c ApplicationData class has a \c backgroundColor
+property of a QColor type, which is set from the QML code with the string "red" rather rather
+than an actual QColor object.
+
+If it is preferred to pass an explicitly-typed value rather than a string, the global
+\l{QmlGlobalQtObject}{Qt object} provides convenience functions for creating some of the object
+types listed above. For example, \l{QML:Qt::rgba()}{Qt.rgba()} creates a QColor value from four
+RGBA values. The QColor returned from this function could be used instead of a string to set
+a QColor-type property or to call a C++ function that requires a QColor parameter.
+
+
+\section1 Writing QML plugins
+
+The QtDeclarative module includes the QDeclarativeExtensionPlugin class, which is an abstract
+class for writing QML plugins. This allows QML extension types to be dynamically loaded into
+QML applications.
+
+See the QDeclarativeExtensionPlugin documentation and \l {How to Create Qt Plugins} for more
+details.
+
+
+\section1 Managing resource files with the Qt resource system
 
+The \l {The Qt Resource System}{Qt resource system} allows resource files to be stored as
+binary files in an application executable. This can be useful when building a mixed
+QML/C++ application as it enables QML files (as well as other resources such as images
+and sound files) to be referred to through the resource system URI scheme rather than
+relative or absolute paths to filesystem resources. Note, however, that if you use the resource
+system, the application executable must be re-compiled whenever a QML source file is changed
+in order to update the resources in the package.
 
-\section1 Network Components
+To use the resource system in a mixed QML/C++ application:
 
-If the URL passed to QDeclarativeComponent is a network resource, or if the QML document references a
-network resource, the QDeclarativeComponent has to fetch the network data before it is able to create
-objects.  In this case, the QDeclarativeComponent will have a \l {QDeclarativeComponent::Loading}{Loading}
-\l {QDeclarativeComponent::status()}{status}.  An application will have to wait until the component
-is \l {QDeclarativeComponent::Ready}{Ready} before calling \l {QDeclarativeComponent::create()}.
+\list
+\o Create a \c .qrc \l {The Qt Resource System}{resource collection file} that lists resource
+   files in XML format
+\o From C++, load the main QML file as a resource using the \c :/ prefix or as a URL with the
+   \c qrc scheme
+\endlist
+
+Once this is done, all files specified by relative paths in QML will be loaded from
+the resource system instead. Use of the resource system is completely transparent to
+the QML layer; this means all QML code should refer to resource files using relative
+paths and should \e not use the \c qrc scheme. This scheme should only be used from
+C++ code for referring to resource files.
 
-The following example shows how to load a QML file from a network resource.  After creating
-the QDeclarativeComponent, it tests whether the component is loading.  If it is, it connects to the
-QDeclarativeComponent::statusChanged() signal and otherwise calls the \c {continueLoading()} method
-directly.  This test is necessary, even for URLs that are known to be remote, just in case
-the component has been cached and is ready immediately.
+Here is a application packaged using the \l {The Qt Resource System}{Qt resource system}.
+The directory structure looks like this:
 
 \code
-MyApplication::MyApplication()
-{
-    // ...
-    component = new QDeclarativeComponent(engine, QUrl("http://www.example.com/main.qml"));
-    if (component->isLoading())
-        QObject::connect(component, SIGNAL(statusChanged(QDeclarativeComponent::Status)),
-                         this, SLOT(continueLoading()));
-    else
-        continueLoading();
-}
-
-void MyApplication::continueLoading()
-{
-    if (component->isError()) {
-        qWarning() << component->errors();
-    } else {
-        QObject *myObject = component->create();
-    }
-}
+project
+    |- example.qrc
+    |- main.qml
+    |- images
+        |- background.png
+    |- main.cpp
+    |- project.pro
 \endcode
 
-\section1 Qt Resources
+The \c main.qml and \c background.png files will be packaged as resource files. This is
+done in the \c example.qrc resource collection file:
 
-QML content can be loaded from \l {The Qt Resource System} using the \e qrc: URL scheme.
-For example:
+\quotefile doc/src/snippets/declarative/qtbinding/resources/example.qrc
 
-\c [project/example.qrc]
-\quotefile doc/src/snippets/declarative/qtbinding/resources/example.qrc 
+Since \c background.png is a resource file, \c main.qml can refer to it using the relative
+path specified in \c example.qrc:
+
+\snippet doc/src/snippets/declarative/qtbinding/resources/main.qml 0
 
-\c [project/project.pro]
-\quotefile doc/src/snippets/declarative/qtbinding/resources/resources.pro 
+To allow QML to locate resource files correctly, the \c main.cpp loads the main QML
+file, \c main.qml, as a resource file using the \c qrc scheme:
 
-\c [project/main.cpp]
 \snippet doc/src/snippets/declarative/qtbinding/resources/main.cpp 0
 
-\c [project/main.qml]
-\snippet doc/src/snippets/declarative/qtbinding/resources/main.qml 0
+Finally \c project.pro uses the RESOURCES variable to indicate that \c example.qrc should
+be used to build the application resources:
+
+\quotefile doc/src/snippets/declarative/qtbinding/resources/resources.pro
+
+See \l {The Qt Resource System} for more information.
 
-Note that the resource system cannot be accessed from QML directly. If the main QML file is
-loaded as a resource, all files specified as relative paths in QML will also be loaded from
-the resource system. Using the resource system is completely transparent to the QML layer.
-This also means that if the main QML file is not loaded as a resource then files in the resource
-system cannot be accessed from QML.
 */
 
+