Rename QState::polished() signal to "propertiesAssigned"

"Polished" was never a very descriptive word, and it already has a
meaning attached in the QStyle API. Additionally, "propertiesAssigned"
has the benefit of giving the relation to the assignProperty() function
as part of the name.

Reviewed-by: Kent Hansen

9 files changed, 47 insertions, 40 deletions

diff --git a/doc/src/examples/stickman.qdoc b/doc/src/examples/stickman.qdoc
index e70c39b..c9e98d0 100644
--- a/doc/src/examples/stickman.qdoc
+++ b/doc/src/examples/stickman.qdoc
@@ -55,9 +55,9 @@
     Animations are implemented as composite states. Each child state of the animation state 
     represents a frame in the animation by setting the position of each joint in the stickman's 
     skeleton to the positions defined for the particular frame. The frames are then bound together 
-    with animated transitions that trigger on the source state's polished() signal. Thus, the 
-    machine will enter the state representing the next frame in the animation immediately after it
-    has finished animating into the previous frame.
+    with animated transitions that trigger on the source state's propertiesAssigned() signal. Thus,
+    the machine will enter the state representing the next frame in the animation immediately after
+    it has finished animating into the previous frame.
     
     \image stickman-example1.png
         
@@ -67,7 +67,8 @@
     
     \snippet examples/animation/stickman/lifecycle.cpp 1
     
-    The states are then bound together with signal transitions that listen to the polished() signal.
+    The states are then bound together with signal transitions that listen to the
+    propertiesAssigned() signal.
     
     \snippet examples/animation/stickman/lifecycle.cpp 2
     
diff --git a/doc/src/frameworks-technologies/statemachine.qdoc b/doc/src/frameworks-technologies/statemachine.qdoc
index ac10314..708561d 100644
--- a/doc/src/frameworks-technologies/statemachine.qdoc
+++ b/doc/src/frameworks-technologies/statemachine.qdoc
@@ -501,9 +501,9 @@
   message box will pop up before the geometry of the button has actually been set.
 
   To ensure that the message box does not pop up until the geometry actually reaches its final
-  value, we can use the state's polished() signal. The polished() signal will be emitted when the
-  the property is assigned its final value, whether this is done immediately or after the animation
-  has finished playing.
+  value, we can use the state's propertiesAssigned() signal. The propertiesAssigned() signal will be
+  emitted when the property is assigned its final value, whether this is done immediately or
+  after the animation has finished playing.
   \code
   \snippet doc/src/snippets/statemachine/main5.cpp 6
   \endcode
@@ -519,14 +519,14 @@
   has been assigned the defined value.
 
   If the global restore policy is set to QStateMachine::RestoreProperties, the state will not emit
-  the polished() signal until these have been executed as well.
+  the propertiesAssigned() signal until these have been executed as well.
 
   \section1 What Happens If A State Is Exited Before The Animation Has Finished
 
   If a state has property assignments, and the transition into the state has animations for the
   properties, the state can potentially be exited before the properties have been assigned to the
   values defines by the state. This is true in particular when there are transitions out from the
-  state that do not depend on the state being polished, as described in the previous section.
+  state that do not depend on the propertiesAssigned signal, as described in the previous section.
 
   The State Machine API guarantees that a property assigned by the state machine either:
   \list
diff --git a/doc/src/snippets/statemachine/main5.cpp b/doc/src/snippets/statemachine/main5.cpp
index 346cbce..ff25b7b 100644
--- a/doc/src/snippets/statemachine/main5.cpp
+++ b/doc/src/snippets/statemachine/main5.cpp
@@ -145,7 +145,7 @@ int main(int argv, char **args)
     connect(s3, SIGNAL(entered()), messageBox, SLOT(exec()));
 
     s1->addTransition(button, SIGNAL(clicked()), s2);
-    s2->addTransition(s2, SIGNAL(polished()), s3);
+    s2->addTransition(s2, SIGNAL(propertiesAssigned()), s3);
 //![6]
 
   }
