Класс QItemDelegate

Класс QItemDelegate предоставляет средства отображения и редактирования элементов данных из модели. Подробнее...

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

Свойства

• clipping : bool

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

Переопределённые открытые функции

Защищённые функции

Переопределённые защищённые функции

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

QItemDelegate может использоваться для предоставления пользовательских функций отображения и редактирования элементов данных для представлений элементов, основанных на классах QAbstractItemView. Использование делегата для этой цели позволяет настроить механизмы отображения и редактирования независимо от модели и представления.

Класс QItemDelegate является одним из классов модели/представления и входит в фреймворк Qt модель/представление. Обратите внимание, что QStyledItemDelegate взял на себя работу по отрисовке представлений элементов Qt. Мы рекомендуем использовать QStyledItemDelegate при создании новых делегатов.

При отображении элементов из пользовательской модели в стандартном представлении часто достаточно просто убедиться, что модель возвращает соответствующие данные для каждого из ролей, которые определяют внешний вид элементов в представлениях. По умолчанию делегат, используемый стандартными представлениями Qt, использует эту информацию о роли для отображения элементов в большинстве обычных форм, ожидаемых пользователями. Однако иногда необходимо иметь ещё больший контроль над внешним видом элементов, чем может предоставить стандартный делегат.

Этот класс предоставляет реализации по умолчанию функций для рисования данных элементов в представлении и редактирования данных из моделей элементов. Реализации по умолчанию виртуальных функций paint() и sizeHint(), определённых в QAbstractItemDelegate, обеспечивают, что делегат реализует ожидаемое поведение представления. Вы можете переопределить эти функции в подклассах для настройки внешнего вида элементов.

При редактировании данных в представлении элементов QItemDelegate предоставляет редактирующий виджет, который является виджетом, размещаемым поверх представления во время редактирования. Редакторы создаются с помощью QItemEditorFactory; по умолчанию статический экземпляр, предоставляемый QItemEditorFactory, устанавливается на всех делегатах элементов. Вы можете установить пользовательский фабричный объект с помощью setItemEditorFactory() или установить новый фабричный объект по умолчанию с помощью QItemEditorFactory::setDefaultFactory(). Редактируются данные, хранящиеся в модели элементов с Qt::EditRole.

Только стандартные функции редактирования для делегатов на основе виджетов переопределены здесь:

• createEditor() возвращает виджет, используемый для изменения данных из модели, и может быть переопределён для настройки поведения редактирования.
• setEditorData() предоставляет виджету данные для обработки.
• updateEditorGeometry() обеспечивает правильное отображение редактора по отношению к представлению элементов.
• setModelData() возвращает обновлённые данные модели.

Сигнал closeEditor() указывает, что пользователь завершил редактирование данных и что редактирующий виджет может быть уничтожен.

Стандартные роли и типы данных

По умолчанию делегат, используемый стандартными представлениями Qt, связывает каждую стандартную роль (определённую в Qt::ItemDataRole) с определёнными типами данных. Модели, возвращающие данные этих типов, могут влиять на внешний вид делегата, как описано в следующей таблице.

Если стандартный делегат не позволяет настроить отображаемый вид или редактирование данных так, как вам нужно, можно создать подкласс QItemDelegate, чтобы реализовать желаемое поведение.

Наследование

При наследовании от QItemDelegate для создания делегата, отображающего элементы с помощью пользовательского рендерера, важно убедиться, что делегат может отображать элементы должным образом для всех необходимых состояний; например, выбранные, отключенные, отмеченные. Документация функции paint() содержит некоторые подсказки о том, как этого добиться.

Вы можете предоставить пользовательские редакторы, используя QItemEditorFactory. Пример Color Editor Factory Example демонстрирует, как можно сделать доступным пользовательский редактор для делегатов со стандартной фабрикой редакторов элементов. Таким образом, нет необходимости создавать подкласс QItemDelegate. Альтернативой является переопределение методов createEditor(), setEditorData(), setModelData() и updateEditorGeometry(). Этот процесс описан в примере Spin Box Delegate Example.

QStyledItemDelegate по сравнению с QItemDelegate

С Qt 4.4 существует два класса делегатов: QItemDelegate и QStyledItemDelegate. Однако, по умолчанию используется QStyledItemDelegate. Эти два класса представляют собой независимые альтернативы для рисования и предоставления редакторов для элементов в представлениях. Разница заключается в том, что QStyledItemDelegate использует текущую тему для рисования своих элементов. Поэтому мы рекомендуем использовать QStyledItemDelegate в качестве базового класса при реализации пользовательских делегатов или при работе со стилями Qt. Код, необходимый для обоих классов, должен быть одинаковым, если только пользовательский делегат не должен использовать тему для рисования.

См. также Классы делегатов, QStyledItemDelegate, QAbstractItemDelegate, Spin Box Delegate Example, Settings Editor Example и Пример иконок.

Документация по членам-функциям

QItemDelegate::QItemDelegate(QObject *parent = nullptr)

Создаёт делегат элемента с заданным parent.

[virtual] QItemDelegate::~QItemDelegate()

Уничтожает делегат элемента.

[override virtual] QWidget *QItemDelegate::createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const

Переопределяет: QAbstractItemDelegate::createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const.

Возвращает виджет, используемый для редактирования элемента, указанного параметром index, для редактирования. Виджет parent и стиль option используются для управления внешним видом виджета редактора.

