Sur cette page

Q3DSurfaceWidgetItem Class

La classe Q3DSurfaceWidgetItem fournit des méthodes pour le rendu des tracés de surface 3D. Plus d'informations...

En-tête : #include <Q3DSurfaceWidgetItem>
CMake : find_package(Qt6 REQUIRED COMPONENTS GraphsWidgets)
target_link_libraries(mytarget PRIVATE Qt6::GraphsWidgets)
qmake : QT += graphswidgets
Héritages : Q3DGraphsWidgetItem

Propriétés

Fonctions publiques

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
void setAxisX(QValue3DAxis *axis)
void setAxisY(QValue3DAxis *axis)
void setAxisZ(QValue3DAxis *axis)
void setFlipHorizontalGrid(bool flip)

Signaux

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)

Description détaillée

Cette classe permet aux développeurs de rendre des tracés de surface en 3D et de les visualiser en faisant pivoter la scène librement. Les propriétés visuelles de la surface, telles que le mode de dessin et l'ombrage, peuvent être contrôlées via QSurface3DSeries.

Le Q3DSurfaceWidgetItem prend en charge la sélection en affichant une boule en surbrillance sur le point de données sur lequel l'utilisateur a cliqué avec le bouton gauche de la souris (lorsque le gestionnaire d'entrée par défaut est utilisé) ou qu'il a sélectionné via QSurface3DSeries. Le pointeur de sélection est accompagné d'une étiquette qui, par défaut, indique la valeur du point de données et ses coordonnées.

La plage de valeurs et le format de l'étiquette affichée sur l'axe peuvent être contrôlés via QValue3DAxis.

Pour faire pivoter le graphique, maintenez le bouton droit de la souris enfoncé et déplacez la souris. Le zoom s'effectue à l'aide de la molette de la souris. Ces deux actions supposent que le gestionnaire d'entrée par défaut est utilisé.

Si aucun axe n'est défini explicitement pour Q3DSurfaceWidgetItem, des axes temporaires par défaut sans étiquette sont créés. Ces axes par défaut peuvent être modifiés via les accesseurs d'axe, mais dès qu'un axe est défini explicitement pour l'orientation, l'axe par défaut pour cette orientation est détruit.

Comment construire un graphe Q3DSurfaceWidgetItem minimal ?

Commencez par construire Q3DSurfaceWidgetItem. Puisque nous exécutons le graphique en tant que fenêtre de premier niveau dans cet exemple, nous devons effacer le drapeau Qt::FramelessWindowHint, qui est activé par défaut :

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

Q3DSurfaceWidgetItem est maintenant prêt à recevoir des données à rendre. Créez des éléments de données pour recevoir des valeurs :

Remarque : dans la nouvelle relation proxy-série, les données sont conservées en série. Par conséquent, pour que le proxy puisse ajouter, supprimer ou modifier les données, il est indispensable de créer d'abord une série.

Introduisez d'abord les données dans les éléments de ligne, puis ajoutez leurs pointeurs à l'élément de données :

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;

Créez une nouvelle série et attribuez-lui des données :

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

Enfin, vous devrez la rendre visible :

surface.widget()->show();

Le code complet nécessaire à la création et à l'affichage de ce graphique est le suivant :

#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();
}

Et voici ce que ces quelques lignes de code produisent :

La scène peut être tournée, zoomée et un point de la surface peut être sélectionné pour voir sa position, mais aucune autre interaction n'est incluse dans cet exemple de code minimal. Vous pouvez en apprendre davantage en vous familiarisant avec les exemples fournis, comme la galerie de graphiques de surface.

Voir également Q3DBarsWidgetItem, Q3DScatterWidgetItem, et Qt Graphs Classes C++ pour la 3D.

Documentation sur les propriétés

axisX : QValue3DAxis*

Cette propriété définit l'axe des x actif.

Définit axis comme l'axe des x actif. Appelle implicitement addAxis() pour transférer la propriété de l'axe à ce graphique.

Si axis est nul, un axe temporaire par défaut sans étiquette et avec une plage qui s'ajuste automatiquement est créé.

Cet axe temporaire est détruit si un autre axe est défini explicitement avec la même orientation.

Fonctions d'accès :

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

Signal Notifier :

void axisXChanged(QValue3DAxis *axis)

Voir aussi addAxis() et releaseAxis().

axisY : QValue3DAxis*

Cette propriété définit l'axe des ordonnées actif.

Définit axis comme axe des ordonnées actif. Appelle implicitement addAxis() pour transférer la propriété de l'axe à ce graphique.

Si axis est nul, un axe temporaire par défaut sans étiquette et avec une plage qui s'ajuste automatiquement est créé.

Cet axe temporaire est détruit si un autre axe est défini explicitement avec la même orientation.

