Skip to content

PythonQt.Qt.QUndoStack

QUndoStack

PythonQtInstanceWrapper object

Native bases: PythonQtInstanceWrapper

Supplemental documentation: Qt 5 reference:

Detailed Description

For an overview of Qt's Undo Framework, see the overview document.

An undo stack maintains a stack of commands that have been applied to a document.

New commands are pushed on the stack using push(). Commands can be undone and redone using undo() and redo(), or by triggering the actions returned by createUndoAction() and createRedoAction().

QUndoStack keeps track of the current command. This is the command which will be executed by the next call to redo(). The index of this command is returned by index(). The state of the edited object can be rolled forward or back using setIndex(). If the top-most command on the stack has already been redone, index() is equal to count().

QUndoStack provides support for undo and redo actions, command compression, command macros, and supports the concept of a clean state.

Undo and Redo Actions

QUndoStack provides convenient undo and redo QAction objects, which can be inserted into a menu or a toolbar. When commands are undone or redone, QUndoStack updates the text properties of these actions to reflect what change they will trigger. The actions are also disabled when no command is available for undo or redo. These actions are returned by QUndoStack::createUndoAction() and QUndoStack::createRedoAction().

Command Compression and Macros

Command compression is useful when several commands can be compressed into a single command that can be undone and redone in a single operation. For example, when a user types a character in a text editor, a new command is created. This command inserts the character into the document at the cursor position. However, it is more convenient for the user to be able to undo or redo typing of whole words, sentences, or paragraphs. Command compression allows these single-character commands to be merged into a single command which inserts or deletes sections of text. For more information, see QUndoCommand::mergeWith() and push().

A command macro is a sequence of commands, all of which are undone and redone in one go. Command macros are created by giving a command a list of child commands. Undoing or redoing the parent command will cause the child commands to be undone or redone. Command macros may be created explicitly by specifying a parent in the QUndoCommand constructor, or by using the convenience functions beginMacro() and endMacro().

Although command compression and macros appear to have the same effect to the user, they often have different uses in an application. Commands that perform small changes to a document may be usefully compressed if there is no need to individually record them, and if only larger changes are relevant to the user. However, for commands that need to be recorded individually, or those that cannot be compressed, it is useful to use macros to provide a more convenient user experience while maintaining a record of each command.

Clean State

QUndoStack supports the concept of a clean state. When the document is saved to disk, the stack can be marked as clean using setClean(). Whenever the stack returns to this state through undoing and redoing commands, it emits the signal cleanChanged(). This signal is also emitted when the stack leaves the clean state. This signal is usually used to enable and disable the save actions in the application, and to update the document's title to reflect that it contains unsaved changes.

Obsolete Commands

QUndoStack is able to delete commands from the stack if the command is no longer needed. One example may be to delete a command when two commands are merged together in such a way that the merged command has no function. This can be seen with move commands where the user moves their mouse to one part of the screen and then moves it to the original position. The merged command results in a mouse movement of 0. This command can be deleted since it serves no purpose. Another example is with networking commands that fail due to connection issues. In this case, the command is to be removed from the stack because the redo() and undo() functions have no function since there was connection issues.

A command can be marked obsolete with the QUndoCommand::setObsolete() function. The QUndoCommand::isObsolete() flag is checked in QUndoStack::push(), QUndoStack::undo(), QUndoStack::redo(), and QUndoStack::setIndex() after calling QUndoCommand::undo(), QUndoCommand::redo() and QUndoCommand:mergeWith() where applicable.

If a command is set obsolete and the clean index is greater than or equal to the current command index, then the clean index will be reset when the command is deleted from the stack.

Source: https://doc.qt.io/archives/qt-5.15/qundostack.html

Complete member index

Every captured member retains its own identity. Identical captured declaration text is linked once; this does not establish native inheritance or interchangeable objects.

