5 files changed, 127 insertions, 10 deletions

diff --git a/src/declarative/util/qmlanimation.cpp b/src/declarative/util/qmlanimation.cpp
index 959f38b..d78f0a1 100644
--- a/src/declarative/util/qmlanimation.cpp
+++ b/src/declarative/util/qmlanimation.cpp
@@ -1085,7 +1085,33 @@ QML_DEFINE_TYPE(Qt,4,6,PropertyAction,QmlPropertyAction)
 /*!
     \qmlclass ParentAction QmlParentAction
     \inherits Animation
-    \brief The ParentAction allows parent changes during transitions.
+    \brief The ParentAction element allows parent changes during animation.
+
+    ParentAction provides a way to specify at what point in a Transition a ParentChange should
+    occur.
+    \qml
+    State {
+        ParentChange {
+            target: myItem
+            parent: newParent
+        }
+    }
+    Transition {
+        SequentialAnimation {
+            PropertyAnimation { ... }
+            ParentAction {}   //reparent myItem now
+            PropertyAnimation { ... }
+        }
+    }
+    \endqml
+
+    It also provides a way to explicitly reparent an item during an animation.
+    \qml
+    SequentialAnimation {
+        ParentAction { target: myItem; parent: newParent }
+        PropertyAnimation {}
+    }
+    \endqml
 
     The ParentAction is immediate - it is not animated in any way.
 */
@@ -1108,6 +1134,11 @@ void QmlParentActionPrivate::init()
     QmlGraphics_setParent_noEvent(cpa, q);
 }
 
+/*!
+    \qmlproperty Item ParentAction::target
+
+    This property holds an explicit target item to reparent.
+ */
 QmlGraphicsItem *QmlParentAction::object() const
 {
     Q_D(const QmlParentAction);
@@ -1120,6 +1151,52 @@ void QmlParentAction::setObject(QmlGraphicsItem *target)
     d->pcTarget = target;
 }
 
