QState Class Reference

The QState class provides a general-purpose state for QStateMachine. More...

#include <qstate.h>

Inheritance diagram for QState:

Public Types
enum	ChildMode { ExclusiveStates, ParallelStates }
	This enum specifies how a state's child states are treated. More...

Signals
void	finished ()
	This signal is emitted when a final child state of this state is entered. More...
void	propertiesAssigned ()
	This signal is emitted when all properties have been assigned their final value. More...
Signals inherited from QAbstractState
void	entered ()
	This signal is emitted when the state has been entered (after onEntry() has been called). More...
void	exited ()
	This signal is emitted when the state has been exited (after onExit() has been called). More...
Signals inherited from QObject
void	destroyed (QObject *=0)
	This signal is emitted immediately before the object obj is destroyed, and can not be blocked. More...

Public Functions
void	addTransition (QAbstractTransition *transition)
	Adds the given transition. More...
QSignalTransition *	addTransition (QObject *sender, const char *signal, QAbstractState *target)
	Adds a transition associated with the given signal of the given sender object, and returns the new QSignalTransition object. More...
QAbstractTransition *	addTransition (QAbstractState *target)
	Adds an unconditional transition from this state to the given target state, and returns then new transition object. More...
void	assignProperty (QObject *object, const char *name, const QVariant &value)
	Instructs this state to set the property with the given name of the given object to the given value when the state is entered. More...
ChildMode	childMode () const
QAbstractState *	errorState () const
QAbstractState *	initialState () const
	QState (QState *parent=0)
	Constructs a new state with the given parent state. More...
	QState (ChildMode childMode, QState *parent=0)
	Constructs a new state with the given childMode and the given parent state. More...
void	removeTransition (QAbstractTransition *transition)
	Removes the given transition from this state. More...
void	setChildMode (ChildMode mode)
	Sets the child mode of this state. More...
void	setErrorState (QAbstractState *state)
	Sets this state's error state to be the given state. More...
void	setInitialState (QAbstractState *state)
	Sets this state's initial state to be the given state. More...
QList< QAbstractTransition * >	transitions () const
	Returns this state's outgoing transitions (i. More...
	~QState ()
	Destroys this state. More...
Public Functions inherited from QAbstractState
QStateMachine *	machine () const
	Returns the state machine that this state is part of, or 0 if the state is not part of a state machine. More...
QState *	parentState () const
	Returns this state's parent state, or 0 if the state has no parent state. More...
	~QAbstractState ()
	Destroys this state. More...
Public Functions inherited from QObject
bool	blockSignals (bool b)
	If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it). More...
const QObjectList &	children () const
	Returns a list of child objects. More...
