| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** 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 The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** 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. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $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 |
| \li \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. |
| \li \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. |
| \li \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. |
| \li \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 |
| \li \b{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. |
| \li \b{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. |
| \li \b{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. |
| */ |