Класс 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, Пример делегата с полями со списком, Пример редактора настроек и Пример иконок.

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

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, данные редактора сохраняются в модели, а редактор закрывается. Если событие — нажатие клавиши 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.