class QUndoStack#

QUndoStack 类是一个 QUndoCommand 对象的堆栈。更多信息...

Inheritance diagram of 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。此命令可以删除，因为它没有任何作用。另一个例子是与网络命令，这些命令由于连接问题失败。在这种情况下，应从堆栈中删除该命令，因为重做和撤销函数没有任何功能，因为存在连接问题。

可以使用 setObsolete() 函数将命令标记为废弃。在调用 undo() 、 redo() 和 QUndoCommand 的 mergeWith() 等方法后，将检查 isObsolete() 标志，用于 push() 、 undo() 、 redo() 和 setIndex()。

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

另请参阅

QUndoCommand QUndoView

注意：

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

属性active: bool#

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

应用程序通常有多个撤销堆栈，每个打开的文档一个。活动堆栈是与当前活动文档相关联的堆栈。如果堆栈属于一个QUndoGroup ，则在堆栈活动时，调用undo() 或 redo() 将转发到此堆栈。如果QUndoGroup 被 QUndoView 观察，则当它活动时，查看将显示此堆栈的内容。如果堆栈不属于QUndoGroup，则将其激活不会有影响。

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

另请参阅

QUndoGroup

访问函数
属性canRedo: bool#

此属性保持此堆栈是否可以重做。

此属性表示是否有可以重做的命令。

另请参阅

canRedo() index() canUndo()

访问函数
属性canUndo: bool#

此属性保持此堆栈是否可以撤销。

此属性表示是否有可以撤销的命令。

另请参阅

canUndo() index() canRedo()

访问函数
属性clean:bool#

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

此属性表示堆栈是否为清洁状态。例如，当文档已保存时，堆栈是清洁的。

访问函数
属性redoText:str#

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

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

访问函数
属性undoLimit:int#

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

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

由于在非空堆栈上设置它可能会删除当前索引处的命令，因此只能在空堆栈上设置此属性。在非空堆栈上调用 setUndoLimit() 将打印警告并执行操作。

访问函数
属性 undoTextᅟ: str#

此属性保存下一个撤销操作的文本。

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

访问函数
__init__([parent=None])#
参数：

parent - QObject

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

另请参阅

push()

beginMacro(text)#
参数：

text - 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()
返回类型:

bool

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

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

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

另请参阅

index() canUndo()

获取属性 canRedoᅟ 的值。

canRedoChanged(canRedo)
参数：

canRedo – bool

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

canRedoᅟ 属性的通知信号。

canUndo()
返回类型:

bool

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

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

与 index() == 0 相同。

另请参阅

index() canRedo()

属性 canUndoᅟ 的获取器。

canUndoChanged(canUndo)#
参数：

canUndo – bool

每当 canUndo() 的值更改时，都会发射此信号。它用于启用或禁用由 createUndoAction() 返回的撤销动作。canUndo 指定新值。

属性 canUndoᅟ 的通知信号。

cleanChanged(clean)#
参数：

clean – bool

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

另请参阅

isClean() setClean()

属性 cleanᅟ 的通知信号。

cleanIndex()#
返回类型:

int

返回干净索引。这是 setClean() 被调用时的索引。

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

另请参阅

isClean() setClean()

clear()#

通过删除它上面的所有命令来清除命令堆栈，并将堆栈恢复到干净状态。

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

此函数通常用于文档内容被放弃时。

另请参阅

QUndoStack()

command(index)#
参数：

index – int

返回类型:

QUndoCommand

返回对指定索引处的指令的 const 指针。

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

另请参阅

child()

count()#
返回类型:

int

返回栈上指令的数量。宏指令被视为一条指令。

createRedoAction(parent[, prefix=""])#
参数：
返回类型:

QAction

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

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

如果 prefix 为空，则使用默认模板“重做 %1”，而不是使用前缀。在 Qt 4.8 之前，默认使用“重做”作为前缀。

createUndoAction(parent[, prefix=""])#
参数：
返回类型:

QAction

创建一个带有指定 parent 的 undo QAction 对象。

触发此动作将调用 undo() 。此动作的文本是将在undo()的下一次调用中撤销的命令文本，前面加上指定的代码类。如果没有可供撤销的命令，此动作将处于禁用状态。

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

endMacro()#

结束宏命令的组成。

如果是嵌套宏集的最外层宏，则此函数会对整个宏命令发出一次 indexChanged()。

另请参阅

beginMacro()

index()#
返回类型:

int

返回当前命令的索引。这是在redo()的下一次调用要执行的命令。它不总是堆栈中最顶部的命令，因为可能会有许多命令被撤销。

indexChanged(idx)#
参数：

idx – int

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

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

另请参阅

index() setIndex()

isActive()#
返回类型:

bool

属性active的获取器。

isClean()#
返回类型:

bool

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

另请参阅

setClean() cleanIndex()

属性clean的获取器。

push(cmd)#
参数：

cmd – QUndoCommand

将cmd推入堆栈或与其最近执行的操作合并。在任何情况下，通过调用其redo()函数执行cmd。

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

在调用redo()和可选的mergeWith()之后，对于cmd或合并的命令，将调用isObsolete()。如果isObsolete返回true，则将cmd或合并的命令从堆栈中删除。

在其他所有情况下，将简单地将在堆栈上cmd。

如果在将cmd推入之前撤销了命令，则当前命令及其上方所有命令将被删除。因此，cmd总是会在堆栈的顶部。

一旦命令被推入，堆栈就对其拥有所有权。没有获取器来返回命令，因为在它执行后修改它几乎总会导致文档状态损坏。

redo()#

通过调用redo() 重做当前命令。增加当前命令索引。

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

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

另请参阅

undo() index()

redoText()#
返回类型:

str

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

另请参阅

actionText() undoText()

获取 redoText 属性的值。

redoTextChanged(redoText)#
参数：

redoText - str

每当redoText() 的值更改时，都会发出此信号。它用于更新通过createRedoAction() 返回的重做动作的文本属性。redoText 指定新的文本。

redoText 属性的通知信号。

resetClean()#

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

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

  • 基于某些模板创建并尚未保存，因此尚未将文件名与文档关联。

  • 从备份文件中恢复。

  • 编辑器外部更改，且用户没有重新加载它。

另请参阅

isClean() setClean() cleanIndex()

setActive([active=true])#
参数：

active – bool

另请参阅

isActive()

属性active的设置器。

setClean()#

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

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

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

setIndex(idx)#
参数：

idx – int

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

另请参阅

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

setUndoLimit(limit)#
参数：

limit – int

另请参阅

undoLimit()

属性undoLimit的设置器。

text(idx)#
参数：

idx – int

返回类型:

str

返回索引为idx的操作文本。

另请参阅

beginMacro()

undo()#

通过调用undo() 撤销当前操作下面的操作。递减当前操作索引。

如果堆栈为空，或者堆栈底部的操作已经被撤销，则此函数不做任何事情。

操作被撤销后，如果isObsolete() 返回 true，则该操作将从堆栈中删除。此外，如果干净的索引大于或等于当前操作索引，则将重置干净索引。

另请参阅

redo() index()

undoLimit()#
返回类型:

int

另请参阅

setUndoLimit()

属性undoLimit的获取器。

undoText()#
返回类型:

str

返回下一次调用undo() 将撤销的操作文本。

另请参阅

actionText() redoText()

属性undoText的获取器。

undoTextChanged(undoText)#
参数：

undoText – str

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

属性 undoText 的通知信号。