QUndoStack Class

成员函数文档

[explicit] QUndoStack::QUndoStack(QObject *parent = nullptr)

使用父对象parent 构建一个空的撤销堆栈。该堆栈初始状态为“干净”状态。如果parent 是一个QUndoGroup 对象，则该堆栈会自动添加到该组中。

另请参阅 push()。

[virtual noexcept] QUndoStack::~QUndoStack()

清除撤销堆栈，删除其中包含的所有命令。如果该堆栈位于QUndoGroup 中，则该堆栈会自动从该组中移除。

另请参阅 QUndoStack()。

void QUndoStack::beginMacro(const QString &text)

开始编写具有给定text 描述的宏命令。

将由指定的text 描述的空命令压入栈中。此后压入栈中的任何命令都将作为该空命令的子命令追加，直到调用endMacro()为止。

对 `beginMacro()` 和 `endMacro()` 的调用可以嵌套，但每次调用 `beginMacro()` 都必须有一个对应的 `endMacro()` 调用。

在宏组合过程中，栈功能会被禁用。这意味着：

• indexChanged() 和cleanChanged() 不会被生成，
• canUndo() 和canRedo() 返回 false，
• 调用 `undo()` 或 `redo()` 不会产生任何效果，
• 撤销/重做操作将被禁用。

当为最外层宏调用endMacro() 时，堆栈将启用，并发出相应的信号。

stack.beginMacro("insert red text");
stack.push(new InsertText(document, idx, text));
stack.push(new SetColor(document, idx, text.length(), Qt::red));
stack.endMacro(); // indexChanged() is emitted

此代码等同于：

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);

另请参阅 endMacro()。

bool QUndoStack::canRedo() const

如果存在可重做的命令，则返回true ；否则返回false 。

如果栈为空，或者栈顶命令已被重做，则此函数返回 `false `。

等同于index() ==count()。

另请参阅 index() 和canUndo()。

[signal] void QUndoStack::canRedoChanged(bool canRedo)

每当canRedo()的值发生变化时，都会触发此信号。它用于启用或禁用createRedoAction()返回的“重做”操作。canRedo 指定新值。

bool QUndoStack::canUndo() const

如果存在可撤销的命令，则返回true ；否则返回false 。

如果命令栈为空，或者栈底的命令已被撤销，则该函数返回 `false `。

等同于index() == 0。

另请参阅 index() 和canRedo()。

[signal] void QUndoStack::canUndoChanged(bool canUndo)

每当canUndo()的值发生变化时，都会触发此信号。它用于启用或禁用createUndoAction()返回的撤销操作。canUndo 指定新值。

[signal] void QUndoStack::cleanChanged(bool clean)

每当栈进入或离开干净状态时，都会发出此信号。如果clean 为真，则栈处于干净状态；否则，该信号表示栈已离开干净状态。

另请参阅 isClean() 和setClean()。

int QUndoStack::cleanIndex() const

返回“干净索引”。这是调用setClean() 时的索引位置。

堆栈可能不具备“干净索引”。这种情况通常发生在文档被保存后，部分命令被撤销，随后又向堆栈中压入了一条新命令。由于push()会在压入新命令之前删除所有已撤销的命令，因此堆栈无法再次恢复到“干净”状态。 在此情况下，该函数返回 -1。在显式调用resetClean() 之后，也可能返回 -1。

另请参阅 isClean() 和setClean()。

void QUndoStack::clear()

通过删除命令堆栈中的所有命令来清空该堆栈，并将堆栈恢复为初始状态。

命令不会被撤销或重做；被编辑对象的状态保持不变。

当文档内容被放弃时，通常会使用此函数。

另请参阅 QUndoStack()。

const QUndoCommand *QUndoStack::command(int index) const

返回指向位于index 处的命令的常量指针。

该函数返回一个 const 指针，因为一旦命令被压入栈并执行，如果随后撤销或重做该命令，修改该命令几乎总是会导致文档状态损坏。

另请参阅 QUndoCommand::child()。

int QUndoStack::count() const

返回栈中命令的数量。宏命令计为一条命令。

另请参阅 index()、setIndex() 和command()。

QAction *QUndoStack::createRedoAction(QObject *parent, const QString &prefix = QString()) const

创建一个带有给定parent 的QAction 重做对象。

触发此操作将导致调用redo()。此操作的文本即为将在下次调用redo() 时被重做的命令文本，其前缀为指定的prefix 。如果没有可重做的命令，此操作将被禁用。

如果prefix 为空，则使用默认模板“Redo %1”代替前缀。在 Qt 4.8 之前，默认使用前缀“Redo”。

另请参阅 createUndoAction()、canRedo() 和QUndoCommand::text()。

QAction *QUndoStack::createUndoAction(QObject *parent, const QString &prefix = QString()) const

创建一个带有给定parent 的QAction 撤销对象。

触发此操作将导致调用undo()。此操作的文本即为下次调用undo() 时将被撤销的命令文本，其前缀为指定的prefix 。如果没有可撤销的命令，此操作将被禁用。

如果prefix 为空，则使用默认模板“Undo %1”代替前缀。在 Qt 4.8 之前，默认使用前缀“Undo”。

另请参阅 createRedoAction()、canUndo()，以及QUndoCommand::text()。

