Класс QUndoCommand

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

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

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

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

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

Обзор фреймворка Qt для отмены/повтор (Undo/Redo), см. обзорный документ.

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().

[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::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().