См. также QAbstractItemDelegate::createEditor().

[protected] void QItemDelegate::drawBackground(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const

Отображает фоновый цвет элемента для заданного index, используя заданного painter и стиль option.

[virtual protected] void QItemDelegate::drawCheck(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, Qt::CheckState state) const

Отображает индикатор отметки в прямоугольнике, заданном параметром rect, используя заданный painter и стиль option, используя заданное state.

[virtual protected] void QItemDelegate::drawDecoration(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, const QPixmap &pixmap) const

Отображает декор pixmap в прямоугольнике, заданном параметром rect, используя заданный painter и стиль option.

[virtual protected] void QItemDelegate::drawDisplay(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, const QString &text) const

Отображает текст text элемента представления в прямоугольнике, заданном параметром rect, используя заданного painter и стиль option.

[virtual protected] void QItemDelegate::drawFocus(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect) const

Отображает область в прямоугольнике, заданном параметром rect, указывая, что она имеет фокус, используя заданного painter и стиль option.

[override virtual protected] bool QItemDelegate::editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index)

Переопределяет: QAbstractItemDelegate::editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index).

[override virtual protected] bool QItemDelegate::eventFilter(QObject *editor, QEvent *event)

Переопределяет: QObject::eventFilter(QObject *watched, QEvent *event).

Возвращает true если заданный editor является допустимым виджетом QWidget и заданное event обработано; в противном случае возвращает false. По умолчанию обрабатываются следующие события нажатия клавиш:

• Tab
• Backtab
• Enter
• Return
• Esc

В случае нажатия клавиш Tab, Backtab, Enter и Return данные editor сохраняются в модели, и редактор закрывается. При нажатии клавиши Tab, представление откроет редактор для следующего элемента. Аналогично, при нажатии клавиши Backtab, представление откроет редактор для предыдущего элемента в представлении.

Если событие является нажатием клавиши Esc, редактор закрывается без сохранения его данных.

См. также commitData() и closeEditor().

QItemEditorFactory *QItemDelegate::itemEditorFactory() const

Возвращает фабрику редакторов, используемую делегатом элемента. Если фабрика редакторов не установлена, функция вернёт null.

См. также setItemEditorFactory().

[override virtual] void QItemDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const

Переопределяет: QAbstractItemDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const.

Отображает делегат, используя заданного painter и стиль option для элемента, указанного параметром index.

При переопределении этой функции в подклассе вы должны обновить область, содержащуюся в переменной rect опции, используя переменную state опции, чтобы определить состояние отображаемого элемента, и соответствующим образом настроить способ его отображения.

Например, выбранный элемент может отображаться иначе, чем невыбранные элементы, как показано в следующем коде:

    if (option.state & QStyle::State_Selected)
        painter->fillRect(option.rect, option.palette.highlight());

    const int size = qMin(option.rect.width(), option.rect.height());
    const int brightness = index.model()->data(index, Qt::DisplayRole).toInt();
    const double radius = (size / 2.0) - (brightness / 255.0 * size / 2.0);
    if (qFuzzyIsNull(radius))
        return;

    painter->save();
    painter->setRenderHint(QPainter::Antialiasing, true);
    painter->setPen(Qt::NoPen);
    if (option.state & QStyle::State_Selected)
        painter->setBrush(option.palette.highlightedText());
    else
    ...

После рисования необходимо убедиться, что рисовальщик возвращен в состояние, в котором он находился при вызове этой функции. Например, может быть полезно вызвать QPainter::save() перед рисованием и QPainter::restore() после него.

См. также QStyle::State.

[override virtual] void QItemDelegate::setEditorData(QWidget *editor, const QModelIndex &index) const

Переопределяет: QAbstractItemDelegate::setEditorData(QWidget *editor, const QModelIndex &index) const.

Устанавливает данные для отображения и редактирования editor из элемента модели данных, указанного модельным index.

Реализация по умолчанию сохраняет данные в пользовательском свойстве виджета editor.

См. также QMetaProperty::isUser().

void QItemDelegate::setItemEditorFactory(QItemEditorFactory *factory)

Устанавливает фабрику редакторов, которая будет использоваться делегатом элементов, в качестве factory. Если фабрика редакторов не задана, делегат элементов будет использовать фабрику редакторов по умолчанию.

См. также itemEditorFactory().

[override virtual] void QItemDelegate::setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const

Переопределяет: QAbstractItemDelegate::setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const.

Получает данные из виджета editor и сохраняет их в указанной model в элементе index.

Реализация по умолчанию получает значение для хранения в модели данных из пользовательского свойства виджета editor.

См. также QMetaProperty::isUser().

[override virtual] QSize QItemDelegate::sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const

Переопределяет: QAbstractItemDelegate::sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const.

Возвращает размер, необходимый делегату для отображения элемента, указанного index, с учетом стилистической информации, предоставленной option.

При переопределении этой функции обратите внимание, что в случае текстовых элементов QItemDelegate добавляет отступ (т.е. 2 * QStyle::PM_FocusFrameHMargin) к длине текста.

[override virtual] void QItemDelegate::updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, const QModelIndex &index) const

Переопределяет: QAbstractItemDelegate::updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, const QModelIndex &index) const.

Обновляет editor для элемента, указанного index, в соответствии с заданным стилем option.