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