Auf dieser Seite

Q3DSurfaceWidgetItem Class

Die Klasse „Q3DSurfaceWidgetItem“ bietet Methoden zum Rendern von 3D-Oberflächendiagrammen. Mehr...

Header: #include <Q3DSurfaceWidgetItem>
CMake: find_package(Qt6 REQUIRED COMPONENTS GraphsWidgets)
target_link_libraries(mytarget PRIVATE Qt6::GraphsWidgets)
qmake: QT += graphswidgets
Erbt: Q3DGraphsWidgetItem

Eigenschaften

Öffentliche Funktionen

Q3DSurfaceWidgetItem(QObject *parent = nullptr)
virtual ~Q3DSurfaceWidgetItem() override
void addAxis(QValue3DAxis *axis)
void addSeries(QSurface3DSeries *series)
QList<QValue3DAxis *> axes() const
QValue3DAxis *axisX() const
QValue3DAxis *axisY() const
QValue3DAxis *axisZ() const
bool flipHorizontalGrid() const
void releaseAxis(QValue3DAxis *axis)
void removeSeries(QSurface3DSeries *series)
(since 6.10) void renderSliceToImage(int index, int requestedIndex, QtGraphs3D::SliceCaptureType sliceType)
QSurface3DSeries *selectedSeries() const
QList<QSurface3DSeries *> seriesList() const

Öffentliche Slots

void setAxisX(QValue3DAxis *axis)
void setAxisY(QValue3DAxis *axis)
void setAxisZ(QValue3DAxis *axis)
void setFlipHorizontalGrid(bool flip)

Signale

void axisXChanged(QValue3DAxis *axis)
void axisYChanged(QValue3DAxis *axis)
void axisZChanged(QValue3DAxis *axis)
void flipHorizontalGridChanged(bool flip)
void selectedSeriesChanged(QSurface3DSeries *series)
(since 6.10) void sliceImageChanged(const QImage &image)

Ausführliche Beschreibung

Diese Klasse ermöglicht es Entwicklern, 3D-Oberflächendiagramme zu rendern und diese durch freies Drehen der Szene zu betrachten. Die visuellen Eigenschaften der Oberfläche, wie z. B. der Zeichnungsmodus und die Schattierung, können über ` QSurface3DSeries` gesteuert werden.

Das `Q3DSurfaceWidgetItem` unterstützt die Auswahl, indem es an dem Datenpunkt, auf den der Benutzer mit der linken Maustaste geklickt hat (sofern der Standard-Eingabehandler verwendet wird) oder der über ` QSurface3DSeries` ausgewählt wurde, eine hervorgehobene Kugel anzeigt. Der Auswahlzeiger wird von einer Beschriftung begleitet, die im Standardfall den Wert des Datenpunkts und die Koordinaten des Punkts anzeigt.

Der Wertebereich und das auf der Achse angezeigte Beschriftungsformat können über ` QValue3DAxis` gesteuert werden.

Um das Diagramm zu drehen, halten Sie die rechte Maustaste gedrückt und bewegen Sie die Maus. Das Zoomen erfolgt über das Mausrad. Beide Aktionen setzen voraus, dass der Standard-Eingabehandler verwendet wird.

Wenn für `Q3DSurfaceWidgetItem` keine Achsen explizit festgelegt sind, werden temporäre Standardachsen ohne Beschriftungen erstellt. Diese Standardachsen können über Achsen-Zugriffsmethoden geändert werden, doch sobald eine Achse für die jeweilige Ausrichtung explizit festgelegt wird, wird die Standardachse für diese Ausrichtung gelöscht.

So erstellen Sie ein minimales Q3DSurfaceWidgetItem-Diagramm

Erstellen Sie zunächst ein `Q3DSurfaceWidgetItem`. Da wir den Graphen in diesem Beispiel als Fenster auf oberster Ebene ausführen, müssen wir das Flag „ Qt::FramelessWindowHint “ zurücksetzen, das standardmäßig gesetzt ist:

