Add documentation about property value modifiers

Previously, property value modifiers were only documented in QtQuick,
when really they are a QtQml module / QML language feature.

This commit also improves the QtQuick documentation for convenience
types, and rearranges some links and content for improved consistency.

Change-Id: Ic4dbe0b8bb85bdfbb8ac2f336c13c2960f8d1842
Reviewed-by: Bea Lam <bea.lam@nokia.com>

10 files changed, 224 insertions, 163 deletions

diff --git a/src/qml/doc/src/cppclasses/topic.qdoc b/src/qml/doc/src/cppclasses/topic.qdoc
index 64f02c985b..93d7bb3190 100644
--- a/src/qml/doc/src/cppclasses/topic.qdoc
+++ b/src/qml/doc/src/cppclasses/topic.qdoc
@@ -77,4 +77,14 @@ See \l{qtqml-cppclasses-expression.html}
 {Qt QML Module C++ Classes - QQmlExpression} for in depth information about
 QQmlExpression.
 
+\section1 The QQmlPropertyValueSource Class
+
+The QQmlPropertyValueSource class is an abstract class which may be inherited
+to provide unique \l{qtqml-typesystem-topic.html#property-modifier-types}
+{property value sources}.
+
+See \l{qtqml-cppclasses-valuesource.html}
+{Qt QML Module C++ Classes - QQmlPropertyValueSource} for in depth information
+about QQmlPropertyValueSource.
+
 */
diff --git a/src/qml/doc/src/cppclasses/valuesource.qdoc b/src/qml/doc/src/cppclasses/valuesource.qdoc
new file mode 100644
index 0000000000..92c8c3acd1
--- /dev/null
+++ b/src/qml/doc/src/cppclasses/valuesource.qdoc
@@ -0,0 +1,36 @@
+/****************************************************************************
+**
+** 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-valuesource.html
+\title Qt QML Module C++ Classes - QQmlPropertyValueSource
+\brief Description of QQmlPropertyValueSource
+
+QQmlPropertyValueSource may be inherited by client-defined classes to provide
+a custom property value source kind of property value modifier.
+
+*/
diff --git a/src/qml/doc/src/qtqml.qdoc b/src/qml/doc/src/qtqml.qdoc
index 7bb3453271..be4232eab1 100644
--- a/src/qml/doc/src/qtqml.qdoc
+++ b/src/qml/doc/src/qtqml.qdoc
@@ -75,6 +75,8 @@ types, animation classes, and canvas integration) for the QML language.
         \li \l{qtqml-cppclasses-engine.html}{QQmlEngine}
         \li \l{qtqml-cppclasses-context.html}{QQmlContext}
         \li \l{qtqml-cppclasses-component.html}{QQmlComponent}
+        \li \l{qtqml-cppclasses-expression.html}{QQmlExpression}
+        \li \l{qtqml-cppclasses-valuesource.html}{QQmlPropertyValueSource}
         \endlist
 
     \li \l{qtqml-typesystem-topic.html}{The QML Type System}
@@ -86,6 +88,7 @@ types, animation classes, and canvas integration) for the QML language.
             \li \l{qtqml-documents-definetypes.html}{Defining Object Types from QML}
             \li \l{qtqml-cppintegration-registercpptypes.html}{Defining Object Types from C++}
             \endlist
