Класс 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

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

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