|  | Home · Overviews · Examples |

# QUndoCommand Class Reference
[com.trolltech.qt.gui module]

The `QUndoCommand` class is the base class of all commands stored on a `QUndoStack`. More...

## Detailed Description

The `QUndoCommand` class is the base class of all commands stored on a `QUndoStack`.

For an overview of Qt's Undo Framework, see the overview document.

A `QUndoCommand` represents a single editing action on a document; for example, inserting or deleting a block of text in a text editor. `QUndoCommand` can apply a change to the document with `redo` and undo the change with `undo`. The implementations for these functions must be provided in a derived class.

        class AppendText : public QUndoCommand
        {
        public:
            AppendText(QString *doc, const QString &text)
                : m_document(doc), m_text(text) { setText("append text"); }
            virtual void undo()
                { m_document->chop(m_text.length()); }
            virtual void redo()
                { m_document->append(m_text); }
        private:
            QString *m_document;
            QString m_text;
        };

A `QUndoCommand` has an associated `text`. This is a short string describing what the command does. It is used to update the text properties of the stack's undo and redo actions; see QUndoStack::createUndoAction() and QUndoStack::createRedoAction().

`QUndoCommand` objects are owned by the stack they were pushed on. `QUndoStack` deletes a command if it has been undone and a new command is pushed. For example:

        MyCommand *command1 = new MyCommand();
        stack->push(command1);
        MyCommand *command2 = new MyCommand();
        stack->push(command2);

        stack->undo();

        MyCommand *command3 = new MyCommand();
        stack->push(command3); // command2 gets deleted

In effect, when a command is pushed, it becomes the top-most command on the stack.

To support command compression, `QUndoCommand` has an `id` and the virtual function `mergeWith`. These functions are used by QUndoStack::push().

To support command macros, a `QUndoCommand` object can have any number of child commands. Undoing or redoing the parent command will cause the child commands to be undone or redone. A command can be assigned to a parent explicitly in the constructor. In this case, the command will be owned by the parent.

The parent in this case is usually an empty command, in that it doesn't provide its own implementation of `undo` and `redo`. Instead, it uses the base implementations of these functions, which simply call `undo` or `redo` on all its children. The parent should, however, have a meaningful `text`.

        QUndoCommand *insertRed = new QUndoCommand(); // an empty command
        insertRed->setText("insert red text");

        new InsertText(document, idx, text, insertRed); // becomes child of insertRed
        new SetColor(document, idx, text.length(), Qt::red, insertRed);

        stack.push(insertRed);

Another way to create macros is to use the convenience functions QUndoStack::beginMacro() and QUndoStack::endMacro().

See also `QUndoStack`.