+        \li \l{qtqml-typesystem-topic.html#property-modifier-types}{Property Modifier Types}
         \endlist
 
     \li \l{qtqml-modules-topic.html}{QML Modules}
diff --git a/src/qml/doc/src/typesystem/topic.qdoc b/src/qml/doc/src/typesystem/topic.qdoc
index 1de87b542d..e12873547e 100644
--- a/src/qml/doc/src/typesystem/topic.qdoc
+++ b/src/qml/doc/src/typesystem/topic.qdoc
@@ -98,4 +98,54 @@ re-used in other QML documents.  See the documentation about
 \l{qtqml-typesystem-objecttypes.html}{object types in the QML type system} for
 in-depth information about object types.
 
+\section1 Property Modifier Types
+
+A property modifier type is a special kind of QML object type.  A property
+modifier type instance affects a property (of a QML object instance) which it
+is applied to.  There are two different kinds of property modifier types:
+\list
+\li property value write interceptors
+\li property value sources
+\endlist
+
+A property value write interceptor can be used to filter or modify values as
+they are written to properties.  Currently, the only supported property
+value write interceptor is the \l Behavior type provided by the \c QtQuick
+import.
+
+A property value source can be used to automatically update the value of a
+property over time.  Clients can define their own property value source types.
+The various \l{qtquick-statesanimations-animations.html}{property animation}
+types provided by the \c QtQuick import are examples of property value
+sources.
+
+Property modifier type instances can be created and applied to a property of
+a QML object through the "<ModifierType> on <propertyName>" syntax, as the
+following example shows:
+
+\qml
+import QtQuick 2.0
+
+Item {
+    width: 400
+    height: 50
+
+    Rectangle {
+        width: 50
+        height: 50
+        color: "red"
+
+        NumberAnimation on x {
+            from: 0
+            to: 350
+            loops: Animation.Infinite
+            duration: 2000
+        }
+    }
+}
+\endqml
+
+See the documentation on \l QQmlPropertyValueSource for information about how
+to define your own property value source types.
+
 */
diff --git a/src/quick/doc/src/concepts/convenience/topic.qdoc b/src/quick/doc/src/concepts/convenience/topic.qdoc
new file mode 100644
index 0000000000..ad70b9a990
--- /dev/null
+++ b/src/quick/doc/src/concepts/convenience/topic.qdoc
@@ -0,0 +1,87 @@
+/****************************************************************************
+**
+** 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 qtquick-convenience-topic.html
+\title Important Concepts In Qt Quick - Convenience Types
+\brief Overview of the convenience types for QML core features
+
+In a highly dynamic user interface, the application developer will often wish
+to react to events and trigger various response logic.  QML has built-in
+support for these concepts through bindings, signals and signal handlers, and
+dynamic object instantiation, but Qt Quick expands upon the support
+provided by the language with various convenience types.
+
+\section1 Dynamic Object Instantiation
+
+QML provides a number of ways to dynamically create and manage QML objects.
+
+Objects can be created dynamically from within imperative JavaScript code
+in various ways.  See \l{qtqml-javascript-dynamicobjectcreation.html}
+{Dynamic QML object creation from JavaScript} for more details.
+
+Qt Quick provides the \l{Loader}, \l{Repeater}, \l{ListView}, \l{GridView} and
+\l{PathView} types which also support dynamic object management, and provide
+a declarative API.
+
+Please see the \l{qtquick-performance.html}{performance guide} for more
+information on using dynamic instantiation and lazy initialization to improve
+application performance.
+
+\section1 Dynamic Bindings
+
+Assigning binding expressions to properties is a fundamental concept of QML,
+and Qt Quick extends upon the idea with the \l Binding type.   While bindings
+are typically specified as property initialization assignments, the \l Binding
+type allows the target of a binding to be defined explicitly and separately
+from the definition of the binding expression itself.
+By declaring a \l Binding instance, the client can dynamically bind properties
+from arbitrary objects at run-time, and can modify the binding target when
+required (or when it becomes available).
+
+\section1 Dynamic Signal Connections
+
+QML supports dynamic signal connections through a signal's \c{connect()}
+method. The QtQuick module provides the convenience \l Connections type which
+allows setting up a signal connection involving an object which isn't part of
+the static object hierarchy.  It also allows the connection to be dynamically
+retargeted at runtime, which allows an application to process different signal
+notifications with different functions depending on the program state.
+
+By declaring a \l Connections instance, the client can dynamically cause
+signals emitted by one object to trigger methods of another object, and can
+modify the connection target when required (or when it becomes available).
+
+\section1 Timer-Based Events
+
+Another common use-case is to trigger functionality some specified period of
+time after a particular event occurs.  These sort of timer-based triggers are
+supported in Qt Quick through the \l Timer type.  Both single-shot and
+recurring timers are supported.
+
+*/
+
diff --git a/src/quick/doc/src/concepts/dynamicinstantiation/topic.qdoc b/src/quick/doc/src/concepts/dynamicinstantiation/topic.qdoc
deleted file mode 100644
index 4040a63655..0000000000
--- a/src/quick/doc/src/concepts/dynamicinstantiation/topic.qdoc
+++ /dev/null
@@ -1,48 +0,0 @@
-/****************************************************************************
-**
-** 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 qtquick-dynamicinstantiation-topic.html
-\title Important Concepts In Qt Quick - Dynamic and Lazy Instantiation
-\brief Overview of the dynamic and lazy instantiation concepts
-
-QML provides a number of ways to dynamically create and manage QML objects.
-The \l{Loader}, \l{Repeater}, \l{ListView}, \l{GridView} and \l{PathView} elements
-all support dynamic object management.
-
-Objects can be created and deleted at runtime from JavaScript code. See
-\l{qtqml-javascript-dynamicobjectcreation.html}{Dynamic QML object creation from JavaScript}
-for more details.
-
-Qt Quick also provides the Loader type which may be used in conjuction with a
-Component or a QML document to instantiate objects lazily and on-demand.
-Please see the \l{qtquick-performance.html}{performance guide} for more
-information on using dynamic instantiation and lazy initialization to improve
-application performance.
-
-*/
-
diff --git a/src/quick/doc/src/concepts/eventinterceptors/topic.qdoc b/src/quick/doc/src/concepts/eventinterceptors/topic.qdoc
deleted file mode 100644
index f6d2e7fe14..0000000000
--- a/src/quick/doc/src/concepts/eventinterceptors/topic.qdoc
+++ /dev/null
@@ -1,69 +0,0 @@
-/****************************************************************************
-**
-** 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 qtquick-eventinterceptors-topic.html
-\title Important Concepts In Qt Quick - Event Interceptors
-\brief Overview of event interceptor concepts
-
-In a highly dynamic user-interface, the application developer will often wish
-to intercept some events (such as property assignments) so that the change can
-be animated.  Interceptors are a first-class concept in Qt Quick, and
-application developers can dynamically intercept property assignments and
-signal emissions, and define dynamic bindings.
-
-\section1 Animating Property Assignments
-
-When the location of a visual item changes, it is often suboptimal to simply
-change the location instantaneously.  It may be better to animate the update
-to allow the user's eye to follow the change, thus providing a seamless
-user-experience.  See the documentation on
-\l{qtquick-concepts-interceptors.html#animating-property-assignments}
-{Animating Property Assignments} for more information about property assignment
-interception.
-
-\section1 Dynamic Bindings
-
-Assigning binding expressions to properties is a fundamental concept of QML,
-and Qt Quick extends upon the idea with dynamic bindings where the target of
-the binding can be defined outside of the binding expression itself.  See the
-\l{qtquick-concepts-interceptors.html#dynamic-bindings}{Dynamic Bindings} page
-for more information about this concept.
-
-\section1 Dynamic Signal Connections
-
-Just as bindings can be retargeted dynamically in Qt Quick, so too can signal
-connections.  This allows highly dynamic dispatch to be implemented in a user
-interface where different visual items need to handle different events,
-depending on the situation, at run-time.  See the documentation about
-\l{qtquick-concepts-interceptors.html#dynamic-signal-connections}
-{Dynamic Signal Connections} for in-depth information.
-
-\section1 Timer-Based Events
-
-*/
-
diff --git a/src/quick/doc/src/concepts/statesanimations/topic.qdoc b/src/quick/doc/src/concepts/statesanimations/topic.qdoc
index 8ca02fd444..25b0958162 100644
--- a/src/quick/doc/src/concepts/statesanimations/topic.qdoc
+++ b/src/quick/doc/src/concepts/statesanimations/topic.qdoc
@@ -89,22 +89,28 @@ and transition elements.  See the documentation on
 {Animations and Transitions In Qt Quick} for information about these elements
 and how to use them.
 
-Animations are not only related to states and transitions between states; for
+
+\section1 Animating Property Assignments
+
+Animations are not only related to states and transitions between states.  For
 example, an animation might be triggered by other events, which are not
-associated with a distinct state.  It is often beneficial to always animate
-changes to certain properties of visual items, regardless of the cause of the
-change (for example, opacity effects).
+associated with a distinct state.
+
+It is often beneficial to always animate changes to certain properties of
+visual items, regardless of the cause of the change (for example, opacity
+effects).  Qt Quick provides the \l Behavior type which allows the client to
+specify animation behavior for changes to properties.  The \l Behavior type
+is an example of a QML object
+\l{qtqml-typesystem-topic.html#property-modifier-types}{property modifier}.
 
-This type of animation is supported in Qt Quick with the \c{Behavior} element
-through the \tt{"Behavior on <Property>"} syntax.  Please see the documentation
-about
+Please see the documentation about
 \l{qtquick-statesanimations-animations.html#default-animation-as-behaviors}
-{default property animation behaviors} for more information about the Behavior
-element and how to use it.
+{default property animations} for more information about using the \l Behavior
+element to provide default property change animations.
 
-It is important to note, however, that using default property animations
-(using Behavior elements) as well as state-transition animations can sometimes
-results in undefined behavior occurring.  Please see the documentation about
+It is important to note, that using default property animations (via the
+\l Behavior type) in combination with state-transition animations can sometimes
+result in undefined behavior occurring.  Please see the documentation about
 \l{qtquick-statesanimations-behaviors.html}
 {using Qt Quick Behaviors with States} for more information about this topic.
 
diff --git a/src/quick/doc/src/qmltypereference.qdoc b/src/quick/doc/src/qmltypereference.qdoc
index def84a3c50..a9ea971825 100644
--- a/src/quick/doc/src/qmltypereference.qdoc
+++ b/src/quick/doc/src/qmltypereference.qdoc
@@ -177,16 +177,7 @@ Visual object transformations
 \li \l {Translate} - Assigns item translation behaviors
 \endlist
 
-\section1 Interceptors
-
-\list
-\li \l {Connections} - Explicitly connects signals and signal handlers
-\li \l {Binding} - Binds any value to any property
-\li \l {Timer} - Provides timed triggers
-\li \l {Behavior} - Triggers animations when a property value is set
-\endlist
-
-\section1 Model/View Types and Data Storage and Access
+\section1 Model/View Types And Data Storage And Access
 
 Models And Model Data
 \list
@@ -223,6 +214,16 @@ Data Storage
 \li The \l{QtQuick.Particles 2} module provides a set of Particle System types for QtQuick 2
 \endlist
 
+\section1 Convenience Types
+
+\list
+\li \l {Loader} - Eases on-demand loading of items or components
+\li \l {Connections} - Explicitly connects signals and signal handlers
+\li \l {Binding} - Binds any value to any property
+\li \l {Timer} - Provides timed triggers
+\li \l {WorkerScript} - Enables the use of threads in a Qt Quick application
+\endlist
+
 \section1 Canvas (similar to HTML5 canvas)
 
 \list
@@ -234,17 +235,4 @@ Data Storage
 \li \l {TextMetrics} - Provides text and font measurement data for use in a Canvas
 \endlist
 
-\section1 Dynamic Instantiation Enablers
-
-\list
-\li \l {QML::Component} - Provides a type-instance factory allowing dynamic instantiation
-\li \l {Loader} - Controls the loading of items or components
-\endlist
-
-\section1 Threading
-
-\list
-\li \l {WorkerScript} - Enables the use of threads in a Qt Quick application
-\endlist
-
 */
diff --git a/src/quick/doc/src/qtquick.qdoc b/src/quick/doc/src/qtquick.qdoc
index 3b980c5212..a5900caa1e 100644
--- a/src/quick/doc/src/qtquick.qdoc
+++ b/src/quick/doc/src/qtquick.qdoc
@@ -53,13 +53,12 @@ a first-class concept in Qt Quick.
 
 \list
 \li \l{qtquick-visualcanvas-topic.html}{The Visual Canvas}
-\li \l{qtquick-positioning-topic.html}{Positioning}
 \li \l{qtquick-input-topic.html}{User Input}
-\li \l{qtquick-eventinterceptors-topic.html}{Event Interceptors}
-\li \l{qtquick-statesanimations-topic.html}{States, Transitions and Animations}
+\li \l{qtquick-positioning-topic.html}{Positioning}
+\li \l{qtquick-statesanimations-topic.html}{States, Transitions And Animations}
 \li \l{qtquick-modelviewsdata-topic.html}{Data - Models, Views and Data Storage}
-\li \l{qtquick-effects-topic.html}{Graphical Effects and Particles}
-\li \l{qtquick-dynamicinstantiation-topic.html}{Dynamic and Lazy Instantiation}
+\li \l{qtquick-effects-topic.html}{Particles And Graphical Effects}
+\li \l{qtquick-convenience-topic.html}{Convenience Types}
 \endlist
 
 When using the QtQuick module, you will need to know how to write QML
@@ -79,17 +78,16 @@ To find out more about using the QML language, see the \l{Qt QML Module Document
         \li \l{qtquick-qmltypereference.html#visual-types}{Visual Types}
         \li \l{qtquick-qmltypereference.html#user-input-types}{User Input Types}
         \li \l{qtquick-qmltypereference.html#positioning}{Positioning}
-        \li \l{qtquick-qmltypereference.html#states-transitions-and-animations}{States, Transitions and Animations}
-        \li \l{qtquick-qmltypereference.html#interceptors}{Interceptors}
-        \li \l{qtquick-qmltypereference.html#model-view-types-and-data-storage-and-access}{Model/View Types and Data Storage and Access}
-        \li \l{qtquick-qmltypereference.html#particles-and-graphical-effects}{Particles and Graphical Effects}
+        \li \l{qtquick-qmltypereference.html#states-transitions-and-animations}{States, Transitions And Animations}
+        \li \l{qtquick-qmltypereference.html#model-view-types-and-data-storage-and-access}{Model/View Types And Data Storage And Access}
+        \li \l{qtquick-qmltypereference.html#particles-and-graphical-effects}{Particles And Graphical Effects}
+        \li \l{qtquick-qmltypereference.html#convenience-types}{Convenience Types}
         \li \l{qtquick-qmltypereference.html#canvas-similar-to-html5-canvas}{Canvas (similar to HTML5 Canvas)}
-        \li \l{qtquick-qmltypereference.html#dynamic-instantiation-enablers}{Dynamic Instantiation Enablers}
         \endlist
 
     \li \l{qtquick-cppextensionpoints.html}{C++ Extension Points}
         \list
-        \li \l{qtquick-cppextensionpoints.html#user-defined-qquickitem-derived-types}{User-Defined QQuickItem-Derived Types}
+        \li \l{qtquick-cppextensionpoints.html#user-defined-qquickitem-derived-types}{Creating User-Defined QQuickItem-Derived Types}
         \li \l{qtquick-cppextensionpoints.html#scene-graph-related-classes}{Scene Graph-Related Classes}
         \endlist