Класс QStyledItemDelegate

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

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

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

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

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

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

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

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

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

• 1 свойство, унаследованное от QObject
• 1 открытый слот, унаследованный от QObject
• 3 сигнала, унаследованные от QAbstractItemDelegate
• 2 сигнала, унаследованные от QObject
• 1 открытая переменная, унаследованная от QObject
• 10 статические открытые члены, унаследованные от QObject
• 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 vs. 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 сохраняются в модели, и редактор закрывается. Если 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().

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