Merge branch '4.7' into qmldocs

5 files changed, 225 insertions, 150 deletions

diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc
index 7416341..53a0c55 100644
--- a/doc/src/declarative/animation.qdoc
+++ b/doc/src/declarative/animation.qdoc
@@ -156,11 +156,13 @@ The \l {PropertyAnimation::}{to} property is also required to specify the new
 \section2 Standalone Animations
 
 Animations can also be created as ordinary QML objects that are not bound to
-any particular objects and properties. An example:
+any particular objects and properties. Here is an example, using a 
+PropertyAnimation object. The animation is explicitly started when the 
+\l Rectangle is clicked:
 
 \snippet doc/src/snippets/declarative/animation-standalone.qml 0
 
-A standalone animation is not running by default and must be started explicitly
+A standalone animation object is not running by default and must be started explicitly
 using the \l {Animation::}{running} property or \l {Animation::}{start()} and
 \l {Animation::}{stop()} methods. Since the animation is not bound to a
 particular object or property, it must define the \l
@@ -183,10 +185,13 @@ object and add it to an item's \l {Item::}{transitions} property. An example:
 
 \snippet doc/src/snippets/declarative/animation-transitions.qml 0
 
-When the \l Rectangle changes to the \e moved state, its \c x and \c y property
-values are changed by the PropertyChanges object, and the PropertyAnimation
-defined within the \l Transition is triggered on these properties. The
-animation will not be applied at any time other than during the state change.
+The PropertyChanges object in the \e moved state defines that when the
+\l Rectangle is in this state, its position should be changed
+to (50, 50). When the \l Rectangle changes to the \e moved state, the 
+\l Transition will be triggered, and the transition's \l PropertyAnimation will
+animate the changes in the \c x and \c y properties to their new values.
+The animation will not be applied at any time other than during the state 
+change.
 
 Notice the example does not set any \l {PropertyAnimation::}{from} and \l
 {PropertyAnimation::}{to} values for the PropertyAnimation. As a convenience,
@@ -234,7 +239,7 @@ and rotation changes.
 
 A ColorAnimation allows color values for the \l {ColorAnimation::}{from} 
 and \l {ColorAnimation::}{to} properties. The
-following animates the rectangle's \l {Rectangle::color} property:
+following animates the rectangle's \l {Rectangle::}{color} property:
 
 \snippet doc/src/snippets/declarative/animation-elements.qml color
 
