source: trunk/doc/src/qundo.qdoc@ 337

/****************************************************************************
**
** 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$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** 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.
*/