Класс 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 есть связанный текст. Это короткая строка, описывающая действие команды. Она используется для обновления свойств текста действий отмены и повтора стека; см. 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

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

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

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

Возвращает значение, указывающее, является ли команда устаревшей.

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