Класс QStyledItemDelegate

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

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

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

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

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

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

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

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

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

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

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

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

Эта функция использует виджет 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 для элемента, указанного индексом, согласно стилю опции.