Класс QStyledItemDelegate

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

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

Открытые функции

Переопределённые открытые функции

Защищённые функции

Переопределённые защищённые функции

Подробное описание

При отображении данных из моделей в представлениях элементов Qt, например, в QTableView, отдельные элементы выводятся делегатом. Кроме того, при редактировании элемента он предоставляет виджет редактора, который размещается поверх представления элементов во время редактирования. QStyledItemDelegate — это делегат по умолчанию для всех представлений элементов Qt и устанавливается на них при их создании.

Класс QStyledItemDelegate — это один из классов модели/представления и является частью фреймворка модели/представления Qt. Делегат позволяет разрабатывать отображение и редактирование элементов независимо от модели и представления.

Данные элементов в моделях присваиваются ItemDataRole; каждый элемент может хранить QVariant для каждой роли. QStyledItemDelegate реализует отображение и редактирование для наиболее распространённых типов данных, ожидаемых пользователями, включая булевы значения, целые числа и строки.

Данные будут отображаться по-разному в зависимости от роли, которую они имеют в модели. В следующей таблице описываются роли и типы данных, которые может обрабатывать делегат для каждой из них. Часто достаточно убедиться, что модель возвращает соответствующие данные для каждой роли, чтобы определить внешний вид элементов в представлениях.

Редакторы создаются с помощью QItemEditorFactory; по умолчанию устанавливается статический экземпляр QItemEditorFactory для всех делегатов элементов. Вы можете установить пользовательский фабрику с помощью setItemEditorFactory() или установить новую фабрику по умолчанию с помощью QItemEditorFactory::setDefaultFactory(). Редактируется данные, хранящиеся в модели с EditRole. См. класс QItemEditorFactory для более подробного введения в фабрики редакторов элементов. Пример Color Editor Factory показывает, как создать пользовательские редакторы с помощью фабрики.

Наследование QStyledItemDelegate

Если делегат не поддерживает отображение необходимых типов данных или требуется настроить отображение элементов, необходимо унаследовать от QStyledItemDelegate и переопределить paint() и, возможно, sizeHint(). Функция paint() вызывается индивидуально для каждого элемента, а с sizeHint() можно указать подсказку для каждого из них.

При переопределении paint() обычно обрабатываются типы данных, которые нужно отобразить, и используется реализация суперкласса для других типов.

Отображение индикаторов флажков выполняется текущей стилем. Стиль также определяет размер и ограничивающие прямоугольники, в которых нужно отображать данные для различных ролей данных. Ограничивающий прямоугольник самого элемента также рассчитывается стилем. При отображении уже поддерживаемых типов данных рекомендуется запрашивать у стиля эти ограничивающие прямоугольники. Более подробное описание этого содержится в описании класса QStyle.

Если требуется изменить какие-либо ограничивающие прямоугольники, рассчитанные стилем, или отображение индикаторов флажков, можно унаследовать от QStyle. Однако обратите внимание, что размер элементов также может повлиять на переопределение sizeHint().

Возможно, пользовательский делегат предоставляет редакторы без использования фабрики редактора элементов. В этом случае необходимо переопределить следующие виртуальные функции:

• createEditor() возвращает виджет, используемый для изменения данных из модели, и может быть переопределён для настройки поведения редактирования.
• setEditorData() предоставляет виджету данные для обработки.
• updateEditorGeometry() гарантирует, что редактор отображается корректно относительно представления элементов.
• setModelData() возвращает обновлённые данные в модель.

Пример Star Delegate демонстрирует создание редакторов путём переопределения этих методов.

QStyledItemDelegate по сравнению с QItemDelegate

Начиная с Qt 4.4, существуют два класса делегатов: QItemDelegate и QStyledItemDelegate. Однако, по умолчанию используется QStyledItemDelegate. Эти два класса — независимые альтернативы для отрисовки и предоставления редакторов для элементов в представлениях. Различие между ними заключается в том, что QStyledItemDelegate использует текущий стиль для отрисовки своих элементов. Поэтому рекомендуется использовать QStyledItemDelegate в качестве базового класса при реализации пользовательских делегатов или при работе со стилями Qt. Код, необходимый для любого из этих классов, должен быть одинаковым, за исключением случаев, когда пользовательский делегат нуждается в использовании стиля для отрисовки.

Если вы хотите настроить отрисовку представлений элементов, вы должны реализовать пользовательский стиль. Подробности см. в документации класса QStyle.

См. также Классы делегатов, QItemDelegate, QAbstractItemDelegate, QStyle, Пример делегата Spin Box, Пример делегата Star и Пример фабрики редактора цвета.

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

