Home

QtUndoManager Class Reference

The QtUndoManager class manages command stacks in an undo/redo framework based on the Command design pattern. More...

#include <qtundo.h>

List of all member functions.

Public Members

QAction * createUndoAction ( QWidget * parent ) const
QAction * createRedoAction ( QWidget * parent ) const
void associateView ( QObject * obj, QtUndoStack * stack )
void disassociateView ( QObject * obj )
bool canUndo () const
bool canRedo () const
QString undoDescription () const
QString redoDescription () const
void setUndoLimit ( uint i )
uint undoLimit () const
QStringList undoList () const
QStringList redoList () const

Public Slots

void undo ( int count = 1 )
void redo ( int count = 1 )

Signals

void undoDescriptionChanged ( const QString & newDescription )
void redoDescriptionChanged ( const QString & newDescription )
void canUndoChanged ( bool enabled )
void canRedoChanged ( bool enabled )

Static Public Members

QtUndoManager * manager ()

Detailed Description

The QtUndoManager class manages command stacks in an undo/redo framework based on the Command design pattern.

For an overview of the Qt Undo/Redo framework, see the overview.

QtUndoManager keeps a list of QtUndoStack objects. Each is a list of QtCommand objects and a pointer to the last executed command (the undo stack's current command). Undo is invoked by calling the current command's QtCommand::undo() function and making the previous command in the stack the current command. Redo is invoked by making the next command in the stack the current command and calling its QtCommand::redo() function.

An application has one global QtUndoManager, accessed through the static function QtUndoManager::manager() (which creates the QtUndoManager when it is called for the first time).

Undo and redo are requested through the undo() and redo() slots. QtUndoManager also provides the functions createUndoAction() and createRedoAction() for creating QAction objects that trigger undo and redo. These QActions have the additional benefit of keeping their text properties in sync with undoDescription() and redoDescription(), as well as disabling themselves whenever no commands are available for undo or redo.

    MainWindow::MainWindow(QWidget *parent, const char *name)
        : QMainWindow(parent, name)
    {
        ...
        QtUndoManager *manager = QtUndoManager::manager();
        QAction *undo_action = manager->createUndoAction(this);
        QAction *redo_action = manager->createRedoAction(this);
        undo_action->setAccel(QKeySequence("Ctrl+Z"));
        redo_action->setAccel(QKeySequence("Shift+Ctrl+Z"));

        QToolBar *toolbar = new QToolBar(this);
        undo_action->addTo(toolbar);
        redo_action->addTo(toolbar);

        QPopupMenu *editmenu = new QPopupMenu(this);
        undo_action->addTo(editmenu);
        redo_action->addTo(editmenu);
        ...
    }

A single application can have multiple undo stacks, typically one for each editor window in an MDI application. Each stack is associated with a widget, called the stack's target. undo() and redo() requests are directed to a stack whenever its target, or a child of its target, has the keyboard focus. A target is associated with a stack in QtUndoStack's constructor. Additional targets may be associated with a stack using associateView(). This is useful when two or more editor windows edit the same underlying object. An SDI aplication typically has a single stack associated with the application's main window.

Whenever the widget with the keyboard focus has no targets in its parent chain, the QAction objects created using createUndoAction() and createRedoAction() are disabled.

Member Function Documentation

void QtUndoManager::associateView ( QObject * obj, QtUndoStack * stack )

Associates the object obj with the given stack, adding obj the stack's targets. undo() and redo() requests will be directed to stack, whenever obj or one of its children has the keyboard focus.

bool QtUndoManager::canRedo () const

Returns true if a command is available for undo; otherwise returns false. Undo is not possible if the widget with the keyboard focus has no targets in its parent chain, or if a target is found but the associated stack is empty, or if the first command on the stack has already been redone.

A QAction returned by createRedoAction() disables itself whenever canRedo() is false.

void QtUndoManager::canRedoChanged ( bool enabled ) `[signal]`

This signal is emitted whenever the state reported by canRedo() changes. enabled is the new state.

This function is useful if you want to trigger redo with a custom widget, rather than the QAction returned by createRedoAction().

See also canRedo(), redoDescriptionChanged(), and canUndoChanged().

bool QtUndoManager::canUndo () const

Returns true if a command is available for redo; otherwise returns false. Redo is not possible if the widget with the keyboard focus has no targets in its parent chain, or if a target is found but the associated stack is empty, or if the last command on the stack has already been undone.

The QAction returned by createUndoAction() disables itself whenever canUndo() is false.

void QtUndoManager::canUndoChanged ( bool enabled ) `[signal]`

This signal is emitted whenever the state reported by canUndo() changes. enabled is the new state.

This function is useful if you want to trigger undo with a custom widget, rather than the QAction returned by createUndoAction().

See also canUndo(), undoDescriptionChanged(), and canRedoChanged().

QAction * QtUndoManager::createRedoAction ( QWidget * parent ) const

Creates a QAction object connected to the QtUndoManager's redo() slot. The parent becomes the owner and parent of the QAction. This is significant, since any accelerators that are assigned to the QAction will only work within the parent.

The returned QAction will keep its text property in sync with redoDescription() and disable itself whenever no commands are available for redo.

If the application's default QMimeSourceFactory contains a pixmap called "redo" or "redo.png", this pixmap is assigned to the QAction.

See also redo(), redoDescription(), and createUndoAction().

QAction * QtUndoManager::createUndoAction ( QWidget * parent ) const

Creates a QAction object connected to the QtUndoManager's undo() slot. The parent becomes the owner and parent of the QAction. This is significant, since any accelerators that are assigned to the QAction will only work within the parent.

The returned QAction will keep its text property in sync with undoDescription() and disable itself whenever no commands are available for undo.

If the application's default QMimeSourceFactory contains a pixmap called "undo" or "undo.png", this pixmap is assigned to the QAction.

See also undo(), undoDescription(), and createRedoAction().

void QtUndoManager::disassociateView ( QObject * obj )

Disassociates obj from any stack.

QtUndoManager * QtUndoManager::manager () `[static]`

Returns the application-global instance of QtUndoManager, creating it if it does not yet exist.

void QtUndoManager::redo ( int count = 1 ) `[slot]`

Directs the redo request to the appropriate QtUndoStack. The stack is chosen by finding the widget with the keyboard focus and searching its parent chain for a target. If a target is found, QtUndoStack::redo() is called on the associated stack. If no such target is found, this function does nothing.

count is the number of commands that should be redone. It defaults to 1.

QString QtUndoManager::redoDescription () const

Returns the current redo description.

The redo description is a string that describes what effects calling QtUndoManager::redo() will have on the edited object.

It contains the text returned by QtCommand::description() for the command preceding the current command on the QtUndoStack associated with the target widget that contains the keyboard focus.

The QAction returned by createRedoAction() keeps its text property in sync with the redo description. This function is useful if you want to trigger redo with a custom widget, rather than with this QAction.

void QtUndoManager::redoDescriptionChanged ( const QString & newDescription ) `[signal]`

This signal is emitted whenever the redo description for the QtUndoStack associated with the target widget that contains the keyboard focus changes. newDescription is the new redo description. It is useful when you want to trigger redo using a custom widget, rather than using the QAction returned by createRedoAction().

See also redoDescription(), canRedoChanged(), and undoDescriptionChanged().

QStringList QtUndoManager::redoList () const

Returns a list of descriptions of all the commands preceding the current command in the stack associated with the currently focused target. If no target has focus, returns an empty list.

void QtUndoManager::setUndoLimit ( uint i )

Sets the maximum size that any stack can grow to, to i. A size of 0 means that the stacks can grow indefinitely.

void QtUndoManager::undo ( int count = 1 ) `[slot]`

Directs an undo request to the appropriate QtUndoStack. The stack is chosen by finding the widget with the keyboard focus and searching its parent chain for a target. If a target is found, QtUndoStack::undo() is called on the associated stack. If no such target is found, this function does nothing.

count is the number of commands that should be undone. It defaults to 1.

QString QtUndoManager::undoDescription () const

Returns the current undo description.

The undo description is a string that describes what effects calling QtUndoManager::undo() will have on the edited object.

It contains the text returned by QtCommand::description() for the current command on the QtUndoStack associated with the target widget that contains the keyboard focus.

The QAction returned by createUndoAction() keeps its text property in sync with the undo description. This function is useful if you want to trigger undo with a custom widget, rather than with this QAction.

void QtUndoManager::undoDescriptionChanged ( const QString & newDescription ) `[signal]`

This signal is emitted whenever the undo description for the QtUndoStack associated with the target widget that contains the keyboard focus changes. newDescription is the new undo description. It is useful when you want to trigger undo using a custom widget, rather than using the QAction returned by createUndoAction().

See also undoDescription(), canUndoChanged(), and redoDescriptionChanged().

uint QtUndoManager::undoLimit () const

Returns the maximum size that any undo stack can grow to. A size of 0 means that the stacks can grow indefinitely.

QStringList QtUndoManager::undoList () const

Returns a list of descriptions of all the commands up to the current command in the stack associated with the currently focused target. If no target has focus, returns an empty list.