Класс QItemDelegate

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

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

Свойства

• clipping : bool

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

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

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

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

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

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

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

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

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

Если event — событие нажатия клавиши 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.