diff options
Diffstat (limited to 'src/imports/statemachine/statemachine.cpp')
-rw-r--r-- | src/imports/statemachine/statemachine.cpp | 223 |
1 files changed, 223 insertions, 0 deletions
diff --git a/src/imports/statemachine/statemachine.cpp b/src/imports/statemachine/statemachine.cpp new file mode 100644 index 0000000000..31d98b7094 --- /dev/null +++ b/src/imports/statemachine/statemachine.cpp @@ -0,0 +1,223 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Ford Motor Company +** Contact: http://www.qt-project.org/legal +** +** This file is part of the QtQml module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Digia gives you certain additional +** rights. These rights are described in the Digia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "statemachine.h" + +#include <QAbstractTransition> +#include <QQmlContext> +#include <QQmlEngine> +#include <QQmlInfo> + +#include <private/qqmlopenmetaobject_p.h> +#include <private/qqmlengine_p.h> + +StateMachine::StateMachine(QObject *parent) + : QStateMachine(parent), m_completed(false), m_running(false) +{ + connect(this, SIGNAL(runningChanged(bool)), SIGNAL(qmlRunningChanged())); +} + +bool StateMachine::isRunning() const +{ + return QStateMachine::isRunning(); +} + +void StateMachine::setRunning(bool running) +{ + if (m_completed) + QStateMachine::setRunning(running); + else + m_running = running; +} + +void StateMachine::componentComplete() +{ + if (QStateMachine::initialState() == NULL && childMode() == QState::ExclusiveStates) + qmlInfo(this) << "No initial state set for StateMachine"; + + // Everything is proper setup, now start the state-machine if we got + // asked to do so. + m_completed = true; + if (m_running) + setRunning(true); +} + +QQmlListProperty<QObject> StateMachine::children() +{ + return QQmlListProperty<QObject>(this, &m_children, m_children.append, m_children.count, m_children.at, m_children.clear); +} + +/*! + \qmltype StateMachine + \inqmlmodule QtStateMachine 1.0 + \inherits StateBase + \ingroup qmlstatemachine + \since 5.4 + + \brief Provides a hierarchical finite state machine. + + StateMachine is based on the concepts and notation of + \l{http://www.wisdom.weizmann.ac.il/~dharel/SCANNED.PAPERS/Statecharts.pdf}{Statecharts}. + StateMachine is part of \l{The Declarative State Machine Framework}. + + A state machine manages a set of states and transitions between those + states; these states and transitions define a state graph. Once a state + graph has been built, the state machine can execute it. StateMachine's + execution algorithm is based on the \l{http://www.w3.org/TR/scxml/}{State Chart XML (SCXML)} + algorithm. The framework's \l{The Declarative State Machine Framework}{overview} + gives several state graphs and the code to build them. + + Before the machine can be started, the \l{StateBase::initialState}{initialState} + must be set. The initial state is the state that the + machine enters when started. You can then set running property to true + or start() the state machine. The started signal is emitted when the + initial state is entered. + + The state machine processes events and takes transitions until a + top-level final state is entered; the state machine then emits the + finished() signal. You can also stop() the state machine + explicitly (you can also set running property to false). + The stopped signal is emitted in this case. + + \section1 Example Usage + The following snippet shows a state machine that will finish when a button + is clicked: + + \snippet qml/statemachine/simplestatemachine.qml document + + If an error is encountered, the machine will look for an + \l{StateBase::errorState}{errorState}, and if one is available, it will + enter this state. After the error state is entered, the type of the error + can be retrieved with error(). The execution of the state graph will not + stop when the error state is entered. If no error state applies to the + erroneous state, the machine will stop executing and an error message will + be printed to the console. + + \clearfloat + + \sa QAbstractState, StateBase, SignalTransition, TimeoutTransition, HistoryState {The Declarative State Machine Framework} +*/ + +/*! + \qmlproperty enumeration StateMachine::globalRestorePolicy + + \brief The restore policy for states of this state machine. + + The default value of this property is QState.DontRestoreProperties. + + This enum specifies the restore policy type. The restore policy + takes effect when the machine enters a state which sets one or more + properties. If the restore policy is set to QState.RestoreProperties, + the state machine will save the original value of the property before the + new value is set. + + Later, when the machine either enters a state which does not set a + value for the given property, the property will automatically be restored + to its initial value. + + 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. + + \list + \li QState.DontRestoreProperties The state machine should not save the initial values of properties and restore them later. + \li QState.RestoreProperties The state machine should save the initial values of properties and restore them later. + \endlist +*/ + +/*! + \qmlproperty bool StateMachine::running + + \brief The running state of this state machine. + \sa start(), stop() +*/ + +/*! + \qmlproperty string StateMachine::errorString + \readonly errorString + + \brief The error string of this state machine. +*/ + + +/*! + \qmlmethod StateMachine::start() + + Starts this state machine. The machine will reset its configuration and + transition to the initial state. When a final top-level state (FinalState) + is entered, the machine will emit the finished() signal. + + \note A state machine will not run without a running event loop, such as + the main application event loop started with QCoreApplication::exec() or + QApplication::exec(). + + \sa started, StateBase::finished, stop(), StateBase::initialState, running +*/ + +/*! + \qmlsignal StateMachine::started() + + This signal is emitted when the state machine has entered its initial state + (StateBase::initialState). + + The corresponding handler is \c onStarted. + + \sa running, start(), StateBase::finished +*/ + +/*! + \qmlmethod StateMachine::stop() + + Stops this state machine. The state machine will stop processing events + and then emit the stopped signal. + + \sa stopped, start(), running +*/ + +/*! + \qmlsignal StateMachine::stopped() + + This signal is emitted when the state machine has stopped. + + The corresponding handler is \c onStopped. + + \sa running, stop(), StateBase::finished +*/ |