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 为 true，则堆栈处于清洁状态；否则，该信号表示堆栈已离开清洁状态。

另请参阅 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 的命令的常量指针。

此函数返回一个常量指针，因为一旦命令被推入堆栈并执行，如果命令被撤销或重做，修改命令几乎总是会破坏文档的状态。

另请参见 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

如果堆栈处于清洁状态，则返回true ；否则返回false 。

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

void QUndoStack::push(QUndoCommand *cmd)

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

如果cmd 的 id 不是-1，且与最近执行的命令的 id 相同，则QUndoStack 会在最近执行的命令上调用QUndoCommand::mergeWith() 试图合并两条命令。如果QUndoCommand::mergeWith() 返回true ，cmd 将被删除。

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

在所有其他情况下，cmd 会被简单地推入堆栈。

如果在推入cmd 之前命令已被撤销，则当前命令和其上的所有命令都会被删除。因此，cmd 最终总是堆栈的最顶层。

一旦命令被推送，堆栈就拥有了它的所有权。没有返回命令的 getter，因为在命令执行后修改它几乎总是会导致文档状态的损坏。

另请参阅 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 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 undoText 指定新文本。