Класс QStyledItemDelegate

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

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

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

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

• 9 открытых функций, унаследованных от QAbstractItemDelegate
• 32 открытых функции, унаследованных от 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() возвращает обновлённые данные в модель.

Пример Звездочного делегата создаёт редакторы, переопределяя эти методы.

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

Если event — нажатие клавиши 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().

[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.