<class name="QUndoCommand" doc="/** <p>The <a href="QUndoCommand.html#QUndoCommand(java.lang.String, com.trolltech.qt.gui.QUndoCommand)"><tt>QUndoCommand</tt></a> class is the base class of all commands stored on a <a href="QUndoStack.html"><tt>QUndoStack</tt></a>.</p> <p>For an overview of Qt's Undo Framework, see the <a href="%2E%2E/qundo.html">overview document</tt></a>.</p> <p>A <a href="QUndoCommand.html#QUndoCommand(java.lang.String, com.trolltech.qt.gui.QUndoCommand)"><tt>QUndoCommand</tt></a> represents a single editing action on a document; for example, inserting or deleting a block of text in a text editor. <a href="QUndoCommand.html#QUndoCommand(java.lang.String, com.trolltech.qt.gui.QUndoCommand)"><tt>QUndoCommand</tt></a> can apply a change to the document with <a href="QUndoCommand.html#redo()"><tt>redo</tt></a> and undo the change with <a href="QUndoCommand.html#undo()"><tt>undo</tt></a>. The implementations for these functions must be provided in a derived class.</p> <pre> class AppendText : public QUndoCommand { public: AppendText(QString *doc, const QString &amp;text) : m_document(doc), m_text(text) { setText(&quot;append text&quot;); } virtual void undo() { m_document-&gt;chop(m_text.length()); } virtual void redo() { m_document-&gt;append(m_text); } private: QString *m_document; QString m_text; };</pre> <p>A <a href="QUndoCommand.html#QUndoCommand(java.lang.String, com.trolltech.qt.gui.QUndoCommand)"><tt>QUndoCommand</tt></a> has an associated <a href="QUndoCommand.html#text()"><tt>text</tt></a>. 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().</p> <p><a href="QUndoCommand.html#QUndoCommand(java.lang.String, com.trolltech.qt.gui.QUndoCommand)"><tt>QUndoCommand</tt></a> objects are owned by the stack they were pushed on. <a href="QUndoStack.html"><tt>QUndoStack</tt></a> deletes a command if it has been undone and a new command is pushed. For example:</p> <pre> MyCommand *command1 = new MyCommand(); stack-&gt;push(command1); MyCommand *command2 = new MyCommand(); stack-&gt;push(command2); stack-&gt;undo(); MyCommand *command3 = new MyCommand(); stack-&gt;push(command3); <span class="comment">// command2 gets deleted</span></pre> <p>In effect, when a command is pushed, it becomes the top-most command on the stack.</p> <p>To support command compression, <a href="QUndoCommand.html#QUndoCommand(java.lang.String, com.trolltech.qt.gui.QUndoCommand)"><tt>QUndoCommand</tt></a> has an <a href="QUndoCommand.html#id()"><tt>id</tt></a> and the virtual function <a href="QUndoCommand.html#mergeWith(com.trolltech.qt.gui.QUndoCommand)"><tt>mergeWith</tt></a>. These functions are used by QUndoStack::push().</p> <p>To support command macros, a <a href="QUndoCommand.html#QUndoCommand(java.lang.String, com.trolltech.qt.gui.QUndoCommand)"><tt>QUndoCommand</tt></a> 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.</p> <p>The parent in this case is usually an empty command, in that it doesn't provide its own implementation of <a href="QUndoCommand.html#undo()"><tt>undo</tt></a> and <a href="QUndoCommand.html#redo()"><tt>redo</tt></a>. Instead, it uses the base implementations of these functions, which simply call <a href="QUndoCommand.html#undo()"><tt>undo</tt></a> or <a href="QUndoCommand.html#redo()"><tt>redo</tt></a> on all its children. The parent should, however, have a meaningful <a href="QUndoCommand.html#text()"><tt>text</tt></a>.</p> <pre> QUndoCommand *insertRed = new QUndoCommand(); <span class="comment">// an empty command</span> insertRed-&gt;setText(&quot;insert red text&quot;); new InsertText(document, idx, text, insertRed); <span class="comment">// becomes child of insertRed</span> new SetColor(document, idx, text.length(), Qt::red, insertRed); stack.push(insertRed);</pre> <p>Another way to create macros is to use the convenience functions QUndoStack::beginMacro() and QUndoStack::endMacro().</p> @see <a href="QUndoStack.html"><tt>QUndoStack</tt></a> */"> <method name="public QUndoCommand(com.trolltech.qt.gui.QUndoCommand parent)" doc="/** <p>Constructs a <a href="QUndoCommand.html#QUndoCommand(java.lang.String, com.trolltech.qt.gui.QUndoCommand)"><tt>QUndoCommand</tt></a> object with parent <tt>parent</tt>.</p> <p>If <tt>parent</tt> 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.</p> @see <tt>~QUndoCommand</tt> */"/> <method name="public QUndoCommand()" doc="/** <p>Equivalent to <a href="QUndoCommand.html#QUndoCommand(java.lang.String, com.trolltech.qt.gui.QUndoCommand)"><tt>QUndoCommand</tt></a>(0). */"/> <method name="public QUndoCommand(java.lang.String text, com.trolltech.qt.gui.QUndoCommand parent)" doc="/** <p>Constructs a <a href="QUndoCommand.html#QUndoCommand(java.lang.String, com.trolltech.qt.gui.QUndoCommand)"><tt>QUndoCommand</tt></a> object with the given <tt>parent</tt> and <tt>text</tt>.</p> <p>If <tt>parent</tt> 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.</p> @see <tt>~QUndoCommand</tt> */"/> <method name="public QUndoCommand(java.lang.String text)" doc="/** <p>Equivalent to <a href="QUndoCommand.html#QUndoCommand(java.lang.String, com.trolltech.qt.gui.QUndoCommand)"><tt>QUndoCommand</tt></a>(<tt>text</tt>, 0). */"/> <method name="public final void setText(java.lang.String text)" doc="/** <p>Sets the command's text to be the <tt>text</tt> specified.</p> <p>The specified text should be a short user-readable string describing what this command does.</p> @see <a href="QUndoCommand.html#text()"><tt>text</tt></a> @see <tt>QUndoStack::createUndoAction</tt> @see <tt>QUndoStack::createRedoAction</tt> */"/> <method name="public final java.lang.String text()" doc="/** <p>Returns a short text string describing what this command does; for example, &quot;insert text&quot;.</p> <p>The text is used when the text properties of the stack's undo and redo actions are updated.</p> @see <a href="QUndoCommand.html#setText(java.lang.String)"><tt>setText</tt></a> @see <tt>QUndoStack::createUndoAction</tt> @see <tt>QUndoStack::createRedoAction</tt> */"/> <method name="public int id()" doc="/** <p>Returns the ID of this command.</p> <p>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.</p> <p>If the command supports compression this function must be overridden in the derived class to return the correct ID. The base implementation returns -1.</p> <p>QUndoStack::push() will only try to merge two commands if they have the same ID, and the ID is not -1.</p> @see <a href="QUndoCommand.html#mergeWith(com.trolltech.qt.gui.QUndoCommand)"><tt>mergeWith</tt></a> @see <tt>QUndoStack::push</tt> */"/> <method name="public boolean mergeWith(com.trolltech.qt.gui.QUndoCommand other)" doc="/** <p>Attempts to merge this command with <tt>other</tt>. Returns true on success; otherwise returns false.</p> <p>If this function returns true, calling this command's <a href="QUndoCommand.html#redo()"><tt>redo</tt></a> must have the same effect as redoing both this command and <tt>other</tt>. Similarly, calling this command's <a href="QUndoCommand.html#undo()"><tt>undo</tt></a> must have the same effect as undoing <tt>other</tt> and this command.</p> <p><a href="QUndoStack.html"><tt>QUndoStack</tt></a> will only try to merge two commands if they have the same id, and the id is not -1.</p> <p>The default implementation returns false.</p> <pre> bool AppendText::mergeWith(const QUndoCommand *other) { if (other-&gt;id() != id()) <span class="comment">// make sure other is also an AppendText command</span> return false; m_text += static_cast&lt;const AppendText*&gt;(other)-&gt;m_text; return true; }</pre> @see <a href="QUndoCommand.html#id()"><tt>id</tt></a> @see <tt>QUndoStack::push</tt> */"/> <method name="public void redo()" doc="/** <p>Applies a change to the document. This function must be implemented in the derived class. Calling QUndoStack::push(), QUndoStack::undo() or QUndoStack::redo() from this function leads to undefined beahavior.</p> <p>The default implementation calls <a href="QUndoCommand.html#redo()"><tt>redo</tt></a> on all child commands.</p> @see <a href="QUndoCommand.html#undo()"><tt>undo</tt></a> */"/> <method name="public void undo()" doc="/** <p>Reverts a change to the document. After <a href="QUndoCommand.html#undo()"><tt>undo</tt></a> is called, the state of the document should be the same as before <a href="QUndoCommand.html#redo()"><tt>redo</tt></a> was called. This function must be implemented in the derived class. Calling QUndoStack::push(), QUndoStack::undo() or QUndoStack::redo() from this function leads to undefined beahavior.</p> <p>The default implementation calls <a href="QUndoCommand.html#undo()"><tt>undo</tt></a> on all child commands in reverse order.</p> @see <a href="QUndoCommand.html#redo()"><tt>redo</tt></a> */"/> </class>