bool	connect (const QObject *sender, const char *signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const
bool	disconnect (const char *signal=0, const QObject *receiver=0, const char *member=0)
bool	disconnect (const QObject *receiver, const char *member=0)
void	dumpObjectInfo ()
	Dumps information about signal connections, etc. More...
void	dumpObjectTree ()
	Dumps a tree of children to the debug output. More...
QList< QByteArray >	dynamicPropertyNames () const
	Returns the names of all properties that were dynamically added to the object using setProperty(). More...
virtual bool	eventFilter (QObject *, QEvent *)
	Filters events if this object has been installed as an event filter for the watched object. More...
template<typename T >
T	findChild (const QString &aName=QString()) const
	Returns the child of this object that can be cast into type T and that is called name, or 0 if there is no such object. More...
template<typename T >
QList< T >	findChildren (const QString &aName=QString()) const
	Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects. More...
template<typename T >
QList< T >	findChildren (const QRegExp &re) const
bool	inherits (const char *classname) const
	Returns true if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns false. More...
void	installEventFilter (QObject *)
	Installs an event filter filterObj on this object. More...
bool	isWidgetType () const
	Returns true if the object is a widget; otherwise returns false. More...
void	killTimer (int id)
	Kills the timer with timer identifier, id. More...
virtual const QMetaObject *	metaObject () const
	Returns a pointer to the meta-object of this object. More...
void	moveToThread (QThread *thread)
	Changes the thread affinity for this object and its children. More...
QString	objectName () const
QObject *	parent () const
	Returns a pointer to the parent object. More...
QVariant	property (const char *name) const
	Returns the value of the object's name property. More...
Q_INVOKABLE	QObject (QObject *parent=0)
	Constructs an object with parent object parent. More...
void	removeEventFilter (QObject *)
	Removes an event filter object obj from this object. More...
void	setObjectName (const QString &name)
void	setParent (QObject *)
	Makes the object a child of parent. More...
bool	setProperty (const char *name, const QVariant &value)
	Sets the value of the object's name property to value. More...
void	setUserData (uint id, QObjectUserData *data)
bool	signalsBlocked () const
	Returns true if signals are blocked; otherwise returns false. More...
int	startTimer (int interval)
	Starts a timer and returns a timer identifier, or returns zero if it could not start a timer. More...
QThread *	thread () const
	Returns the thread in which the object lives. More...
QObjectUserData *	userData (uint id) const
virtual	~QObject ()
	Destroys the object, deleting all its child objects. More...

Protected Functions
bool	event (QEvent *e)
	Reimplemented Function More...
void	onEntry (QEvent *event)
	Reimplemented Function More...
void	onExit (QEvent *event)
	Reimplemented Function More...
	QState (QStatePrivate &dd, QState *parent)
Protected Functions inherited from QAbstractState
	QAbstractState (QState *parent=0)
	Constructs a new state with the given parent state. More...
	QAbstractState (QAbstractStatePrivate &dd, QState *parent)
Protected Functions inherited from QObject
virtual void	childEvent (QChildEvent *)
	This event handler can be reimplemented in a subclass to receive child events. More...
virtual void	connectNotify (const char *signal)
	This virtual function is called when something has been connected to signal in this object. More...
virtual void	customEvent (QEvent *)
	This event handler can be reimplemented in a subclass to receive custom events. More...
virtual void	disconnectNotify (const char *signal)
	This virtual function is called when something has been disconnected from signal in this object. More...
	QObject (QObjectPrivate &dd, QObject *parent=0)
int	receivers (const char *signal) const
	Returns the number of receivers connected to the signal. More...
QObject *	sender () const
	Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns 0. More...
int	senderSignalIndex () const
virtual void	timerEvent (QTimerEvent *)
	This event handler can be reimplemented in a subclass to receive timer events for the object. More...

Properties
ChildMode	childMode
	the child mode of this state More...
QAbstractState *	errorState
	the error state of this state More...
QAbstractState *	initialState
	the initial state of this state (one of its child states) More...

Additional Inherited Members
Public Slots inherited from QObject
void	deleteLater ()
	Schedules this object for deletion. More...
Static Public Functions inherited from QObject
static bool	connect (const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
	Creates a connection of the given type from the signal in the sender object to the method in the receiver object. More...
static bool	connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)
static bool	disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *member)
	Disconnects signal in object sender from method in object receiver. More...
static bool	disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &member)
static uint	registerUserData ()
static QString	tr (const char *sourceText, const char *comment=0, int n=-1)
static QString	trUtf8 (const char *sourceText, const char *comment=0, int n=-1)
Static Public Variables inherited from QObject
static const QMetaObject	staticMetaObject
	This variable stores the meta-object for the class. More...
Protected Variables inherited from QObject
QScopedPointer< QObjectData >	d_ptr
Static Protected Variables inherited from QObject
static const QMetaObject	staticQtMetaObject
Related Functions inherited from QObject
T	qFindChildqFindChildren (const QObject *obj, const QString &name)()
QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QString &name)()
QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QRegExp &regExp)()
T *	qobject_cast (QObject *object)
	QObjectList
void *	qt_find_obj_child (QObject *parent, const char *type, const QString &name)
	Returns a pointer to the object named name that inherits type and with a given parent. More...

Detailed Description

The QState class provides a general-purpose state for QStateMachine.

Since

4.6

QState objects can have child states, and can have transitions to other states. QState is part of The State Machine Framework.

The addTransition() function adds a transition. The removeTransition() function removes a transition. The transitions() function returns the state's outgoing transitions.

The assignProperty() function is used for defining property assignments that should be performed when a state is entered.

Top-level states must be passed a QStateMachine object as their parent state, or added to a state machine using QStateMachine::addState().

States with Child States

The childMode property determines how child states are treated. For non-parallel state groups, the setInitialState() function must be called to set the initial state. The child states are mutually exclusive states, and the state machine needs to know which child state to enter when the parent state is the target of a transition.

The state emits the QState::finished() signal when a final child state (QFinalState) is entered.

The setErrorState() sets the state's error state. The error state is the state that the state machine will transition to if an error is detected when attempting to enter the state (e.g. because no initial state has been set).

Definition at line 61 of file qstate.h.

Enumerations

ChildMode

enum QState::ChildMode

This enum specifies how a state's child states are treated.

• ExclusiveStates The child states are mutually exclusive and an initial state must be set by calling QState::setInitialState().

• ParallelStates The child states are parallel. When the parent state is entered, all its child states are entered in parallel.

Enumerator
ExclusiveStates
ParallelStates

Definition at line 69 of file qstate.h.

                   {
        ExclusiveStates,
        ParallelStates
    };

Constructors and Destructors

QState() [1/3]

QState::QState

(

QState *

parent = 0

)

Constructs a new state with the given parent state.

Definition at line 168 of file qstate.cpp.

    : QAbstractState(*new QStatePrivate, parent)
{
}

