QQuickWidget Class
Die Klasse QQuickWidget bietet ein Widget für die Anzeige einer Qt Quick Benutzeroberfläche. Mehr...
| Kopfzeile: | #include <QQuickWidget> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS QuickWidgets)target_link_libraries(mytarget PRIVATE Qt6::QuickWidgets) |
| qmake: | QT += quickwidgets |
| Vererbt: | QWidget |
Öffentliche Typen
| enum | ResizeMode { SizeViewToRootObject, SizeRootObjectToView } |
| enum | Status { Null, Ready, Loading, Error } |
Eigenschaften
- resizeMode : ResizeMode
- source : QUrl
- status : const Status
Öffentliche Funktionen
| QQuickWidget(QWidget *parent = nullptr) | |
| QQuickWidget(QQmlEngine *engine, QWidget *parent) | |
| QQuickWidget(const QUrl &source, QWidget *parent = nullptr) | |
| virtual | ~QQuickWidget() override |
| QQmlEngine * | engine() const |
| QList<QQmlError> | errors() const |
| QSurfaceFormat | format() const |
| QImage | grabFramebuffer() const |
| QSize | initialSize() const |
| QQuickWindow * | quickWindow() const |
| QQuickWidget::ResizeMode | resizeMode() const |
| QQmlContext * | rootContext() const |
| QQuickItem * | rootObject() const |
| void | setClearColor(const QColor &color) |
| void | setFormat(const QSurfaceFormat &format) |
| void | setResizeMode(QQuickWidget::ResizeMode) |
| QUrl | source() const |
| QQuickWidget::Status | status() const |
Öffentliche Slots
| void | setSource(const QUrl &url) |
Signale
| void | sceneGraphError(QQuickWindow::SceneGraphError error, const QString &message) |
| void | statusChanged(QQuickWidget::Status status) |
Reimplementierte geschützte Funktionen
| virtual void | dragEnterEvent(QDragEnterEvent *e) override |
| virtual void | dragLeaveEvent(QDragLeaveEvent *e) override |
| virtual void | dragMoveEvent(QDragMoveEvent *e) override |
| virtual void | dropEvent(QDropEvent *e) override |
| virtual bool | event(QEvent *e) override |
| virtual void | focusInEvent(QFocusEvent *event) override |
| virtual bool | focusNextPrevChild(bool next) override |
| virtual void | focusOutEvent(QFocusEvent *event) override |
| virtual void | hideEvent(QHideEvent *) override |
| virtual void | keyPressEvent(QKeyEvent *e) override |
| virtual void | keyReleaseEvent(QKeyEvent *e) override |
| virtual void | mouseDoubleClickEvent(QMouseEvent *e) override |
| virtual void | mouseMoveEvent(QMouseEvent *e) override |
| virtual void | mousePressEvent(QMouseEvent *e) override |
| virtual void | mouseReleaseEvent(QMouseEvent *e) override |
| virtual void | paintEvent(QPaintEvent *event) override |
| virtual void | showEvent(QShowEvent *) override |
| virtual void | wheelEvent(QWheelEvent *e) override |
Detaillierte Beschreibung
Dies ist ein bequemer Wrapper für QQuickWindow, der automatisch eine QML-Szene lädt und anzeigt, wenn die URL der Hauptquelldatei angegeben wird. Alternativ können Sie Ihre eigenen Objekte mit QQmlComponent instanziieren und sie in einem manuell eingerichteten QQuickWidget platzieren.
Typische Verwendung:
QQuickWidget *view = new QQuickWidget; view->setSource(QUrl::fromLocalFile("myqmlfile.qml")); view->show();
Um Fehler im Zusammenhang mit dem Laden und Ausführen von QML mit QQuickWidget zu erhalten, können Sie sich mit dem Signal statusChanged() verbinden und auf QQuickWidget::Error überwachen. Die Fehler sind über QQuickWidget::errors() verfügbar.
QQuickWidget verwaltet auch die Größe des View- und Root-Objekts. Standardmäßig ist resizeMode auf SizeViewToRootObject eingestellt, wodurch die Komponente geladen und die Größe an die Größe der Ansicht angepasst wird. Alternativ kann resizeMode auf SizeRootObjectToView gesetzt werden, wodurch die Größe der Ansicht an die Größe des Stammobjekts angepasst wird.
Überlegungen zur Leistung
QQuickWidget ist eine Alternative zur Verwendung von QQuickView und QWidget::createWindowContainer(). Die Einschränkungen bezüglich der Stapelreihenfolge gelten nicht, was QQuickWidget zu einer flexibleren Alternative macht, die sich eher wie ein gewöhnliches Widget verhält.
Die oben genannten Vorteile gehen jedoch auf Kosten der Leistung:
- Im Gegensatz zu QQuickWindow und QQuickView ist bei QQuickWidget mindestens ein zusätzlicher Rendering-Durchgang erforderlich, der auf einen Farbpuffer außerhalb des Bildschirms abzielt, typischerweise eine 2D-Textur, gefolgt vom Zeichnen eines Textur-Quads. Dies bedeutet eine erhöhte Belastung vor allem für die Fragment-Verarbeitung der GPU.
- Die Verwendung von QQuickWidget deaktiviert die Renderschleife auf allen Plattformen. Das bedeutet, dass einige der Vorteile von Threaded Rendering, z.B. Animator Klassen und vsync-gesteuerte Animationen, nicht zur Verfügung stehen werden.
Hinweis: Vermeiden Sie den Aufruf von winId() auf einem QQuickWidget. Diese Funktion löst die Erstellung eines nativen Fensters aus, was zu Leistungseinbußen und möglicherweise zu Rendering-Störungen führt. Der gesamte Zweck von QQuickWidget ist es, Quick-Szenen ohne ein separates natives Fenster zu rendern, daher sollte es immer vermieden werden, es zu einem nativen Widget zu machen.
Grafik-API-Unterstützung
QQuickWidget funktioniert mit allen 3D-Grafik-APIs, die von Qt Quick unterstützt werden, sowie mit dem software Backend. Andere Backends, z.B. OpenVG, sind jedoch nicht kompatibel und der Versuch, ein QQuickWidget zu konstruieren, wird zu Problemen führen.
Das Überschreiben der Standard-Grafik-API der Plattform erfolgt auf die gleiche Weise wie bei QQuickWindow und QQuickView: entweder durch einen frühen Aufruf von QQuickWindow::setGraphicsApi(), bevor das erste QQuickWidget konstruiert wird, oder durch Setzen der Umgebungsvariablen QSG_RHI_BACKEND.
Hinweis: Ein Top-Level-Fenster kann nur eine einzige Grafik-API für das Rendering verwenden. Wenn Sie zum Beispiel versuchen, ein QQuickWidget, das Vulkan verwendet, und ein QOpenGLWidget in der Widget-Hierarchie desselben Top-Level-Fensters zu platzieren, werden Probleme auftreten und eines der Widgets wird nicht wie erwartet gerendert.
Szenengraph und Kontext-Persistenz
QQuickWidget unterstützt QQuickWindow::isPersistentSceneGraph(), was bedeutet, dass Anwendungen entscheiden können - durch den Aufruf von QQuickWindow::setPersistentSceneGraph() auf dem Fenster, das von der Funktion quickWindow() zurückgegeben wird -, dass Szenegraph-Knoten und andere Qt Quick szenenbezogene Ressourcen freigegeben werden, wenn das Widget ausgeblendet wird. Standardmäßig ist Persistenz aktiviert, genau wie bei QQuickWindow.
Wenn mit OpenGL gearbeitet wird, bietet QQuickWindow die Möglichkeit, persistente OpenGL-Kontexte ebenfalls zu deaktivieren. Diese Einstellung wird derzeit von QQuickWidget ignoriert und der Kontext ist immer persistent. Der OpenGL-Kontext wird also nicht zerstört, wenn das Widget versteckt wird. Der Kontext wird nur zerstört, wenn das Widget zerstört wird oder wenn das Widget in die Hierarchie eines anderen Widgets auf oberster Ebene repariert wird. Einige Anwendungen, insbesondere solche, die ihre eigenen Grafik-Ressourcen haben, weil sie benutzerdefiniertes OpenGL-Rendering in der Qt Quick -Szene durchführen, möchten letzteres vielleicht deaktivieren, da sie nicht darauf vorbereitet sind, den Verlust des Kontextes zu handhaben, wenn ein QQuickWidget in ein anderes Fenster verschoben wird. Solche Anwendungen können das Attribut QCoreApplication::AA_ShareOpenGLContexts setzen. Eine Diskussion über die Details der Initialisierung und Bereinigung von Ressourcen finden Sie in der Dokumentation QOpenGLWidget.
Hinweis: QQuickWidget bietet weniger feinkörnige Kontrolle über seinen internen OpenGL-Kontext als QOpenGLWidget, und es gibt subtile Unterschiede, insbesondere die Tatsache, dass die Deaktivierung des persistenten Szenengraphen zur Zerstörung des Kontexts bei einem Fensterwechsel führt, unabhängig vom Vorhandensein von QCoreApplication::AA_ShareOpenGLContexts.
Einschränkungen
Wenn man andere Widgets darunter platziert und das QQuickWidget transparent macht, führt das nicht zu den erwarteten Ergebnissen: die Widgets darunter sind nicht sichtbar. Das liegt daran, dass in der Praxis das QQuickWidget vor allen anderen regulären, nicht-OpenGL-Widgets gezeichnet wird und daher durchsichtige Lösungen nicht möglich sind. Andere Arten von Layouts, wie z.B. Widgets über dem QQuickWidget, werden wie erwartet funktionieren.
Wenn es unbedingt notwendig ist, kann diese Einschränkung durch das Setzen des Qt::WA_AlwaysStackOnTop -Attributs auf dem QQuickWidget überwunden werden. Beachten Sie jedoch, dass dadurch die Stapelreihenfolge unterbrochen wird. Zum Beispiel wird es nicht möglich sein, andere Widgets über dem QQuickWidget zu haben, so dass es nur in Situationen verwendet werden sollte, in denen ein halbtransparentes QQuickWidget mit anderen Widgets sichtbar darunter erforderlich ist.
Diese Einschränkung gilt nur, wenn sich unter dem QQuickWidget im selben Fenster andere Widgets befinden. Das Fenster halbtransparent zu machen, wobei andere Anwendungen und der Desktop im Hintergrund sichtbar sind, wird auf traditionelle Weise gemacht: Setzen Sie Qt::WA_TranslucentBackground auf das Fenster der obersten Ebene, fordern Sie einen Alphakanal an und ändern Sie die klare Farbe des Qt Quick Scenegraph über setClearColor() in Qt::transparent.
Handhabung der Tabulatortaste
Wenn die Taste [TAB] gedrückt wird, erhält das Element innerhalb des QQuickWidget den Fokus. Wenn dieses Element den [TAB] Tastendruck verarbeiten kann, wird der Fokus innerhalb des Elements entsprechend geändert, andernfalls erhält das nächste Widget in der Fokuskette den Fokus.
Siehe auch Attribute von C++-Typen für QML freilegen, Qt Quick Widgets Beispiel, und QQuickView.
Dokumentation der Mitgliedstypen
enum QQuickWidget::ResizeMode
Diese Aufzählung gibt an, wie die Größe der Ansicht geändert werden soll.
| Konstante | Wert | Beschreibung |
|---|---|---|
QQuickWidget::SizeViewToRootObject | 0 | Die Größe der Ansicht wird mit dem Stammelement in der QML angepasst. |
QQuickWidget::SizeRootObjectToView | 1 | Die Ansicht passt die Größe des Stammelements automatisch an die Größe der Ansicht an. |
enum QQuickWidget::Status
Gibt den Ladestatus der QQuickWidget an.
| Konstante | Wert | Beschreibung |
|---|---|---|
QQuickWidget::Null | 0 | Diese QQuickWidget hat keine Quelle gesetzt. |
QQuickWidget::Ready | 1 | Diese QQuickWidget hat die QML-Komponente geladen und erstellt. |
QQuickWidget::Loading | 2 | Diese QQuickWidget lädt gerade Netzwerkdaten. |
QQuickWidget::Error | 3 | Ein oder mehrere Fehler sind aufgetreten. Rufen Sie errors() auf, um eine Liste der Fehler zu erhalten. |
Dokumentation der Eigenschaft
resizeMode : ResizeMode
Bestimmt, ob die Ansicht die Größe des Fensterinhalts ändern soll.
Wenn diese Eigenschaft auf SizeViewToRootObject (Standard) gesetzt ist, wird die Größe der Ansicht an die Größe des Stammelements in der QML angepasst.
Wenn diese Eigenschaft auf SizeRootObjectToView gesetzt ist, passt die Ansicht die Größe des Stammelements automatisch an die Größe der Ansicht an.
Unabhängig von dieser Eigenschaft ist der sizeHint der Ansicht die Anfangsgröße des Stammelements. Beachten Sie jedoch, dass sich diese Größe ändern kann, da QML dynamisch geladen wird.
Zugriffsfunktionen:
| QQuickWidget::ResizeMode | resizeMode() const |
| void | setResizeMode(QQuickWidget::ResizeMode) |
Siehe auch initialSize().
source : QUrl
Diese Eigenschaft enthält die URL der Quelle der QML-Komponente.
Achten Sie darauf, dass die angegebene URL vollständig und korrekt ist. Verwenden Sie insbesondere QUrl::fromLocalFile(), wenn Sie eine Datei aus dem lokalen Dateisystem laden.
Hinweis: Das Setzen einer Quell-URL führt dazu, dass die QML-Komponente instanziiert wird, auch wenn die URL gegenüber dem aktuellen Wert unverändert ist.
Zugriffsfunktionen:
[read-only] status : const Status
Der aktuelle Stand der Komponente status.
Zugriffsfunktionen:
| QQuickWidget::Status | status() const |
Benachrichtigungssignal:
| void | statusChanged(QQuickWidget::Status status) |
Mitgliederfunktion Dokumentation
[explicit] QQuickWidget::QQuickWidget(QWidget *parent = nullptr)
Konstruiert ein QQuickWidget mit einer Standard-QML-Engine als Kind von parent.
Der Standardwert von parent ist nullptr.
QQuickWidget::QQuickWidget(QQmlEngine *engine, QWidget *parent)
Konstruiert ein QQuickWidget mit dem angegebenen QML engine als Kind von parent.
Hinweis: Das QQuickWidget übernimmt nicht den Besitz des angegebenen engine Objekts; es liegt in der Verantwortung des Aufrufers, die Engine zu zerstören. Wenn die engine vor der Ansicht gelöscht wird, gibt status() QQuickWidget::Error zurück.
[explicit] QQuickWidget::QQuickWidget(const QUrl &source, QWidget *parent = nullptr)
Konstruiert ein QQuickWidget mit einer Standard-QML-Engine und der angegebenen QML source als Kind von parent.
Der Standardwert von parent ist nullptr.
[override virtual noexcept] QQuickWidget::~QQuickWidget()
Zerstört die QQuickWidget.
[override virtual protected] void QQuickWidget::dragEnterEvent(QDragEnterEvent *e)
Reimplements: QWidget::dragEnterEvent(QDragEnterEvent *event).
[override virtual protected] void QQuickWidget::dragLeaveEvent(QDragLeaveEvent *e)
Reimplements: QWidget::dragLeaveEvent(QDragLeaveEvent *event).
[override virtual protected] void QQuickWidget::dragMoveEvent(QDragMoveEvent *e)
Reimplements: QWidget::dragMoveEvent(QDragMoveEvent *event).
[override virtual protected] void QQuickWidget::dropEvent(QDropEvent *e)
Reimplements: QWidget::dropEvent(QDropEvent *event).
QQmlEngine *QQuickWidget::engine() const
Gibt einen Zeiger auf die QQmlEngine zurück, die für die Instanzierung von QML-Komponenten verwendet wird.
QList<QQmlError> QQuickWidget::errors() const
Gibt die Liste der Fehler zurück, die während des letzten Kompilier- oder Erstellungsvorgangs aufgetreten sind. Wenn der Status nicht Error ist, wird eine leere Liste zurückgegeben.
Siehe auch status.
[override virtual protected] bool QQuickWidget::event(QEvent *e)
Reimplements: QWidget::event(QEvent *Event).
[override virtual protected] void QQuickWidget::focusInEvent(QFocusEvent *event)
Reimplements: QWidget::focusInEvent(QFocusEvent *event).
[override virtual protected] bool QQuickWidget::focusNextPrevChild(bool next)
Reimplements: QWidget::focusNextPrevChild(bool next).
[override virtual protected] void QQuickWidget::focusOutEvent(QFocusEvent *event)
Reimplements: QWidget::focusOutEvent(QFocusEvent *event).
QSurfaceFormat QQuickWidget::format() const
Gibt das aktuelle Oberflächenformat zurück.
Wenn das Widget noch nicht angezeigt wurde, wird das angeforderte Format zurückgegeben.
Siehe auch setFormat().
QImage QQuickWidget::grabFramebuffer() const
Rendert ein Bild und liest es wieder in ein Bild ein.
Hinweis: Dies ist ein potenziell teurer Vorgang.
[override virtual protected] void QQuickWidget::hideEvent(QHideEvent *)
Reimplements: QWidget::hideEvent(QHideEvent *event).
QSize QQuickWidget::initialSize() const
Gibt die Anfangsgröße des Stammobjekts zurück.
Wenn resizeMode SizeRootObjectToView ist, wird die Größe des Stammobjekts an die Größe der Ansicht angepasst. Diese Funktion gibt die Größe des Stammobjekts zurück, bevor es in der Größe geändert wurde.
[override virtual protected] void QQuickWidget::keyPressEvent(QKeyEvent *e)
Reimplements: QWidget::keyPressEvent(QKeyEvent *event).
[override virtual protected] void QQuickWidget::keyReleaseEvent(QKeyEvent *e)
Reimplements: QWidget::keyReleaseEvent(QKeyEvent *event).
[override virtual protected] void QQuickWidget::mouseDoubleClickEvent(QMouseEvent *e)
Reimplements: QWidget::mouseDoubleClickEvent(QMouseEvent *event).
[override virtual protected] void QQuickWidget::mouseMoveEvent(QMouseEvent *e)
Reimplements: QWidget::mouseMoveEvent(QMouseEvent *event).
[override virtual protected] void QQuickWidget::mousePressEvent(QMouseEvent *e)
Reimplements: QWidget::mousePressEvent(QMouseEvent *event).
[override virtual protected] void QQuickWidget::mouseReleaseEvent(QMouseEvent *e)
Reimplements: QWidget::mouseReleaseEvent(QMouseEvent *event).
[override virtual protected] void QQuickWidget::paintEvent(QPaintEvent *event)
Reimplements: QWidget::paintEvent(QPaintEvent *event).
QQuickWindow *QQuickWidget::quickWindow() const
Gibt den Offscreen QQuickWindow zurück, der von diesem Widget verwendet wird, um das Qt Quick Rendering zu steuern. Dies ist nützlich, wenn Sie QQuickWindow APIs verwenden wollen, die derzeit nicht von QQuickWidget zur Verfügung gestellt werden, z.B. die Verbindung mit dem QQuickWindow::beforeRendering() Signal, um native OpenGL Inhalte unter Qt Quick's eigenem Rendering zu zeichnen.
Warnung: Verwenden Sie den Rückgabewert dieser Funktion mit Vorsicht. Versuchen Sie insbesondere nicht, die QQuickWindow anzuzeigen, und seien Sie sehr vorsichtig, wenn Sie andere QWindow-only APIs verwenden.
Warnung: Das Offscreen-Fenster kann während der Lebensdauer des QQuickWidget gelöscht (und neu erstellt) werden, insbesondere wenn das Widget in ein anderes QQuickWindow verschoben wird. Wenn Sie wissen müssen, wann das Fenster ersetzt wurde, verbinden Sie sich mit seinem destroyed()-Signal.
QQmlContext *QQuickWidget::rootContext() const
Diese Funktion gibt die Wurzel der Kontexthierarchie zurück. Jede QML-Komponente wird in einem QQmlContext instanziiert. QQmlContext ist für die Übergabe von Daten an QML-Komponenten unerlässlich. In QML sind die Kontexte hierarchisch angeordnet, und diese Hierarchie wird von QQmlEngine verwaltet.
QQuickItem *QQuickWidget::rootObject() const
Gibt die Wurzel der Ansicht item zurück. Kann null sein, wenn setSource() nicht aufgerufen wurde, wenn es mit fehlerhaftem QtQuick Code aufgerufen wurde oder während der QtQuick Inhalt erstellt wird.
[signal] void QQuickWidget::sceneGraphError(QQuickWindow::SceneGraphError error, const QString &message)
Dieses Signal wird ausgegeben, wenn während der Initialisierung des Szenengraphen ein error aufgetreten ist.
Anwendungen sollten sich mit diesem Signal verbinden, wenn sie Fehler, wie z.B. Fehler bei der OpenGL-Kontexterzeugung, auf eine eigene Art und Weise behandeln wollen. Wenn kein Slot mit dem Signal verbunden ist, wird das Verhalten anders sein: Quick druckt die message oder zeigt eine Messagebox an und beendet die Anwendung.
Dieses Signal wird vom GUI-Thread ausgesendet.
Siehe auch QQuickWindow::sceneGraphError().
void QQuickWidget::setClearColor(const QColor &color)
Legt die klare color fest. Standardmäßig ist dies eine undurchsichtige Farbe.
Um eine halbtransparente QQuickWidget zu erhalten, rufen Sie diese Funktion mit color auf Qt::transparent gesetzt, setzen Sie das Qt::WA_TranslucentBackground Widget-Attribut auf der obersten Ebene des Fensters und fordern Sie einen Alphakanal über setFormat() an.
Siehe auch QQuickWindow::setColor().
void QQuickWidget::setFormat(const QSurfaceFormat &format)
Setzt die Oberfläche format für den Kontext und die Offscreen-Oberfläche, die von diesem Widget verwendet wird.
Rufen Sie diese Funktion auf, wenn Sie einen Kontext für eine bestimmte OpenGL-Version oder ein bestimmtes Profil anfordern müssen. Die Größen für Tiefen-, Schablonen- und Alphapuffer werden automatisch festgelegt und müssen nicht explizit angefordert werden.
Siehe auch QWindow::setFormat(), QWindow::format(), und format().
[slot] void QQuickWidget::setSource(const QUrl &url)
Setzt die Quelle auf url, lädt die QML-Komponente und instanziiert sie.
Achten Sie darauf, dass die angegebene URL vollständig und korrekt ist. Verwenden Sie insbesondere QUrl::fromLocalFile(), wenn Sie eine Datei aus dem lokalen Dateisystem laden.
Ein mehrfacher Aufruf dieser Methode mit der gleichen URL führt dazu, dass die QML-Komponente neu instanziiert wird.
Hinweis: Setter-Funktion für die Eigenschaft source.
Siehe auch source().
[override virtual protected] void QQuickWidget::showEvent(QShowEvent *)
Reimplements: QWidget::showEvent(QShowEvent *event).
QUrl QQuickWidget::source() const
Gibt die Quell-URL zurück, falls gesetzt.
Hinweis: Getter-Funktion für die Eigenschaft source.
Siehe auch setSource().
[signal] void QQuickWidget::statusChanged(QQuickWidget::Status status)
Dieses Signal wird ausgesendet, wenn sich die aktuelle status der Komponente ändert.
Hinweis: Benachrichtigungssignal für die Eigenschaft status.
[override virtual protected] void QQuickWidget::wheelEvent(QWheelEvent *e)
Reimplements: QWidget::wheelEvent(QWheelEvent *event).
© 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.
