Класс QUndoStack

Класс QUndoStack представляет собой стек объектов QUndoCommand. Подробнее...

• Список всех членов, включая унаследованные

Свойства

• active : bool
• undoLimit : int

• 1 свойство унаследовано от QObject

Публичные функции

• 34 публичные функции унаследованы от QObject

Публичные слоты

• 1 публичный слот унаследован от QObject

Сигналы

• 2 сигнала унаследованы от QObject

Дополнительные унаследованные члены

• 1 публичная переменная унаследована от QObject
• 10 статических публичных членов унаследованы от QObject
• 9 защищенных функций унаследованы от QObject
• 2 защищенных переменных унаследованы от QObject

Подробное описание

Класс QUndoStack представляет собой стек объектов QUndoCommand.

Обзор фреймворка отмены/повтор Qt см. в документе-обзоре.

Стек отмены хранит стек команд, которые были применены к документу.

Новые команды добавляются в стек с помощью push(). Команды можно отменить и повторить, используя undo() и redo(), или вызывая действия, возвращаемые createUndoAction() и createRedoAction().

QUndoStack отслеживает текущую команду. Это команда, которая будет выполнена при следующем вызове redo(). Индекс этой команды возвращается index(). Состояние изменённого объекта можно перемотать вперёд или назад, используя setIndex(). Если верхняя команда в стеке уже была повторена, index() равно count().

QUndoStack предоставляет поддержку действий отмены и повтора, сжатия команд, макросов команд и поддерживает понятие чистого состояния.

Действия отмены и повтора

QUndoStack предоставляет удобные объекты QAction отмены и повтора, которые можно вставлять в меню или панель инструментов. При отмене или повторе команд QUndoStack обновляет текстовые свойства этих действий, чтобы отразить, какое изменение они вызовут. Действия также отключаются, когда нет доступной команды для отмены или повтора. Эти действия возвращаются QUndoStack::createUndoAction() и QUndoStack::createRedoAction().

Сжатие команд и макросы

Сжатие команд полезно, когда несколько команд можно сжать в одну команду, которая может быть отменена и повторена за один раз. Например, когда пользователь вводит символ в текстовом редакторе, создаётся новая команда. Эта команда вставляет символ в документ в позиции курсора. Однако для пользователя удобнее возможность отмены или повтора ввода целых слов, предложений или абзацев. Сжатие команд позволяет объединить эти команды для ввода отдельных символов в одну команду, которая вставляет или удаляет части текста. Для получения дополнительной информации см. QUndoCommand::mergeWith() и push().

Макрос команды — это последовательность команд, которые отменяются и повторяются за один раз. Макросы команд создаются, присваивая команде список дочерних команд. Отмена или повторение родительской команды вызовет отмену или повторение дочерних команд. Макросы команд можно создавать явно, указывая родителя в конструкторе QUndoCommand, или с помощью удобных функций beginMacro() и endMacro().

Хотя сжатие команд и макросы, по-видимому, оказывают одинаковый эффект для пользователя, они часто используются по-разному в приложении. Команды, выполняющие небольшие изменения в документе, могут быть полезно сжаты, если нет необходимости записывать их индивидуально, и если только более крупные изменения важны для пользователя. Однако для команд, которые необходимо записывать индивидуально или которые нельзя сжать, полезно использовать макросы для обеспечения более удобного пользовательского опыта, сохраняя при этом запись каждой команды.

Чистое состояние

QUndoStack поддерживает концепцию чистого состояния. Когда документ сохраняется на диск, стек можно пометить как чистый, используя setClean(). Всякий раз, когда стек возвращается в это состояние путем отмены и повторения команд, он излучает сигнал cleanChanged(). Этот сигнал также излучается, когда стек выходит из чистого состояния. Этот сигнал обычно используется для включения и отключения действий сохранения в приложении и для обновления заголовка документа, чтобы отразить, что он содержит несохраненные изменения.

Устаревшие команды

QUndoStack может удалять команды из стека, если команда больше не нужна. Одним примером может быть удаление команды, когда две команды объединяются таким образом, что объединенная команда не выполняет никакой функции. Это можно увидеть с командами перемещения, когда пользователь перемещает указатель мыши в одну часть экрана, а затем перемещает его в исходное положение. Объединенная команда приводит к перемещению мыши на 0. Эту команду можно удалить, так как она не выполняет никакой функции. Другой пример — с командами сетевого взаимодействия, которые завершаются неудачно из-за проблем с подключением. В этом случае команда должна быть удалена из стека, поскольку функции redo() и undo() не выполняют никакой функции из-за проблем с подключением.

