|  | Home

# QtAbstractStateGroup Class Reference
[QtCore module]

The QtAbstractStateGroup class is the base class of states that can have children. More...

     #include <QtAbstractStateGroup>

Inherits QtAbstractState.

Inherited by QtParallelStateGroup and QtState.

- List of all members, including inherited members

### Public Types

- enum HistoryType { ShallowHistory, DeepHistory }
- enum RestorePolicy { GlobalRestorePolicy, DoNotRestoreProperties, RestoreProperties }

### Public Functions

- ~QtAbstractStateGroup ()
- QtAnimationState * addAnimatedTransition ( QtAbstractTransition * transition, QtAbstractState * targetState, QtAbstractAnimation * animation = 0 )
- QtAnimationState * addAnimatedTransition ( const QObject * sender, const char * signal, QtAbstractState * targetState, QtAbstractAnimation * animation = 0 )
- void addEntryAction ( QtStateAction * action )
- void addExitAction ( QtStateAction * action )
- void addFinishedTransition ( QtAbstractState * target )
- QtHistoryState * addHistoryState ( HistoryType type = ShallowHistory )
- void addTransition ( QtAbstractTransition * transition, QtAbstractState * target )
- void addTransition ( QtAbstractTransition * transition, const QList<QtAbstractState *> & targets )
- void addTransition ( const QObject * sender, const char * signal, QtAbstractState * target )
- void addTransition ( QtAbstractTransition * transition )
- void addTransition ( QtAbstractState * target )
- QtAbstractState * errorState () const
- void invokeMethodOnEntry ( QObject * object, const char * method, const QList<QVariant> & arguments = QList<QVariant> () )
- void invokeMethodOnExit ( QObject * object, const char * method, const QList<QVariant> & arguments = QList<QVariant> () )
- void removeTransition ( QtAbstractTransition * transition )
- RestorePolicy restorePolicy () const
- void setErrorState ( QtAbstractState * state )
- void setPropertyOnEntry ( QObject * object, const char * name, const QVariant & value )
- void setPropertyOnExit ( QObject * object, const char * name, const QVariant & value )
- void setRestorePolicy ( RestorePolicy restorePolicy )

- 1 public function inherited from QtAbstractState
- 29 public functions inherited from QObject

### Protected Functions

- QtAbstractStateGroup ( QtAbstractStateGroup * parent = 0 )

- 2 protected functions inherited from QtAbstractState
- 7 protected functions inherited from QObject

### Additional Inherited Members

- 1 property inherited from QObject
- 1 public slot inherited from QObject
- 1 signal inherited from QObject
- 1 public type inherited from QObject
- 4 static public members inherited from QObject
- 2 protected variables inherited from QObject

## Detailed Description

The QtAbstractStateGroup class is the base class of states that can have children.

The QtAbstractStateGroup class is the abstract base class of states that can have child states. QtAbstractStateGroup is part of The State Machine Framework.

The addTransition() function adds a transition. The removeTransition() function removes a transition.

     QtAbstractStateGroup *s1 = ...;
     QtAbstractState *s2 = ...;
     QPushButton button;
     s1->addTransition(&button, SIGNAL(clicked()), s2);

The addHistoryState() function adds a history state.

You can add actions to a state with the addEntryAction() and addExitAction() functions. The state executes the actions when the state is entered and exited, respectively.

QtState provides built-in actions for setting properties and invoking methods of QObjects. The setPropertyOnEntry() and setPropertyOnExit() functions are used for defining property assignments that should be performed when a state is entered and exited, respectively.

     QLabel label;
     QtStateMachine machine;
     QtState *s1 = new QtState();
     s1->setPropertyOnEntry(&label, "text"; "Entered state s1");
     machine.addState(s1);

The invokeMethodOnEntry() and invokeMethodOnExit() functions are used for defining method invocations that should be performed when a state is entered and exited, respectively.

     QtState *s2 = new QtState();
     s2->invokeMethodOnEntry(&label, "showMaximized");
     machine.addState(s2);

## Member Type Documentation

### enum QtAbstractStateGroup::HistoryType

