doc/src/qundo.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Lesser General Public License Usage
  17 ** Alternatively, this file may be used under the terms of the GNU Lesser
  18 ** General Public License version 2.1 as published by the Free Software
  19 ** Foundation and appearing in the file LICENSE.LGPL included in the
  20 ** packaging of this file.  Please review the following information to
  21 ** ensure the GNU Lesser General Public License version 2.1 requirements
  22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  23 **
  24 ** In addition, as a special exception, Nokia gives you certain additional
  25 ** rights.  These rights are described in the Nokia Qt LGPL Exception
  26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  27 **
  28 ** If you have questions regarding the use of this file, please contact
  29 ** Nokia at qt-info@nokia.com.
  30 **
  31 **
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 /*!
  43 \page qundo.html
  44 \title Overview of Qt's Undo Framework
  45 \keyword Undo framework
  46 \ingroup architecture
  47
  48 \section1 Introduction
  49
  50 Qt's Undo Framework is an implementation of the Command pattern, for
  51 implementing undo/redo functionality in applications.
  52
  53 The Command pattern is based on the idea that all editing in
  54 an application is done by creating instances of command objects.
  55 Command objects apply changes to the document and are stored
  56 on a command stack. Furthermore, each command knows how to undo its
  57 changes to bring the document back to its previous state. As long
  58 as the application only uses command objects to change the state of
  59 the document, it is possible to undo a sequence of commands by
  60 traversing the stack downwards and calling undo
  61 on each command in turn. It is also possible to redo a sequence of
  62 commands by traversing the stack upwards and calling
  63 redo on each command.
  64
  65 \section1 Classes
  66
  67 The framework consists of four classes:
  68
  69 \list
  70 \i \l QUndoCommand is the base class of all commands stored on an
  71         undo stack. It can apply (redo) or undo a single change in the document.
  72 \i \l QUndoStack is a list of QUndoCommand objects. It contains all the
  73         commands executed on the document and can roll the document's state
  74         backwards or forwards by undoing or redoing them.
  75 \i \l QUndoGroup is a group of undo stacks. It is useful when an application
  76         contains more than one undo stack, typically one for each opened
  77         document. QUndoGroup provides a single pair of undo/redo slots for all
  78         the stacks in the group. It forwards undo and redo requests to
  79         the active stack, which is the stack associated with the document that
  80         is currently being edited by the user.
  81 \i \l QUndoView is a widget which shows the contents of an undo stack. Clicking
  82         on a command in the view rolls the document's state backwards or
  83         forwards to that command.
  84 \endlist
  85
  86 \section1 Concepts
  87
  88 The following concepts are supported by the framework:
  89
  90 \list
  91 \i \bold{Clean state:} Used to signal when the document enters and leaves a
  92     state that has been saved to disk. This is typically used to disable or
  93     enable the save actions, and to update the document's title bar.
  94 \i \bold{Command compression:} Used to compress sequences of commands into a
  95     single command.
  96     For example: In a text editor, the commands that insert individual
  97     characters into the document can be compressed into a single command that
  98     inserts whole sections of text. These bigger changes are more convenient
  99     for the user to undo and redo.
 100 \i \bold{Command macros:} A sequence of commands, all of which are undone or
 101     redone in one step.
 102     These simplify the task of writing an application, since a set of simpler
 103     commands can be composed into more complex commands. For example, a command
 104     that moves a set of selected objects in a document can be created by
 105     combining a set of commands, each of which moves a single object.
 106 \endlist
 107
 108 QUndoStack provides convenient undo and redo QAction objects that
 109 can be inserted into a menu or a toolbar. The text properties of these
 110 actions always reflect what command will be undone or redone when
 111 they are triggered. Similarly, QUndoGroup provides undo and redo actions
 112 that always behave like the undo and redo actions of the active stack.
 113 */