Класс QUndoStack

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

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

Свойства

• 1 свойство унаследовано от QObject

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

• 31 открытая функция унаследована от QObject

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

• 1 открытый слот унаследован от QObject

Сигналы

• 2 сигнала унаследованы от QObject

Статические публичные члены

• 9 статических публичных членов, унаследованных от QObject

Дополнительные унаследованные члены

• 9 защищенных функций, унаследованных от QObject

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

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

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

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

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

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

bool QUndoStack::canUndo() const

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

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

Синоним к index() == 0.

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

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

[signal] void QUndoStack::canUndoChanged(bool canUndo)

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

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

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

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

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

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

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

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

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

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

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

bool QUndoStack::isClean() const

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

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

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

void QUndoStack::push(QUndoCommand *cmd)

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

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

[slot] void QUndoStack::redo()

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

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

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

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

QString QUndoStack::redoText() const

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

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

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

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

QString QUndoStack::text(int idx) const

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

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

[slot] void QUndoStack::undo()

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

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

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

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

QString QUndoStack::undoText() const

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

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

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

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

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

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