QUndoStack Class

Dokumentation der Mitgliedsfunktionen

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

Konstruiert einen leeren Rückgängig-Stapel mit dem übergeordneten parent. Der Stapel befindet sich zunächst im sauberen Zustand. Wenn parent ein QUndoGroup Objekt ist, wird der Stapel automatisch zur Gruppe hinzugefügt.

Siehe auch push().

[virtual noexcept] QUndoStack::~QUndoStack()

Zerstört den Rückgängig-Stapel und löscht alle Befehle, die sich auf ihm befinden. Wenn sich der Stapel in einer QUndoGroup befindet, wird der Stapel automatisch aus der Gruppe entfernt.

Siehe auch QUndoStack().

void QUndoStack::beginMacro(const QString &text)

Beginnt die Komposition eines Makrobefehls mit der angegebenen text Beschreibung.

Ein leerer Befehl, der durch die angegebene text beschrieben wird, wird auf den Stack geschoben. Alle nachfolgenden Befehle, die auf den Stack gelegt werden, werden an die Kinder des leeren Befehls angehängt, bis endMacro() aufgerufen wird.

Aufrufe von beginMacro() und endMacro() können verschachtelt werden, aber jeder Aufruf von beginMacro() muss einen passenden Aufruf von endMacro() haben.

Während ein Makro zusammengesetzt wird, ist der Stack deaktiviert. Das bedeutet, dass:

• indexChanged() und cleanChanged() werden nicht ausgegeben,
• canUndo() und canRedo() geben false zurück,
• der Aufruf von undo() oder redo() keine Auswirkungen hat,
• die Undo/Redo-Aktionen sind deaktiviert.

Der Stack wird aktiviert und entsprechende Signale werden ausgegeben, wenn endMacro() für das äußerste Makro aufgerufen wird.

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

Dieser Code ist äquivalent zu:

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

Siehe auch endMacro().

bool QUndoStack::canRedo() const

Gibt true zurück, wenn ein Befehl zur Wiederholung verfügbar ist; andernfalls wird false zurückgegeben.

Diese Funktion gibt false zurück, wenn der Stapel leer ist oder wenn der oberste Befehl auf dem Stapel bereits wiederholt wurde.

Synonym zu index() == count().

Siehe auch index() und canUndo().

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

Dieses Signal wird ausgesendet, wenn sich der Wert von canRedo() ändert. Es wird verwendet, um die von createRedoAction() zurückgegebene Redo-Aktion zu aktivieren oder zu deaktivieren. canRedo gibt den neuen Wert an.

bool QUndoStack::canUndo() const

Gibt true zurück, wenn ein Befehl zum Rückgängigmachen verfügbar ist; andernfalls false.

Diese Funktion gibt false zurück, wenn der Stapel leer ist oder wenn der unterste Befehl auf dem Stapel bereits rückgängig gemacht wurde.

Synonym zu index() == 0.

Siehe auch index() und canRedo().

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

Dieses Signal wird ausgesendet, wenn sich der Wert von canUndo() ändert. Es wird verwendet, um die von createUndoAction() zurückgegebene Rückgängig-Maßnahme zu aktivieren oder zu deaktivieren. canUndo gibt den neuen Wert an.

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

Dieses Signal wird immer dann ausgegeben, wenn der Stack den sauberen Zustand erreicht oder verlässt. Wenn clean wahr ist, befindet sich der Stapel in einem sauberen Zustand; andernfalls zeigt dieses Signal an, dass er den sauberen Zustand verlassen hat.

Siehe auch isClean() und setClean().

int QUndoStack::cleanIndex() const

Gibt den sauberen Index zurück. Dies ist der Index, bei dem setClean() aufgerufen wurde.

Ein Stapel hat möglicherweise keinen sauberen Index. Dies geschieht, wenn ein Dokument gespeichert wird, einige Befehle rückgängig gemacht werden und dann ein neuer Befehl eingefügt wird. Da push() alle rückgängig gemachten Befehle löscht, bevor der neue Befehl eingefügt wird, kann der Stapel nicht mehr in den sauberen Zustand zurückkehren. In diesem Fall gibt die Funktion -1 zurück. Die -1 kann auch nach einem expliziten Aufruf von resetClean() zurückgegeben werden.

Siehe auch isClean() und setClean().

void QUndoStack::clear()

Löscht den Befehlsstapel, indem alle Befehle darin gelöscht werden, und setzt den Stapel in den sauberen Zustand zurück.

Befehle werden nicht rückgängig gemacht oder wiederhergestellt; der Zustand des bearbeiteten Objekts bleibt unverändert.

Diese Funktion wird normalerweise verwendet, wenn der Inhalt des Dokuments aufgegeben wird.

