Merge remote-tracking branch 'origin/4.7' into HEAD

1 files changed, 86 insertions, 12 deletions

diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc
index 915123f..5a95551 100644
--- a/doc/src/declarative/extending.qdoc
+++ b/doc/src/declarative/extending.qdoc
@@ -112,6 +112,75 @@ Person {
 \l {Extending QML - Adding Types Example} shows the complete code used to create
 the \c Person type.
 
+\section1 QML Type Versioning
+
+In C++ adding a new method or property cannot break old applications.
+In QML, however, new methods and properties can change what a name previously
+resolved to to within a scope chain.
+
+For example, consider these two QML files
+
+\code
+// main.qml
+import QtQuick 1.0
+Item {
+    id: root
+    MyComponent {}
+}
+\endcode
+
+\code
+// MyComponent.qml
+import MyModule 1.0
+CppItem {
+    value: root.x
+}
+\endcode
+
+where CppItem maps to the C++ class QCppItem.
+
+If the author of QCppItem adds a "root" property to QCppItem in a new version of the module, 
+it will break the above program as \c root.x now resolves to a different value.
+The solution is to allow the author of QCppItem to state that the new \c root property is 
+only available from a particular version of QCppItem onwards. This permits new properties
+and features to be added to existing elements without breaking existing programs. 
+
+QML enables this by allowing the properties, methods and signals of a class to be tagged with
+a particular \e revision, so that they are only accessible if the relevant module version
+is imported.  In this case, the author can tag the \c root property as being added in
+\e {revision 1} of the class, and register that revision in version 1.1 of the module.
+
+The REVISION tag is used to mark the \c root property as added in revision 1 of the class.
+Methods such as Q_INVOKABLE's, signals and slots can also be tagged for a
+revision using the \c Q_REVISION(x) macro:
+
+\code
+class CppItem : public QObject
+{
+    Q_OBJECT
+    Q_PROPERTY(int root READ root WRITE setRoot NOTIFY rootChanged REVISION 1)
+
+signals:
+    Q_REVISION(1) void rootChanged();
+};
+\endcode
+
+To register the new class revision to a particular version the following function is used:
+
+\code
+template<typename T, int metaObjectRevision>
+int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
+\endcode
+
+To register \c CppItem version 1 for \c {MyModule 1.1}:
+
+\code
+qmlRegisterType<QCppItem,1>("MyModule", 1, 1, "CppItem")
+\endcode
+
+\c root is only available when MyModule 1.1 is imported.
+
+
 \section1 Object and List Property Types
 
 \snippet examples/declarative/cppextensions/referenceexamples/properties/example.qml 0
@@ -733,12 +802,14 @@ It is optional for a property to have a default value. The default value is a co
 behaviorally identical to doing it in two steps, like this:
 
 \qml
-// Use default value
-property int myProperty: 10
+Item {
+    // Use default value
+    property int myProperty: 10
 
-// Longer, but behaviorally identical
-property int myProperty
-myProperty: 10
+    // Longer, but behaviorally identical
+    property int myProperty
+    myProperty: 10
+}
 \endqml
 
 
@@ -769,9 +840,11 @@ QML object types can also be used as property types. This includes
 defined like this:
 
 \qml
-property Item itemProperty
-property QtObject objectProperty
-property MyCustomType customProperty
+Item {
+    property Item itemProperty
+    property QtObject objectProperty
+    property MyCustomType customProperty
+}
 \endqml
 
 Such object-type properties default to an \c undefined value.
@@ -784,7 +857,9 @@ see the \l {variant}{variant type documentation} for details.
 list:
 
 \qml
-property list<Item> listOfItems
+Item {
+    property list<Item> listOfItems
+}
 \endqml
 
 Note that list properties cannot be modified like ordinary JavaScript
@@ -825,7 +900,7 @@ If the \l{Item::children}{children} property was not the default property for
 \qml
 Item {
     children: [
-        Rectangle {}
+        Rectangle {},
         Rectangle {}
     ]
 }
@@ -1075,7 +1150,7 @@ code removes the connection created in \c application.qml above:
 \qml
 // application.qml
 Item {
-    ...
+    // ...
 
     function removeSignal() {
         button.clicked.disconnect(item.myMethod)
@@ -1100,5 +1175,4 @@ MouseArea {
 
 Whenever the \l MouseArea \c clicked signal is emitted, the \c rect.buttonClicked signal will
 automatically be emitted as well.
-
 */