PySide6.QtGui.QUndoStack

class QUndoStack

QUndoStack 类是一个 QUndoCommand 对象的堆栈。更多…

PySide6.QtGui.QUndoStack 的继承图

概要

属性

方法

插槽

信号

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述

有关Qt的撤销框架的概述，请参阅概述文档。

撤销栈维护了一个已应用于文档的命令栈。

新命令通过push()推入堆栈。命令可以通过undo()和redo()撤销和重做，或者通过触发createUndoAction()和createRedoAction()返回的操作来实现。

QUndoStack 跟踪当前命令。这是通过下一次调用redo()将执行的命令。此命令的索引由index()返回。可以使用setIndex()向前或向后滚动编辑对象的状态。如果堆栈上的最顶部命令已经被重做，index()等于count()。

QUndoStack 提供了对撤销和重做操作的支持，命令压缩，命令宏，并支持干净状态的概念。

撤销和重做操作

QUndoStack 提供了方便的撤销和重做 QAction 对象，这些对象可以插入到菜单或工具栏中。当命令被撤销或重做时，QUndoStack 会更新这些操作的文本属性，以反映它们将触发的更改。当没有可用的命令进行撤销或重做时，这些操作也会被禁用。这些操作由 createUndoAction() 和 createRedoAction() 返回。

命令压缩和宏

当多个命令可以压缩成一个可以一次性撤销和重做的命令时，命令压缩非常有用。例如，当用户在文本编辑器中输入一个字符时，会创建一个新命令。该命令将字符插入到文档中的光标位置。然而，对于用户来说，能够撤销或重做整个单词、句子或段落的输入更为方便。命令压缩允许将这些单字符命令合并成一个插入或删除文本部分的命令。有关更多信息，请参见mergeWith()和push()。

命令宏是一系列命令的序列，所有这些命令都可以一次性撤销和重做。命令宏是通过给一个命令指定一系列子命令来创建的。撤销或重做父命令将导致子命令被撤销或重做。命令宏可以通过在QUndoCommand构造函数中显式指定父命令来创建，或者通过使用便捷函数beginMacro()和endMacro()来创建。

尽管命令压缩和宏对用户来说似乎有相同的效果，但它们在应用程序中通常有不同的用途。如果不需要单独记录对文档进行小更改的命令，并且只有较大的更改对用户相关，那么这些命令可能有用压缩。然而，对于需要单独记录的命令，或者那些无法压缩的命令，使用宏来提供更便捷的用户体验，同时保持每个命令的记录是有用的。

清理状态

QUndoStack 支持干净状态的概念。当文档保存到磁盘时，可以使用 setClean() 将堆栈标记为干净。每当堆栈通过撤销和重做命令返回到此状态时，它会发出信号 cleanChanged()。当堆栈离开干净状态时，也会发出此信号。此信号通常用于启用和禁用应用程序中的保存操作，并更新文档的标题以反映其包含未保存的更改。

过时的命令

QUndoStack 能够在命令不再需要时从堆栈中删除命令。一个例子是当两个命令以某种方式合并在一起，使得合并后的命令没有功能时，删除一个命令。这可以在移动命令中看到，用户将鼠标移动到屏幕的一个部分，然后将其移回原始位置。合并后的命令导致鼠标移动为0。由于这个命令没有用处，因此可以删除它。另一个例子是由于连接问题而失败的网络命令。在这种情况下，命令应从堆栈中移除，因为由于连接问题，redo() 和 undo() 函数没有功能。

可以使用setObsolete()函数将命令标记为过时。在调用undo()、redo()和QUndoCommand:mergeWith()后，在push()、undo()、redo()和setIndex()中检查isObsolete()标志。

如果命令被设置为过时且清理索引大于或等于当前命令索引，则当命令从堆栈中删除时，清理索引将被重置。

另请参阅

QUndoCommand QUndoView

注意

当使用from __feature__ import true_property时，属性可以直接使用，否则通过访问器函数使用。

property activeᅟ: bool

此属性保存此堆栈的活动状态。

