diff options
Diffstat (limited to 'doc/src/qundo.qdoc')
| -rw-r--r-- | doc/src/qundo.qdoc | 113 |
1 files changed, 113 insertions, 0 deletions
diff --git a/doc/src/qundo.qdoc b/doc/src/qundo.qdoc new file mode 100644 index 0000000..5358c12 --- /dev/null +++ b/doc/src/qundo.qdoc @@ -0,0 +1,113 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (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 qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qundo.html +\title Overview of Qt's Undo Framework +\keyword Undo framework +\ingroup architecture + +\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. +*/ |