Команду можно пометить как устаревшую с помощью функции QUndoCommand::setObsolete(). Флаг QUndoCommand::isObsolete() проверяется в QUndoStack::push(), QUndoStack::undo(), QUndoStack::redo() и QUndoStack::setIndex() после вызова QUndoCommand::undo(), QUndoCommand::redo() и QUndoCommand:mergeWith(), где это применимо.

Если команда помечена как устаревшая, а индекс чистого состояния больше или равен текущему индексу команды, то индекс чистого состояния будет сброшен, когда команда будет удалена из стека.

См. также QUndoCommand и QUndoView.

Документация функций-членов

QUndoStack::QUndoStack(QObject *parent = nullptr)

Создает пустой стек отмены с родительским элементом parent. Стек поначалу будет в чистом состоянии. Если parent — объект QUndoGroup, стек автоматически добавляется в группу.

См. также push().

[virtual] 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 истинно, стек находится в чистом состоянии; в противном случае этот сигнал указывает, что он вышел из чистого состояния.

См. также isClean() и setClean().

int QUndoStack::cleanIndex() const

Возвращает индекс чистого состояния. Это индекс, на котором был вызван setClean().

У стека может не быть индекса чистого состояния. Это происходит, если документ сохранен, некоторые команды отменены, затем нажата новая команда. Так как push() удаляет все отменённые команды перед добавлением новой, стек не может снова вернуться в чистое состояние. В этом случае эта функция возвращает -1. -1 также может быть возвращено после явного вызова resetClean().

См. также isClean() и setClean().

void QUndoStack::clear()

Очищает стек команд, удаляя все команды в нем и возвращает стек в чистое состояние.

Команды не отменяются и не повторяются; состояние отредактированного объекта остается неизменным.

Эта функция обычно используется, когда содержимое документа отбрасывается.

См. также QUndoStack().

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

Возвращает указатель на константу команды в index.

Эта функция возвращает указатель const, потому что изменение команды после её добавления в стек и выполнения почти всегда приводит к повреждению состояния документа, если команда будет позже отменена или повторена.

Эта функция была добавлена в Qt 4.4.

См. также QUndoCommand::child().

int QUndoStack::count() const

Возвращает количество команд в стеке. Макрокоманды считаются как одна команда.

См. также index(), setIndex(), и command().

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

Создаёт объект QAction для повторения действий с заданным parent.

Вызов этого действия вызовет функцию redo(). Текст этого действия — текст команды, которая будет повторена в следующем вызове redo(), с указанным префиксом prefix. Если доступной команды для повторения нет, это действие будет отключено.

Если prefix пустое, используется шаблон по умолчанию «Повторить %1» вместо префикса. До Qt 4.8 по умолчанию использовался префикс «Повторить».

См. также createUndoAction(), canRedo(), и QUndoCommand::text().

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

Создаёт объект QAction для отмены действий с заданным parent.

Вызов этого действия вызовет функцию undo(). Текст этого действия — текст команды, которая будет отменена в следующем вызове undo(), с указанным префиксом prefix. Если доступной команды для отмены нет, это действие будет отключено.

Если prefix пустое, используется шаблон по умолчанию «Отменить %1» вместо префикса. До Qt 4.8 по умолчанию использовался префикс «Отменить».

См. также 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 в стек или объединяет его с последней выполненной командой. В любом случае выполняет cmd, вызывая его функцию redo().

Если у cmd есть идентификатор, отличный от -1, и если идентификатор совпадает с идентификатором последней выполненной команды, QUndoStack попытается объединить две команды, вызвав QUndoCommand::mergeWith() для последней выполненной команды. Если QUndoCommand::mergeWith() вернёт true, cmd удаляется.

После вызова QUndoCommand::redo() и, при необходимости, QUndoCommand::mergeWith(), функция QUndoCommand::isObsolete() будет вызвана для cmd или объединённой команды. Если QUndoCommand::isObsolete() вернёт true, cmd или объединённая команда будут удалены из стека.

Во всех остальных случаях cmd просто добавляется в стек.

Если команды были отменены до добавления cmd, текущая команда и все команды выше неё удаляются. Таким образом, cmd всегда оказывается вверху стека.

После добавления команды стек принимает на себя её владение. Нет методов для получения команды, так как изменение её после выполнения почти всегда приводит к повреждению состояния документа.

См. также 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.

Этот метод обычно вызывается в следующих случаях, когда документ был:

• создан на основе шаблона и не был сохранён, поэтому с документом ещё не ассоциирован ни один файл.
• восстановлен из файла резервной копии.
• изменён вне редактора, и пользователь его не перезагрузил.

Эта функция была добавлена в Qt 5.8.

См. также 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 указывает новый текст.