Класс QUndoStack

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

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

Свойства

• active : bool
• undoLimit : int

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

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

• 31 открытая функция унаследована от 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(). Этот сигнал также излучается, когда стек покидает чистое состояние. Этот сигнал обычно используется для включения и отключения действий сохранения в приложении и для обновления заголовка документа, чтобы отразить, что он содержит несохраненные изменения.

См. также 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 истинно, стек находится в чистом состоянии; в противном случае этот сигнал указывает, что стек покинул чистое состояние.

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

int QUndoStack::cleanIndex() const

Возвращает индекс чистого состояния. Это индекс, в котором был вызван setClean().

Стек может не иметь индекса чистого состояния. Это происходит, если документ сохранён, некоторые команды отменены, затем вставлена новая команда. Так как push() удаляет все отменённые команды перед добавлением новой, стек не может вернуться в чистое состояние снова. В этом случае эта функция возвращает -1.

См. также 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 удаляется.

Во всех остальных случаях cmd просто помещается в стек.

Если команды были отменены до помещения cmd, текущая команда и все команды над ней удаляются. Таким образом, cmd всегда оказывается на вершине стека.

После помещения команды в стек, стек становится её владельцем. Нет методов для возвращения команды, так как изменение её после выполнения почти всегда приведёт к нарушению состояния документа.

См. также QUndoCommand::id() и QUndoCommand::mergeWith().

[slot] void QUndoStack::redo()

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

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

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

QString QUndoStack::redoText() const

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

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

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

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

[slot] void QUndoStack::setClean()

Помечает стек как чистый и излучает cleanChanged(), если стек не был чистым.

Это обычно делается при сохранении документа, например.

Всякий раз, когда стек возвращается в это состояние с помощью команд отмены/повторного выполнения, он излучает сигнал cleanChanged(). Этот сигнал также излучается, когда стек выходит из чистого состояния.

См. также isClean() и 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(). Уменьшает индекс текущей команды.

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

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

QString QUndoStack::undoText() const

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

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

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

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