一个应用程序通常有多个撤销栈，每个打开的文档对应一个。活动栈是与当前活动文档相关联的栈。如果栈属于一个QUndoGroup，当它处于活动状态时，调用undo()或redo()将会被转发到这个栈。如果QUndoGroup被QUndoView监视，当它处于活动状态时，视图将显示这个栈的内容。如果栈不属于QUndoGroup，使其处于活动状态将不会有任何效果。

程序员的责任是通过调用setActive()来指定哪个堆栈是活动的，通常是在关联的文档窗口获得焦点时。

另请参阅

QUndoGroup

Access functions:
property canRedoᅟ: bool

此属性表示此堆栈是否可以重做。

此属性指示是否存在可以重做的命令。

另请参阅

canRedo() index() canUndo()

Access functions:
property canUndoᅟ: bool

此属性表示此堆栈是否可以撤销。

此属性指示是否存在可以撤销的命令。

另请参阅

canUndo() index() canRedo()

Access functions:
property cleanᅟ: bool

此属性保存此堆栈的清理状态。

此属性指示堆栈是否干净。例如，当文档已保存时，堆栈是干净的。

Access functions:
property redoTextᅟ: str

此属性保存下一个重做命令的重做文本。

此属性保存将在下一次调用redo()时重做的命令文本。

Access functions:
property undoLimitᅟ: int

此属性保存此堆栈上的最大命令数。

当堆栈上的命令数量超过堆栈的undoLimit时，命令将从堆栈底部删除。宏命令（具有子命令的命令）被视为一个命令。默认值为0，表示没有限制。

此属性只能在撤销堆栈为空时设置，因为在非空堆栈上设置它可能会删除当前索引处的命令。在非空堆栈上调用setUndoLimit()会打印警告并且不执行任何操作。

Access functions:
property undoTextᅟ: str

此属性保存下一个被撤销命令的撤销文本。

此属性保存将在下一次调用undo()时撤销的命令的文本。

Access functions:
__init__([parent=None])
Parameters:

父对象 – QObject

使用父对象 parent 构造一个空的撤销堆栈。堆栈最初将处于干净状态。如果 parent 是一个 QUndoGroup 对象，堆栈会自动添加到该组中。

另请参阅

push()

beginMacro(text)
Parameters:

文本 – str

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

开始使用给定的text描述来组合宏命令。

由指定的text描述的空命令被推入堆栈。任何后续推入堆栈的命令都将附加到空命令的子项中，直到调用endMacro()。

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

在编写宏时，堆栈被禁用。这意味着：

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

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

此代码等同于：

insertRed = QUndoCommand() # an empty command()
insertRed.setText("insert red text")
InsertText(document, idx, text, insertRed) # becomes child of insertRed
SetColor(document, idx, text.length(), Qt.red, insertRed)
stack.push(insertRed)

另请参阅

endMacro()

canRedo()
Return type:

布尔

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

如果堆栈为空或堆栈上的顶部命令已被重做，此函数返回 false。

与 index() == count() 同义。

另请参阅

index() canUndo()

属性 canRedoᅟ 的获取器。

canRedoChanged(canRedo)
Parameters:

canRedo – 布尔值

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

属性 canRedoᅟ 的通知信号。

canUndo()
Return type:

布尔

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

如果堆栈为空，或者堆栈底部的命令已经被撤销，此函数将返回 false。

与 index() == 0 同义。

另请参阅

index() canRedo()

属性 canUndoᅟ 的获取器。

canUndoChanged(canUndo)
Parameters:

canUndo – 布尔值

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

属性 canUndoᅟ 的通知信号。

cleanChanged(clean)
Parameters:

clean – 布尔值

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

另请参阅

isClean() setClean()

属性 cleanᅟ 的通知信号。

cleanIndex()
Return type:

整数

返回清理索引。这是调用setClean()时的索引。

堆栈可能没有干净的索引。这种情况发生在文档被保存后，一些命令被撤销，然后一个新的命令被推送。由于push()在推送新命令之前会删除所有已撤销的命令，堆栈无法再次返回到干净状态。在这种情况下，此函数返回-1。在显式调用resetClean()后，也可能返回-1。