+/*!
+    \qmlproperty Item ParentAction::matchTarget
+    This property holds the item this action will match against -- the item
+    that the action will reparent, assuming its parent has changed.
+
+    In the following example, \c myItem will be reparented by the ParentAction, while
+    \c myOtherItem will not.
+    \qml
+    State {
+        ParentChange {
+            target: myItem
+            parent: newParent
+        }
+        ParentChange {
+            target: myOtherItem
+            parent: otherNewParent
+        }
+    }
+    Transition {
+        SequentialAnimation {
+            PropertyAnimation { ... }
+            ParentAction { matchTargets: myItem }
+            PropertyAnimation { ... }
+        }
+    }
+    \endqml
+
+    This property is typically used for an action appearing as part of a Transition.
+ */
+QmlGraphicsItem *QmlParentAction::matchTarget() const
+{
+    Q_D(const QmlParentAction);
+    return d->pcTarget;
+}
+
+void QmlParentAction::setMatchTarget(QmlGraphicsItem *target)
+{
+    Q_D(QmlParentAction);
+    d->pcMatchTarget = target;
+}
+
+/*!
+    \qmlproperty Item ParentAction::parent
+
+    The item to reparent to (i.e. the new parent).
+ */
 QmlGraphicsItem *QmlParentAction::parent() const
 {
     Q_D(const QmlParentAction);
@@ -1176,23 +1253,29 @@ void QmlParentAction::transition(QmlStateActions &actions,
 
     QmlParentActionData *data = new QmlParentActionData;
 
-    bool explicitMatchFound = false;
+    if (d->pcTarget && d->pcMatchTarget) {
+        qmlInfo(this) << tr("matchTarget and target are mutually exclusive.");
+        return;
+    }
 
     for (int ii = 0; ii < actions.count(); ++ii) {
         Action &action = actions[ii];
 
         if (action.event && action.event->typeName() == QLatin1String("ParentChange")
-            && (!d->target || static_cast<QmlParentChange*>(action.event)->object() == d->target)) {
+            && !d->pcTarget
+            && (!d->pcMatchTarget || static_cast<QmlParentChange*>(action.event)->object() == d->pcMatchTarget)) {
             Action myAction = action;
             data->reverse = action.reverseEvent;
+            //### this logic differs from PropertyAnimation
+            //    (probably a result of modified vs. done)
             if (d->pcParent) {
+                //### should we disallow this case?
                 QmlParentChange *pc = new QmlParentChange;
                 pc->setObject(d->pcTarget);
-                pc->setParent(d->pcParent);
+                pc->setParent(static_cast<QmlParentChange*>(action.event)->parent());
                 myAction.event = pc;
                 data->pc = pc;
                 data->actions << myAction;
-                if (d->target) explicitMatchFound = true;
                 break;  //only match one
             } else {
                 action.actionDone = true;
@@ -1201,7 +1284,7 @@ void QmlParentAction::transition(QmlStateActions &actions,
         }
     }
 
-    if (!explicitMatchFound && d->pcTarget && d->pcParent) {
+    if (d->pcTarget && d->pcParent) {
         data->reverse = false;
         Action myAction;
         QmlParentChange *pc = new QmlParentChange;
diff --git a/src/declarative/util/qmlanimation_p.h b/src/declarative/util/qmlanimation_p.h
index 0ed5082..f126dee 100644
--- a/src/declarative/util/qmlanimation_p.h
+++ b/src/declarative/util/qmlanimation_p.h
@@ -229,6 +229,7 @@ class QmlParentAction : public QmlAbstractAnimation
     Q_DECLARE_PRIVATE(QmlParentAction)
 
     Q_PROPERTY(QmlGraphicsItem *target READ object WRITE setObject)
+    Q_PROPERTY(QmlGraphicsItem *matchTarget READ matchTarget WRITE setMatchTarget)
     Q_PROPERTY(QmlGraphicsItem *parent READ parent WRITE setParent)
 
 public:
@@ -238,6 +239,9 @@ public:
     QmlGraphicsItem *object() const;
     void setObject(QmlGraphicsItem *);
 
+    QmlGraphicsItem *matchTarget() const;
+    void setMatchTarget(QmlGraphicsItem *);
+
     QmlGraphicsItem *parent() const;
     void setParent(QmlGraphicsItem *);
 
diff --git a/src/declarative/util/qmlanimation_p_p.h b/src/declarative/util/qmlanimation_p_p.h
index c66fa7a..e50415f 100644
--- a/src/declarative/util/qmlanimation_p_p.h
+++ b/src/declarative/util/qmlanimation_p_p.h
@@ -271,11 +271,12 @@ class QmlParentActionPrivate : public QmlAbstractAnimationPrivate
     Q_DECLARE_PUBLIC(QmlParentAction)
 public:
     QmlParentActionPrivate()
-    : QmlAbstractAnimationPrivate(), pcTarget(0), pcParent(0) {}
+    : QmlAbstractAnimationPrivate(), pcTarget(0), pcMatchTarget(0), pcParent(0) {}
 
     void init();
 
     QmlGraphicsItem *pcTarget;
+    QmlGraphicsItem *pcMatchTarget;
     QmlGraphicsItem *pcParent;
 
     void doAction();
diff --git a/src/declarative/util/qmlpropertychanges.cpp b/src/declarative/util/qmlpropertychanges.cpp
index da8aa7e..a1e92b5 100644
--- a/src/declarative/util/qmlpropertychanges.cpp
+++ b/src/declarative/util/qmlpropertychanges.cpp
@@ -287,6 +287,15 @@ void QmlPropertyChanges::setObject(QObject *o)
     d->object = 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.
+*/
 bool QmlPropertyChanges::restoreEntryValues() const
 {
     Q_D(const QmlPropertyChanges);
@@ -380,6 +389,25 @@ QmlPropertyChanges::ActionList QmlPropertyChanges::actions()
     return list;
 }
 
+/*!
+    \qmlproperty bool PropertyChanges::explicit
+
+    If explicit is set to true, any potential bindings will be interpreted as
+    once-off assignments that occur when the state is entered.
+
+    In the following example, the addition of explicit prevents myItem.width from
+    being bound to parent.width. Instead, it is assigned the value of parent.width
+    at the time of the state change.
+    \qml
+    PropertyChanges {
+        target: myItem
+        explicit: true
+        width: parent.width
+    }
+    \endqml
+
+    By default, explicit is false.
+*/
 bool QmlPropertyChanges::isExplicit() const
 {
     Q_D(const QmlPropertyChanges);
diff --git a/src/declarative/util/qmlstateoperations.cpp b/src/declarative/util/qmlstateoperations.cpp
index 7e0ac66..2d32fdb 100644
--- a/src/declarative/util/qmlstateoperations.cpp
+++ b/src/declarative/util/qmlstateoperations.cpp
@@ -76,18 +76,19 @@ void QmlParentChangePrivate::doChange(QmlGraphicsItem *targetParent, QmlGraphics
         const QTransform &transform = target->itemTransform(targetParent, &ok);
         if (transform.type() >= QTransform::TxShear || !ok) {
             qmlInfo(q) << QObject::tr("Unable to preserve appearance under complex transform");
+            ok = false;
         }
 
         qreal scale = 1;
         qreal rotation = 0;
-        if (transform.type() != QTransform::TxRotate) {
+        if (ok && transform.type() != QTransform::TxRotate) {
             if (transform.m11() == transform.m22())
                 scale = transform.m11();
             else {
                 qmlInfo(q) << QObject::tr("Unable to preserve appearance under non-uniform scale");
                 ok = false;
             }
-        } else if (transform.type() == QTransform::TxRotate) {
+        } else if (ok && transform.type() == QTransform::TxRotate) {
             if (transform.m11() == transform.m22())
                 scale = qSqrt(transform.m11()*transform.m11() + transform.m12()*transform.m12());
             else {
@@ -105,7 +106,7 @@ void QmlParentChangePrivate::doChange(QmlGraphicsItem *targetParent, QmlGraphics
 
         qreal xt = transform.dx();
         qreal yt = transform.dy();
-        if (target->transformOrigin() != QmlGraphicsItem::TopLeft) {
+        if (ok && target->transformOrigin() != QmlGraphicsItem::TopLeft) {
             qreal tempxt = target->transformOriginPoint().x();
             qreal tempyt = target->transformOriginPoint().y();
             QTransform t;