Класс 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 сохраняются в модели, и редактор закрывается. При нажатии клавиши 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 и сохраняет их в указанной модели в элементе 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.