Класс QUndoCommand

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

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

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

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

Класс 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(QUndoCommand *parent = nullptr)

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

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

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

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

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

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

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

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

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