Класс QUndoStack

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

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

Свойства

• active : bool
• undoLimit : int

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

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

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

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

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

Сигналы

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

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

• 11 статических открытых членов унаследованы от 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 = Q_NULLPTR)

Создаёт пустой стек отмены с родителем parent. Стек изначально будет в чистом состоянии. Если parent является объектом QUndoGroup, стек автоматически добавляется в группу.

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

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

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

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

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

bool QUndoStack::canUndo() const

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

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

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

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

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

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

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

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

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

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

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

[signal] void QUndoStack::redoTextChanged(const QString &redoText)

Этот сигнал испускается всякий раз, когда значение redoText() изменяется. Используется для обновления свойства текста действия повторного выполнения, возвращаемого createRedoAction(). 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().

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

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

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