Класс 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 пустое, используется шаблон по умолчанию "Redo %1", вместо префикса. До Qt 4.8, по умолчанию использовался префикс "Redo".

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

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

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

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

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

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