Siehe auch QUndoStack().

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

Gibt einen Konstantenzeiger auf den Befehl an index zurück.

Diese Funktion gibt einen const-Zeiger zurück, da die Änderung eines Befehls, nachdem er auf den Stack geschoben und ausgeführt wurde, fast immer den Zustand des Dokuments beschädigt, wenn der Befehl später rückgängig gemacht oder erneut ausgeführt wird.

Siehe auch QUndoCommand::child().

int QUndoStack::count() const

Gibt die Anzahl der Befehle auf dem Stack zurück. Makrobefehle werden als ein Befehl gezählt.

Siehe auch index(), setIndex(), und command().

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

Erzeugt ein redo QAction Objekt mit dem angegebenen parent.

Das Auslösen dieser Aktion führt zu einem Aufruf von redo(). Der Text dieser Aktion ist der Text des Befehls, der beim nächsten Aufruf von redo() wiederholt wird, vorangestellt durch den angegebenen prefix. Wenn kein Befehl zur Wiederholung verfügbar ist, wird diese Aktion deaktiviert.

Wenn prefix leer ist, wird die Standardvorlage "Redo %1" anstelle des Präfixes verwendet. Vor Qt 4.8 wurde standardmäßig das Präfix "Redo" verwendet.

Siehe auch createUndoAction(), canRedo(), und QUndoCommand::text().

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

Erzeugt ein Undo-Objekt QAction mit dem angegebenen parent.

Das Auslösen dieser Aktion führt zu einem Aufruf von undo(). Der Text dieser Aktion ist der Text des Befehls, der beim nächsten Aufruf von undo() rückgängig gemacht werden soll, mit dem Präfix prefix. Wenn kein Befehl zum Rückgängigmachen verfügbar ist, wird diese Aktion deaktiviert.

Wenn prefix leer ist, wird die Standardvorlage "Undo %1" anstelle des Präfixes verwendet. Vor Qt 4.8 wurde standardmäßig das Präfix "Undo" verwendet.

Siehe auch createRedoAction(), canUndo(), und QUndoCommand::text().

void QUndoStack::endMacro()

Beendet die Komposition eines Makrobefehls.

Wenn dies das äußerste Makro in einem Satz verschachtelter Makros ist, gibt diese Funktion indexChanged() einmal für den gesamten Makrobefehl aus.

Siehe auch beginMacro().

int QUndoStack::index() const

Gibt den Index des aktuellen Befehls zurück. Dies ist der Befehl, der beim nächsten Aufruf von redo() ausgeführt wird. Es ist nicht immer der oberste Befehl auf dem Stack, da eine Reihe von Befehlen rückgängig gemacht worden sein kann.

Siehe auch setIndex(), undo(), redo(), und count().

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

Dieses Signal wird immer dann ausgegeben, wenn ein Befehl den Zustand des Dokuments verändert. Dies geschieht, wenn ein Befehl rückgängig gemacht oder erneut ausgeführt wird. Wenn ein Makrobefehl rückgängig gemacht oder wiederhergestellt wird oder setIndex() aufgerufen wird, wird dieses Signal nur einmal ausgegeben.

idx gibt den Index des aktuellen Befehls an, d. h. den Befehl, der beim nächsten Aufruf von redo() ausgeführt wird.

Siehe auch index() und setIndex().

bool QUndoStack::isClean() const

Wenn sich der Stapel im sauberen Zustand befindet, wird true zurückgegeben; andernfalls wird false zurückgegeben.

Siehe auch setClean() und cleanIndex().

void QUndoStack::push(QUndoCommand *cmd)

Schiebt cmd auf den Stapel oder fügt es mit dem zuletzt ausgeführten Befehl zusammen. In beiden Fällen wird cmd durch Aufruf seiner Funktion redo() ausgeführt.

Wenn die ID von cmd nicht -1 ist und die ID mit der des zuletzt ausgeführten Befehls übereinstimmt, versucht QUndoStack, die beiden Befehle durch den Aufruf von QUndoCommand::mergeWith() mit dem zuletzt ausgeführten Befehl zusammenzuführen. Wenn QUndoCommand::mergeWith() true zurückgibt, wird cmd gelöscht.

Nach dem Aufruf von QUndoCommand::redo() und ggf. QUndoCommand::mergeWith() wird QUndoCommand::isObsolete() für cmd oder den zusammengefassten Befehl aufgerufen. Wenn QUndoCommand::isObsolete() true zurückgibt, wird cmd oder der zusammengefasste Befehl vom Stapel gelöscht.

In allen anderen Fällen wird cmd einfach auf den Stack geschoben.