Fonctions d'accès :

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

Signal Notifier :

void axisYChanged(QValue3DAxis *axis)

Voir aussi addAxis() et releaseAxis().

axisZ : QValue3DAxis*

Cette propriété définit l'axe z actif.

Définit axis comme axe z actif. Appelle implicitement addAxis() pour transférer la propriété de l'axe à ce graphique.

Si axis est nul, un axe temporaire par défaut sans étiquette et avec une plage qui s'ajuste automatiquement est créé.

Cet axe temporaire est détruit si un autre axe est défini explicitement avec la même orientation.

Fonctions d'accès :

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

Signal Notifier :

void axisZChanged(QValue3DAxis *axis)

Voir aussi addAxis() et releaseAxis().

flipHorizontalGrid : bool

Cette propriété indique si la grille de l'axe horizontal est affichée en haut du graphique plutôt qu'en bas.

Dans certains cas d'utilisation, la grille de l'axe horizontal est principalement couverte par la surface, il peut donc être plus utile d'afficher la grille de l'axe horizontal en haut du graphique plutôt qu'en bas. Un cas d'utilisation typique est l'affichage de spectrogrammes en 2D à l'aide de la projection orthographique avec un point de vue du haut vers le bas.

Si false, la grille de l'axe horizontal et les étiquettes sont dessinées sur le fond horizontal du graphique. Si true, la grille de l'axe horizontal et les étiquettes sont dessinées sur le côté opposé du graphique par rapport à l'arrière-plan horizontal. La valeur par défaut est false.

Fonctions d'accès :

bool flipHorizontalGrid() const
void setFlipHorizontalGrid(bool flip)

Signal de notification :

void flipHorizontalGridChanged(bool flip)

[read-only] selectedSeries : QSurface3DSeries*

Cette propriété contient la série sélectionnée ou null.

Si le mode de sélection a été défini sur MultiSeries, cette propriété contient la série qui possède le point sélectionné.

Fonctions d'accès :

QSurface3DSeries *selectedSeries() const

Signal Notifier :

void selectedSeriesChanged(QSurface3DSeries *series)

Member Function Documentation

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

Construit un nouveau graphe de surface 3D avec l'option parent.

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

Détruit le graphe de surface 3D.

void Q3DSurfaceWidgetItem::addAxis(QValue3DAxis *axis)

Ajoute axis au graphique. Les axes ajoutés via addAxis ne sont pas encore utilisés, addAxis est simplement utilisé pour donner la propriété de axis au graphique. L'adresse axis ne doit pas être nulle ou ajoutée à un autre graphique.

Voir aussi releaseAxis(), setAxisX(), setAxisY() et setAxisZ().

void Q3DSurfaceWidgetItem::addSeries(QSurface3DSeries *series)

Ajoute le site series au graphique. Un graphique peut contenir plusieurs séries, mais n'a qu'un seul ensemble d'axes. Si la série nouvellement ajoutée a spécifié un élément sélectionné, elle sera mise en évidence et toute sélection existante sera effacée. Une seule série ajoutée peut avoir une sélection active.

Voir également Q3DGraphsWidgetItem::hasSeries().

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

Renvoie la liste de tous les axes ajoutés.

Voir aussi addAxis().

void Q3DSurfaceWidgetItem::releaseAxis(QValue3DAxis *axis)

Libère la propriété du site axis à l'appelant, s'il est ajouté à ce graphique. Si l'adresse axis libérée est utilisée, un nouvel axe par défaut sera créé et activé.

Si l'axe par défaut est libéré et ajouté plus tard, il se comporte comme n'importe quel autre axe.

Voir également addAxis(), setAxisX(), setAxisY() et setAxisZ().

void Q3DSurfaceWidgetItem::removeSeries(QSurface3DSeries *series)

Supprime le site series du graphique.

Voir aussi Q3DGraphsWidgetItem::hasSeries().

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

Exporte la vue en tranches demandée vers une image. Le résultat de la coupe est la série de index. Pour exporter toutes les séries, fixez index à -1. La tranche exportée est une ligne ou une colonne, définie par sliceType, à un endroit donné requestedIndex.

Le signal sliceImageChanged est émis lorsque l'image est prête et peut être capturé comme suit :

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

item->renderSliceToImage(sliceType, index);

L'image est rendue avec les paramètres d'anticrénelage actuels.

Cette fonction a été introduite dans Qt 6.10.

Voir également QQuickItem::grabToImage() et sliceImageChanged().

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

Renvoie la liste des séries ajoutées à ce graphique.

Voir également Q3DGraphsWidgetItem::hasSeries().

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

Émise lorsque renderSliceToImage a préparé le site image.

Cette fonction a été introduite dans Qt 6.10.

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