Класс QStyledItemDelegate

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

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

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

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

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

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

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

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

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