Класс QUndoStack

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

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

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

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

[signal] 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, since 5.8] 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.

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

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