Класс 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().