Класс QUndoStack

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

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

Свойства

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

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

Сигналы

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

Для обзора фреймворка Qt Undo см. документ обзора.

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

Новые команды добавляются в стек с помощью 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 задаёт новое значение.

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

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

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

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

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

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