This repository has been archived by the owner on Sep 4, 2019. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 23
/
Copy pathtrafficlight.qdoc
111 lines (83 loc) · 5.22 KB
/
trafficlight.qdoc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page trafficlight
\example trafficlight
\title Traffic Light Example
\section1 Description
The Traffic Light example shows how to use \l{The State Machine Framework}
to implement the control flow of a traffic light.
\image trafficlight-example.png
\section1 Overview
In this example we'll learn how to use the QStateMachine, QState and QHistoryState classes to
model our business logic with a state machine.
The state chart that describes the business logic looks like the following:
\image trafficlight-statechart-example.png
We have the two top-level states 'runningState' and 'pausedState' and the user can switch between
them by clicking the 'Pause' button.
The 'runningState' has four child states: 'stopState', 'waitState', 'driveState' and 'slowState' which
represent the four possible phases of a traffic light. The transition between these four states is triggered
via the \c timeout() signal of a QTimer.
The history state, that is entered when coming back from the 'pausedState', ensures that the state will
be activated which has been active when the 'runningState' was left before.
\section1 The UI
The UI of this sample application consists of a traffic light, a 'Pause' and a 'Quit' button.
The business logic of the application is encapsulated in the class TrafficLightController, which is
exported to the UI as '_trafficLightController'.
If the user clicks the 'Pause' button, the \c pause() slot of the TrafficLightController object is invoked
and if the user clicks on the 'Quit' button, the \c quit() slot of the Application object is invoked.
\snippet trafficlight/assets/main.qml 1
The traffic light is implemented in TrafficLight.qml and instantiated inside main.qml
\snippet trafficlight/assets/main.qml 0
The TrafficLight object has a custom property 'controller' which points to the TrafficLightController object.
All three colors of the TrafficLight are implemented as \c ImageViews that show different images depending on
their state (on/off). The background image contains the colors that represent the 'off' state and the 'on' state
is represented by overlay images
\snippet trafficlight/assets/TrafficLight.qml 0
To switch a color on or off we simple change the opacity of the overlay image. In this example the opacity properties
are bound against the appropriated properties of the TrafficLightController object.
\section1 TrafficLightController
The \c TrafficLightController is the central class of this application. It contains the QStateMachine instance that drives
the business logic and provides the properties that represent the state of the single traffic light colors
\snippet trafficlight/src/TrafficLightController.hpp 0
Inside the constructor of \c TrafficLightController we initialize the properties with their default values, set up the state machine
and start the timer that is used to trigger the transitions between the traffic light phases.
\snippet trafficlight/src/TrafficLightController.cpp 0
Inside \c setupStateMachine() we create the QStateMachine object and all the QState objects.
\snippet trafficlight/src/TrafficLightController.cpp 3
The \l{QState::}{assignProperty()} calls on the QState objects ensure that whenever the state is entered, the given value will be assigned
to the named property on the passed object. So whenever the 'driveState' is entered, the 'greenOn' property of the TrafficLightController object
will be set to \c true, in all other states to \c false.
When the 'greenOn' property is changed, the properties setter method \c setGreenOn() will be invoked.
\snippet trafficlight/src/TrafficLightController.cpp 1
Inside this method we check whether the state has changed, and only if that's the case we update the internal state and emit the change notification
signal.
The next step inside \c setupStateMachine() is to wire up the states with transitions. As trigger for the transitions between the traffic light phases
the \l{QTimer::}{timeout()} signal of the QTimer object is used. For the transitions between 'runningState' and 'pausedState' the \c pauseRequested()
signal of the \c TrafficLightController object is used, which is emitted whenever the user clicks on the 'Pause' button
\snippet trafficlight/src/TrafficLightController.cpp 2
*/