Member Kind Signature Summary
__init__ function (self, *args: Any, **kwargs: Any) -> None Native constructor; consult class documentation for supported overloads. (shared captured text)
active attribute Any This property holds the active status of this stack. (shared captured text)
beginMacro function (self, text: str) -> None Begins composition of a macro command with the given text description. (shared captured text)
blockSignals function (self, b: Any) -> bool X.blockSignals(b) -> bool (shared captured text)
canRedo attribute bool This property holds whether this stack can redo. (shared captured text)
canRedoChanged function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QUndoStack.canRedoChanged; argument details are not documented.
canUndo attribute bool This property holds whether this stack can undo. (shared captured text)
canUndoChanged function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QUndoStack.canUndoChanged; argument details are not documented.
childEvent function (self, event: Any) -> Any (shared captured text)
children function (self) -> tuple X.children() -> tuple (shared captured text)
className function (self, *args: Any, **kwargs: Any) -> Any Return the classname of the object (shared captured text)
clean attribute Any This property holds the clean status of this stack. (shared captured text)
cleanChanged function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QUndoStack.cleanChanged; argument details are not documented.
cleanIndex function (self) -> int X.cleanIndex() -> int (shared captured text)
clear function (self) -> None Clears the command stack by deleting all commands on it, and returns the stack to the clean state. (shared captured text)
command function (self, index: int) -> Any X.command(index) -> PythonQt.QtGui.QUndoCommand (shared captured text)
connect function (self, signal: Any, receiver: Any, slot: Any, type: Any) -> bool X.connect(signal, receiver, slot, type) -> bool (shared captured text)
count function (self) -> int X.count() -> int (shared captured text)
createRedoAction function (self, parent: Any, prefix: str) -> Any X.createRedoAction(parent, prefix) -> PythonQt.QtGui.QAction (shared captured text)
createUndoAction function (self, parent: Any, prefix: str) -> Any X.createUndoAction(parent, prefix) -> PythonQt.QtGui.QAction (shared captured text)
customEvent function (self, event: Any) -> Any (shared captured text)
delete function (self, *args: Any, **kwargs: Any) -> Any Deletes the C++ object (at your own risk, my friend!) (shared captured text)
deleteLater function (self) -> Any (shared captured text)
destroyed function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QUndoStack.destroyed; argument details are not documented.
disconnect function (self, signal: Any, receiver: Any, slot: Any) -> bool X.disconnect(signal, receiver, slot) -> bool (shared captured text)
dumpObjectInfo function (self) -> Any (shared captured text)
dumpObjectTree function (self) -> Any (shared captured text)
dynamicPropertyNames function (self) -> Any (shared captured text)
endMacro function (self) -> None Ends composition of a macro command. (shared captured text)
event function (self, event: Any) -> bool X.event(event) -> bool (shared captured text)
eventFilter function (self, watched: Any, event: Any) -> bool X.eventFilter(watched, event) -> bool (shared captured text)
findChild function (self, type: Any, name: Any) -> Any X.findChild(type, name) -> PythonQt.private.QObject (shared captured text)
findChildren function (self, type: Any, name: Any) -> tuple X.findChildren(type, name) -> tuple (shared captured text)
help function (self, *args: Any, **kwargs: Any) -> Any Shows the help of available methods for this class (shared captured text)
index function (self) -> int X.index() -> int (shared captured text)
indexChanged function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QUndoStack.indexChanged; argument details are not documented.
inherits function (self, *args: Any, **kwargs: Any) -> Any Returns if the class inherits or is of given type name (shared captured text)
installEventFilter function (self, filterObj: Any) -> Any (shared captured text)
isActive function (self) -> bool X.isActive() -> bool (shared captured text)
isClean function (self) -> bool X.isClean() -> bool (shared captured text)
isSignalConnected function (self, signal: Any) -> bool X.isSignalConnected(signal) -> bool (shared captured text)
isWidgetType function (self) -> bool X.isWidgetType() -> bool (shared captured text)
isWindowType function (self) -> bool X.isWindowType() -> bool (shared captured text)
killTimer function (self, id: Any) -> Any (shared captured text)
metaObject function (self) -> Any X.metaObject() -> PythonQt.QtCore.QMetaObject (shared captured text)
moveToThread function (self, thread: Any) -> Any (shared captured text)
objectName attribute Any (shared captured text)
objectNameChanged function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QUndoStack.objectNameChanged; argument details are not documented.
parent function (self) -> Any X.parent() -> PythonQt.private.QObject (shared captured text)
property function (self, name: Any) -> Any X.property(name) -> object (shared captured text)
push function (self, cmd: Any) -> None Pushes cmd on the stack or merges it with the most recently executed command. (shared captured text)
redo function (self) -> None Redoes the current command by calling [QUndoCommand::redo](https://doc.qt.io/archives/qt-5.15/qundocommand.html#redo)(). (shared captured text)
redoText attribute str This property holds the redo text of the next command that is redone. (shared captured text)
redoTextChanged function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QUndoStack.redoTextChanged; argument details are not documented.
removeEventFilter function (self, obj: Any) -> Any (shared captured text)
resetClean function (self) -> None Leaves the clean state and emits [cleanChanged](https://doc.qt.io/archives/qt-5.15/qundostack.html#cleanChanged)() if the stack was clean. (shared captured text)
sender function (self) -> Any X.sender() -> PythonQt.private.QObject (shared captured text)
senderSignalIndex function (self) -> int X.senderSignalIndex() -> int (shared captured text)
setActive function (self, active: bool) -> None (shared captured text)
setClean function (self) -> None Marks the stack as clean and emits [cleanChanged](https://doc.qt.io/archives/qt-5.15/qundostack.html#cleanChanged)() if the stack was not already clean. (shared captured text)
setIndex function (self, idx: int) -> None Repeatedly calls [undo](https://doc.qt.io/archives/qt-5.15/qundostack.html#undo)() or [redo](https://doc.qt.io/archives/qt-5.15/qundostack.html#redo)() until the current command index reaches idx. (shared captured text)
setObjectName function (self, name: Any) -> Any (shared captured text)
setParent function (self, parent: Any) -> Any (shared captured text)
setProperty function (self, name: Any, value: Any) -> bool X.setProperty(name, value) -> bool (shared captured text)
setUndoLimit function (self, limit: int) -> None (shared captured text)
signalsBlocked function (self) -> bool X.signalsBlocked() -> bool (shared captured text)
startTimer function (self, interval: Any, timerType: Any) -> int X.startTimer(interval, timerType) -> int (shared captured text)
text function (self, idx: int) -> str X.text(idx) -> str (shared captured text)
thread function (self) -> Any (shared captured text)
timerEvent function (self, event: Any) -> Any (shared captured text)
tr function (self, text: Any, ambig: Any, n: Any) -> str X.tr(text, ambig, n) -> str (shared captured text)
undo function (self) -> None Undoes the command below the current command by calling [QUndoCommand::undo](https://doc.qt.io/archives/qt-5.15/qundocommand.html#undo)(). (shared captured text)
undoLimit attribute int This property holds the maximum number of commands on this stack. (shared captured text)
undoText attribute str This property holds the undo text of the next command that is undone. (shared captured text)
undoTextChanged function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QUndoStack.undoTextChanged; argument details are not documented.