Класс QStyledItemDelegate

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

Этот класс был представлен в Qt 4.2).

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

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

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

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

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

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

При отображении данных из моделей в представлениях элементов 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() возвращает обновлённые данные в модель.

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

QStyledItemDelegate против QItemDelegate

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

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

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

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

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 для определения, включено ли оно или выделено.

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