1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtCore module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include "qstate.h"

    43 

    44 #ifndef QT_NO_STATEMACHINE

    45 

    46 #include "qstate_p.h"

    47 #include "qhistorystate.h"

    48 #include "qhistorystate_p.h"

    49 #include "qabstracttransition.h"

    50 #include "qabstracttransition_p.h"

    51 #include "qsignaltransition.h"

    52 #include "qstatemachine.h"

    53 #include "qstatemachine_p.h"

    54 

    55 QT_BEGIN_NAMESPACE

    56 

    57 /*!

    58   \class QState

    59 

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

    61 

    62   \since 4.6

    63   \ingroup statemachine

    64 

    65   QState objects can have child states, and can have transitions to other

    66   states. QState is part of \l{The State Machine Framework}.

    67 

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

    69   function removes a transition.

    70 

    71   The assignProperty() function is used for defining property assignments that

    72   should be performed when a state is entered.

    73 

    74   Top-level states must be passed a QStateMachine object as their parent

    75   state, or added to a state machine using QStateMachine::addState().

    76 

    77   \section1 States with Child States

    78 

    79   The childMode property determines how child states are treated. For

    80   non-parallel state groups, the setInitialState() function must be called to

    81   set the initial state. The child states are mutually exclusive states, and

    82   the state machine needs to know which child state to enter when the parent

    83   state is the target of a transition.

    84 

    85   The state emits the QState::finished() signal when a final child state

    86   (QFinalState) is entered.

    87 

    88   The setErrorState() sets the state's error state. The error state is the

    89   state that the state machine will transition to if an error is detected when

    90   attempting to enter the state (e.g. because no initial state has been set).

    91 

    92 */

    93 

    94 /*!

    95     \property QState::initialState

    96 

    97     \brief the initial state of this state (one of its child states)

    98 */

    99 

   100 /*!

   101     \property QState::errorState

   102 

   103     \brief the error state of this state

   104 */

   105 

   106 /*!

   107     \property QState::childMode

   108 

   109     \brief the child mode of this state

   110 

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

   112 */

   113 

   114 /*!

   115   \enum QState::ChildMode

   116 

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

   118 

   119   \value ExclusiveStates The child states are mutually exclusive and an

   120   initial state must be set by calling QState::setInitialState().

   121 

   122   \value ParallelStates The child states are parallel. When the parent state

   123   is entered, all its child states are entered in parallel.

   124 */

   125 

   126 QStatePrivate::QStatePrivate()

   127     : errorState(0), initialState(0), childMode(QState::ExclusiveStates)

   128 {

   129 }

   130 

   131 QStatePrivate::~QStatePrivate()

   132 {

   133 }

   134 

   135 void QStatePrivate::emitFinished()

   136 {

   137     Q_Q(QState);

   138     emit q->finished();

   139 }

   140 

   141 void QStatePrivate::emitPolished()

   142 {

   143     Q_Q(QState);

   144     emit q->polished();

   145 }

   146 

   147 /*!

   148   Constructs a new state with the given \a parent state.

   149 */

   150 QState::QState(QState *parent)

   151     : QAbstractState(*new QStatePrivate, parent)

   152 {

   153 }

   154 

   155 /*!

   156   Constructs a new state with the given \a childMode and the given \a parent

   157   state.

   158 */

   159 QState::QState(ChildMode childMode, QState *parent)

   160     : QAbstractState(*new QStatePrivate, parent)

   161 {

   162     Q_D(QState);

   163     d->childMode = childMode;

   164 }

   165 

   166 /*!

   167   \internal

   168 */

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

   170     : QAbstractState(dd, parent)

   171 {

   172 }

   173 

   174 /*!

   175   Destroys this state.

   176 */

   177 QState::~QState()

   178 {

   179 }

   180 

   181 QList<QAbstractState*> QStatePrivate::childStates() const

   182 {

   183     QList<QAbstractState*> result;

   184     QList<QObject*>::const_iterator it;

   185     for (it = children.constBegin(); it != children.constEnd(); ++it) {

   186         QAbstractState *s = qobject_cast<QAbstractState*>(*it);

   187         if (!s || qobject_cast<QHistoryState*>(s))

   188             continue;

   189         result.append(s);

   190     }

   191     return result;

   192 }

   193 

   194 QList<QHistoryState*> QStatePrivate::historyStates() const

   195 {

   196     QList<QHistoryState*> result;

   197     QList<QObject*>::const_iterator it;

   198     for (it = children.constBegin(); it != children.constEnd(); ++it) {

   199         QHistoryState *h = qobject_cast<QHistoryState*>(*it);

   200         if (h)

   201             result.append(h);

   202     }

   203     return result;

   204 }

   205 

   206 QList<QAbstractTransition*> QStatePrivate::transitions() const

   207 {

   208     QList<QAbstractTransition*> result;

   209     QList<QObject*>::const_iterator it;

   210     for (it = children.constBegin(); it != children.constEnd(); ++it) {

   211         QAbstractTransition *t = qobject_cast<QAbstractTransition*>(*it);

   212         if (t)

   213             result.append(t);

   214     }

   215     return result;

   216 }

   217 

   218 #ifndef QT_NO_PROPERTIES

   219 

   220 /*!

   221   Instructs this state to set the property with the given \a name of the given

   222   \a object to the given \a value when the state is entered.

   223 

   224   \sa polished()

   225 */

   226 void QState::assignProperty(QObject *object, const char *name,

   227                             const QVariant &value)

   228 {

   229     Q_D(QState);

   230     if (!object) {

   231         qWarning("QState::assignProperty: cannot assign property '%s' of null object", name);

   232         return;

   233     }

   234     for (int i = 0; i < d->propertyAssignments.size(); ++i) {

   235         QPropertyAssignment &assn = d->propertyAssignments[i];

   236         if ((assn.object == object) && (assn.propertyName == name)) {

   237             assn.value = value;

   238             return;

   239         }

   240     }

   241     d->propertyAssignments.append(QPropertyAssignment(object, name, value));

   242 }

   243 

   244 #endif // QT_NO_PROPERTIES

   245 

   246 /*!

   247   Returns this state's error state. 

   248 

   249   \sa QStateMachine::error()

   250 */

   251 QAbstractState *QState::errorState() const

   252 {

   253     Q_D(const QState);

   254     return d->errorState;

   255 }

   256 

   257 /*!

   258   Sets this state's error state to be the given \a state. If the error state

   259   is not set, or if it is set to 0, the state will inherit its parent's error

   260   state recursively. If no error state is set for the state itself or any of 

   261   its ancestors, an error will cause the machine to stop executing and an error

   262   will be printed to the console.

   263 */

   264 void QState::setErrorState(QAbstractState *state)

   265 {

   266     Q_D(QState);

   267     if (state != 0 && qobject_cast<QStateMachine*>(state)) {

   268         qWarning("QStateMachine::setErrorState: root state cannot be error state");

   269         return;

   270     }

   271     if (state != 0 && (!state->machine() || ((state->machine() != machine()) && !qobject_cast<QStateMachine*>(this)))) {

   272         qWarning("QState::setErrorState: error state cannot belong "

   273                  "to a different state machine");

   274         return;

   275     }

   276 

   277     d->errorState = state;

   278 }

   279 

   280 /*!

   281   Adds the given \a transition. The transition has this state as the source.

   282   This state takes ownership of the transition. If the transition is successfully

   283   added, the function will return the \a transition pointer. Otherwise it will return null.

   284 */

   285 QAbstractTransition *QState::addTransition(QAbstractTransition *transition)

   286 {

   287     Q_D(QState);

   288     if (!transition) {

   289         qWarning("QState::addTransition: cannot add null transition");

   290         return 0;

   291     }

   292 

   293     transition->setParent(this);

   294     const QList<QWeakPointer<QAbstractState> > &targets = QAbstractTransitionPrivate::get(transition)->targetStates;

   295     for (int i = 0; i < targets.size(); ++i) {

   296         QAbstractState *t = targets.at(i).data();

   297         if (!t) {

   298             qWarning("QState::addTransition: cannot add transition to null state");

   299             return 0;

   300         }

   301         if ((QAbstractStatePrivate::get(t)->machine() != d->machine())

   302             && QAbstractStatePrivate::get(t)->machine() && d->machine()) {

   303             qWarning("QState::addTransition: cannot add transition "

   304                      "to a state in a different state machine");

   305             return 0;

   306         }

   307     }

   308     if (machine() != 0 && machine()->configuration().contains(this))

   309         QStateMachinePrivate::get(machine())->registerTransitions(this);

   310     return transition;

   311 }

   312 

   313 /*!

   314   Adds a transition associated with the given \a signal of the given \a sender

   315   object, and returns the new QSignalTransition object. The transition has

   316   this state as the source, and the given \a target as the target state.

   317 */

   318 QSignalTransition *QState::addTransition(QObject *sender, const char *signal,

   319                                          QAbstractState *target)

   320 {

   321     if (!sender) {

   322         qWarning("QState::addTransition: sender cannot be null");

   323         return 0;

   324     }

   325     if (!signal) {

   326         qWarning("QState::addTransition: signal cannot be null");

   327         return 0;

   328     }

   329     if (!target) {

   330         qWarning("QState::addTransition: cannot add transition to null state");

   331         return 0;

   332     }

   333     int offset = (*signal == '0'+QSIGNAL_CODE) ? 1 : 0;

   334     const QMetaObject *meta = sender->metaObject();

   335     if (meta->indexOfSignal(signal+offset) == -1) {

   336         if (meta->indexOfSignal(QMetaObject::normalizedSignature(signal+offset)) == -1) {

   337             qWarning("QState::addTransition: no such signal %s::%s",

   338                      meta->className(), signal+offset);

   339             return 0;

   340         }

   341     }

   342     QSignalTransition *trans = new QSignalTransition(sender, signal);

   343     trans->setTargetState(target);

   344     addTransition(trans);

   345     return trans;

   346 }

   347 

   348 namespace {

   349 

   350 // ### Make public?

   351 class UnconditionalTransition : public QAbstractTransition

   352 {

   353 public:

   354     UnconditionalTransition(QAbstractState *target)

   355         : QAbstractTransition()

   356     { setTargetState(target); }

   357 protected:

   358     void onTransition(QEvent *) {}

   359     bool eventTest(QEvent *) { return true; }

   360 };

   361 

   362 } // namespace

   363 

   364 /*!

   365   Adds an unconditional transition from this state to the given \a target

   366   state, and returns then new transition object.

   367 */

   368 QAbstractTransition *QState::addTransition(QAbstractState *target)

   369 {

   370     if (!target) {

   371         qWarning("QState::addTransition: cannot add transition to null state");

   372         return 0;

   373     }

   374     UnconditionalTransition *trans = new UnconditionalTransition(target);

   375     return addTransition(trans);

   376 }

   377 

   378 /*!

   379   Removes the given \a transition from this state.  The state releases

   380   ownership of the transition.

   381 

   382   \sa addTransition()

   383 */

   384 void QState::removeTransition(QAbstractTransition *transition)

   385 {

   386     Q_D(QState);

   387     if (!transition) {

   388         qWarning("QState::removeTransition: cannot remove null transition");

   389         return;

   390     }

   391     if (transition->sourceState() != this) {

   392         qWarning("QState::removeTransition: transition %p's source state (%p)"

   393                  " is different from this state (%p)",

   394                  transition, transition->sourceState(), this);

   395         return;

   396     }

   397     QStateMachinePrivate *mach = QStateMachinePrivate::get(d->machine());

   398     if (mach)

   399         mach->unregisterTransition(transition);

   400     transition->setParent(0);

   401 }

   402 

   403 /*!

   404   \reimp

   405 */

   406 void QState::onEntry(QEvent *event)

   407 {

   408     Q_UNUSED(event);

   409 }

   410 

   411 /*!

   412   \reimp

   413 */

   414 void QState::onExit(QEvent *event)

   415 {

   416     Q_UNUSED(event);

   417 }

   418 

   419 /*!

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

   421 */

   422 QAbstractState *QState::initialState() const

   423 {

   424     Q_D(const QState);

   425     return d->initialState;

   426 }

   427 

   428 /*!

   429   Sets this state's initial state to be the given \a state.

   430   \a state has to be a child of this state.

   431 */

   432 void QState::setInitialState(QAbstractState *state)

   433 {

   434     Q_D(QState);

   435     if (d->childMode == QState::ParallelStates) {

   436         qWarning("QState::setInitialState: ignoring attempt to set initial state "

   437                  "of parallel state group %p", this);

   438         return;

   439     }

   440     if (state && (state->parentState() != this)) {

   441         qWarning("QState::setInitialState: state %p is not a child of this state (%p)",

   442                  state, this);

   443         return;

   444     }

   445     d->initialState = state;

   446 }

   447 

   448 /*!

   449   Returns the child mode of this state.

   450 */

   451 QState::ChildMode QState::childMode() const

   452 {

   453     Q_D(const QState);

   454     return d->childMode;

   455 }

   456 

   457 /*!

   458   Sets the child \a mode of this state.

   459 */

   460 void QState::setChildMode(ChildMode mode)

   461 {

   462     Q_D(QState);

   463     d->childMode = mode;

   464 }

   465 

   466 /*!

   467   \reimp

   468 */

   469 bool QState::event(QEvent *e)

   470 {

   471     return QAbstractState::event(e);

   472 }

   473 

   474 /*!

   475   \fn QState::finished()

   476 

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

   478 

   479   \sa QFinalState

   480 */

   481 

   482 /*!

   483   \fn QState::polished()

   484 

   485   This signal is emitted when all properties have been assigned their final value.

   486 

   487   \sa QState::assignProperty(), QAbstractTransition::addAnimation()

   488 */

   489 

   490 QT_END_NAMESPACE

   491 

   492 #endif //QT_NO_STATEMACHINE