1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the QtCore module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40#include "qabstractstate.h"
41#include "qabstractstate_p.h"
42#include "qstate.h"
43#include "qstate_p.h"
44#include "qstatemachine.h"
45#include "qstatemachine_p.h"
46
47QT_BEGIN_NAMESPACE
48
49/*!
50 \class QAbstractState
51 \inmodule QtCore
52
53 \brief The QAbstractState class is the base class of states of a QStateMachine.
54
55 \since 4.6
56 \ingroup statemachine
57
58 The QAbstractState class is the abstract base class of states that are part
59 of a QStateMachine. It defines the interface that all state objects have in
60 common. QAbstractState is part of \l{The State Machine Framework}.
61
62 The entered() signal is emitted when the state has been entered. The
63 exited() signal is emitted when the state has been exited.
64
65 The parentState() function returns the state's parent state. The machine()
66 function returns the state machine that the state is part of.
67
68 \section1 Subclassing
69
70 The onEntry() function is called when the state is entered; reimplement this
71 function to perform custom processing when the state is entered.
72
73 The onExit() function is called when the state is exited; reimplement this
74 function to perform custom processing when the state is exited.
75*/
76
77/*!
78 \property QAbstractState::active
79 \since 5.4
80
81 \brief the active property of this state. A state is active between
82 entered() and exited() signals.
83*/
84
85
86QAbstractStatePrivate::QAbstractStatePrivate(StateType type)
87 : stateType(type), isMachine(false), active(false), parentState(nullptr)
88{
89}
90
91QStateMachine *QAbstractStatePrivate::machine() const
92{
93 QObject *par = parent;
94 while (par != nullptr) {
95 if (QStateMachine *mach = qobject_cast<QStateMachine*>(object: par))
96 return mach;
97 par = par->parent();
98 }
99 return nullptr;
100}
101
102void QAbstractStatePrivate::callOnEntry(QEvent *e)
103{
104 Q_Q(QAbstractState);
105 q->onEntry(event: e);
106}
107
108void QAbstractStatePrivate::callOnExit(QEvent *e)
109{
110 Q_Q(QAbstractState);
111 q->onExit(event: e);
112}
113
114void QAbstractStatePrivate::emitEntered()
115{
116 Q_Q(QAbstractState);
117 emit q->entered(QAbstractState::QPrivateSignal());
118 if (!active) {
119 active = true;
120 emit q->activeChanged(active: true);
121 }
122}
123
124void QAbstractStatePrivate::emitExited()
125{
126 Q_Q(QAbstractState);
127 if (active) {
128 active = false;
129 emit q->activeChanged(active: false);
130 }
131 emit q->exited(QAbstractState::QPrivateSignal());
132}
133
134/*!
135 Constructs a new state with the given \a parent state.
136*/
137QAbstractState::QAbstractState(QState *parent)
138 : QObject(*new QAbstractStatePrivate(QAbstractStatePrivate::AbstractState), parent)
139{
140}
141
142/*!
143 \internal
144*/
145QAbstractState::QAbstractState(QAbstractStatePrivate &dd, QState *parent)
146 : QObject(dd, parent)
147{
148}
149
150/*!
151 Destroys this state.
152*/
153QAbstractState::~QAbstractState()
154{
155}
156
157/*!
158 Returns this state's parent state, or \nullptr if the state has no
159 parent state.
160*/
161QState *QAbstractState::parentState() const
162{
163 Q_D(const QAbstractState);
164 if (d->parentState != parent())
165 d->parentState = qobject_cast<QState*>(object: parent());
166 return d->parentState;
167}
168
169/*!
170 Returns the state machine that this state is part of, or \nullptr if
171 the state is not part of a state machine.
172*/
173QStateMachine *QAbstractState::machine() const
174{
175 Q_D(const QAbstractState);
176 return d->machine();
177}
178
179/*!
180 Returns whether this state is active.
181
182 \sa activeChanged(bool), entered(), exited()
183*/
184bool QAbstractState::active() const
185{
186 Q_D(const QAbstractState);
187 return d->active;
188}
189
190/*!
191 \fn QAbstractState::onExit(QEvent *event)
192
193 This function is called when the state is exited. The given \a event is what
194 caused the state to be exited. Reimplement this function to perform custom
195 processing when the state is exited.
196*/
197
198/*!
199 \fn QAbstractState::onEntry(QEvent *event)
200
201 This function is called when the state is entered. The given \a event is
202 what caused the state to be entered. Reimplement this function to perform
203 custom processing when the state is entered.
204*/
205
206/*!
207 \fn QAbstractState::entered()
208
209 This signal is emitted when the state has been entered (after onEntry() has
210 been called).
211*/
212
213/*!
214 \fn QAbstractState::exited()
215
216 This signal is emitted when the state has been exited (after onExit() has
217 been called).
218*/
219
220/*!
221 \fn QAbstractState::activeChanged(bool active)
222 \since 5.4
223
224 This signal is emitted when the active property is changed with \a active as argument.
225
226 \sa QAbstractState::active, entered(), exited()
227*/
228
229/*!
230 \reimp
231*/
232bool QAbstractState::event(QEvent *e)
233{
234 return QObject::event(event: e);
235}
236
237QT_END_NAMESPACE
238
239#include "moc_qabstractstate.cpp"
240

source code of qtbase/src/corelib/statemachine/qabstractstate.cpp