Q3DSurfaceWidgetItem Class
La classe `Q3DSurfaceWidgetItem` fournit des méthodes permettant de générer des graphiques de surface en 3D. En savoir plus...
| En-tête : | #include <Q3DSurfaceWidgetItem> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS GraphsWidgets) target_link_libraries(mytarget PRIVATE Qt6::GraphsWidgets) |
| qmake : | QT += graphswidgets |
| Hérite de : | Q3DGraphsWidgetItem |
- Liste de tous les membres, y compris les membres hérités
- Q3DSurfaceWidgetItem fait partie des classes C++ pour widgets d'Qt Graphs .
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 |
Emplacements publics
| 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 générer des graphiques de surface en 3D et de les visualiser en faisant pivoter librement la scène. Les propriétés visuelles de la surface, telles que le mode d'affichage et l'ombrage, peuvent être contrôlées via QSurface3DSeries.
Le Q3DSurfaceWidgetItem prend en charge la sélection en affichant une boule mise 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 sélectionné via QSurface3DSeries. Le pointeur de sélection est accompagné d’une étiquette qui, par défaut, affiche la valeur du point de données et les coordonnées de ce point.
La plage de valeurs et le format de l'étiquette affichés 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 par défaut temporaires 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 une orientation, l’axe par défaut correspondant à cette orientation est détruit.
Comment construire un graphique Q3DSurfaceWidgetItem minimal
Commencez par créer un objet Q3DSurfaceWidgetItem. Étant donné que, dans cet exemple, nous exécutons le graphe en tant que fenêtre de niveau supérieur, nous devons désactiver 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 désormais prêt à recevoir les données à afficher. Créez des éléments de données pour recevoir les valeurs :
Remarque : dans la nouvelle relation de série proxy, les données sont stockées dans des séries. 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.
QSurfaceDataArray data;
QSurfaceDataRow dataRow1;
QSurfaceDataRow dataRow2;Commencez par alimenter les éléments de ligne en données, 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 pour créer et afficher 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 le résultat obtenu avec ces quelques lignes de code :

