Класс 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"); }
    virtual void undo()
        { m_document->chop(m_text.length()); }
    virtual void redo()
        { 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 = Q_NULLPTR)

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

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

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

QUndoCommand::QUndoCommand(const QString &text, QUndoCommand *parent = Q_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().