diff --git a/examples/animation/stickman/lifecycle.cpp b/examples/animation/stickman/lifecycle.cpp
index 250fb85..1b6f9cd 100644
--- a/examples/animation/stickman/lifecycle.cpp
+++ b/examples/animation/stickman/lifecycle.cpp
@@ -194,14 +194,14 @@ QState *LifeCycle::makeState(QState *parentState, const QString &animationFileNa
             topLevel->setInitialState(frameState);
         else
 //! [2]
-            previousState->addTransition(previousState, SIGNAL(polished()), frameState);
+            previousState->addTransition(previousState, SIGNAL(propertiesAssigned()), frameState);
 //! [2]
         
         previousState = frameState;
     }
 
     // Loop
-    previousState->addTransition(previousState, SIGNAL(polished()), topLevel->initialState());
+    previousState->addTransition(previousState, SIGNAL(propertiesAssigned()), topLevel->initialState());
 
     return topLevel;
 
diff --git a/src/corelib/statemachine/qstate.cpp b/src/corelib/statemachine/qstate.cpp
index ea20619..6d89248 100644
--- a/src/corelib/statemachine/qstate.cpp
+++ b/src/corelib/statemachine/qstate.cpp
@@ -139,10 +139,10 @@ void QStatePrivate::emitFinished()
     emit q->finished();
 }
 
-void QStatePrivate::emitPolished()
+void QStatePrivate::emitPropertiesAssigned()
 {
     Q_Q(QState);
-    emit q->polished();
+    emit q->propertiesAssigned();
 }
 
 /*!
@@ -228,7 +228,7 @@ QList<QAbstractTransition*> QStatePrivate::transitions() const
   Instructs this state to set the property with the given \a name of the given
   \a object to the given \a value when the state is entered.
 
-  \sa polished()
+  \sa propertiesAssigned()
 */
 void QState::assignProperty(QObject *object, const char *name,
                             const QVariant &value)
@@ -491,9 +491,15 @@ bool QState::event(QEvent *e)
 */
 
 /*!
-  \fn QState::polished()
+  \fn QState::propertiesAssigned()
 
-  This signal is emitted when all properties have been assigned their final value.
+  This signal is emitted when all properties have been assigned their final value. If the state
+  assigns a value to one or more properties for which an animation exists (either set on the
+  transition or as a default animation on the state machine), then the signal will not be emitted
+  until all such animations have finished playing.
+
+  If there are no relevant animations, or no property assignments defined for the state, then
+  the signal will be emitted immediately before the state is entered.
 
   \sa QState::assignProperty(), QAbstractTransition::addAnimation()
 */
diff --git a/src/corelib/statemachine/qstate.h b/src/corelib/statemachine/qstate.h
index 781382d..423f940 100644
--- a/src/corelib/statemachine/qstate.h
+++ b/src/corelib/statemachine/qstate.h
@@ -94,7 +94,7 @@ public:
 
 Q_SIGNALS:
     void finished();
-    void polished();
+    void propertiesAssigned();
 
 protected:
     void onEntry(QEvent *event);
diff --git a/src/corelib/statemachine/qstate_p.h b/src/corelib/statemachine/qstate_p.h
index 34c8838..7fe6279 100644
--- a/src/corelib/statemachine/qstate_p.h
+++ b/src/corelib/statemachine/qstate_p.h
@@ -94,7 +94,7 @@ public:
     QList<QAbstractTransition*> transitions() const;
 
     void emitFinished();
-    void emitPolished();
+    void emitPropertiesAssigned();
 
     QAbstractState *errorState;
     QAbstractState *initialState;