This enum specifies the type of history that a QtHistoryState records.

Constant | Value | Description
--- | --- | ---
`QtAbstractStateGroup::ShallowHistory` | `0` | Only the immediate child states of the parent state are recorded. In this case a transition with the history state as its target will end up in the immediate child state that the parent was in the last time it was exited. This is the default.
`QtAbstractStateGroup::DeepHistory` | `1` | Nested states are recorded. In this case a transition with the history state as its target will end up in the most deeply nested descendant state the parent was in the last time it was exited.

### enum QtAbstractStateGroup::RestorePolicy

This enum specifies the restore policy type for a state. The restore policy takes effect when the machine enters a state which has entry actions of the type QtStateSetPropertyAction. If the restore policy of the state is set to RestoreProperties, the state machine will save the value of the property before the QtStateSetPropertyAction is executed.

Later, when the machine either enters a state which has its restore policy set to DoNotRestoreProperties or when it enters a state which does not set a value for the given property, the property will automatically be restored to its initial value. The state machine will only detect which properties are being set if they are being set using a QtStateSetPropertyAction object set as entry action on a state.

Special rules apply when using QtAnimationState. If a QtAnimationState registers that a property should be restored before entering the target state of its QtStateFinishedTransition, it will restore this property using a QtPropertyAnimation.

Only one initial value will be saved for any given property. If a value for a property has already been saved by the state machine, it will not be overwritten until the property has been successfully restored. Once the property has been restored, the state machine will clear the initial value until it enters a new state which sets the property and which has RestoreProperties as its restore policy.

Constant | Value | Description
--- | --- | ---
`QtAbstractStateGroup::GlobalRestorePolicy` | `0` | The restore policy for the state should be retrieved using QtStateMachine::globalRestorePolicy()
`QtAbstractStateGroup::DoNotRestoreProperties` | `1` | The state machine should not save the initial values of properties set in the state and restore them later.
`QtAbstractStateGroup::RestoreProperties` | `2` | The state machine should save the initial values of properties set in the state and restore them later.

See also setRestorePolicy(), restorePolicy(), addEntryAction(), and setPropertyOnEntry().

## Member Function Documentation

### QtAbstractStateGroup::QtAbstractStateGroup ( QtAbstractStateGroup * parent = 0 ) `[protected]`

Constructs a new state group with the given parent state.

### QtAbstractStateGroup::~QtAbstractStateGroup ()

Destroys this state group.

### QtAnimationState * QtAbstractStateGroup::addAnimatedTransition ( QtAbstractTransition * transition, QtAbstractState * targetState, QtAbstractAnimation * animation = 0 )

Adds an animated transition from the current state to targetState.

The animated transition has an intermediate QtAnimationState which plays animation before entering targetState. This QtAnimationState will be entered when transition is taken by the state machine. When the animation has finished playing, the targetState will be entered.

The new QtAnimationState object will become a child of targetState's parent state.

     QPushButton button;
     QtPropertyAnimation animation(&button, "geometry");
     animation.setEndValue(QRect(100, 100, 400, 400));

     QtStateMachine machine;

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

     QtTransition *transition = new QtTransition(MyEventType);
     s1->addAnimatedTransition(transition, s2, &animation);

The function returns the new QtAnimationState. This state can be used if you want to add additional transitions into or out from the animation state, and if you want to add additional animations.

See also QtAnimationState.

### QtAnimationState * QtAbstractStateGroup::addAnimatedTransition ( const QObject * sender, const char * signal, QtAbstractState * targetState, QtAbstractAnimation * animation = 0 )

This is an overloaded member function, provided for convenience.

Adds an animated transition from the current state to targetState for animation.

This function creates a QtSignalTransition for the sender and signal, and calls addAnimatedTransition() with this transition object.

### void QtAbstractStateGroup::addEntryAction ( QtStateAction * action )

Adds the given action to this state. The action will be executed when this state is entered. The state takes ownership of the action.

See also addExitAction().

### void QtAbstractStateGroup::addExitAction ( QtStateAction * action )

Adds the given action to this state. The action will be executed when this state is exited. The state takes ownership of the action.