Wenn Befehle rückgängig gemacht wurden, bevor cmd verschoben wurde, werden der aktuelle Befehl und alle Befehle darüber gelöscht. Daher steht cmd am Ende immer ganz oben auf dem Stapel.

Sobald ein Befehl verschoben wurde, ist der Stack Eigentümer des Befehls. Es gibt keine Getter, die den Befehl zurückgeben, da eine Änderung des Befehls nach seiner Ausführung fast immer zu einer Beschädigung des Dokumentzustands führt.

Siehe auch QUndoCommand::id() und QUndoCommand::mergeWith().

[slot] void QUndoStack::redo()

Wiederholt den aktuellen Befehl durch Aufruf von QUndoCommand::redo(). Erhöht den Index des aktuellen Befehls.

Wenn der Stapel leer ist oder wenn der oberste Befehl auf dem Stapel bereits wiederholt wurde, führt diese Funktion nichts aus.

Wenn QUndoCommand::isObsolete() für den aktuellen Befehl true zurückgibt, wird der Befehl vom Stapel gelöscht. Wenn der Clean-Index größer oder gleich dem aktuellen Befehlsindex ist, wird der Clean-Index zurückgesetzt.

Siehe auch undo() und index().

QString QUndoStack::redoText() const

Gibt den Text des Befehls zurück, der beim nächsten Aufruf von redo() erneut ausgeführt werden soll.

Siehe auch QUndoCommand::actionText() und undoText().

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

Dieses Signal wird ausgesendet, wenn sich der Wert von redoText() ändert. Es wird verwendet, um die Texteigenschaft der Redo-Aktion zu aktualisieren, die von createRedoAction() zurückgegeben wird. redoText gibt den neuen Text an.

[slot] void QUndoStack::resetClean()

Verlässt den sauberen Zustand und gibt cleanChanged() aus, wenn der Stapel sauber war. Diese Methode setzt den Clean-Index auf -1 zurück.

Sie wird typischerweise in den folgenden Fällen aufgerufen, wenn ein Dokument:

• auf der Grundlage einer Vorlage erstellt und noch nicht gespeichert wurde, so dass dem Dokument noch kein Dateiname zugeordnet wurde.
• aus einer Sicherungsdatei wiederhergestellt wurde.
• außerhalb des Editors geändert wurde und der Benutzer es nicht neu geladen hat.

Siehe auch isClean(), setClean(), und cleanIndex().

[slot] void QUndoStack::setClean()

Markiert den Stapel als sauber und gibt cleanChanged() aus, wenn der Stapel nicht bereits sauber war.

Dies wird typischerweise aufgerufen, wenn z. B. ein Dokument gespeichert wird.

Wann immer der Stapel durch die Verwendung von Undo-/Redo-Befehlen in diesen Zustand zurückkehrt, wird das Signal cleanChanged() ausgegeben. Dieses Signal wird auch ausgegeben, wenn der Stack den Clean-Status verlässt.

Siehe auch isClean(), resetClean(), und cleanIndex().

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

Ruft wiederholt undo() oder redo() auf, bis der aktuelle Befehlsindex idx erreicht. Diese Funktion kann verwendet werden, um den Zustand des Dokuments vorwärts oder rückwärts zu rollen. indexChanged() wird nur einmal ausgegeben.

Siehe auch index(), count(), undo(), und redo().

QString QUndoStack::text(int idx) const

Gibt den Text des Befehls mit dem Index idx zurück.

Siehe auch beginMacro().

[slot] void QUndoStack::undo()

Macht den Befehl unterhalb des aktuellen Befehls durch Aufruf von QUndoCommand::undo() rückgängig. Verringert den Index des aktuellen Befehls.

Wenn der Stapel leer ist oder wenn der unterste Befehl auf dem Stapel bereits rückgängig gemacht wurde, bewirkt diese Funktion nichts.

Wenn QUndoCommand::isObsolete() nach dem Rückgängigmachen des Befehls true zurückgibt, wird der Befehl vom Stapel gelöscht. Wenn der Clean-Index größer oder gleich dem aktuellen Befehlsindex ist, wird der Clean-Index außerdem zurückgesetzt.

Siehe auch redo() und index().

QString QUndoStack::undoText() const

Gibt den Text des Befehls zurück, der beim nächsten Aufruf von undo() rückgängig gemacht werden soll.

Siehe auch QUndoCommand::actionText() und redoText().

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

Dieses Signal wird ausgesendet, wenn sich der Wert von undoText() ändert. Es wird verwendet, um die Texteigenschaft der Rückgängig-Aktion zu aktualisieren, die von createUndoAction() zurückgegeben wird. undoText gibt den neuen Text an.