diff --git a/doc/src/declarative/elements.qdoc b/doc/src/declarative/elements.qdoc
index 55b71e1..94abe10 100644
--- a/doc/src/declarative/elements.qdoc
+++ b/doc/src/declarative/elements.qdoc
@@ -26,112 +26,151 @@
 ****************************************************************************/
 
 /*!
-\page qmlelements.html
-\target elements
-\title QML Elements
-
-The following table lists the QML elements provided by the \l{QtDeclarative} module.
-
-\table 
-\header \o {2,1} \bold {Basic Visual Items}
-\row \o \l {Item} \o Basic item element inherited by all visual items in QML
-\row \o \l {Rectangle} \o Basic visual rectangle element
-\row \o \l {Gradient} \o Defines a gradient between two or more colors
-\row \o \l {GradientStop} \o Defines a color used in a \l {Gradient}
-\row \o \l {Image} \o Allows the use of bitmaps to a scene
-\row \o \l {BorderImage} (Item-specific) \o Defines an image as a border
-\row \o \l {AnimatedImage} \o For playing animations stored as a series of frames
-\row \o \l {Text} \o Allows the use of formatted text in a scene
-\row \o \l {TextInput} \o Displays an editable line of text
-\row \o \l {IntValidator} \o Validator for integer values
-\row \o \l {DoubleValidator} \o Validator for non-integer values
-\row \o \l {RegExpValidator} \o Validator for string regular expressions
-\row \o \l {TextEdit} \o Displays multiple lines of editable formatted text
-
-\header \o {2,1} \bold {Basic Interaction Items}
-\row \o \l {MouseArea} \o Handles mouse interactions
-\row \o \l {FocusScope} \o For keyboard focus handling 
-\row \o \l {Flickable} \o Provides a surface that can be "flicked"  
-\row \o \l {Flipable} \o Provides a surface that produces flipping effects
-\row \o \l {GestureArea} (experimental) \o Enables simple gesture handling
-
-\header \o {2,1} \bold {States}
-\row \o \l {State} \o Defines sets of configurations of objects and properties
-\row \o \l {PropertyChanges} \o Describes property changes within a state
-\row \o \l {StateGroup} \o Contains a set of states and state transitions
-\row \o \l {StateChangeScript} \o Allows script binding in a state
-\row \o \l {ParentChange} (Item-specific) \o Re-parent an Item in a state change
-\row \o \l {AnchorChanges} \o Change the anchors of an item in a state
-
-\header \o {2,1} \bold {Animation and Transitions}
-\row \o \l {Behavior} \o Specifies a default animation for property changes
-\row \o \l {SequentialAnimation} \o Runs animations sequentially
-\row \o \l {ParallelAnimation} \o Runs animations in parallel
-\row \o \l {PropertyAnimation} \o Animates property changes
-\row \o \l {NumberAnimation} \o Animates properties of type qreal
-\row \o \l {Vector3dAnimation} \o Animates properties of type QVector3d
-\row \o \l {ColorAnimation} \o Animates color changes
-\row \o \l {RotationAnimation} \o Animates rotations
-\row \o \l {ParentAnimation} \o Animates parent changes
-\row \o \l {AnchorAnimation} \o Animates anchor changes
-\row \o \l {PauseAnimation} \o Pauses an animation 
-\row \o \l {SmoothedAnimation} \o Allows a property to smoothly track a value
-\row \o \l {SpringAnimation} \o Allows a property to track a value in a spring-like motion
-\row \o \l {PropertyAction} \o Sets immediate property changes during animation
-\row \o \l {ScriptAction} \o Runs scripts during an animation
-\row \o \l {Transition} \o Animates transitions during state changes
-
-\header \o {2,1} \bold {Working with Data}
-\row \o \l {Binding} \o Binds any value to any property
-\row \o \l {ListModel} \o Defines a list of data
-\row \o \l {ListElement} \o Defines a data item in a \l {ListModel}
-\row \o \l {VisualItemModel} \o Contains items that already defines its own visual delegate
-\row \o \l {VisualDataModel} \o Encapsulates a model and a delegate
-\row \o \l {Package} \o Collection that enables sharing of items within different views
-\row \o \l {XmlListModel} \o Specifies a model using XPath expressions 
-\row \o \l {XmlRole}  \o Specifies a role for an \l {XmlListModel}
-
-\header \o {2,1} \bold {Views}
-\row \o \l {ListView} \o Provides a list visualization of a model
-\row \o \l {GridView} \o Provides a grid visualization of a model
-\row \o \l {PathView} \o Visualizes a model's contents along a path
-\row \o \l {Path} \o Defines a path used by \l {PathView}
-\row \o \l {PathLine}  \o Defines a line in \l {Path}
-\row \o \l {PathQuad}  \o Defines a quadratic Bezier curve in a \l {Path}
-\row \o \l {PathCubic}  \o Defines a cubic Bezier curve in a \l {Path}
-\row \o \l {PathAttribute}  \o Allows the setting of attributes along a \l {Path}
-\row \o \l {PathPercent}  \o Modifies the item distribution along a \l {Path}
-\row \o \l {WebView} \o Allows the addition of web content to a canvas
-
-\header \o {2,1} \bold {Positioners}
-\row \o \l {Column} \o Arranges its children vertically
-\row \o \l {Row} \o Arranges its children horizontally
-\row \o \l {Grid} \o Positions its children in a grid
-\row \o \l {Flow} \o Positions its children with wrapping support
-
-\header \o {2,1} \bold {Utility}
-\row \o \l {Connections} \o Explicitly connects signals and signal handlers
-\row \o \l {Component} \o Encapsulate QML items as a component
-\row \o \l {Timer} \o Provides timed triggers 
-\row \o \l {QML:QtObject} {QtObject} \o Basic element containing only the objectName property
-\row \o \l {WorkerScript} \o Enables the use of threads in QML
-\row \o \l {Loader} \o Controls the loading of items or components
-\row \o \l {Repeater} \o Uses a model to create multiples of components
-\row \o \l {SystemPalette} \o Provides access to the Qt palettes
-\row \o \l {FontLoader} \o Loads fonts by name or URL
-\row \o \l {LayoutItem} \o Allows declarative UI elements inside Qt's Graphics View layouts 
-
-\header \o {2,1} \bold {Transforms}
-\row \o \l {Scale} \o Assigns item scaling behaviors
-\row \o \l {Rotation} \o Assigns item rotation behaviors
-\row \o \l {Translate} \o Assigns item translation behaviors
-
-\header \o {2,1} \bold {Effects}
-\row \o \l {Particles} (experimental) \o Generates and animates particles
-\row \o \l {ParticleMotionLinear} \o Adds linear motion behavior to \l {Particles}
-\row \o \l {ParticleMotionGravity} \o Adds gravitational motion to \l {Particles}
-\row \o \l {ParticleMotionWander} \o Adds varied motions to \l {Particles}
-\endtable
+  \page qdeclarativeelements.html
+  \target elements
+  \title QML Elements
 
+  This is a dictionary of all the QML elements available in the \l
+  {QtDeclarative} {Qt Declarative} module. 
+
+  To see the QML elements listed by
+  functional area, \l{Groups Of Related QML Elements} {look here}.
+
+  \generatelist qmlclasses
+
+*/
+
+
+/*!
+    \group qml-groups
+    \title Groups Of Related QML Elements
+
+    \brief If you know what kind of QML element you want (Basic Visual, 
+    Interaction, Animation, etc), look here.
+
+    This is a list of functional groups of QML elements.
+
+    \generatelist{related}
+
+*/
+
+/*!
+    \group qml-basic-visual-elements
+    \title Basic QML Visual Elements
+    \ingroup qml-groups
+
+    \brief Elements for constructing basic visual items.
+
+    \generatelist{related}
+
+*/
+
+/*!
+    \group qml-basic-interaction-elements
+    \title Basic QML Interaction Elements
+    \ingroup qml-groups
+
+    \brief Elements for handling basic interactions.
+
+    \generatelist{related}
+
+*/
+
+/*!
+    \group qml-state-elements
+    \title QML State Elements
+    \ingroup qml-groups
+
+    \brief Elements for handling state changes.
+
+    \generatelist{related}
+
+*/
+
+/*!
+    \group qml-event-elements
+    \title QML Event Elements
+    \ingroup qml-groups
+
+    \brief Elements for handling events.
+
+    \generatelist{related}
+
+*/
+
+/*!
+    \group qml-animation-transition
+    \title QML Animation and Transition Elements
+    \ingroup qml-groups
+
+    \brief Elements for handling animations and transitions.
+
+    \generatelist{related}
+
+*/
+
+/*!
+    \group qml-working-with-data
+    \title Working With Data in QML
+    \ingroup qml-groups
+
+    \brief Elements for working with data.
+
+    \generatelist{related}
+
+*/
+
+/*!
+    \group qml-view-elements
+    \title QML View Elements
+    \ingroup qml-groups
+
+    \brief Elements for handling views.
+
+    \generatelist{related}
+
+*/
+
+/*!
+    \group qml-positioning-elements
+    \title QML Positioning Elements
+    \ingroup qml-groups
+
+    \brief Elements for positioning items.
+
+    \generatelist{related}
+
+*/
+
+/*!
+    \group qml-utility-elements
+    \title QML Utility Elements
+    \ingroup qml-groups
+
+    \brief Elements for handling misc operations.
+
+    \generatelist{related}
+
+*/
+
+/*!
+    \group qml-transform-elements
+    \title QML Transform Elements
+    \ingroup qml-groups
+
+    \brief Elements for handling transformations.
+
+    \generatelist{related}
+
+*/
+
+/*!
+    \group qml-particle-elements
+    \title QML Particle Elements
+    \ingroup qml-groups
+
+    \brief Elements for handling particle effects.
+
+    \generatelist{related}
 
 */