void QUndoStack::endMacro()

结束宏命令的编写。

如果这是一组嵌套宏中最外层的宏，则该函数会为整个宏命令调用一次indexChanged()。

另请参阅 beginMacro()。

int QUndoStack::index() const

返回当前命令的索引。这是下次调用 `redo()` 时将要执行的命令。它不一定是栈顶的命令，因为可能已有若干命令被撤销。

另请参阅 setIndex()、undo()、redo() 以及count()。

[signal] void QUndoStack::indexChanged(int idx)

每当某个命令修改文档的状态时，都会发出此信号。这通常发生在撤销或重做命令时。当撤销或重做宏命令，或者调用setIndex()时，此信号仅发出一次。

idx 指定当前命令的索引，即下次调用redo() 时将执行的命令。

另请参见 index() 和setIndex()。

bool QUndoStack::isClean() const

如果栈处于“clean”状态，则返回true ；否则返回false 。

另请参见 setClean() 和cleanIndex()。

void QUndoStack::push(QUndoCommand *cmd)

将cmd 压入栈中，或将其与最近执行的命令合并。无论哪种情况，都会通过调用其redo()函数来执行cmd 。

如果 `cmd` 的 id 不为 -1，且该 id 与最近执行的命令的 id 相同，则 `QUndoStack ` 将尝试通过在最近执行的命令上调用 `QUndoCommand::mergeWith()` 来合并这两个命令。如果 `QUndoCommand::mergeWith()` 返回 `true`，则 `cmd ` 将被删除。

在调用QUndoCommand::redo() 以及（如适用）QUndoCommand::mergeWith() 之后，将针对cmd 或合并后的命令调用QUndoCommand::isObsolete()。如果QUndoCommand::isObsolete() 返回true ，则cmd 或合并后的命令将从栈中删除。

在所有其他情况下，cmd 仅会被压入堆栈。

如果在将cmd 压入栈之前已撤销了某些命令，则当前命令及其上方的所有命令都会被删除。因此，cmd 最终总会成为栈顶。

一旦命令被压入栈中，栈便对其拥有所有权。没有用于返回该命令的获取器，因为在命令执行后对其进行修改几乎总是会导致文档状态的损坏。

另请参阅 QUndoCommand::id() 和QUndoCommand::mergeWith()。

[slot] void QUndoStack::redo()

通过调用 `QUndoCommand::redo()` 重新执行当前命令。将当前命令索引递增。

如果命令栈为空，或者栈顶的命令已被重做，则此函数不执行任何操作。

如果QUndoCommand::isObsolete() 对于当前命令返回 true，则该命令将从栈中删除。此外，如果清理索引大于或等于当前命令索引，则清理索引将被重置。

另请参阅 undo() 和index()。

QString QUndoStack::redoText() const

返回将在下次调用 `redo()` 时被重做的命令文本。

另请参阅 QUndoCommand::actionText() 和undoText()。

[signal] void QUndoStack::redoTextChanged(const QString &redoText)

每当redoText()的值发生变化时，都会触发此信号。它用于更新createRedoAction()返回的“重做”操作的text属性。redoText 指定新的文本内容。

[slot] void QUndoStack::resetClean()

如果栈处于干净状态，则退出干净状态并调用cleanChanged()。此方法将干净索引重置为-1。

通常在以下情况下调用此方法，即当文档：

• 基于某个模板创建且尚未保存，因此该文档尚未关联文件名。
• 从备份文件中恢复。
• 在编辑器外部被修改，且用户未重新加载该文档。

另请参见 isClean()、setClean() 和cleanIndex()。

[slot] void QUndoStack::setClean()

将栈标记为“干净”，如果栈此前尚未处于“干净”状态，则调用cleanChanged()。

通常在保存文档时会调用此方法，例如。

每当栈通过撤销/重做命令返回此状态时，都会发出cleanChanged() 信号。当栈离开“干净”状态时，也会发出此信号。

另请参阅 isClean()、resetClean() 和cleanIndex()。

[slot] void QUndoStack::setIndex(int idx)

反复调用undo() 或redo()，直到当前命令索引达到idx 。该函数可用于将文档的状态向前或向后回滚。indexChanged() 仅触发一次。

另请参阅 index()、count()、undo() 和redo()。

QString QUndoStack::text(int idx) const

返回索引位置为idx 处的命令文本。

另请参阅 beginMacro()。

[slot] void QUndoStack::undo()

通过调用QUndoCommand::undo()来撤销当前命令下方的命令。将当前命令索引递减。

如果堆栈为空，或者堆栈底部的命令已被撤销，则此函数不执行任何操作。

撤销命令后，如果 `QUndoCommand::isObsolete()` 返回 `true`，则该命令将从堆栈中删除。此外，如果清理索引大于或等于当前命令索引，则清理索引将被重置。

另请参阅 redo() 和index()。

QString QUndoStack::undoText() const

返回将在下次调用 `undo()` 时被撤销的命令的文本。

另请参阅 QUndoCommand::actionText() 和redoText()。

[signal] void QUndoStack::undoTextChanged(const QString &undoText)

每当undoText()的值发生变化时，都会触发此信号。它用于更新createUndoAction()返回的撤销操作的text属性。undoText 指定新的文本内容。