Класс QItemDelegate

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

Этот класс был представлен в Qt 4.2).

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

Свойства

• 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.

Эта функция была введена в Qt 4.2.

[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
    ...

После отрисовки необходимо убедиться, что painter возвращён в состояние, в котором он был предоставлен при вызове этой функции. Например, может быть полезно вызвать 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.