La scène peut être pivotée, agrandie, et il est possible de sélectionner un point de la surface pour afficher sa position, mais cet exemple de code minimal ne comprend aucune autre interaction. Vous pouvez en savoir plus 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é indique l'axe des x actif.
Définit ` axis ` comme axe x actif. Appelle implicitement la méthode ` addAxis()` pour transférer la propriété de l'axe à ce graphique.
Si axis est nul, un axe temporaire par défaut, sans étiquettes et dont la plage s'ajuste automatiquement, est créé.
Cet axe temporaire est détruit si un autre axe est explicitement défini avec la même orientation.
Fonctions d’accès :
| QValue3DAxis * | axisX() const |
| void | setAxisX(QValue3DAxis *axis) |
Signal de notification :
| void | axisXChanged(QValue3DAxis *axis) |
Voir également addAxis() et releaseAxis().
axisY : QValue3DAxis*
Cette propriété désigne l'axe des y actif.
Définit axis comme axe y actif. Appelle implicitement la méthode addAxis() pour transférer la propriété de l'axe à ce graphique.
Si axis est nul, un axe temporaire par défaut, sans étiquettes et dont la plage s'ajuste automatiquement, est créé.
Cet axe temporaire est détruit si un autre axe est explicitement défini avec la même orientation.
Fonctions d'accès :
| QValue3DAxis * | axisY() const |
| void | setAxisY(QValue3DAxis *axis) |
Signal de notification :
| void | axisYChanged(QValue3DAxis *axis) |
Voir également addAxis() et releaseAxis().
axisZ : QValue3DAxis*
Cette propriété définit l'axe Z actif.
Définit axis comme axe Z actif. Appelle implicitement la méthode addAxis() pour transférer la propriété de l'axe à ce graphique.
Si axis est nul, un axe temporaire par défaut, sans étiquettes et dont la plage s'ajuste automatiquement, est créé.
Cet axe temporaire est détruit si un autre axe est explicitement défini avec la même orientation.
Fonctions d'accès :
| QValue3DAxis * | axisZ() const |
| void | setAxisZ(QValue3DAxis *axis) |
Signal de notification :
| void | axisZChanged(QValue3DAxis *axis) |
Voir également addAxis() et releaseAxis().
flipHorizontalGrid : bool
Cette propriété détermine si la grille de l'axe horizontal s'affiche au-dessus du graphique plutôt qu'en dessous.
Dans certains cas d'utilisation, la grille de l'axe horizontal est en grande partie recouverte par la surface ; il peut donc être plus utile d'afficher la grille de l'axe horizontal au-dessus du graphique plutôt qu'en dessous. Un cas d'utilisation typique est l'affichage de spectrogrammes 2D utilisant une projection orthographique avec un point de vue de haut en bas.
Si ` false`, la grille et les étiquettes de l’axe horizontal sont dessinées sur l’arrière-plan horizontal du graphique. Si ` true`, la grille et les étiquettes de l’axe horizontal sont dessinées du côté opposé au fond horizontal du graphique. 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 la valeur null.
Si selectionMode est défini sur « MultiSeries », cette propriété contient la série à laquelle appartient le point sélectionné.
Fonctions d'accès :
| QSurface3DSeries * | selectedSeries() const |
Signal de notification :
| void | selectedSeriesChanged(QSurface3DSeries *series) |
Documentation des fonctions membres
[explicit] Q3DSurfaceWidgetItem::Q3DSurfaceWidgetItem(QObject *parent = nullptr)
Crée un nouveau graphique de surface en 3D avec l'option « parent ».
[override virtual noexcept] Q3DSurfaceWidgetItem::~Q3DSurfaceWidgetItem()
Supprime le graphique de surface 3D.
void Q3DSurfaceWidgetItem::addAxis(QValue3DAxis *axis)
Ajoute axis au graphe. Les axes ajoutés via addAxis ne sont pas encore utilisés ; addAxis sert simplement à attribuer la propriété de l'axis au graphe. L'axis ne doit pas être null ni avoir été ajouté à un autre graphe.
Voir également releaseAxis(), setAxisX(), setAxisY() et setAxisZ().
void Q3DSurfaceWidgetItem::addSeries(QSurface3DSeries *series)
Ajoute la série « series » au graphique. Un graphique peut contenir plusieurs séries, mais ne dispose que d’un seul jeu d’axes. Si la série nouvellement ajoutée comporte un élément sélectionné, celui-ci sera mis en surbrillance et toute sélection existante sera désélectionnée. Une seule série ajoutée peut faire l’objet d’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)
Restitue la propriété de l'axis à l'appelant, s'il est ajouté à ce graphe. Si l'axis restitué est en cours d'utilisation, un nouvel axe par défaut sera créé et activé.
Si l’axe par défaut est libéré puis rajouté ultérieurement, il se comporte comme n’importe quel autre axe.
Voir également addAxis(), setAxisX(), setAxisY() et setAxisZ().
void Q3DSurfaceWidgetItem::removeSeries(QSurface3DSeries *series)
Supprime l'series e du graphe.
Voir aussi Q3DGraphsWidgetItem::hasSeries().
[since 6.10] void Q3DSurfaceWidgetItem::renderSliceToImage(int index, int requestedIndex, QtGraphs3D::SliceCaptureType sliceType)
Exporte la vue de coupe demandée vers une image. Le résultat de la coupe est la série de index. Pour exporter toutes les séries, définissez index sur -1. La coupe exportée correspond à une ligne ou une colonne, définie par sliceType, à une requestedIndex donnée.
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 aussi Q3DGraphsWidgetItem::hasSeries().
[signal, since 6.10] void Q3DSurfaceWidgetItem::sliceImageChanged(const QImage &image)
Émis lorsque ` renderSliceToImage ` a préparé ` 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.