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
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
|
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** 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, Nokia gives you certain
** additional rights. These rights are described in the Nokia Qt LGPL
** Exception version 1.1, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
**
**
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example tools/undoframework
\title Undo Framework Example
This example shows how to implement undo/redo functionality
with the Qt undo framework.
\image undoframeworkexample.png The Undo Diagram Example
In the Qt undo framework, all actions that the user performs are
implemented in classes that inherit QUndoCommand. An undo command
class knows how to both \l{QUndoCommand::}{redo()} - or just do
the first time - and \l{QUndoCommand::}{undo()} an action. For
each action the user performs, a command is placed on a
QUndoStack. Since the stack contains all commands executed
(stacked in chronological order) on the document, it can roll the
state of the document backwards and forwards by undoing and redoing
its commands. See the \l{Overview of Qt's Undo Framework}{overview
document} for a high-level introduction to the undo framework.
The undo example implements a simple diagram application. It is
possible to add and delete items, which are either box or
rectangular shaped, and move the items by dragging them with the
mouse. The undo stack is shown in a QUndoView, which is a list in
which the commands are shown as list items. Undo and redo are
available through the edit menu. The user can also select a command
from the undo view.
We use the \l{The Graphics View Framework}{graphics view
framework} to implement the diagram. We only treat the related
code briefly as the framework has examples of its own (e.g., the
\l{Diagram Scene Example}).
The example consists of the following classes:
\list
\o \c MainWindow is the main window and arranges the
example's widgets. It creates the commands based
on user input and keeps them on the command stack.
\o \c AddCommand adds an item to the scene.
\o \c DeleteCommand deletes an item from the scene.
\o \c MoveCommand when an item is moved the MoveCommand keeps record
of the start and stop positions of the move, and it
moves the item according to these when \c redo() and \c undo()
is called.
\o \c DiagramScene inherits QGraphicsScene and
emits signals for the \c MoveComands when an item is moved.
\o \c DiagramItem inherits QGraphicsPolygonItem and represents
an item in the diagram.
\endlist
\section1 MainWindow Class Definition
\snippet examples/tools/undoframework/mainwindow.h 0
The \c MainWindow class maintains the undo stack, i.e., it creates
\l{QUndoCommand}s and pushes and pops them from the stack when it
receives the \c triggered() signal from \c undoAction and \c
redoAction.
\section1 MainWindow Class Implementation
We will start with a look at the constructor:
\snippet examples/tools/undoframework/mainwindow.cpp 0
In the constructor, we set up the DiagramScene and QGraphicsView.
Here is the \c createUndoView() function:
\snippet examples/tools/undoframework/mainwindow.cpp 1
The QUndoView is a widget that display the text, which is set with
the \l{QUndoCommand::}{setText()} function, for each QUndoCommand
in the undo stack in a list.
Here is the \c createActions() function:
\snippet examples/tools/undoframework/mainwindow.cpp 2
\codeline
\snippet examples/tools/undoframework/mainwindow.cpp 3
\dots
\snippet examples/tools/undoframework/mainwindow.cpp 5
The \c createActions() function sets up all the examples actions
in the manner shown above. The
\l{QUndoStack::}{createUndoAction()} and
\l{QUndoStack::}{createRedoAction()} helps us crate actions that
are disabled and enabled based on the state of the stack. Also,
the text of the action will be updated automatically based on the
\l{QUndoCommand::}{text()} of the undo commands. For the other
actions we have implemented slots in the \c MainWindow class.
Here is the \c createMenus() function:
\snippet examples/tools/undoframework/mainwindow.cpp 6
\dots
\snippet examples/tools/undoframework/mainwindow.cpp 7
\dots
\snippet examples/tools/undoframework/mainwindow.cpp 8
We have to use the QMenu \c aboutToShow() and \c aboutToHide()
signals since we only want \c deleteAction to be enabled when we
have selected an item.
Here is the \c itemMoved() slot:
\snippet examples/tools/undoframework/mainwindow.cpp 9
We simply push a MoveCommand on the stack, which calls \c redo()
on it.
Here is the \c deleteItem() slot:
\snippet examples/tools/undoframework/mainwindow.cpp 10
An item must be selected to be deleted. We need to check if it is
selected as the \c deleteAction may be enabled even if an item is
not selected. This can happen as we do not catch a signal or event
when an item is selected.
Here is the \c itemMenuAboutToShow() and itemMenuAboutToHide() slots:
\snippet examples/tools/undoframework/mainwindow.cpp 11
\codeline
\snippet examples/tools/undoframework/mainwindow.cpp 12
We implement \c itemMenuAboutToShow() and \c itemMenuAboutToHide()
to get a dynamic item menu. These slots are connected to the
\l{QMenu::}{aboutToShow()} and \l{QMenu::}{aboutToHide()} signals.
We need this to disable or enable the \c deleteAction.
Here is the \c addBox() slot:
\snippet examples/tools/undoframework/mainwindow.cpp 13
The \c addBox() function creates an AddCommand and pushes it on
the undo stack.
Here is the \c addTriangle() sot:
\snippet examples/tools/undoframework/mainwindow.cpp 14
The \c addTriangle() function creates an AddCommand and pushes it
on the undo stack.
Here is the implementation of \c about():
\snippet examples/tools/undoframework/mainwindow.cpp 15
The about slot is triggered by the \c aboutAction and displays an
about box for the example.
\section1 AddCommand Class Definition
\snippet examples/tools/undoframework/commands.h 2
The \c AddCommand class adds DiagramItem graphics items to the
DiagramScene.
\section1 AddCommand Class Implementation
We start with the constructor:
\snippet examples/tools/undoframework/commands.cpp 7
We first create the DiagramItem to add to the DiagramScene. The
\l{QUndoCommand::}{setText()} function let us set a QString that
describes the command. We use this to get custom messages in the
QUndoView and in the menu of the main window.
\snippet examples/tools/undoframework/commands.cpp 8
\c undo() removes the item from the scene. We need to update the
scene as ...(ask Andreas)
\snippet examples/tools/undoframework/commands.cpp 9
We set the position of the item as we do not do this in the
constructor.
\section1 DeleteCommand Class Definition
\snippet examples/tools/undoframework/commands.h 1
The DeleteCommand class implements the functionality to remove an
item from the scene.
\section1 DeleteCommand Class Implementation
\snippet examples/tools/undoframework/commands.cpp 4
We know that there must be one selected item as it is not possible
to create a DeleteCommand unless the item to be deleted is
selected and that only one item can be selected at any time.
The item must be unselected if it is inserted back into the
scene.
\snippet examples/tools/undoframework/commands.cpp 5
The item is simply reinserted into the scene.
\snippet examples/tools/undoframework/commands.cpp 6
The item is removed from the scene.
\section1 MoveCommand Class Definition
\snippet examples/tools/undoframework/commands.h 0
The \l{QUndoCommand::}{mergeWith()} is reimplemented to make
consecutive moves of an item one MoveCommand, i.e, the item will
be moved back to the start position of the first move.
\section1 MoveCommand Class Implementation
The constructor of MoveCommand looks like this:
\snippet examples/tools/undoframework/commands.cpp 0
We save both the old and new positions for undo and redo
respectively.
\snippet examples/tools/undoframework/commands.cpp 2
We simply set the items old position and update the scene.
\snippet examples/tools/undoframework/commands.cpp 3
We set the item to its new position.
\snippet examples/tools/undoframework/commands.cpp 1
Whenever a MoveCommand is created, this function is called to
check if it should be merged with the previous command. It is the
previous command object that is kept on the stack. The function
returns true if the command is merged; otherwise false.
We first check whether it is the same item that has been moved
twice, in which case we merge the commands. We update the position
of the item so that it will take the last position in the move
sequence when undone.
\section1 DiagramScene Class Definition
\snippet examples/tools/undoframework/diagramscene.h 0
The DiagramScene implements the functionality to move a
DiagramItem with the mouse. It emits a signal when a move is
completed. This is caught by the \c MainWindow, which makes
MoveCommands. We do not examine the implementation of DiagramScene
as it only deals with graphics framework issues.
\section1 The \c main() Function
The \c main() function of the program looks like this:
\snippet examples/tools/undoframework/main.cpp 0
We draw a grid in the background of the DiagramScene, so we use a
resource file. The rest of the function creates the \c MainWindow and
shows it as a top level window.
*/
|