Overview of Qt’s Undo Framework#

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.

Classes#

The framework consists of four classes:

  • 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.

  • 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.

  • 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.

  • 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.

Concepts#

The following concepts are supported by the framework:

  • 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.

  • 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.

  • 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.

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.