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

1 files changed, 49 insertions, 71 deletions

diff --git a/src/declarative/util/qdeclarativepropertychanges.cpp b/src/declarative/util/qdeclarativepropertychanges.cpp
index 12c6353..c28ada3 100644
--- a/src/declarative/util/qdeclarativepropertychanges.cpp
+++ b/src/declarative/util/qdeclarativepropertychanges.cpp
@@ -61,51 +61,34 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \qmlclass PropertyChanges QDeclarativePropertyChanges
+    \ingroup qml-state-elements
     \since 4.7
     \brief The PropertyChanges element describes new property bindings or values for a state.
 
-    PropertyChanges provides a state change that modifies the properties of an item.
+    PropertyChanges is used to define the property values or bindings in a 
+    \l State. This enables an item's property values to be changed when it
+    \l {QML States}{changes between states}.
 
-    Here is a property change that modifies the text and color of a \l Text element
-    when it is clicked:
+    To create a PropertyChanges object, specify the \l target item whose 
+    properties are to be modified, and define the new property values or
+    bindings. For example:
     
-    \qml
-    Text {
-        id: myText
-        width: 100; height: 100
-        text: "Hello"
-        color: "blue"
-
-        states: State {
-            name: "myState"
-
-            PropertyChanges {
-                target: myText
-                text: "Goodbye"
-                color: "red"
-            }
-        }
-
-        MouseArea { anchors.fill: parent; onClicked: myText.state = 'myState' }
-    }
-    \endqml
-
-    By default, PropertyChanges will establish new bindings where appropriate.
-    For example, the following creates a new binding for myItem's \c height property.
-
-    \qml
-    PropertyChanges {
-        target: myItem
-        height: parent.height
-    }
-    \endqml
-
-    If you don't want a binding to be established (and instead just want to assign
-    the value of the binding at the time the state is entered),
-    you should set the PropertyChange's \l{PropertyChanges::explicit}{explicit}
+    \snippet doc/src/snippets/declarative/propertychanges.qml import 
+    \codeline
+    \snippet doc/src/snippets/declarative/propertychanges.qml 0
+
+    When the mouse is pressed, the \l Rectangle changes to the \e resized
+    state. In this state, the PropertyChanges object sets the rectangle's 
+    color to blue and the \c height value to that of \c container.height.
+
+    Note this automatically binds \c rect.height to \c container.height 
+    in the \e resized state. If a property binding should not be
+    established, and the height should just be set to the value of
+    \c container.height at the time of the state change, set the \l explicit
     property to \c true.
-    
-    State-specific script for signal handlers can also be specified:
+   
+    A PropertyChanges object can also override the default signal handler
+    for an object to implement a signal handler specific to the new state:
 
     \qml
     PropertyChanges {
@@ -114,36 +97,31 @@ QT_BEGIN_NAMESPACE
     }
     \endqml
 
-    You can reset a property in a state change by assigning \c undefined. In the following
-    example we reset \c theText's width when we enter state1. This will give the text its
-    natural width (which is the whole string on one line).
+    \note PropertyChanges can be used to change anchor margins, but not other anchor
+    values; use AnchorChanges for this instead. Similarly, to change an \l Item's
+    \l {Item::}{parent} value, use ParentChanges instead.
 
-    \qml
-    import Qt 4.7
-
-    Rectangle {
-        width: 640
-        height: 480
-        Text {
-            id: theText
-            width: 50
-            wrapMode: Text.WordWrap
-            text: "a text string that is longer than 50 pixels"
-        }
 
-        states: State {
-            name: "state1"
-            PropertyChanges {
-                target: theText
-                width: undefined
-            }
-        }
-    }
-    \endqml
+    \section2 Resetting property values
 
-    Anchor margins should be changed with PropertyChanges, but other anchor changes or changes to
-    an Item's parent should be done using the associated change elements
-    (ParentChange and AnchorChanges, respectively).
+    The \c undefined value can be used to reset the property value for a state.
+    In the following example, when \c theText changes to the \e widerText
+    state, its \c width property is reset, giving the text its natural width
+    and displaying the whole string on a single line.
+
+    \snippet doc/src/snippets/declarative/propertychanges.qml reset
+
+
+    \section2 Immediate property changes in transitions
+
+    When \l Transitions are used to animate state changes, they animate 
+    properties from their values in the current state to those defined in the
+    new state (as defined by PropertyChanges objects). However, 
+    it is sometimes desirable to set a property value \e immediately during a 
+    \l Transition, without animation; in these cases, the PropertyAction 
+    element can be used to force an immediate property change.
+
+    See the PropertyAction documentation for more details.
 
     \sa {declarative/animation/states}{states example}, {qmlstate}{States}, QtDeclarative
 */
@@ -396,12 +374,12 @@ void QDeclarativePropertyChanges::setObject(QObject *o)
 
 /*!
     \qmlproperty bool PropertyChanges::restoreEntryValues
-    
-    Whether or not the previous values should be restored when
-    leaving the state. By default, restoreEntryValues is true.
 
-    By setting restoreEntryValues to false, you can create a temporary state
-    that has permanent effects on property values.
+    This property holds whether the previous values should be restored when
+    leaving the state. 
+
+    The default value is \c true. Setting this value to \c false creates a
+    temporary state that has permanent effects on property values.
 */
 bool QDeclarativePropertyChanges::restoreEntryValues() const
 {