Класс QStyledItemDelegate

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

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

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

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

• 9 открытых функций унаследованы от QAbstractItemDelegate
• 31 открытых функций унаследованы от QObject

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

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

• 9 защищенных функций унаследованы от QObject

Дополнительные унаследованные члены

• 1 свойство унаследовано от QObject
• 1 открытый слот унаследован от QObject
• 3 сигнала унаследованы от QAbstractItemDelegate
• 2 сигнала унаследованы от QObject
• 11 статические открытые члены унаследованы от QObject

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

Класс 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 = Q_NULLPTR)

Создает делегат элементов с заданным parent.

QStyledItemDelegate::~QStyledItemDelegate()

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

[virtual] QWidget *QStyledItemDelegate::createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const

Переопределено из QAbstractItemDelegate::createEditor().

Возвращает виджет, используемый для редактирования элемента, указанного 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().

[virtual protected] bool QStyledItemDelegate::editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index)

Переопределено из QAbstractItemDelegate::editorEvent().

[virtual protected] bool QStyledItemDelegate::eventFilter(QObject *editor, QEvent *event)

Переопределено из QObject::eventFilter().

Возвращает 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, editor закрывается без сохранения его данных.

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

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

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

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

QItemEditorFactory *QStyledItemDelegate::itemEditorFactory() const

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

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

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

Переопределено из QAbstractItemDelegate::paint().

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

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

При переопределении paint в подклассе. Используйте initStyleOption() для настройки option так же, как и QStyledItemDelegate.

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

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

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

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

Переопределено из QAbstractItemDelegate::setEditorData().

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

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

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

void QStyledItemDelegate::setItemEditorFactory(QItemEditorFactory *factory)

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

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

[virtual] void QStyledItemDelegate::setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const

Переопределено из QAbstractItemDelegate::setModelData().

Получает данные из виджета editor и сохраняет их в указанной модели model по индексу index.

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

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

[virtual] QSize QStyledItemDelegate::sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const

Переопределено из QAbstractItemDelegate::sizeHint().

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

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

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

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

Переопределено из QAbstractItemDelegate::updateEditorGeometry().

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