Класс 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::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 сохраняются в модели, и редактор закрывается. Если событие event — нажатие клавиши Tab, представление откроет редактор для следующего элемента в представлении. Аналогично, если event — нажатие клавиши 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.