Класс QItemDelegate

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

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

Свойства

• clipping : bool

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

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

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

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

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

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

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

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

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

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

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

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

[virtual] QItemDelegate::~QItemDelegate()

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

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

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

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

[override 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 сохраняются в модели, и редактор закрывается. Если event является нажатием клавиши Tab, представление откроет редактор для следующего элемента. Аналогично, если event является нажатием клавиши Backtab, представление откроет редактор для предыдущего элемента.

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

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

QItemEditorFactory *QItemDelegate::itemEditorFactory() const

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

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

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

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

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

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

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

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

void QItemDelegate::setItemEditorFactory(QItemEditorFactory *factory)

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

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

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

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

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

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

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

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

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

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

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

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

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

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