Класс QUndoCommand

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

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

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

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

Для обзора механизма отмены/повтор 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 есть связанный text(). Это короткая строка, описывающая, что делает команда. Она используется для обновления свойств текста действий отмены и повтора стека; см. 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 имеет id() и виртуальную функцию mergeWith(). Эти функции используются функцией QUndoStack::push().

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

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

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 с заданным parent и text.

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

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

QUndoCommand::QUndoCommand(QUndoCommand *parent = nullptr)

Конструирует объект QUndoCommand с родителем parent.

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

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

[virtual] QUndoCommand::~QUndoCommand()

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

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

QString QUndoCommand::actionText() const

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

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

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

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

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

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

int QUndoCommand::childCount() const

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

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

[virtual] int QUndoCommand::id() const

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

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

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

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

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

[since 5.9] bool QUndoCommand::isObsolete() const

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

Булево значение используется для автоматического удаления команд, которые больше не нужны в стеке. Функция 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().

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