source: trunk/doc/src/frameworks-technologies/qundo.qdoc

/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** 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 Free Documentation License
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
** $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.
*/