QItemDelegate Class
Die Klasse QItemDelegate bietet Anzeige- und Bearbeitungsmöglichkeiten für Datenelemente aus einem Modell. Mehr...
| Kopfzeile: | #include <QItemDelegate> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets)target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Vererbungen: | QAbstractItemDelegate |
Eigenschaften
- clipping : bool
Öffentliche Funktionen
| QItemDelegate(QObject *parent = nullptr) | |
| virtual | ~QItemDelegate() |
| bool | hasClipping() const |
| QItemEditorFactory * | itemEditorFactory() const |
| void | setClipping(bool clip) |
| void | setItemEditorFactory(QItemEditorFactory *factory) |
Reimplementierte öffentliche Funktionen
| virtual QWidget * | createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const override |
| virtual void | paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const override |
| virtual void | setEditorData(QWidget *editor, const QModelIndex &index) const override |
| virtual void | setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const override |
| virtual QSize | sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const override |
| virtual void | updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, const QModelIndex &index) const override |
Geschützte Funktionen
| void | drawBackground(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const |
| virtual void | drawCheck(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, Qt::CheckState state) const |
| virtual void | drawDecoration(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, const QPixmap &pixmap) const |
| virtual void | drawDisplay(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, const QString &text) const |
| virtual void | drawFocus(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect) const |
Reimplementierte geschützte Funktionen
| virtual bool | editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index) override |
| virtual bool | eventFilter(QObject *editor, QEvent *event) override |
Detaillierte Beschreibung
QItemDelegate kann verwendet werden, um benutzerdefinierte Anzeigefunktionen und Editor-Widgets für Elementansichten basierend auf QAbstractItemView Unterklassen bereitzustellen. Durch die Verwendung eines Delegaten für diesen Zweck können die Anzeige- und Bearbeitungsmechanismen unabhängig von Modell und Ansicht angepasst und entwickelt werden.
Die Klasse QItemDelegate gehört zu den Model/View-Klassen und ist Teil des Model/View-Frameworks von Qt. Beachten Sie, dass QStyledItemDelegate die Aufgabe übernommen hat, Qt's Item Views zu zeichnen. Wir empfehlen die Verwendung von QStyledItemDelegate, wenn Sie neue Delegates erstellen.
Bei der Anzeige von Elementen aus einem benutzerdefinierten Modell in einer Standardansicht reicht es oft aus, einfach sicherzustellen, dass das Modell geeignete Daten für jede der roles zurückgibt, die das Aussehen von Elementen in Ansichten bestimmen. Der Standarddelegat, der von den Standardansichten von Qt verwendet wird, nutzt diese Rolleninformationen, um Elemente in den meisten der üblichen Formen anzuzeigen, die von Benutzern erwartet werden. Manchmal ist es jedoch notwendig, noch mehr Kontrolle über das Aussehen von Elementen zu haben, als der Standarddelegat bieten kann.
Diese Klasse bietet Standardimplementierungen der Funktionen zum Zeichnen von Elementdaten in einer Ansicht und zum Bearbeiten von Daten aus Elementmodellen. Standardimplementierungen der virtuellen Funktionen paint() und sizeHint(), die in QAbstractItemDelegate definiert sind, werden bereitgestellt, um sicherzustellen, dass der Delegat das korrekte Grundverhalten implementiert, das von Ansichten erwartet wird. Sie können diese Funktionen in Unterklassen neu implementieren, um das Aussehen von Elementen anzupassen.
Bei der Bearbeitung von Daten in einer Elementansicht stellt QItemDelegate ein Editor-Widget zur Verfügung, ein Widget, das während der Bearbeitung über der Ansicht platziert wird. Editoren werden mit QItemEditorFactory erstellt; eine statische Standardinstanz, die von QItemEditorFactory bereitgestellt wird, wird auf allen Item-Delegates installiert. Sie können eine benutzerdefinierte Fabrik mit setItemEditorFactory() oder eine neue Standardfabrik mit QItemEditorFactory::setDefaultFactory() einstellen. Es sind die Daten, die im Item-Modell mit Qt::EditRole gespeichert sind, die bearbeitet werden.
Nur die Standard-Bearbeitungsfunktionen für Widget-basierte Delegierte werden hier neu implementiert:
- createEditor() gibt das Widget zurück, das zum Ändern von Daten aus dem Modell verwendet wird, und kann zur Anpassung des Editierverhaltens neu implementiert werden.
- setEditorData() versorgt das Widget mit den zu bearbeitenden Daten.
- updateEditorGeometry() stellt sicher, dass der Editor in Bezug auf die Elementansicht korrekt angezeigt wird.
- setModelData() gibt aktualisierte Daten an das Modell zurück.
Das Signal closeEditor() zeigt an, dass der Benutzer die Bearbeitung der Daten abgeschlossen hat und dass das Editor-Widget zerstört werden kann.
Standard-Rollen und Datentypen
Der Standarddelegat, der von den mit Qt gelieferten Standardansichten verwendet wird, assoziiert jede Standardrolle (definiert durch Qt::ItemDataRole) mit bestimmten Datentypen. Modelle, die Daten in diesen Typen zurückgeben, können das Aussehen des Delegaten wie in der folgenden Tabelle beschrieben beeinflussen.
| Rolle | Akzeptierte Typen |
|---|---|
| Qt::BackgroundRole | QBrush ( |
| Qt::CheckStateRole | Qt::CheckState |
| Qt::DecorationRole | QIcon, QPixmap und QColor |
| Qt::DisplayRole | QString und Typen mit einer String-Darstellung |
| Qt::EditRole | Siehe QItemEditorFactory für Details |
| Qt::FontRole | QFont |
| Qt::SizeHintRole | QSize |
| Qt::TextAlignmentRole | Qt::Alignment |
| Qt::ForegroundRole | QBrush ( |
Wenn der Standarddelegat nicht den Grad der Anpassung erlaubt, den Sie benötigen, entweder für Anzeigezwecke oder für die Bearbeitung von Daten, ist es möglich, QItemDelegate zu unterklassifizieren, um das gewünschte Verhalten zu implementieren.
Unterklassifizierung
Wenn Sie QItemDelegate unterklassifizieren, um einen Delegaten zu erstellen, der Elemente unter Verwendung eines benutzerdefinierten Renderers anzeigt, ist es wichtig sicherzustellen, dass der Delegat Elemente für alle erforderlichen Zustände, wie ausgewählt, deaktiviert, markiert, darstellen kann. Die Dokumentation der Funktion paint() enthält einige Hinweise, die zeigen, wie dies erreicht werden kann.
Sie können benutzerdefinierte Editoren bereitstellen, indem Sie QItemEditorFactory verwenden. Der folgende Code zeigt, wie ein benutzerdefinierter Editor für Delegierte mit der Standard-Elementeditor-Fabrik verfügbar gemacht werden kann.
QItemEditorFactory *editorFactory = new QItemEditorFactory; QItemEditorCreatorBase *creator = new QStandardItemEditorCreator<MyFancyDateTimeEdit>(); editorFactory->registerEditor(QMetaType::QDateTime, creator); QItemEditorFactory::setDefaultFactory(editorFactory);
Nachdem die Standard-Editor-Fabrik eingestellt wurde, verwenden alle Standard-Element-Delegaten diese (auch die Delegaten, die vor dem Einstellen der Standard-Fabrik erstellt wurden).
Auf diese Weise können Sie die Unterklassifizierung von QItemDelegate vermeiden, und alle Werte des angegebenen Typs (z. B. QMetaType::QDateTime) werden mit dem bereitgestellten Editor bearbeitet (wie MyFancyDateTimeEdit im obigen Beispiel).
Eine Alternative ist die Neuimplementierung von createEditor(), setEditorData(), setModelData() und updateEditorGeometry(). Dieser Prozess wird in der Übersichtsdokumentation zur Model/View-Programmierung beschrieben.
QStyledItemDelegate vs. QItemDelegate
Seit Qt 4.4 gibt es zwei Delegate-Klassen: QItemDelegate und QStyledItemDelegate. Der Standard-Delegate ist jedoch QStyledItemDelegate. Diese beiden Klassen sind unabhängige Alternativen zum Malen und Bereitstellen von Editoren für Elemente in Ansichten. Der Unterschied zwischen ihnen ist, dass QStyledItemDelegate den aktuellen Stil verwendet, um seine Elemente zu malen. Wir empfehlen daher die Verwendung von QStyledItemDelegate als Basisklasse bei der Implementierung von benutzerdefinierten Delegaten oder bei der Arbeit mit Qt-Stylesheets. Der für beide Klassen erforderliche Code sollte gleich sein, es sei denn, der benutzerdefinierte Delegat muss den Stil zum Zeichnen verwenden.
Siehe auch Delegate Classes, QStyledItemDelegate, und QAbstractItemDelegate.
Dokumentation der Eigenschaften
clipping : bool
ob der Delegierte die Malereignisse abschneiden soll
Mit dieser Eigenschaft wird der Malclip auf die Größe des Objekts eingestellt. Der Standardwert ist on. Dies ist z. B. nützlich, wenn Bilder größer sind als die Größe des Objekts.
Zugriffsfunktionen:
| bool | hasClipping() const |
| void | setClipping(bool clip) |
Dokumentation der Mitgliedsfunktionen
[explicit] QItemDelegate::QItemDelegate(QObject *parent = nullptr)
Konstruiert einen Item-Delegaten mit dem angegebenen parent.
[virtual noexcept] QItemDelegate::~QItemDelegate()
Zerstört den Objektdelegaten.
[override virtual] QWidget *QItemDelegate::createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const
Reimplements: QAbstractItemDelegate::createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const.
Gibt das Widget zurück, das zur Bearbeitung des durch index angegebenen Elements verwendet wird. Das Widget parent und der Stil option werden verwendet, um zu steuern, wie das Editor-Widget erscheint.
Siehe auch QAbstractItemDelegate::createEditor().
[protected] void QItemDelegate::drawBackground(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const
Rendert den Artikelhintergrund für das angegebene index, unter Verwendung des angegebenen painter und des Stils option.
[virtual protected] void QItemDelegate::drawCheck(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, Qt::CheckState state) const
Rendert einen Prüfindikator innerhalb des durch rect angegebenen Rechtecks, unter Verwendung des angegebenen painter und des Stils option, unter Verwendung des angegebenen state.
[virtual protected] void QItemDelegate::drawDecoration(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, const QPixmap &pixmap) const
Rendert die Dekoration pixmap innerhalb des durch rect angegebenen Rechtecks unter Verwendung des angegebenen painter und des Stils option.
[virtual protected] void QItemDelegate::drawDisplay(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, const QString &text) const
Rendert die Elementansicht text innerhalb des durch rect angegebenen Rechtecks unter Verwendung des angegebenen painter und des Stils option.
[virtual protected] void QItemDelegate::drawFocus(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect) const
Rendert den Bereich innerhalb des durch rect angegebenen Rechtecks und zeigt an, dass er den Fokus hat, wobei der angegebene painter und Stil option verwendet wird.
[override virtual protected] bool QItemDelegate::editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index)
Reimplements: QAbstractItemDelegate::editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index).
[override virtual protected] bool QItemDelegate::eventFilter(QObject *editor, QEvent *event)
Reimplements: QObject::eventFilter(QObject *watched, QEvent *event).
Gibt true zurück, wenn das angegebene editor ein gültiges QWidget ist und das angegebene event behandelt wird; andernfalls gibt es false zurück. Die folgenden Tastendruck-Ereignisse werden standardmäßig behandelt:
- Tab
- Backtab
- Enter
- Return
- Esc
Bei den Ereignissen Tab, Backtab, Enter und Return werden die Daten von editor in das Modell übernommen und der Editor wird geschlossen. Wenn event ein Tab Tastendruck ist, öffnet die Ansicht einen Editor für das nächste Element in der Ansicht. Handelt es sich bei event um einen Backtab Tastendruck, öffnet die Ansicht einen Editor für das vorherige Element in der Ansicht.
Handelt es sich bei dem Ereignis um einen Esc Tastendruck, wird die editor geschlossen , ohne dass die Daten übernommen werden.
Siehe auch commitData() und closeEditor().
QItemEditorFactory *QItemDelegate::itemEditorFactory() const
Gibt die vom Elementdelegaten verwendete Editorfabrik zurück. Wenn keine Editorfabrik gesetzt ist, gibt die Funktion null zurück.
Siehe auch setItemEditorFactory().
[override virtual] void QItemDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const
Reimplements: QAbstractItemDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const.
Rendert den Delegaten unter Verwendung des angegebenen painter und des Stils option für das durch index angegebene Element.
Wenn Sie diese Funktion in einer Unterklasse neu implementieren, sollten Sie den von der Variable rect der Option gehaltenen Bereich aktualisieren, indem Sie die Variable state der Option verwenden, um den Status des anzuzeigenden Elements zu bestimmen, und die Art und Weise, wie es gezeichnet wird, entsprechend anpassen.
So kann es beispielsweise erforderlich sein, ein ausgewähltes Element anders darzustellen als nicht ausgewählte Elemente, wie im folgenden Code gezeigt:
if (option.state & QStyle::State_Selected) painter->fillRect(option.rect, option.palette.highlight());
Nach dem Malen sollten Sie sicherstellen, dass der Painter in den Zustand zurückversetzt wird, in dem er beim Aufruf dieser Funktion geliefert wurde. Es kann zum Beispiel sinnvoll sein, QPainter::save() vor dem Malen und QPainter::restore() danach aufzurufen.
Siehe auch QStyle::State.
[override virtual] void QItemDelegate::setEditorData(QWidget *editor, const QModelIndex &index) const
Reimplements: QAbstractItemDelegate::setEditorData(QWidget *editor, const QModelIndex &index) const.
Legt die vom editor anzuzeigenden und zu bearbeitenden Daten aus dem vom Model index angegebenen Datenmodellelement fest.
Die Standardimplementierung speichert die Daten in der Benutzereigenschaft des Widgets editor.
Siehe auch QMetaProperty::isUser().
void QItemDelegate::setItemEditorFactory(QItemEditorFactory *factory)
Legt die vom Elementdelegierten zu verwendende Editorfabrik auf die angegebene factory fest. Wenn keine Editor-Fabrik eingestellt ist, verwendet der Elementdelegierte die Standard-Editor-Fabrik.
Siehe auch itemEditorFactory().
[override virtual] void QItemDelegate::setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const
Reimplements: QAbstractItemDelegate::setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const.
Holt Daten aus dem Widget editor und speichert sie im angegebenen model unter dem Element index.
Die Standardimplementierung bezieht den im Datenmodell zu speichernden Wert aus der Benutzereigenschaft des editor Widgets.
Siehe auch QMetaProperty::isUser().
[override virtual] QSize QItemDelegate::sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const
Reimplements: QAbstractItemDelegate::sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const.
Gibt die Größe zurück, die der Delegierte benötigt, um das von index angegebene Element anzuzeigen, wobei die von option bereitgestellten Stilinformationen berücksichtigt werden.
Bei der Neuimplementierung dieser Funktion ist zu beachten, dass QItemDelegate im Falle von Textelementen einen Rand (d. h. 2 * QStyle::PM_FocusFrameHMargin) zur Länge des Textes hinzufügt.
[override virtual] void QItemDelegate::updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, const QModelIndex &index) const
Reimplements: QAbstractItemDelegate::updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, const QModelIndex &index) const.
Aktualisiert die editor für das durch index angegebene Element gemäß dem angegebenen Stil option.
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
