The State Machine Framework

Detecting That All Properties Have Been Set In A State

When animations are used to assign properties, a state no longer defines the exact values that a property will have when the machine is in the given state. While the animation is running, the property can potentially have any value, depending on the animation.

In some cases, it can be useful to be able to detect when the property has actually been assigned the value defined by a state.

Say we have the following code:

     QMessageBox *messageBox = new QMessageBox(mainWindow);
     messageBox->addButton(QMessageBox::Ok);
     messageBox->setText("Button geometry has been set!");
     messageBox->setIcon(QMessageBox::Information);

     QState *s1 = new QState();

     QState *s2 = new QState();
     s2->assignProperty(button, "geometry", QRectF(0, 0, 50, 50));
     connect(s2, SIGNAL(entered()), messageBox, SLOT(exec()));

     s1->addTransition(button, SIGNAL(clicked()), s2);

When button is clicked, the machine will transition into state s2, which will set the geometry of the button, and then pop up a message box to alert the user that the geometry has been changed.

In the normal case, where animations are not used, this will operate as expected. However, if an animation for the geometry of button is set on the transition between s1 and s2, the animation will be started when s2 is entered, but the geometry property will not actually reach its defined value before the animation is finished running. In this case, the 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 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.

     QMessageBox *messageBox = new QMessageBox(mainWindow);
     messageBox->addButton(QMessageBox::Ok);
     messageBox->setText("Button geometry has been set!");
     messageBox->setIcon(QMessageBox::Information);

     QState *s1 = new QState();

     QState *s2 = new QState();
     s2->assignProperty(button, "geometry", QRectF(0, 0, 50, 50));

     QState *s3 = new QState();
     connect(s3, SIGNAL(entered()), messageBox, SLOT(exec()));

     s1->addTransition(button, SIGNAL(clicked()), s2);
     s2->addTransition(s2, SIGNAL(propertiesAssigned()), s3);

In this example, when button is clicked, the machine will enter s2. It will remain in state s2 until the geometry property has been set to QRect(0, 0, 50, 50). Then it will transition into s3. When s3 is entered, the message box will pop up. If the transition into s2 has an animation for the geometry property, then the machine will stay in s2 until the animation has finished playing. If there is no such animation, it will simply set the property and immediately enter state s3.

Either way, when the machine is in state s3, you are guaranteed that the property geometry has been assigned the defined value.

If the global restore policy is set to QStateMachine::RestoreProperties, the state will not emit the propertiesAssigned() signal until these have been executed as well.

 QState *s1 = new QState();
 QState *s2 = new QState();

 s2->assignProperty(object, "fooBar", 2.0);
 s1->addTransition(s2);

 QStateMachine machine;
 machine.setInitialState(s1);
 machine.addDefaultAnimation(new QPropertyAnimation(object, "fooBar"));