另请参阅

isClean() setClean()

clear()

通过删除命令堆栈上的所有命令来清除命令堆栈，并将其返回到干净状态。

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

此函数通常在文档内容被废弃时使用。

另请参阅

QUndoStack()

command(index)
Parameters:

索引 – int

Return type:

QUndoCommand

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

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

另请参阅

child()

count()
Return type:

整数

返回堆栈上的命令数量。宏命令被视为一个命令。

createRedoAction(parent[, prefix=""])
Parameters:

  • parent – QObject

  • prefix – str

Return type:

QAction

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

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

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

createUndoAction(parent[, prefix=""])
Parameters:

  • parent – QObject

  • prefix – str

Return type:

QAction

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

触发此操作将导致调用undo()。此操作的文本是将在下一次调用undo()时撤销的命令的文本，前面加上指定的prefix。如果没有可用的撤销命令，此操作将被禁用。

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

endMacro()

结束宏命令的组成。

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

另请参阅

beginMacro()

index()
Return type:

整数

返回当前命令的索引。这是在下一次调用redo()时将执行的命令。它不一定是堆栈中最顶层的命令，因为可能已经撤销了一些命令。

indexChanged(idx)
Parameters:

idx – 整数

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

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

另请参阅

index() setIndex()

isActive()
Return type:

布尔

属性 activeᅟ 的获取器。

isClean()
Return type:

布尔

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

另请参阅

setClean() cleanIndex()

属性 cleanᅟ 的获取器。

push(cmd)
Parameters:

cmd – QUndoCommand

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

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

在调用redo()以及适用的mergeWith()之后，将会为cmd或合并的命令调用isObsolete()。如果isObsolete()返回true，那么cmd或合并的命令将从堆栈中删除。

在所有其他情况下，cmd 只是被推入堆栈。

如果在cmd被推入之前命令被撤销，当前命令及其上方的所有命令都将被删除。因此，cmd始终位于堆栈的最顶部。

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

另请参阅

id() mergeWith()

redo()

通过调用redo()重新执行当前命令。增加当前命令的索引。

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

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

另请参阅

undo() index()

redoText()
Return type:

字符串

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

另请参阅

actionText() undoText()

属性 redoTextᅟ 的获取器。

redoTextChanged(redoText)
Parameters:

redoText – str

每当redoText()的值发生变化时，就会发出此信号。它用于更新由createRedoAction()返回的重做操作的文本属性。redoText指定了新文本。

属性 redoTextᅟ 的通知信号。

resetClean()

离开干净状态并发出cleanChanged()如果堆栈是干净的。此方法将干净索引重置为-1。

通常在以下情况下调用，当文档已经：

  • 基于某个模板创建且尚未保存，因此尚未为文档关联文件名。

  • 从备份文件恢复。

  • 在编辑器外部更改，用户未重新加载。

另请参阅

isClean() setClean() cleanIndex()

setActive([active=true])
Parameters:

active – 布尔值

另请参阅

isActive()

属性 activeᅟ 的设置器。

setClean()

将堆栈标记为干净，如果堆栈之前不干净，则发出cleanChanged()。

这通常在文档保存时调用，例如。

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

setIndex(idx)
Parameters:

idx – 整数

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

另请参阅

index() count() undo() redo()

setUndoLimit(limit)
Parameters:

limit – int

另请参阅

undoLimit()

属性 undoLimitᅟ 的设置器。

text(idx)
Parameters:

idx – 整数

Return type:

字符串

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

另请参阅

beginMacro()

undo()

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

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

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

另请参阅

redo() index()

undoLimit()
Return type:

整数

另请参阅

setUndoLimit()

属性 undoLimitᅟ 的获取器。

undoText()
Return type:

字符串

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

另请参阅

actionText() redoText()

属性 undoTextᅟ 的获取器。

undoTextChanged(undoText)
Parameters:

undoText – str

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

属性 undoTextᅟ 的通知信号。