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 "qabstracttransition.h"

    43 

    44 #ifndef QT_NO_STATEMACHINE

    45 

    46 #include "qabstracttransition_p.h"

    47 #include "qabstractstate.h"

    48 #include "qstate.h"

    49 #include "qstatemachine.h"

    50 

    51 QT_BEGIN_NAMESPACE

    52 

    53 /*!

    54   \class QAbstractTransition

    55 

    56   \brief The QAbstractTransition class is the base class of transitions between QAbstractState objects.

    57 

    58   \since 4.6

    59   \ingroup statemachine

    60 

    61   The QAbstractTransition class is the abstract base class of transitions

    62   between states (QAbstractState objects) of a

    63   QStateMachine. QAbstractTransition is part of \l{The State Machine

    64   Framework}.

    65 

    66   The sourceState() function returns the source of the transition. The

    67   targetStates() function returns the targets of the transition. The machine()

    68   function returns the state machine that the transition is part of.

    69 

    70   The triggered() signal is emitted when the transition has been triggered.

    71 

    72   Transitions can cause animations to be played. Use the addAnimation()

    73   function to add an animation to the transition.

    74 

    75   \section1 Subclassing

    76 

    77   The eventTest() function is called by the state machine to determine whether

    78   an event should trigger the transition. In your reimplementation you

    79   typically check the event type and cast the event object to the proper type,

    80   and check that one or more properties of the event meet your criteria.

    81 

    82   The onTransition() function is called when the transition is triggered;

    83   reimplement this function to perform custom processing for the transition.

    84 */

    85 

    86 /*!

    87     \property QAbstractTransition::sourceState

    88 

    89     \brief the source state (parent) of this transition

    90 */

    91 

    92 /*!

    93     \property QAbstractTransition::targetState

    94 

    95     \brief the target state of this transition

    96 

    97     If a transition has no target state, the transition may still be

    98     triggered, but this will not cause the state machine's configuration to

    99     change (i.e. the current state will not be exited and re-entered).

   100 */

   101 

   102 /*!

   103     \property QAbstractTransition::targetStates

   104 

   105     \brief the target states of this transition

   106 

   107     If multiple states are specified, all must be descendants of the same

   108     parallel group state.

   109 */

   110 

   111 QAbstractTransitionPrivate::QAbstractTransitionPrivate()

   112 {

   113 }

   114 

   115 QAbstractTransitionPrivate *QAbstractTransitionPrivate::get(QAbstractTransition *q)

   116 {

   117     return q->d_func();

   118 }

   119 

   120 QStateMachine *QAbstractTransitionPrivate::machine() const

   121 {

   122     QState *source = sourceState();

   123     if (!source)

   124         return 0;

   125     return source->machine();

   126 }

   127 

   128 bool QAbstractTransitionPrivate::callEventTest(QEvent *e)

   129 {

   130     Q_Q(QAbstractTransition);

   131     return q->eventTest(e);

   132 }

   133 

   134 void QAbstractTransitionPrivate::callOnTransition(QEvent *e)

   135 {

   136     Q_Q(QAbstractTransition);

   137     q->onTransition(e);

   138 }

   139 

   140 QState *QAbstractTransitionPrivate::sourceState() const

   141 {

   142     return qobject_cast<QState*>(parent);

   143 }

   144 

   145 void QAbstractTransitionPrivate::emitTriggered()

   146 {

   147     Q_Q(QAbstractTransition);

   148     emit q->triggered();

   149 }

   150 

   151 /*!

   152   Constructs a new QAbstractTransition object with the given \a sourceState.

   153 */

   154 QAbstractTransition::QAbstractTransition(QState *sourceState)

   155     : QObject(*new QAbstractTransitionPrivate, sourceState)

   156 {

   157 }

   158 

   159 /*!

   160   \internal

   161 */

   162 QAbstractTransition::QAbstractTransition(QAbstractTransitionPrivate &dd,

   163                                          QState *parent)

   164     : QObject(dd, parent)

   165 {

   166 }

   167 

   168 /*!

   169   Destroys this transition.

   170 */

   171 QAbstractTransition::~QAbstractTransition()

   172 {

   173 }

   174 

   175 /*!

   176   Returns the source state of this transition, or 0 if this transition has no

   177   source state.

   178 */

   179 QState *QAbstractTransition::sourceState() const

   180 {

   181     Q_D(const QAbstractTransition);

   182     return d->sourceState();

   183 }

   184 

   185 /*!

   186   Returns the target state of this transition, or 0 if the transition has no

   187   target.

   188 */

   189 QAbstractState *QAbstractTransition::targetState() const

   190 {

   191     Q_D(const QAbstractTransition);

   192     if (d->targetStates.isEmpty())

   193         return 0;

   194     return d->targetStates.first().data();

   195 }

   196 

   197 /*!

   198   Sets the \a target state of this transition.

   199 */

   200 void QAbstractTransition::setTargetState(QAbstractState* target)

   201 {

   202     Q_D(QAbstractTransition);

   203     if (!target)

   204         d->targetStates.clear();

   205     else

   206         setTargetStates(QList<QAbstractState*>() << target);

   207 }

   208 

   209 /*!

   210   Returns the target states of this transition, or an empty list if this

   211   transition has no target states.

   212 */

   213 QList<QAbstractState*> QAbstractTransition::targetStates() const

   214 {

   215     Q_D(const QAbstractTransition);

   216     QList<QAbstractState*> result;

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

   218         QAbstractState *target = d->targetStates.at(i).data();

   219         if (target)

   220             result.append(target);

   221     }

   222     return result;

   223 }

   224 

   225 /*!

   226   Sets the target states of this transition to be the given \a targets.

   227 */

   228 void QAbstractTransition::setTargetStates(const QList<QAbstractState*> &targets)

   229 {

   230     Q_D(QAbstractTransition);

   231 

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

   233         QAbstractState *target = targets.at(i);

   234         if (!target) {

   235             qWarning("QAbstractTransition::setTargetStates: target state(s) cannot be null");

   236             return;

   237         }

   238     }

   239 

   240     d->targetStates.clear();

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

   242         d->targetStates.append(targets.at(i));

   243 }

   244 

   245 /*!

   246   Returns the state machine that this transition is part of, or 0 if the

   247   transition is not part of a state machine.

   248 */

   249 QStateMachine *QAbstractTransition::machine() const

   250 {

   251     Q_D(const QAbstractTransition);

   252     return d->machine();

   253 }

   254 

   255 #ifndef QT_NO_ANIMATION

   256 

   257 /*!

   258   Adds the given \a animation to this transition.

   259   The transition does not take ownership of the animation.

   260 

   261   \sa removeAnimation(), animations()

   262 */

   263 void QAbstractTransition::addAnimation(QAbstractAnimation *animation)

   264 {

   265     Q_D(QAbstractTransition);

   266     if (!animation) {

   267         qWarning("QAbstractTransition::addAnimation: cannot add null animation");

   268         return;

   269     }

   270     d->animations.append(animation);

   271 }

   272 

   273 /*!

   274   Removes the given \a animation from this transition.

   275 

   276   \sa addAnimation()

   277 */

   278 void QAbstractTransition::removeAnimation(QAbstractAnimation *animation)

   279 {

   280     Q_D(QAbstractTransition);

   281     if (!animation) {

   282         qWarning("QAbstractTransition::removeAnimation: cannot remove null animation");

   283         return;

   284     }

   285     d->animations.removeOne(animation);

   286 }

   287 

   288 /*!

   289   Returns the list of animations associated with this transition, or an empty

   290   list if it has no animations.

   291 

   292   \sa addAnimation()

   293 */

   294 QList<QAbstractAnimation*> QAbstractTransition::animations() const

   295 {

   296     Q_D(const QAbstractTransition);

   297     return d->animations;

   298 }

   299 

   300 #endif

   301 

   302 /*!

   303   \fn QAbstractTransition::eventTest(QEvent *event)

   304 

   305   This function is called to determine whether the given \a event should cause

   306   this transition to trigger. Reimplement this function and return true if the

   307   event should trigger the transition, otherwise return false.

   308 */

   309 

   310 /*!

   311   \fn QAbstractTransition::onTransition(QEvent *event)

   312 

   313   This function is called when the transition is triggered. The given \a event

   314   is what caused the transition to trigger. Reimplement this function to

   315   perform custom processing when the transition is triggered.

   316 */

   317 

   318 /*!

   319   \fn QAbstractTransition::triggered()

   320 

   321   This signal is emitted when the transition has been triggered (after

   322   onTransition() has been called).

   323 */

   324 

   325 /*!

   326   \reimp

   327 */

   328 bool QAbstractTransition::event(QEvent *e)

   329 {

   330     return QObject::event(e);

   331 }

   332 

   333 QT_END_NAMESPACE

   334 

   335 #endif //QT_NO_STATEMACHINE