Класс QUndoCommand

Класс QUndoCommand — базовый класс всех команд, хранящихся в стеке команд QUndoStack. Подробнее...

Этот класс был представлен в Qt 4.2.

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

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

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

Обзор механизма отмены/повтора в Qt см. в документе-обзоре.

Объект QUndoCommand представляет собой отдельное действие редактирования документа; например, вставка или удаление блока текста в текстовом редакторе. QUndoCommand может применить изменение к документу с помощью redo() и отменить изменение с помощью undo(). Реализации этих функций должны быть предоставлены в производном классе.

class AppendText : public QUndoCommand
{
public:
    AppendText(QString *doc, const QString &text)
        : m_document(doc), m_text(text) { setText("append text"); }
    void undo() override
        { m_document->chop(m_text.length()); }
    void redo() override
        { m_document->append(m_text); }
private:
    QString *m_document;
    QString m_text;
};

У объекта QUndoCommand есть связанный с ним текст. Это короткая строка, описывающая, что делает команда. Она используется для обновления свойств текста действий отмены и повтора стека; см. QUndoStack::createUndoAction() и QUndoStack::createRedoAction().

Объекты QUndoCommand принадлежат стеку, в который они были добавлены. QUndoStack удаляет команду, если она была отменена, и затем добавлена новая команда. Например:

MyCommand *command1 = new MyCommand();
stack->push(command1);
MyCommand *command2 = new MyCommand();
stack->push(command2);

stack->undo();

MyCommand *command3 = new MyCommand();
stack->push(command3); // command2 gets deleted

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

Для поддержки сжатия команд у QUndoCommand есть идентификатор() и виртуальная функция mergeWith(). Эти функции используются функцией QUndoStack::push().

Для поддержки макросов команд объект QUndoCommand может иметь любое количество дочерних команд. Отмена или повторение родительской команды приведет к отмене или повторению дочерних команд. Команде можно явно назначить родителя в конструкторе. В этом случае команда будет принадлежать родителю.

В данном случае родитель обычно является пустой командой, которая не предоставляет собственную реализацию undo() и redo(). Вместо этого она использует базовые реализации этих функций, которые просто вызывают undo() или redo() для всех своих дочерних команд. Однако у родителя должен быть осмысленный текст.

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);

Другой способ создания макросов — использовать служебные функции QUndoStack::beginMacro() и QUndoStack::endMacro().

См. также QUndoStack.

Документация по функциям-членам

QUndoCommand::QUndoCommand(const QString &text, QUndoCommand *parent = nullptr)

Создает объект QUndoCommand с заданным родительским элементом и текстом.

Если родитель не nullptr, эта команда добавляется в список дочерних элементов родителя. Тогда родительская команда владеет этой командой и удалит ее в своём деструкторе.

См. также ~QUndoCommand().

QUndoCommand::QUndoCommand(QUndoCommand *parent = nullptr)

Создает объект QUndoCommand с родителем parent.

Если родитель не nullptr, эта команда добавляется в список дочерних элементов родителя. Тогда родительская команда владеет этой командой и удалит её в своём деструкторе.

См. также ~QUndoCommand().

[virtual] QUndoCommand::~QUndoCommand()

Уничтожает объект QUndoCommand и все дочерние команды.

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

QString QUndoCommand::actionText() const

Возвращает короткую строку текста, описывающую, что делает эта команда; например, "вставить текст".

Текст используется при обновлении свойств текста действий отмены и повтора стека.

Эта функция была представлена в Qt 4.8.

См. также text(), setText(), QUndoStack::createUndoAction(), и QUndoStack::createRedoAction().

const QUndoCommand *QUndoCommand::child(int index) const

Возвращает дочернюю команду по индексу index.

Эта функция была представлена в Qt 4.4.

См. также childCount() и QUndoStack::command().

int QUndoCommand::childCount() const

Возвращает количество дочерних команд в этой команде.