QQuickWidget quickWidget;
Q3DSurfaceWidgetItem surface;
surface.setWidget(&quickWidget);
surface.widget()->setMinimumSize(QSize(256, 256));

Nun ist `Q3DSurfaceWidgetItem` bereit, die zu rendernden Daten zu empfangen. Erstellen Sie Datenelemente, um Werte zu empfangen:

Hinweis: In der neuen „Proxy-Series“-Beziehung werden Daten in Serien gespeichert. Damit der Proxy Daten hinzufügen, löschen oder bearbeiten kann, muss daher zunächst eine Serie erstellt werden.

Führen Sie zunächst die Daten in die Zeilenelemente ein und fügen Sie anschließend deren Zeiger dem Datenelement hinzu:

dataRow1 << QSurfaceDataItem(0.0f, 0.1f, 0.5f) << QSurfaceDataItem(1.0f, 0.5f, 0.5f);
dataRow2 << QSurfaceDataItem(0.0f, 1.8f, 1.0f) << QSurfaceDataItem(1.0f, 1.2f, 1.0f);
data << dataRow1 << dataRow2;

Erstellen Sie eine neue Serie und weisen Sie ihr Daten zu:

QSurface3DSeries series;
series.dataProxy()->resetArray(data);
surface.addSeries(&series);

Abschließend müssen Sie die Serie als sichtbar festlegen:

surface.widget()->show();

Der vollständige Code zum Erstellen und Anzeigen dieses Diagramms lautet:

#include <QtGraphs>
#include <QtGraphsWidgets/q3dsurfacewidgetitem.h>
#include <QtWidgets/qapplication.h>

int main(int argc, char **argv)
{
    QApplication app(argc, argv);

    QQuickWidget quickWidget;
    Q3DSurfaceWidgetItem surface;
    surface.setWidget(&quickWidget);
    surface.widget()->setMinimumSize(QSize(256, 256));
    QSurfaceDataArray data;
    QSurfaceDataRow dataRow1;
    QSurfaceDataRow dataRow2;

    dataRow1 << QSurfaceDataItem(0.0f, 0.1f, 0.5f) << QSurfaceDataItem(1.0f, 0.5f, 0.5f);
    dataRow2 << QSurfaceDataItem(0.0f, 1.8f, 1.0f) << QSurfaceDataItem(1.0f, 1.2f, 1.0f);
    data << dataRow1 << dataRow2;

    QSurface3DSeries series;
    series.dataProxy()->resetArray(data);
    surface.addSeries(&series);
    surface.widget()->show();

    return app.exec();
}

Und das ist das Ergebnis dieser wenigen Codezeilen:

3D-Oberflächendiagramm mit geneigter grüner Ebene

Die Szene lässt sich drehen und vergrößern, und es kann ein Oberflächenpunkt ausgewählt werden, um dessen Position anzuzeigen; weitere Interaktionen sind in diesem minimalen Code-Beispiel jedoch nicht enthalten. Weitere Informationen erhalten Sie, wenn Sie sich mit den bereitgestellten Beispielen vertraut machen, beispielsweise in der Surface Graph Gallery.

Siehe auch „ Q3DBarsWidgetItem“ , „ Q3DScatterWidgetItem “ und „Qt Graphs “ – C++-Klassen für 3D.

Dokumentation zu den Eigenschaften

axisX : QValue3DAxis*

Diese Eigenschaft gibt die aktive x-Achse an.

Legt „ axis “ als aktive x-Achse fest. Ruft implizit „ addAxis()“ auf, um die Eigentumsrechte an der Achse auf dieses Diagramm zu übertragen.

Ist axis null, wird eine temporäre Standardachse ohne Beschriftungen und mit einem sich automatisch anpassenden Bereich erstellt.

Diese temporäre Achse wird gelöscht, wenn eine andere Achse explizit auf dieselbe Ausrichtung gesetzt wird.

Zugriffsfunktionen:

QValue3DAxis *axisX() const
void setAxisX(QValue3DAxis *axis)

Benachrichtigungssignal:

void axisXChanged(QValue3DAxis *axis)

Siehe auch ` addAxis()` und ` releaseAxis()`.

axisY : QValue3DAxis*

Diese Eigenschaft gibt die aktive y-Achse an.

Legt „ axis “ als aktive y-Achse fest. Ruft implizit „ addAxis()“ auf, um die Eigentumsrechte an der Achse auf dieses Diagramm zu übertragen.

Ist axis null, wird eine temporäre Standardachse ohne Beschriftungen und mit einem sich automatisch anpassenden Bereich erstellt.

Diese temporäre Achse wird gelöscht, wenn eine andere Achse explizit auf dieselbe Ausrichtung gesetzt wird.

Zugriffsfunktionen:

QValue3DAxis *axisY() const
void setAxisY(QValue3DAxis *axis)

Notifier-Signal:

void axisYChanged(QValue3DAxis *axis)

Siehe auch ` addAxis()` und ` releaseAxis()`.

axisZ : QValue3DAxis*

Diese Eigenschaft gibt die aktive Z-Achse an.

Legt „ axis “ als aktive Z-Achse fest. Ruft implizit „ addAxis()“ auf, um die Eigentumsrechte an der Achse auf dieses Diagramm zu übertragen.

Ist axis null, wird eine temporäre Standardachse ohne Beschriftungen und mit einem sich automatisch anpassenden Bereich erstellt.

Diese temporäre Achse wird gelöscht, wenn eine andere Achse explizit auf dieselbe Ausrichtung gesetzt wird.

Zugriffsfunktionen:

QValue3DAxis *axisZ() const
void setAxisZ(QValue3DAxis *axis)

Notifier-Signal:

void axisZChanged(QValue3DAxis *axis)

Siehe auch ` addAxis()` und ` releaseAxis()`.

flipHorizontalGrid : bool

Diese Eigenschaft gilt unabhängig davon, ob das Raster der horizontalen Achse oben oder unten im Diagramm angezeigt wird.

In manchen Anwendungsfällen wird das horizontale Achsenraster größtenteils von der Oberfläche überdeckt, sodass es sinnvoller sein kann, das horizontale Achsenraster oberhalb des Diagramms statt darunter anzuzeigen. Ein typischer Anwendungsfall hierfür ist die Darstellung von 2D-Spektrogrammen unter Verwendung einer orthogonalen Projektion mit einer Blickrichtung von oben nach unten.

Wenn „ false “ gesetzt ist, werden das horizontale Achsenraster und die Beschriftungen auf dem horizontalen Hintergrund des Diagramms gezeichnet. Wenn „ true “ gesetzt ist, werden das horizontale Achsenraster und die Beschriftungen auf der dem horizontalen Hintergrund gegenüberliegenden Seite des Diagramms gezeichnet. Die Standardeinstellung ist „ false “.

Zugriffsfunktionen:

bool flipHorizontalGrid() const
void setFlipHorizontalGrid(bool flip)

Benachrichtigungssignal:

void flipHorizontalGridChanged(bool flip)

[read-only] selectedSeries : QSurface3DSeries*

Diese Eigenschaft enthält die ausgewählte Reihe oder den Wert „null“.

Wenn für „selectionMode“ der Wert „ MultiSeries “ festgelegt ist, enthält diese Eigenschaft die Reihe, zu der der ausgewählte Punkt gehört.

Zugriffsfunktionen:

QSurface3DSeries *selectedSeries() const

Benachrichtigungssignal:

void selectedSeriesChanged(QSurface3DSeries *series)

Dokumentation der Mitgliedsfunktionen

[explicit] Q3DSurfaceWidgetItem::Q3DSurfaceWidgetItem(QObject *parent = nullptr)

Erstellt ein neues 3D-Oberflächendiagramm mit der optionalen Funktion „ parent “.

[override virtual noexcept] Q3DSurfaceWidgetItem::~Q3DSurfaceWidgetItem()