QState() [2/3]

QState::QState	(	ChildMode	childMode,
		QState *	parent = 0
	)

Constructs a new state with the given childMode and the given parent state.

Definition at line 177 of file qstate.cpp.

    : QAbstractState(*new QStatePrivate, parent)
{
    Q_D(QState);
    d->childMode = childMode;
}

~QState()

QState::~QState

(

)

Destroys this state.

Definition at line 195 of file qstate.cpp.

{
}

QState() [3/3]

QState::QState ( QStatePrivate &  dd, QState *  parent  )

protected

Warning

This function is not part of the public interface.

Definition at line 187 of file qstate.cpp.

    : QAbstractState(dd, parent)
{
}

Functions

addTransition() [1/3]

void QState::addTransition

(

QAbstractTransition *

transition

)

Adds the given transition.

The transition has this state as the source. This state takes ownership of the transition.

Definition at line 308 of file qstate.cpp.

Referenced by QStateMachinePrivate::_q_start(), addTransition(), and QStateMachinePrivate::goToState().

{
    Q_D(QState);
    if (!transition) {
        qWarning("QState::addTransition: cannot add null transition");
        return ;
    }

    transition->setParent(this);
    const QList<QWeakPointer<QAbstractState> > &targets = QAbstractTransitionPrivate::get(transition)->targetStates;
    for (int i = 0; i < targets.size(); ++i) {
        QAbstractState *t = targets.at(i).data();
        if (!t) {
            qWarning("QState::addTransition: cannot add transition to null state");
            return ;
        }
        if ((QAbstractStatePrivate::get(t)->machine() != d->machine())
            && QAbstractStatePrivate::get(t)->machine() && d->machine()) {
            qWarning("QState::addTransition: cannot add transition "
                     "to a state in a different state machine");
            return ;
        }
    }
    if (machine() != 0 && machine()->configuration().contains(this))
        QStateMachinePrivate::get(machine())->registerTransitions(this);
}

addTransition() [2/3]

QSignalTransition * QState::addTransition	(	QObject *	sender,
		const char *	signal,
		QAbstractState *	target
	)

Adds a transition associated with the given signal of the given sender object, and returns the new QSignalTransition object.

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

Definition at line 340 of file qstate.cpp.

{
    if (!sender) {
        qWarning("QState::addTransition: sender cannot be null");
        return 0;
    }
    if (!signal) {
        qWarning("QState::addTransition: signal cannot be null");
        return 0;
    }
    if (!target) {
        qWarning("QState::addTransition: cannot add transition to null state");
        return 0;
    }
    int offset = (*signal == '0'+QSIGNAL_CODE) ? 1 : 0;
    const QMetaObject *meta = sender->metaObject();
    if (meta->indexOfSignal(signal+offset) == -1) {
        if (meta->indexOfSignal(QMetaObject::normalizedSignature(signal+offset)) == -1) {
            qWarning("QState::addTransition: no such signal %s::%s",
                     meta->className(), signal+offset);
            return 0;
        }
    }
    QSignalTransition *trans = new QSignalTransition(sender, signal);
    trans->setTargetState(target);
    addTransition(trans);
    return trans;
}

addTransition() [3/3]

QAbstractTransition * QState::addTransition

(

QAbstractState *

target

)

Adds an unconditional transition from this state to the given target state, and returns then new transition object.

Definition at line 390 of file qstate.cpp.

{
    if (!target) {
        qWarning("QState::addTransition: cannot add transition to null state");
        return 0;
    }
    UnconditionalTransition *trans = new UnconditionalTransition(target);
    addTransition(trans);
    return trans;
}

assignProperty()

void QState::assignProperty	(	QObject *	object,
		const char *	name,
		const QVariant &	value
	)

Instructs this state to set the property with the given name of the given object to the given value when the state is entered.

See also

propertiesAssigned()

Definition at line 250 of file qstate.cpp.

{
    Q_D(QState);
    if (!object) {
        qWarning("QState::assignProperty: cannot assign property '%s' of null object", name);
        return;
    }
    for (int i = 0; i < d->propertyAssignments.size(); ++i) {
        QPropertyAssignment &assn = d->propertyAssignments[i];
        if ((assn.object == object) && (assn.propertyName == name)) {
            assn.value = value;
            return;
        }
    }
    d->propertyAssignments.append(QPropertyAssignment(object, name, value));
}

childMode()

ChildMode QState::childMode

(

)

const

Referenced by QState(), and setInitialState().

errorState()

QAbstractState* QState::errorState

(

)

const

Referenced by assignProperty().

event()

bool QState::event ( QEvent *  e )

protectedvirtual

Reimplemented Function

Reimplemented from QAbstractState.

Reimplemented in QStateMachine.

Definition at line 509 of file qstate.cpp.

