Класс QItemDelegate

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

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

Свойства

• clipping : bool

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

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

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

• 9 открытых функций унаследовано от QAbstractItemDelegate
• 32 открытых функции унаследовано от 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::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, Spin Box Delegate Example, Settings Editor Example и Icons Example.

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

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.