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