Класс QItemDelegate

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

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

Свойства

• clipping : bool

• 1 свойство унаследовано от QObject

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

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

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

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

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

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

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

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

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

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

QItemDelegate может использоваться для предоставления настраиваемых функций отображения и виджетов редактирования для представлений элементов, основанных на подклассах QAbstractItemView. Использование делегата для этой цели позволяет настроить механизмы отображения и редактирования независимо от модели и представления.

Класс QItemDelegate — один из классов модели/представления и является частью фреймворка модели/представления Qt. Обратите внимание, что QStyledItemDelegate взял на себя задачу рисования представлений элементов Qt. Мы рекомендуем использовать QStyledItemDelegate при создании новых делегатов.

При отображении элементов из пользовательской модели в стандартном представлении часто достаточно просто убедиться, что модель возвращает соответствующие данные для каждого из ролей, которые определяют внешний вид элементов в представлениях. По умолчанию используемый Qt стандартный делегат использует эту информацию о ролях для отображения элементов в большинстве обычных форм, ожидаемых пользователями. Однако иногда необходимо иметь ещё больший контроль над внешним видом элементов, чем может предоставить стандартный делегат.

Этот класс предоставляет стандартные реализации функций для рисования данных элементов в представлении и редактирования данных из моделей элементов. Стандартные реализации виртуальных функций paint() и sizeHint(), определенных в QAbstractItemDelegate, предоставляются для обеспечения того, что делегат реализует правильное базовое поведение, ожидаемое представлениями. Вы можете переопределить эти функции в подклассах для настройки внешнего вида элементов.

При редактировании данных в представлении элементов QItemDelegate предоставляет виджет редактора, который является виджетом, размещаемым поверх представления во время редактирования. Редакторы создаются с помощью QItemEditorFactory; стандартный статический экземпляр, предоставляемый QItemEditorFactory, устанавливается на всех делегатах элементов. Вы можете установить пользовательский фабричный объект с помощью setItemEditorFactory() или установить новый стандартный фабричный объект с помощью QItemEditorFactory::setDefaultFactory(). Редактируется информация, хранящаяся в модели элементов с помощью Qt::EditRole.

Только стандартные функции редактирования для делегатов на основе виджетов переопределены здесь:

• createEditor() возвращает виджет, используемый для изменения данных из модели, и может быть переопределён для настройки поведения редактирования.
• setEditorData() предоставляет виджету данные для манипуляций.
• updateEditorGeometry() гарантирует правильное отображение редактора относительно представления элементов.
• setModelData() возвращает обновлённые данные в модель.

Сигнал closeEditor() указывает, что пользователь завершил редактирование данных, и что виджет редактора может быть уничтожен.

Стандартные роли и типы данных

Стандартный делегат, используемый стандартными представлениями, поставляемыми с Qt, связывает каждую стандартную роль (определённую в Qt::ItemDataRole) с определёнными типами данных. Модели, которые возвращают данные в этих типах, могут влиять на внешний вид делегата, как описано в следующей таблице.

Если стандартный делегат не позволяет достичь необходимого уровня настройки, как для отображения, так и для редактирования данных, можно создать подкласс QItemDelegate для реализации нужного поведения.

Наследование

При наследовании от QItemDelegate для создания делегата, отображающего элементы с помощью пользовательского рендерера, важно убедиться, что делегат может правильно отображать элементы во всех необходимых состояниях; например, выделенный, отключенный, выбранный. Документация для функции paint() содержит некоторые подсказки, показывающие, как этого можно добиться.

Вы можете предоставить пользовательские редакторы, используя QItemEditorFactory. Пример фабрики редактора цвета Color Editor Factory Example показывает, как можно сделать доступным пользовательский редактор делегатам с помощью стандартной фабрики редактора элементов. Таким образом, нет необходимости наследоваться от QItemDelegate. Альтернативой является переопределение createEditor(), setEditorData(), setModelData() и updateEditorGeometry(). Этот процесс описан в примере делегата с полями ввода Spin Box Delegate Example.

QStyledItemDelegate против QItemDelegate