Эта функция была представлена в Qt 4.4.

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

[virtual] int QUndoCommand::id() const

Возвращает идентификатор этой команды.

Идентификатор команды используется при сжатии команд. Он должен быть целым числом, уникальным для класса этой команды, или -1, если команда не поддерживает сжатие.

Если команда поддерживает сжатие, эта функция должна быть переопределена в производном классе для возвращения правильного идентификатора. Базовая реализация возвращает -1.

QUndoStack::push() будет пытаться объединить две команды только в том случае, если у них одинаковый идентификатор и он не равен -1.

См. также mergeWith() и QUndoStack::push().

bool QUndoCommand::isObsolete() const

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

Булево значение используется для автоматического удаления команд, которые больше не нужны в стеке. Функция isObsolete проверяется в функциях QUndoStack::push(), QUndoStack::undo(), QUndoStack::redo() и QUndoStack::setIndex().

Эта функция была представлена в Qt 5.9.

См. также setObsolete(), mergeWith(), QUndoStack::push(), QUndoStack::undo() и QUndoStack::redo().

[virtual] bool QUndoCommand::mergeWith(const QUndoCommand *command)

Попытка объединения этой команды с командой command. Возвращает true при успехе; в противном случае возвращает false.

Если эта функция возвращает true, вызов redo() этой команды должен иметь тот же эффект, что и повторение и этой команды, и команды command. Аналогично, вызов undo() этой команды должен иметь тот же эффект, что и отмена команды command и этой команды.

QUndoStack будет пытаться объединить две команды только в том случае, если у них одинаковый идентификатор, а идентификатор не равен -1.

По умолчанию реализация возвращает false.

bool AppendText::mergeWith(const QUndoCommand *other)
{
    if (other->id() != id()) // make sure other is also an AppendText command
        return false;
    m_text += static_cast<const AppendText*>(other)->m_text;
    return true;
}

См. также id() и QUndoStack::push().

[virtual] void QUndoCommand::redo()

Применяет изменение к документу. Эта функция должна быть реализована в производном классе. Вызов QUndoStack::push(), QUndoStack::undo() или QUndoStack::redo() из этой функции приводит к неопределенному поведению.

По умолчанию реализация вызывает redo() для всех дочерних команд.

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

void QUndoCommand::setObsolete(bool obsolete)

Устанавливает устарелость команды на obsolete.

Эта функция была добавлена в Qt 5.9.

См. также isObsolete(), mergeWith(), QUndoStack::push(), QUndoStack::undo() и QUndoStack::redo().

void QUndoCommand::setText(const QString &text)

Устанавливает текст команды на указанный text.

Указанный текст должен быть коротким строковым описанием, понятным пользователю, того, что делает эта команда.

Если вам нужно иметь две разные строки для text() и actionText(), разделите их символом «\n» и передайте в эту функцию. Даже если вы не используете эту возможность для английских строк во время разработки, вы можете позволить переводчикам использовать две разные строки, чтобы удовлетворить потребности конкретных языков. Описанная функция и функция actionText() доступны с Qt 4.8.

См. также text(), actionText(), QUndoStack::createUndoAction() и QUndoStack::createRedoAction().

QString QUndoCommand::text() const

Возвращает короткий текстовый строковый заголовок, описывающий действие команды; например, «вставка текста».

Текст используется для названий элементов в QUndoView.

См. также actionText(), setText(), QUndoStack::createUndoAction() и QUndoStack::createRedoAction().

[virtual] void QUndoCommand::undo()

Отменяет изменение в документе. После вызова undo(), состояние документа должно быть таким же, как и до вызова redo(). Эта функция должна быть реализована в производном классе. Вызов QUndoStack::push(), QUndoStack::undo() или QUndoStack::redo() из этой функции приводит к неопределенному поведению.

По умолчанию реализация вызывает undo() для всех дочерних команд в обратном порядке.

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