diff --git a/doc/src/declarative/example-slideswitch.qdoc b/doc/src/declarative/example-slideswitch.qdoc
index f056892..1a40f14 100644
--- a/doc/src/declarative/example-slideswitch.qdoc
+++ b/doc/src/declarative/example-slideswitch.qdoc
@@ -115,7 +115,7 @@ For more information on scripts see \l{Integrating JavaScript}.
 At this point, when the switch toggles between the two states the knob will instantly change its \c x position between 1 and 78.
 In order for the the knob to move smoothly we add a transition that will animate the \c x property with an easing curve for a duration of 200ms.
 
-For more information on transitions see \l{state-transitions}{QML Transitions}.
+For more information on transitions see \l{qdeclarativeanimation.html#transitions}{QML Transitions}.
 
 \section1 Usage
 The switch can be used in a QML file, like this:
diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc
index 9e51a40..467b7d0 100644
--- a/doc/src/declarative/modules.qdoc
+++ b/doc/src/declarative/modules.qdoc
@@ -302,5 +302,13 @@ For examples of \c qmldir files for plugins, see the
 \l {declarative/cppextensions/plugins}{Plugins} example and 
 \l {Tutorial: Writing QML extensions with C++}.
 
+
+\section1 Debugging
+
+The \c QML_IMPORT_TRACE environment variable can be useful for debugging
+when there are problems with finding and loading modules. See 
+\l{Debugging module imports} for more information.
+
+
 */
 /
diff --git a/doc/src/declarative/qdeclarativestates.qdoc b/doc/src/declarative/qdeclarativestates.qdoc
index 0b91756..274040a 100644
--- a/doc/src/declarative/qdeclarativestates.qdoc
+++ b/doc/src/declarative/qdeclarativestates.qdoc
@@ -84,18 +84,34 @@ Rectangle.
 
 \snippet doc/src/snippets/declarative/states.qml 0
  
-A \l State item defines all the changes to be made in the new state. You
+The \l State item defines all the changes to be made in the new state. It
 could specify additional properties to be changed, or create additional 
-PropertyChanges for other objects. (Note that a \l State can modify the
-properties of other objects, not just the object that owns the state.)
+PropertyChanges for other objects. It can also modify the properties of other 
+objects, not just the object that owns the state. For example:
 
-For example:
+\qml
+Rectangle {
+    ...
+    states: [
+        State {
+            name: "moved"
+            PropertyChanges { target: myRect; x: 50; y: 50; color: "blue" }
+            PropertyChanges { target: someOtherItem; width: 1000 }            
+        }
+    ]
+}
+\endqml
+
+As a convenience, if an item only has one state, its \l {Item::}{states} 
+property can be defined as a single \l State, without the square-brace list
+syntax:
 
 \qml
-State {
-    name: "moved"
-    PropertyChanges { target: myRect; x: 50; y: 50; color: "blue" }
-    PropertyChanges { target: someOtherItem; width: 1000 }            
+Item {
+    ...
+    states: State {
+        ...
+    }
 }
 \endqml
 
@@ -118,54 +134,61 @@ transitions between them.
 
 Of course, the \l Rectangle in the example above could have simply been moved
 by setting its position to (50, 50) in the mouse area's \c onClicked handler.
-However, aside from enabling batched property changes, the use of states allows
-an item to revert to its \e {default state}, which contains all of the items'
-initial property values before they were modified in a state change.
+However, aside from enabling batched property changes, one of the features of
+QML states is the ability of an item to revert to its \e {default state}.
+The default state contains all of an item's initial property values before 
+they were modified in a state change.
 
-The default state is specified by an empty string. If the MouseArea in the
-above example was changed to this:
+For example, suppose the \l Rectangle should move to (50,50) when the mouse is
+pressed, and then move back to its original position when the mouse is 
+released. This can be achieved by using the \l {State::}{when} property,
+like this:
 
-\qml
-MouseArea {
-    anchors.fill: parent
-    onClicked: myRect.state == 'moved' ? myRect.state = "" : myRect.state = 'moved';
-}
-\endqml      
-
-This would toggle the \l Rectangle's state between the \e moved and \e default
-states when clicked. The properties can be reverted to their initial
-values without requiring the definition of another \l State that defines these
-value changes.
+\qml 
+Rectangle {
+    ...
 
+    MouseArea {
+        id: mouseArea
+        anchors.fill: parent
+    }
 
+    states: State {
+        name: "moved"; when: mouseArea.pressed
+        ...
+    }
+}
+\endqml 
 
-\section1 The "when" property
+The \l {State::}{when} property is set to an expression that evaluates to
+\c true when the item should be set to that state. When the mouse is pressed,
+the state is changed to \e moved. When it is released, the item reverts to its
+\e default state, which defines all of the item's original property values.
 
-The \l {State::}{when} property is useful for specifying when a state should be
-applied. This can be set to an expression that evaluates to \c true when an
-item should change to a particular state.
+Alternatively, an item can be explicitly set to its default state by setting its
+\l {Item::}{state} property to an empty string (""). For example, instead of
+using the \l {State::}{when} property, the above code could be changed to:
 
-If the above example was changed to this:
- 
 \qml 
 Rectangle {
     ...
 
     MouseArea {
-        id: mouseArea
         anchors.fill: parent
+        onPressed: myRect.state = 'moved';
+        onReleased: myRect.state = '';
     }
 
     states: State {
-        name: "moved"; when: mouseArea.pressed
+        name: "moved"
         ...
     }
+}
 \endqml 
 
-The \l Rectangle would automatically change to the \e moved state when the
-mouse is pressed, and revert to the default state when it is released. This is
-simpler (and a better, more declarative method) than creating \c onPressed 
-and \c onReleased handlers in the MouseArea to set the current state.
+Obviously it makes sense to use the \l {State::}{when} property when possible
+as it provides a simpler (and a better, more declarative) solution than 
+assigning the state from signal handlers.
 
 
 \section1 Animating state changes