Начиная с Qt 4.4, существуют два класса делегатов: QItemDelegate и QStyledItemDelegate. Однако, по умолчанию используется QStyledItemDelegate. Эти два класса представляют собой независимые альтернативы для рисования и предоставления редакторов для элементов в представлениях. Разница между ними заключается в том, что QStyledItemDelegate использует текущий стиль для рисования своих элементов. Поэтому мы рекомендуем использовать QStyledItemDelegate в качестве базового класса при реализации пользовательских делегатов или при работе со стилями Qt. Код, необходимый для любого из классов, должен быть одинаковым, если только пользовательский делегат не должен использовать стиль для рисования.

См. также Классы делегатов, QStyledItemDelegate, QAbstractItemDelegate, Пример делегата с полями ввода, Пример редактора настроек и Пример иконок.

Документация по членам-функциям

QItemDelegate::QItemDelegate(QObject *parent = Q_NULLPTR)

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

QItemDelegate::~QItemDelegate()

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

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

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

Возвращает виджет, используемый для редактирования элемента, указанного index, для редактирования. Виджет parent и стиль option используются для управления внешним видом виджета редактора.

См. также QAbstractItemDelegate::createEditor().

[protected] void QItemDelegate::drawBackground(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const

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

Эта функция была добавлена в Qt 4.2.

[virtual protected] void QItemDelegate::drawCheck(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, Qt::CheckState state) const

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

[virtual protected] void QItemDelegate::drawDecoration(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, const QPixmap &pixmap) const

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

[virtual protected] void QItemDelegate::drawDisplay(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, const QString &text) const

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

[virtual protected] void QItemDelegate::drawFocus(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect) const

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

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

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

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

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

Возвращает true, если заданный editor является действительным QWidget, и заданное event обрабатывается; в противном случае возвращает false. По умолчанию обрабатываются следующие события нажатия клавиш:

• Tab
• Backtab
• Enter
• Return
• Esc

В случае нажатия клавиш Tab, Backtab, Enter и Return данные editor сохраняются в модель, и редактор закрывается. Если событие — нажатие клавиши Tab, представление откроет редактор для следующего элемента. Аналогично, если событие — нажатие клавиши Backtab, представление откроет редактор для предыдущего элемента.

Если событие — нажатие клавиши Esc, редактор закрывается без сохранения данных.

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

QItemEditorFactory *QItemDelegate::itemEditorFactory() const

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

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

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

Переопределяет метод из QAbstractItemDelegate::paint().

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

При переопределении этой функции в подклассе необходимо обновить область, содержащуюся в переменной rect опции, используя переменную state опции для определения состояния отображаемого элемента и соответствующим образом скорректировать способ его отрисовки.

Например, выделенный элемент может нуждаться в отображении иначе, чем невыделенные элементы, как показано в следующем коде:

    if (option.state & QStyle::State_Selected)
        painter->fillRect(option.rect, option.palette.highlight());

    int size = qMin(option.rect.width(), option.rect.height());
    int brightness = index.model()->data(index, Qt::DisplayRole).toInt();
    double radius = (size / 2.0) - (brightness / 255.0 * size / 2.0);
    if (radius == 0.0)
        return;

    painter->save();
    painter->setRenderHint(QPainter::Antialiasing, true);
    painter->setPen(Qt::NoPen);
    if (option.state & QStyle::State_Selected)
        painter->setBrush(option.palette.highlightedText());
    else
    ...

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

См. также QStyle::State.

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

Переопределяет метод из QAbstractItemDelegate::setEditorData().

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

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

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

void QItemDelegate::setItemEditorFactory(QItemEditorFactory *factory)

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

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

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

Переопределяет метод из QAbstractItemDelegate::setModelData().

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

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

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

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

Переопределяет метод из QAbstractItemDelegate::sizeHint().

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

При переопределении этой функции обратите внимание, что в случае текстовых элементов QItemDelegate добавляет отступ (т.е. 2 * QStyle::PM_FocusFrameHMargin) к длине текста.

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

Переопределяет метод из QAbstractItemDelegate::updateEditorGeometry().

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