Contents

• Public Functions
• Detailed Description

Detailed Description

TheQUndoCommand class is the base class of all commands stored on aQUndoStack.

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

AQUndoCommand 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 withredo() and undo the change withundo(). The implementations for these functions must be provided in a derived class.

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

AQUndoCommand has an associatedtext(). 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; seeQUndoStack::createUndoAction() andQUndoStack::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 anid() and the virtual functionmergeWith(). These functions are used byQUndoStack::push().

To support command macros, aQUndoCommand 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 ofundo() andredo(). Instead, it uses the base implementations of these functions, which simply callundo() orredo() on all its children. The parent should, however, have a meaningfultext().

QUndoCommand*insertRed=newQUndoCommand();// an empty commandinsertRed->setText("insert red text");new InsertText(document, idx, text, insertRed);// becomes child of insertRednew SetColor(document, idx, text.length(),Qt::red, insertRed);stack.push(insertRed);

Another way to create macros is to use the convenience functionsQUndoStack::beginMacro() andQUndoStack::endMacro().

Member Function Documentation

QUndoCommand::QUndoCommand(QUndoCommand * parent = 0)

Constructs aQUndoCommand object with parentparent.

Ifparent is not 0, this command is appended to parent's child list. The parent command then owns this command and will delete it in its destructor.

See also~QUndoCommand().

QUndoCommand::QUndoCommand(constQString & text,QUndoCommand * parent = 0)

Constructs aQUndoCommand object with the givenparent andtext.

Ifparent is not 0, this command is appended to parent's child list. The parent command then owns this command and will delete it in its destructor.

See also~QUndoCommand().

[virtual]QUndoCommand::~QUndoCommand()

Destroys theQUndoCommand object and all child commands.

See alsoQUndoCommand().

QString QUndoCommand::actionText() const

Returns a short text string describing what this command does; for example, "insert text".

The text is used when the text properties of the stack's undo and redo actions are updated.

This function was introduced in Qt 4.8.

See alsotext(),setText(),QUndoStack::createUndoAction(), andQUndoStack::createRedoAction().

constQUndoCommand * QUndoCommand::child(int index) const

Returns the child command atindex.

This function was introduced in Qt 4.4.

See alsochildCount() andQUndoStack::command().

int QUndoCommand::childCount() const

Returns the number of child commands in this command.

This function was introduced in Qt 4.4.

See alsochild().

[virtual]int QUndoCommand::id() const

Returns the ID of this command.

A command ID is used in command compression. It must be an integer unique to this command's class, or -1 if the command doesn't support compression.

If the command supports compression this function must be overridden in the derived class to return the correct ID. The base implementation returns -1.

QUndoStack::push() will only try to merge two commands if they have the same ID, and the ID is not -1.

See alsomergeWith() andQUndoStack::push().

[virtual]bool QUndoCommand::mergeWith(constQUndoCommand * command)

Attempts to merge this command withcommand. Returns true on success; otherwise returns false.

If this function returns true, calling this command'sredo() must have the same effect as redoing both this command andcommand. Similarly, calling this command'sundo() must have the same effect as undoingcommand and this command.

QUndoStack will only try to merge two commands if they have the same id, and the id is not -1.

The default implementation returns false.

bool AppendText::mergeWith(constQUndoCommand*other){if (other->id()!= id())// make sure other is also an AppendText commandreturnfalse;    m_text+=static_cast<const AppendText*>(other)->m_text;returntrue;}

See alsoid() andQUndoStack::push().

[virtual]void QUndoCommand::redo()

Applies a change to the document. This function must be implemented in the derived class. CallingQUndoStack::push(),QUndoStack::undo() orQUndoStack::redo() from this function leads to undefined beahavior.

The default implementation calls redo() on all child commands.

See alsoundo().

void QUndoCommand::setText(constQString & text)

Sets the command's text to be thetext specified.

The specified text should be a short user-readable string describing what this command does.

If you need to have two different strings fortext() andactionText(), separate them with "\n" and pass into this function. Even if you do not use this feature for English strings during development, you can still let translators use two different strings in order to match specific languages' needs. The described feature and the functionactionText() are available since Qt 4.8.

See alsotext(),actionText(),QUndoStack::createUndoAction(), andQUndoStack::createRedoAction().

QString QUndoCommand::text() const

Returns a short text string describing what this command does; for example, "insert text".

The text is used for names of items inQUndoView.

See alsoactionText(),setText(),QUndoStack::createUndoAction(), andQUndoStack::createRedoAction().

[virtual]void QUndoCommand::undo()

Reverts a change to the document. After undo() is called, the state of the document should be the same as beforeredo() was called. This function must be implemented in the derived class. CallingQUndoStack::push(),QUndoStack::undo() orQUndoStack::redo() from this function leads to undefined beahavior.

The default implementation calls undo() on all child commands in reverse order.

See alsoredo().