Класс QStyledItemDelegate

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

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

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

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

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

Статические открытые члены

• 9 статических открытых членов, унаследованных от QObject

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

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

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

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

• 1 свойство, унаследованное от QObject
• 1 открытый слот, унаследованный от QObject
• 3 сигнала, унаследованные от QAbstractItemDelegate
• 2 сигнала, унаследованные от 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 = nullptr)

Конструирует делегат элементов с заданным parent.

[virtual] QStyledItemDelegate::~QStyledItemDelegate()

Удаляет делегат элементов.

[override 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().

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

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

[override 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 сохраняются в модели, и редактор закрывается. Если событие — нажатие клавиши 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().

Отображает делегат с помощью заданного 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().

Устанавливает данные для отображения и редактирования в 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().

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

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

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

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

Реализовано повторно из QAbstractItemDelegate::sizeHint().

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

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

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

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

Реализовано повторно из QAbstractItemDelegate::updateEditorGeometry().

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