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
|
/****************************************************************************
**
** 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 either Technology Preview License Agreement or the
** Beta Release License Agreement.
**
** 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.0, 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.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at http://qt.nokia.com/contact.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qundo.html
\title Overview of Qt's Undo Framework
\keyword Undo framework
\ingroup frameworks-technologies
\section1 Introduction
Qt's Undo Framework is an implementation of the Command pattern, for
implementing undo/redo functionality in applications.
The Command pattern is based on the idea that all editing in
an application is done by creating instances of command objects.
Command objects apply changes to the document and are stored
on a command stack. Furthermore, each command knows how to undo its
changes to bring the document back to its previous state. As long
as the application only uses command objects to change the state of
the document, it is possible to undo a sequence of commands by
traversing the stack downwards and calling undo
on each command in turn. It is also possible to redo a sequence of
commands by traversing the stack upwards and calling
redo on each command.
\section1 Classes
The framework consists of four classes:
\list
\i \l QUndoCommand is the base class of all commands stored on an
undo stack. It can apply (redo) or undo a single change in the document.
\i \l QUndoStack is a list of QUndoCommand objects. It contains all the
commands executed on the document and can roll the document's state
backwards or forwards by undoing or redoing them.
\i \l QUndoGroup is a group of undo stacks. It is useful when an application
contains more than one undo stack, typically one for each opened
document. QUndoGroup provides a single pair of undo/redo slots for all
the stacks in the group. It forwards undo and redo requests to
the active stack, which is the stack associated with the document that
is currently being edited by the user.
\i \l QUndoView is a widget which shows the contents of an undo stack. Clicking
on a command in the view rolls the document's state backwards or
forwards to that command.
\endlist
\section1 Concepts
The following concepts are supported by the framework:
\list
\i \bold{Clean state:} Used to signal when the document enters and leaves a
state that has been saved to disk. This is typically used to disable or
enable the save actions, and to update the document's title bar.
\i \bold{Command compression:} Used to compress sequences of commands into a
single command.
For example: In a text editor, the commands that insert individual
characters into the document can be compressed into a single command that
inserts whole sections of text. These bigger changes are more convenient
for the user to undo and redo.
\i \bold{Command macros:} A sequence of commands, all of which are undone or
redone in one step.
These simplify the task of writing an application, since a set of simpler
commands can be composed into more complex commands. For example, a command
that moves a set of selected objects in a document can be created by
combining a set of commands, each of which moves a single object.
\endlist
QUndoStack provides convenient undo and redo QAction objects that
can be inserted into a menu or a toolbar. The text properties of these
actions always reflect what command will be undone or redone when
they are triggered. Similarly, QUndoGroup provides undo and redo actions
that always behave like the undo and redo actions of the active stack.
*/
|