Löscht die 3D-Oberflächengrafik.

void Q3DSurfaceWidgetItem::addAxis(QValue3DAxis *axis)

Fügt „ axis “ zum Diagramm hinzu. Die über „addAxis“ hinzugefügten Achsen werden noch nicht verwendet; „addAxis“ dient lediglich dazu, die Zuständigkeit für den „ axis “ dem Diagramm zuzuweisen. Der „ axis “ darf nicht null sein oder bereits einem anderen Diagramm hinzugefügt worden sein.

Siehe auch „ releaseAxis()“, „ setAxisX()“, „ setAxisY()“ und „ setAxisZ()“.

void Q3DSurfaceWidgetItem::addSeries(QSurface3DSeries *series)

Fügt die „ series “ zum Diagramm hinzu. Ein Diagramm kann mehrere Reihen enthalten, verfügt jedoch nur über ein Achsenpaar. Wenn für die neu hinzugefügte Reihe ein Element ausgewählt wurde, wird dieses hervorgehoben und eine eventuell vorhandene Auswahl wird aufgehoben. Nur eine der hinzugefügten Reihen kann aktiv ausgewählt sein.

Siehe auch „ Q3DGraphsWidgetItem::hasSeries()“.

QList<QValue3DAxis *> Q3DSurfaceWidgetItem::axes() const

Gibt die Liste aller hinzugefügten Achsen zurück.

Siehe auch ` addAxis()`.

void Q3DSurfaceWidgetItem::releaseAxis(QValue3DAxis *axis)

Gibt die Eigentumsrechte an der „ axis “ an den Aufrufer zurück, sofern diese zu diesem Graphen hinzugefügt wurde. Wenn die freigegebene „ axis “ gerade verwendet wird, wird eine neue Standardachse erstellt und als aktiv gesetzt.

Wird die Standardachse freigegeben und später wieder hinzugefügt, verhält sie sich wie jede andere Achse.

Siehe auch „ addAxis()“, „ setAxisX()“, „ setAxisY()“ und „ setAxisZ()“.

void Q3DSurfaceWidgetItem::removeSeries(QSurface3DSeries *series)

Entfernt den „ series “ aus dem Diagramm.

Siehe auch „ Q3DGraphsWidgetItem::hasSeries()“.

[since 6.10] void Q3DSurfaceWidgetItem::renderSliceToImage(int index, int requestedIndex, QtGraphs3D::SliceCaptureType sliceType)

Exportiert die angeforderte Schnittansicht in ein Bild. Das Schnitt-Ergebnis ist die Reihe „ index “. Um alle Reihen zu exportieren, setzen Sie „ index “ auf -1. Der exportierte Schnitt ist eine Zeile oder Spalte, die durch „ sliceType “ an einer bestimmten Position „ requestedIndex “ definiert ist.

Das Signal „ sliceImageChanged “ wird ausgegeben, sobald das Bild fertig ist, und kann wie folgt erfasst werden:

connect(item, &Q3DSurfaceWidgetItem::sliceImageChanged, this, [](const QImage &image) {
    // ~~~
});

item->renderSliceToImage(sliceType, index);

Das Bild wird mit den aktuellen Antialiasing-Einstellungen gerendert.

Diese Funktion wurde in Qt 6.10 eingeführt.

Siehe auch „ QQuickItem::grabToImage()“ und „ sliceImageChanged()“.

QList<QSurface3DSeries *> Q3DSurfaceWidgetItem::seriesList() const

Gibt die Liste der zu diesem Diagramm hinzugefügten Reihen zurück.

Siehe auch „ Q3DGraphsWidgetItem::hasSeries()“.

[signal, since 6.10] void Q3DSurfaceWidgetItem::sliceImageChanged(const QImage &image)

Wird ausgelöst, wenn „ renderSliceToImage “ die „ image “ vorbereitet hat.

Diese Funktion wurde in Qt 6.10 eingeführt.

© 2026 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.