diff --git a/src/corelib/statemachine/qstatemachine.cpp b/src/corelib/statemachine/qstatemachine.cpp
index 0d07093..0648d14 100644
--- a/src/corelib/statemachine/qstatemachine.cpp
+++ b/src/corelib/statemachine/qstatemachine.cpp
@@ -807,7 +807,7 @@ void QStateMachinePrivate::applyProperties(const QList<QAbstractTransition*> &tr
             if (anim->state() == QAbstractAnimation::Running) {
                 // The animation is still running. This can happen if the
                 // animation is a group, and one of its children just finished,
-                // and that caused a state to emit its polished() signal, and
+                // and that caused a state to emit its propertiesAssigned() signal, and
                 // that triggered a transition in the machine.
                 // Just stop the animation so it is correctly restarted again.
                 anim->stop();
@@ -829,7 +829,7 @@ void QStateMachinePrivate::applyProperties(const QList<QAbstractTransition*> &tr
         }
     }
 
-    // Emit polished signal for entered states that have no animated properties.
+    // Emit propertiesAssigned signal for entered states that have no animated properties.
     for (int i = 0; i < enteredStates.size(); ++i) {
         QState *s = qobject_cast<QState*>(enteredStates.at(i));
         if (s 
@@ -837,7 +837,7 @@ void QStateMachinePrivate::applyProperties(const QList<QAbstractTransition*> &tr
             && !animationsForState.contains(s)
 #endif
             )
-            QStatePrivate::get(s)->emitPolished();
+            QStatePrivate::get(s)->emitPropertiesAssigned();
     }
 }
 
@@ -1100,7 +1100,7 @@ void QStateMachinePrivate::_q_animationFinished()
     animations.removeOne(anim);
     if (animations.isEmpty()) {
         animationsForState.erase(it);
-        QStatePrivate::get(qobject_cast<QState*>(state))->emitPolished();
+        QStatePrivate::get(qobject_cast<QState*>(state))->emitPropertiesAssigned();
     }
 }
 
diff --git a/tests/auto/qstatemachine/tst_qstatemachine.cpp b/tests/auto/qstatemachine/tst_qstatemachine.cpp
index fb6567a..9a2b2ed 100644
--- a/tests/auto/qstatemachine/tst_qstatemachine.cpp
+++ b/tests/auto/qstatemachine/tst_qstatemachine.cpp
@@ -184,7 +184,7 @@ private slots:
     void twoAnimatedTransitions();
     void playAnimationTwice();
     void nestedTargetStateForAnimation();
-    void polishedSignalTransitionsReuseAnimationGroup();
+    void propertiesAssignedSignalTransitionsReuseAnimationGroup();
     void animatedGlobalRestoreProperty();
     void specificTargetValueOfAnimation();
 
@@ -1319,9 +1319,9 @@ void tst_QStateMachine::assignProperty()
     QCOMPARE(s1->objectName(), QString::fromLatin1("foo"));
 
     {
-        QSignalSpy polishedSpy(s1, SIGNAL(polished()));
+        QSignalSpy propertiesAssignedSpy(s1, SIGNAL(propertiesAssigned()));
         machine.start();
-        QTRY_COMPARE(polishedSpy.count(), 1);
+        QTRY_COMPARE(propertiesAssignedSpy.count(), 1);
     }
 
     // nested states
@@ -1371,7 +1371,7 @@ void tst_QStateMachine::assignPropertyWithAnimation()
         QCOMPARE(trans->animations().size(), 1);
         QCOMPARE(trans->animations().at(0), (QAbstractAnimation*)&anim);
         QFinalState *s3 = new QFinalState(&machine);
-        s2->addTransition(s2, SIGNAL(polished()), s3);
+        s2->addTransition(s2, SIGNAL(propertiesAssigned()), s3);
 
         machine.setInitialState(s1);
         QSignalSpy finishedSpy(&machine, SIGNAL(finished()));
@@ -1399,7 +1399,7 @@ void tst_QStateMachine::assignPropertyWithAnimation()
         anim2.setDuration(150);
         trans->addAnimation(&anim2);
         QFinalState *s3 = new QFinalState(&machine);
-        s2->addTransition(s2, SIGNAL(polished()), s3);
+        s2->addTransition(s2, SIGNAL(propertiesAssigned()), s3);
 
         machine.setInitialState(s1);
         QSignalSpy finishedSpy(&machine, SIGNAL(finished()));
@@ -1427,7 +1427,7 @@ void tst_QStateMachine::assignPropertyWithAnimation()
         group.addAnimation(new QPropertyAnimation(&obj, "bar"));
         trans->addAnimation(&group);
         QFinalState *s3 = new QFinalState(&machine);
-        s2->addTransition(s2, SIGNAL(polished()), s3);
+        s2->addTransition(s2, SIGNAL(propertiesAssigned()), s3);
 
         machine.setInitialState(s1);
         QSignalSpy finishedSpy(&machine, SIGNAL(finished()));
