Класс QUndoStack

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

Этот класс был представлен в Qt 4.2.

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

Свойства

Открытые функции

Открытые слоты

Сигналы

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

Для обзора механизма отмены 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().

void QUndoStack::canRedoChanged(bool canRedo)

Этот сигнал испускается всякий раз, когда значение canRedo() изменяется. Он используется для включения или выключения действия повторного выполнения, возвращаемого createRedoAction(). canRedo задаёт новое значение.

Примечание: Сигнал уведомления для свойства canRedo.

void QUndoStack::canUndoChanged(bool canUndo)

Этот сигнал испускается всякий раз, когда значение canUndo() изменяется. Он используется для включения или выключения действия отмены, возвращаемого createUndoAction(). canUndo задаёт новое значение.

Примечание: Сигнал уведомления для свойства canUndo.

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

Этот сигнал излучается всякий раз, когда стек переходит в состояние чистоты или выходит из него. Если clean имеет значение true, стек находится в состоянии чистоты; в противном случае этот сигнал указывает на то, что он вышел из состояния чистоты.

Примечание: Сигнал уведомления для свойства clean.

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

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

Этот сигнал излучается всякий раз, когда команда изменяет состояние документа. Это происходит при отмене или повторении команды. При отмене или повторении макрокоманды, или при вызове setIndex(), этот сигнал излучается только один раз.

idx указывает индекс текущей команды, т. е. команды, которая будет выполнена при следующем вызове redo().

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

[slot] void QUndoStack::redo()

Повторяет текущую команду, вызвав QUndoCommand::redo(). Увеличивает индекс текущей команды.

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

Если для текущей команды QUndoCommand::isObsolete() возвращает true, то команда будет удалена из стека. Кроме того, если индекс чистоты больше или равен индексу текущей команды, то индекс чистоты сбрасывается.

См. также undo() и index().

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

Этот сигнал излучается всякий раз, когда значение redoText() изменяется. Он используется для обновления свойства текста действия повтора, возвращаемого createRedoAction(). redoText указывает новый текст.

Примечание: Сигнал уведомления для свойства 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().

[slot] void QUndoStack::undo()

Отменяет команду, расположенную ниже текущей команды, вызвав QUndoCommand::undo(). Уменьшает индекс текущей команды.

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

После отмены команды, если QUndoCommand::isObsolete() возвращает true, то команда будет удалена из стека. Кроме того, если индекс чистоты больше или равен индексу текущей команды, то индекс чистоты сбрасывается.

См. также redo() и index().

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

Этот сигнал излучается всякий раз, когда значение undoText() изменяется. Он используется для обновления свойства текста действия отмены, возвращаемого createUndoAction(). undoText указывает новый текст.

Примечание: Сигнал уведомления для свойства undoText.

[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().

Примечание: Функция-получатель для свойства canRedo.

См. также index() и canUndo().

bool QUndoStack::canUndo() const

Возвращает true если есть команда, доступная для отмены; в противном случае возвращает false.

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

Эквивалентно index() == 0.

Примечание: Функция-получатель для свойства canUndo.

См. также index() и canRedo().

int QUndoStack::cleanIndex() const

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

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

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

void QUndoStack::clear()

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

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

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

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

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

Возвращает указатель на постоянную команду в позиции index.

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

Эта функция была введена в 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().

bool QUndoStack::isClean() const

Если стек находится в состоянии чистоты, возвращает true; в противном случае возвращает false.

Примечание: Функция-получатель для свойства clean.

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

void QUndoStack::push(QUndoCommand *cmd)

Добавляет cmd в стек или объединяет его с самой последней выполненной командой. В любом случае, выполняет cmd, вызывая его функцию redo().

Если cmd's id не -1, и если id совпадает с id последней выполненной команды, 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().

QString QUndoStack::redoText() const

Возвращает текст команды, которая будет выполнена при следующем вызове redo().

Примечание: Функция-получатель для свойства redoText.

См. также QUndoCommand::actionText() и undoText().

QString QUndoStack::text(int idx) const

Возвращает текст команды с индексом idx.

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

QString QUndoStack::undoText() const

Возвращает текст команды, которая будет отменена при следующем вызове undo().

Примечание: Функция-получатель для свойства undoText.

См. также QUndoCommand::actionText() и redoText().