See also addEntryAction().

### void QtAbstractStateGroup::addFinishedTransition ( QtAbstractState * target )

Adds a transition that's triggered by the finished event of this state, and that has the given target state.

See also QtStateFinishedEvent.

### QtHistoryState * QtAbstractStateGroup::addHistoryState ( HistoryType type = ShallowHistory )

Creates a history state of the given type for this state and returns the new state. The history state becomes a child of this state.

### void QtAbstractStateGroup::addTransition ( QtAbstractTransition * transition, QtAbstractState * target )

Adds the given transition. The transition has this state as the source, and the given target as the target state.

See also removeTransition().

### void QtAbstractStateGroup::addTransition ( QtAbstractTransition * transition, const QList<QtAbstractState *> & targets )

This is an overloaded member function, provided for convenience.

Adds the given transition. The transition has this state as the source, and the given targets as the target states.

### void QtAbstractStateGroup::addTransition ( const QObject * sender, const char * signal, QtAbstractState * target )

This is an overloaded member function, provided for convenience.

Adds a transition associated with the given signal of the given sender object. The transition has this state as the source, and the given target as the target state.

### void QtAbstractStateGroup::addTransition ( QtAbstractTransition * transition )

This is an overloaded member function, provided for convenience.

Adds the given transition. The transition has this state as the source, and has no target.

### void QtAbstractStateGroup::addTransition ( QtAbstractState * target )

This is an overloaded member function, provided for convenience.

Adds an unconditional transition from this state to the given target state.

### QtAbstractState * QtAbstractStateGroup::errorState () const

Returns this state group's error state.

See also QtStateMachine::errorState() and QtStateMachine::setErrorState().

### void QtAbstractStateGroup::invokeMethodOnEntry ( QObject * object, const char * method, const QList<QVariant> & arguments = QList<QVariant> () )

Instructs this QtState to invoke the given method of the given object with the given arguments when the state is entered. This function will create an object of QtStateInvokeMethodAction and add it to the entry actions of the state.

See also invokeMethodOnExit(), setPropertyOnEntry(), and addEntryAction().

### void QtAbstractStateGroup::invokeMethodOnExit ( QObject * object, const char * method, const QList<QVariant> & arguments = QList<QVariant> () )

Instructs this QtState to invoke the given method of the given object with the given arguments when the state is exited. This function will create an object of QtStateInvokeMethodAction and add it to the exit actions of the state.

See also invokeMethodOnEntry(), setPropertyOnExit(), and addExitAction().

### void QtAbstractStateGroup::removeTransition ( QtAbstractTransition * transition )

Removes the given transition from this state. The state releases ownership of the transition.

See also addTransition().

### RestorePolicy QtAbstractStateGroup::restorePolicy () const

Returns the restore policy for this state.

See also setRestorePolicy().

### void QtAbstractStateGroup::setErrorState ( QtAbstractState * state )

Sets this state group's error state to be the given state. If the error state is not set, or if it is set to 0, the state will inherit its parent's error state recursively.

See also QtStateMachine::setErrorState() and QtStateMachine::errorState().

### void QtAbstractStateGroup::setPropertyOnEntry ( QObject * object, const char * name, const QVariant & value )

Instructs this QtState to set the property with the given name of the given object to the given value when the state is entered. This function will create an object of QtStateSetPropertyAction and add it to the entry actions of the state.

See also setPropertyOnExit(), invokeMethodOnEntry(), and addEntryAction().

### void QtAbstractStateGroup::setPropertyOnExit ( QObject * object, const char * name, const QVariant & value )

Instructs this QtState to set the property with the given name of the given object to the given value when the state is exited. This function will create an object of QtStateSetPropertyAction and add it to the exit actions of the state.

See also setPropertyOnEntry(), invokeMethodOnExit(), and addExitAction().

### void QtAbstractStateGroup::setRestorePolicy ( RestorePolicy restorePolicy )

Sets the restore policy of this state to restorePolicy.

The default restore policy is QtAbstractStateGroup::GlobalRestorePolicy.

See also restorePolicy().