@@ -1473,10 +1473,10 @@ void tst_QStateMachine::assignPropertyWithAnimation()
         anim2.setDuration(250);
         trans->addAnimation(&anim2);
 
-        s21->addTransition(s21, SIGNAL(polished()), s22);
+        s21->addTransition(s21, SIGNAL(propertiesAssigned()), s22);
 
         QFinalState *s3 = new QFinalState(&machine);
-        s22->addTransition(s2, SIGNAL(polished()), s3);
+        s22->addTransition(s2, SIGNAL(propertiesAssigned()), s3);
 
         machine.setInitialState(s1);
         QSignalSpy finishedSpy(&machine, SIGNAL(finished()));
@@ -1513,13 +1513,13 @@ void tst_QStateMachine::assignPropertyWithAnimation()
         machine.setInitialState(group);
         machine.start();
         QTRY_COMPARE(machine.configuration().contains(s1), true);
-        QSignalSpy polishedSpy(s2, SIGNAL(polished()));
+        QSignalSpy propertiesAssignedSpy(s2, SIGNAL(propertiesAssigned()));
         emitter.emitSignalWithNoArg();
         QTRY_COMPARE(machine.configuration().contains(s2), true);
-        QVERIFY(polishedSpy.isEmpty());
+        QVERIFY(propertiesAssignedSpy.isEmpty());
         emitter.emitSignalWithNoArg(); // will cause animations from s1-->s2 to abort
         QTRY_COMPARE(machine.configuration().contains(s3), true);
-        QVERIFY(polishedSpy.isEmpty());
+        QVERIFY(propertiesAssignedSpy.isEmpty());
         QCOMPARE(obj.property("foo").toInt(), 911);
         QCOMPARE(obj.property("bar").toInt(), 789);
     }
@@ -3089,7 +3089,7 @@ void tst_QStateMachine::twoAnimations()
 
     QState *s3 = new QState(&machine);
     QObject::connect(s3, SIGNAL(entered()), QCoreApplication::instance(), SLOT(quit()));
-    s2->addTransition(s2, SIGNAL(polished()), s3);
+    s2->addTransition(s2, SIGNAL(propertiesAssigned()), s3);
 
     machine.setInitialState(s1);
     machine.start();
@@ -3241,7 +3241,7 @@ void tst_QStateMachine::nestedTargetStateForAnimation()
     at->addAnimation(animation);
 
     QState *s3 = new QState(&machine);
-    s2->addTransition(s2Child, SIGNAL(polished()), s3);
+    s2->addTransition(s2Child, SIGNAL(propertiesAssigned()), s3);
 
     QObject::connect(s3, SIGNAL(entered()), QCoreApplication::instance(), SLOT(quit()));
 
@@ -3258,7 +3258,7 @@ void tst_QStateMachine::nestedTargetStateForAnimation()
     QCOMPARE(counter.counter, 2);
 }
 
-void tst_QStateMachine::polishedSignalTransitionsReuseAnimationGroup()
+void tst_QStateMachine::propertiesAssignedSignalTransitionsReuseAnimationGroup()
 {
     QStateMachine machine;
     QObject *object = new QObject(&machine);
@@ -3275,9 +3275,9 @@ void tst_QStateMachine::polishedSignalTransitionsReuseAnimationGroup()
     QParallelAnimationGroup animationGroup;
     animationGroup.addAnimation(new QPropertyAnimation(object, "foo"));
     QSignalSpy animationFinishedSpy(&animationGroup, SIGNAL(finished()));
-    s1->addTransition(s1, SIGNAL(polished()), s2)->addAnimation(&animationGroup);
-    s2->addTransition(s2, SIGNAL(polished()), s3)->addAnimation(&animationGroup);
-    s3->addTransition(s3, SIGNAL(polished()), s4);
+    s1->addTransition(s1, SIGNAL(propertiesAssigned()), s2)->addAnimation(&animationGroup);
+    s2->addTransition(s2, SIGNAL(propertiesAssigned()), s3)->addAnimation(&animationGroup);
+    s3->addTransition(s3, SIGNAL(propertiesAssigned()), s4);
 
     machine.setInitialState(s1);
     QSignalSpy machineFinishedSpy(&machine, SIGNAL(finished()));