QStyledItemDelegate::QStyledItemDelegate(QObject *parent = nullptr)

Конструирует делегат элементов с заданным parent.

[virtual] QStyledItemDelegate::~QStyledItemDelegate()

Уничтожает делегат элементов.

[override virtual] QWidget *QStyledItemDelegate::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().

[virtual] QString QStyledItemDelegate::displayText(const QVariant &value, const QLocale &locale) const

Эта функция возвращает строку, которую делегат будет использовать для отображения Qt::DisplayRole модели в locale. value — значение Qt::DisplayRole, предоставленное моделью.

В реализации по умолчанию используется QLocale::toString для преобразования value в QString.

Эта функция не вызывается для пустых индексов модели, то есть для индексов, для которых модель возвращает недействительный QVariant.

См. также QAbstractItemModel::data().

[override virtual protected] bool QStyledItemDelegate::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 QStyledItemDelegate::eventFilter(QObject *editor, QEvent *event)

Переопределяет: QObject::eventFilter(QObject *watched, QEvent *event).

Возвращает true если заданный editor является допустимым QWidget и заданный event обработан; в противном случае возвращает false. По умолчанию обрабатываются следующие события нажатия клавиш:

• Tab
• Backtab
• Enter
• Return
• Esc

Если тип editor — QTextEdit или QPlainTextEdit, то события нажатия клавиш Enter и Return не обрабатываются.

В случае нажатия клавиш Tab, Backtab, Enter и Return данные editor сохраняются в модели, и редактор закрывается. Если событие — нажатие клавиши Tab, вью покажет редактор для следующего элемента. Аналогично, если событие — нажатие клавиши Backtab, вью покажет редактор для предыдущего элемента.

Если событие — нажатие клавиши Esc, редактор закрывается без сохранения данных.

См. также commitData() и closeEditor().

[virtual protected] void QStyledItemDelegate::initStyleOption(QStyleOptionViewItem *option, const QModelIndex &index) const

Инициализирует option значениями, используя индекс index. Этот метод полезен для подклассов, когда им нужен QStyleOptionViewItem, но они не хотят заполнять всю информацию самостоятельно.

См. также QStyleOption::initFrom().

QItemEditorFactory *QStyledItemDelegate::itemEditorFactory() const

Возвращает фабрику редакторов, используемую делегатом элементов. Если фабрика редакторов не установлена, функция вернёт null.

См. также setItemEditorFactory().

[override virtual] void QStyledItemDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const

Переопределяет: QAbstractItemDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const.

Отображает делегат, используя заданный painter и стиль option для элемента, указанного index.

Эта функция отрисовывает элемент, используя QStyle представления.

При переопределении paint в подклассе используйте initStyleOption(), чтобы настроить option аналогично QStyledItemDelegate.

Всякий раз, когда это возможно, используйте option при отрисовке. Особенно его переменную rect, чтобы определить, где отрисовывать, и его state, чтобы определить, включен ли он или выделен.

После отрисовки убедитесь, что рисовальщик возвращён в состояние, в котором он был при вызове этой функции. Например, полезно вызвать QPainter::save() перед отрисовкой и QPainter::restore() после.

См. также QItemDelegate::paint(), QStyle::drawControl() и QStyle::CE_ItemViewItem.

[override virtual] void QStyledItemDelegate::setEditorData(QWidget *editor, const QModelIndex &index) const

Переопределяет: QAbstractItemDelegate::setEditorData(QWidget *editor, const QModelIndex &index) const.

Устанавливает данные для отображения и редактирования в editor из элемента модели данных, указанного индексом модели index.

В реализации по умолчанию данные хранятся в пользовательском свойстве виджета editor.

См. также QMetaProperty::isUser().

void QStyledItemDelegate::setItemEditorFactory(QItemEditorFactory *factory)

Устанавливает фабрику редакторов, которую должен использовать делегат элементов, в заданную factory. Если фабрика редакторов не установлена, делегат элементов будет использовать фабрику редакторов по умолчанию.

См. также itemEditorFactory().

[override virtual] void QStyledItemDelegate::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 QStyledItemDelegate::sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const

Переопределяет: QAbstractItemDelegate::sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const.

Возвращает размер, необходимый делегату для отображения элемента, указанного индексом index, с учетом информации о стиле, предоставленной option.

Данная функция использует виджет QStyle для определения размера элемента.

См. также QStyle::sizeFromContents() и QStyle::CT_ItemViewItem.

[override virtual] void QStyledItemDelegate::updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, const QModelIndex &index) const

Переопределяет: QAbstractItemDelegate::updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, const QModelIndex &index) const.

Обновляет editor для элемента, указанного index, согласно стилю option.