Referenced by QStateMachine::event().

{
    Q_D(QState);
    if ((e->type() == QEvent::ChildAdded) || (e->type() == QEvent::ChildRemoved)) {
        d->childStatesListNeedsRefresh = true;
        d->transitionsListNeedsRefresh = true;
    }
    return QAbstractState::event(e);
}

finished

QState::finished ( )

signal

This signal is emitted when a final child state of this state is entered.

See also

QFinalState

initialState()

QAbstractState* QState::initialState

(

)

const

Referenced by onExit(), and QStateMachine::start().

onEntry()

void QState::onEntry ( QEvent *  event )

protectedvirtual

Reimplemented Function

Implements QAbstractState.

Reimplemented in QStateMachine.

Definition at line 446 of file qstate.cpp.

Referenced by QStateMachine::onEntry().

{
    Q_UNUSED(event);
}

onExit()

void QState::onExit ( QEvent *  event )

protectedvirtual

Reimplemented Function

Implements QAbstractState.

Reimplemented in QStateMachine.

Definition at line 454 of file qstate.cpp.

Referenced by QStateMachine::onExit().

{
    Q_UNUSED(event);
}

propertiesAssigned

QState::propertiesAssigned ( )

signal

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.

See also

QState::assignProperty(), QAbstractTransition::addAnimation()

removeTransition()

void QState::removeTransition

(

QAbstractTransition *

transition

)

Removes the given transition from this state.

The state releases ownership of the transition.

See also

addTransition()

Definition at line 407 of file qstate.cpp.

{
    Q_D(QState);
    if (!transition) {
        qWarning("QState::removeTransition: cannot remove null transition");
        return;
    }
    if (transition->sourceState() != this) {
        qWarning("QState::removeTransition: transition %p's source state (%p)"
                 " is different from this state (%p)",
                 transition, transition->sourceState(), this);
        return;
    }
    QStateMachinePrivate *mach = QStateMachinePrivate::get(d->machine());
    if (mach)
        mach->unregisterTransition(transition);
    transition->setParent(0);
}

setChildMode()

void QState::setChildMode

(

ChildMode

mode

)

Sets the child mode of this state.

Definition at line 500 of file qstate.cpp.

{
    Q_D(QState);
    d->childMode = mode;
}

setErrorState()

void QState::setErrorState

(

QAbstractState *

state

)

Sets this state'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. If no error state is set for the state itself or any of its ancestors, an error will cause the machine to stop executing and an error will be printed to the console.

Definition at line 288 of file qstate.cpp.

{
    Q_D(QState);
    if (state != 0 && qobject_cast<QStateMachine*>(state)) {
        qWarning("QStateMachine::setErrorState: root state cannot be error state");
        return;
    }
    if (state != 0 && (!state->machine() || ((state->machine() != machine()) && !qobject_cast<QStateMachine*>(this)))) {
        qWarning("QState::setErrorState: error state cannot belong "
                 "to a different state machine");
        return;
    }

    d->errorState = state;
}

setInitialState()

void QState::setInitialState

(

QAbstractState *

state

)

Sets this state's initial state to be the given state.

state has to be a child of this state.

Definition at line 472 of file qstate.cpp.

{
    Q_D(QState);
    if (d->childMode == QState::ParallelStates) {
        qWarning("QState::setInitialState: ignoring attempt to set initial state "
                 "of parallel state group %p", this);
        return;
    }
    if (state && (state->parentState() != this)) {
        qWarning("QState::setInitialState: state %p is not a child of this state (%p)",
                 state, this);
        return;
    }
    d->initialState = state;
}

transitions()

QList< QAbstractTransition * > QState::transitions

(

)

const

Returns this state's outgoing transitions (i.

Since

4.7

e. transitions where this state is the source state), or an empty list if this state has no outgoing transitions.

See also

addTransition()

Definition at line 437 of file qstate.cpp.

{
    Q_D(const QState);
    return d->transitions();
}

Properties

childMode

QState::ChildMode QState::childMode

private

the child mode of this state

Returns the child mode of this state.

The default value of this property is QState::ExclusiveStates.

Definition at line 66 of file qstate.h.

errorState

QAbstractState * QState::errorState

private

the error state of this state

Returns this state's error state.

See also

QStateMachine::error()

Definition at line 65 of file qstate.h.

Referenced by QStateMachinePrivate::findErrorState().

initialState

QAbstractState * QState::initialState

private

the initial state of this state (one of its child states)

Returns this state's initial state, or 0 if the state has no initial state.

Definition at line 64 of file qstate.h.

Referenced by QStateMachinePrivate::_q_start(), and QStateMachinePrivate::addStatesToEnter().

---

The documentation for this class was generated from the following files:

• /src/corelib/statemachine/qstate.h
• /src/corelib/statemachine/qstate.cpp