Q3DBars Class
La classe Q3DBars propose des méthodes permettant d'afficher des graphiques à barres en 3D. En savoir plus...
| En-tête : | #include <Q3DBars> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS DataVisualization) target_link_libraries(mytarget PRIVATE Qt6::DataVisualization) |
| qmake : | QT += datavisualization |
| Depuis : | QtDataVisualization 1.0 |
| Hérite de : | QAbstract3DGraph |
| Statut : | Obsolète |
Cette classe est obsolète. Nous déconseillons fortement de l'utiliser dans du nouveau code.
Propriétés
|
|
Fonctions publiques
| Q3DBars(const QSurfaceFormat *format = nullptr, QWindow *parent = nullptr) | |
| virtual | ~Q3DBars() |
| void | addAxis(QAbstract3DAxis *axis) |
| void | addSeries(QBar3DSeries *series) |
| QList<QAbstract3DAxis *> | axes() const |
| QSizeF | barSeriesMargin() const |
| QSizeF | barSpacing() const |
| float | barThickness() const |
| QCategory3DAxis * | columnAxis() const |
| float | floorLevel() const |
| void | insertSeries(int index, QBar3DSeries *series) |
| bool | isBarSpacingRelative() const |
| bool | isMultiSeriesUniform() const |
| QBar3DSeries * | primarySeries() const |
| void | releaseAxis(QAbstract3DAxis *axis) |
| void | removeSeries(QBar3DSeries *series) |
| QCategory3DAxis * | rowAxis() const |
| QBar3DSeries * | selectedSeries() const |
| QList<QBar3DSeries *> | seriesList() const |
| void | setBarSeriesMargin(const QSizeF &margin) |
| void | setBarSpacing(const QSizeF &spacing) |
| void | setBarSpacingRelative(bool relative) |
| void | setBarThickness(float thicknessRatio) |
| void | setColumnAxis(QCategory3DAxis *axis) |
| void | setFloorLevel(float level) |
| void | setMultiSeriesUniform(bool uniform) |
| void | setPrimarySeries(QBar3DSeries *series) |
| void | setRowAxis(QCategory3DAxis *axis) |
| void | setValueAxis(QValue3DAxis *axis) |
| QValue3DAxis * | valueAxis() const |
Signaux
| void | barSeriesMarginChanged(const QSizeF &margin) |
| void | barSpacingChanged(const QSizeF &spacing) |
| void | barSpacingRelativeChanged(bool relative) |
| void | barThicknessChanged(float thicknessRatio) |
| void | columnAxisChanged(QCategory3DAxis *axis) |
| void | floorLevelChanged(float level) |
| void | multiSeriesUniformChanged(bool uniform) |
| void | primarySeriesChanged(QBar3DSeries *series) |
| void | rowAxisChanged(QCategory3DAxis *axis) |
| void | selectedSeriesChanged(QBar3DSeries *series) |
| void | valueAxisChanged(QValue3DAxis *axis) |
Description détaillée
Cette classe permet aux développeurs d'afficher des graphiques à barres en 3D et de les visualiser en faisant pivoter librement la scène. La rotation s'effectue en maintenant le bouton droit de la souris enfoncé et en déplaçant la souris. Le zoom s'effectue à l'aide de la molette de la souris. La sélection, si elle est activée, s'effectue à l'aide du bouton gauche de la souris. La scène peut être réinitialisée à la vue par défaut de la caméra en cliquant sur la molette de la souris. Sur les appareils tactiles, la rotation s'effectue par « tap-and-move », la sélection par « tap-and-hold » et le zoom par « pinch ».
Si aucun axe n’est explicitement défini dans Q3DBars, 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 explicitement défini pour une orientation donnée, l’axe par défaut correspondant à cette orientation est supprimé.
Q3DBars prend en charge l’affichage simultané de plusieurs séries. Il n’est pas nécessaire que toutes les séries aient le même nombre de lignes et de colonnes. Les étiquettes de lignes et de colonnes sont reprises de la première série ajoutée, sauf si elles sont explicitement définies pour les axes de lignes et de colonnes.
Comment créer un graphique Q3DBars minimal
Commencez par créer une instance de Q3DBars. Comme nous exécutons le graphique en tant que fenêtre de niveau supérieur dans cet exemple, nous devons désactiver le drapeau « Qt::FramelessWindowHint », qui est activé par défaut :
Q3DBars bars;
bars.setFlags(bars.flags() ^ Qt::FramelessWindowHint);Après avoir créé l’instance de Q3DBars, vous pouvez configurer la fenêtre de données en modifiant la plage sur les axes des lignes et des colonnes. Cette étape n’est pas obligatoire, car la fenêtre de données affiche par défaut l’intégralité des données de la série. Si le volume de données est important, il est généralement préférable de n’en afficher qu’une partie. Pour cet exemple, configurons la fenêtre de données pour qu'elle affiche les cinq premières lignes et colonnes :
bars.rowAxis()->setRange(0, 4);
bars.columnAxis()->setRange(0, 4);Q3DBars est désormais prêt à recevoir les données à afficher. Créez une série comportant une ligne de 5 valeurs :
QBar3DSeries *series = new QBar3DSeries;
QBarDataRow *data = new QBarDataRow;
*data << 1.0f << 3.0f << 7.5f << 5.0f << 2.2f;
series->dataProxy()->addRow(data);
bars.addSeries(series);Remarque : nous avons défini la fenêtre de données sur 5 x 5, mais nous n’ajoutons qu’une seule ligne de données. Ce n’est pas grave, les autres lignes resteront simplement vides.
Enfin, vous devrez le rendre visible :
bars.show();Le code complet nécessaire pour créer et afficher ce graphique est le suivant :
#include <QtDataVisualization>
int main(int argc, char **argv)
{
qputenv("QSG_RHI_BACKEND", "opengl");
QGuiApplication app(argc, argv);
Q3DBars bars;
bars.setFlags(bars.flags() ^ Qt::FramelessWindowHint);
bars.rowAxis()->setRange(0, 4);
bars.columnAxis()->setRange(0, 4);
QBar3DSeries *series = new QBar3DSeries;
QBarDataRow *data = new QBarDataRow;
*data << 1.0f << 3.0f << 7.5f << 5.0f << 2.2f;
series->dataProxy()->addRow(data);
bars.addSeries(series);
bars.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 une barre pour afficher sa valeur, mais cet exemple de code minimal ne comporte aucune autre interaction. Vous pouvez en apprendre davantage en vous familiarisant avec les exemples fournis, comme le graphique à barres.
Voir également Q3DScatter, Q3DSurface et Qt Data Visualization C++ Classes.
Documentation sur les propriétés
[since 6.3] barSeriesMargin : QSizeF
Marge entre les colonnes des séries dans les dimensions X et Z. Les valeurs recommandées se situent dans l'intervalle [0, 1).
La valeur par défaut est (0.0, 0.0). Cette propriété permet d'afficher côte à côte les barres de différentes séries, tout en conservant un espace entre les colonnes.
Cette énumération a été introduite dans Qt 6.3.
Fonctions d'accès :
| QSizeF | barSeriesMargin() const |
| void | setBarSeriesMargin(const QSizeF &margin) |
Signal de notification :
| void | barSeriesMarginChanged(const QSizeF &margin) |
Voir également barSpacing.
barSpacing : QSizeF
Espacement des barres dans les axes X et Z.
Réglé par défaut sur (1.0, 1.0). L'espacement est influencé par la propriété « barSpacingRelative ».
Fonctions d'accès :
| QSizeF | barSpacing() const |
| void | setBarSpacing(const QSizeF &spacing) |
Signal de notification :
| void | barSpacingChanged(const QSizeF &spacing) |
Voir également barSpacingRelative, multiSeriesUniform et barSeriesMargin.
barSpacingRelative : bool
Cette propriété s'applique que l'espacement soit absolu ou relatif à l'épaisseur des barres.
Si elle est définie sur « true », la valeur « 0.0 » signifie que les barres sont placées côte à côte, « 1.0 » signifie qu’un espace égal à l’épaisseur d’une barre est laissé entre les barres, et ainsi de suite. La valeur par défaut est « true ».
Fonctions d'accès :
| bool | isBarSpacingRelative() const |
| void | setBarSpacingRelative(bool relative) |
Signal de notification :
| void | barSpacingRelativeChanged(bool relative) |
barThickness : float
Cette propriété définit le rapport d'épaisseur de la barre entre les dimensions X et Z.
La valeur « 1.0 » signifie que les barres ont une largeur égale à leur profondeur, tandis que la valeur « 0.5 » leur confère une profondeur deux fois supérieure à leur largeur. La valeur par défaut est « 1.0 ».
Fonctions d'accès :
| float | barThickness() const |
| void | setBarThickness(float thicknessRatio) |
Signal de notification :
| void | barThicknessChanged(float thicknessRatio) |
columnAxis : QCategory3DAxis*
Cette propriété contient l'axe associé à la colonne active.
Fonctions d'accès :
| QCategory3DAxis * | columnAxis() const |
| void | setColumnAxis(QCategory3DAxis *axis) |
Signal de notification :
| void | columnAxisChanged(QCategory3DAxis *axis) |
floorLevel : float
Cette propriété définit le niveau minimal du graphique à barres selon les coordonnées de l'axe Y.
Le niveau de base effectif sera limité par les valeurs minimales et maximales de l'axe Y. La valeur par défaut est zéro.
Fonctions d'accès :
| float | floorLevel() const |
| void | setFloorLevel(float level) |
Signal de notification :
| void | floorLevelChanged(float level) |
multiSeriesUniform : bool
Cette propriété s'applique que les barres soient mises à l'échelle selon les proportions définies pour une seule série, même si plusieurs séries sont affichées.
Si l’option « true » est sélectionnée, la fonction « bar spacing » ne s’appliquera correctement qu’à l’axe X. La valeur par défaut est « false ».
Fonctions d'accès :
| bool | isMultiSeriesUniform() const |
| void | setMultiSeriesUniform(bool uniform) |
Signal de notification :
| void | multiSeriesUniformChanged(bool uniform) |
primarySeries : QBar3DSeries*
Cette propriété contient la série principale du graphique.
Fonctions d'accès :
| QBar3DSeries * | primarySeries() const |
| void | setPrimarySeries(QBar3DSeries *series) |
Signal de notification :
| void | primarySeriesChanged(QBar3DSeries *series) |
rowAxis : QCategory3DAxis*
Cette propriété contient l'axe associé à la ligne active.
Fonctions d'accès :
| QCategory3DAxis * | rowAxis() const |
| void | setRowAxis(QCategory3DAxis *axis) |
Signal de notification :
| void | rowAxisChanged(QCategory3DAxis *axis) |
[read-only] selectedSeries : QBar3DSeries*
Cette propriété contient la série sélectionnée ou une valeur nulle.
Si le paramètre selectionMode est associé au drapeau « SelectionMultiSeries », cette propriété contient la série à laquelle appartient la barre sélectionnée.
Fonctions d'accès :
| QBar3DSeries * | selectedSeries() const |
Signal de notification :
| void | selectedSeriesChanged(QBar3DSeries *series) |
valueAxis : QValue3DAxis*
Définit l'axe de valeur actif (l'axe Y) sur axis. Appelle implicitement la fonction addAxis() pour transférer la propriété de axis à 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 * | valueAxis() const |
| void | setValueAxis(QValue3DAxis *axis) |
Signal de notification :
| void | valueAxisChanged(QValue3DAxis *axis) |
Voir également addAxis() et releaseAxis().
Documentation des fonctions membres
[explicit] Q3DBars::Q3DBars(const QSurfaceFormat *format = nullptr, QWindow *parent = nullptr)
Crée un nouveau graphique à barres en 3D avec, en option, une fenêtre d'parent s et une surface d'format.
[virtual noexcept] Q3DBars::~Q3DBars()
Supprime le graphique à barres en 3D.
void Q3DBars::addAxis(QAbstract3DAxis *axis)
axis Ajoute l'axis au graphe. Les axes ajoutés via addAxis ne sont pas encore utilisés ; addAxis sert simplement à attribuer la propriété de l' au graphe. L'axis ne doit pas être nulle ni avoir été ajoutée à un autre graphe.
Voir également releaseAxis(), setValueAxis(), setRowAxis() et setColumnAxis().
void Q3DBars::addSeries(QBar3DSeries *series)
Ajoute l'series e au graphique. Un graphique peut contenir plusieurs séries, mais un seul jeu d'axes ; les lignes et les colonnes de toutes les séries doivent donc correspondre pour que les données visualisées aient un sens. Si le graphique comporte plusieurs séries visibles, seule la série principale générera les libellés de lignes ou de colonnes sur les axes lorsque ces libellés ne sont pas explicitement définis sur les axes. Si la série nouvellement ajoutée a spécifié une barre sélectionnée, celle-ci sera mise en surbrillance et toute sélection existante sera effacée. Une seule série ajoutée peut avoir une sélection active.
Voir également seriesList(), primarySeries et QAbstract3DGraph::hasSeries().
QList<QAbstract3DAxis *> Q3DBars::axes() const
Renvoie la liste de tous les axes ajoutés.
Voir aussi addAxis().
void Q3DBars::insertSeries(int index, QBar3DSeries *series)
Insère l'series à la position index dans la liste des séries. Si l'series a déjà été ajoutée à la liste, elle est déplacée vers la nouvelle index.
Remarque : lors du déplacement d’une série vers une nouvelle index postérieure à son ancien index, la nouvelle position dans la liste est calculée comme si la série se trouvait toujours à son ancien index ; l’index final correspond donc en réalité à index diminué d’un.
Voir également addSeries(), seriesList() et QAbstract3DGraph::hasSeries().
void Q3DBars::releaseAxis(QAbstract3DAxis *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(), setValueAxis(), setRowAxis() et setColumnAxis().
void Q3DBars::removeSeries(QBar3DSeries *series)
Supprime l'series e du graphe.
Voir aussi QAbstract3DGraph::hasSeries().
QList<QBar3DSeries *> Q3DBars::seriesList() const
Renvoie la liste des séries ajoutées à ce graphique.
Voir aussi QAbstract3DGraph::hasSeries().
void Q3DBars::setColumnAxis(QCategory3DAxis *axis)
Définit l'axe de la colonne active sur ` axis`. Appelle implicitement la fonction ` addAxis()` pour transférer la propriété de l'axe à ce graphique.
Si axis est nul, un axe temporaire par défaut sans étiquettes est créé. Cet axe temporaire est détruit si un autre axe est explicitement défini avec la même orientation.
Remarque : fonctionde définition de la propriété columnAxis.
Voir également columnAxis(), addAxis() et releaseAxis().
void Q3DBars::setPrimarySeries(QBar3DSeries *series)
Définit la série « series » comme série principale du graphique. La série principale détermine les libellés des axes des lignes et des colonnes lorsque ceux-ci ne sont pas explicitement définis sur les axes.
Si la série spécifiée n’est pas encore ajoutée au graphique, le fait de la définir comme série principale entraîne également son ajout implicite au graphique.
Si la série principale elle-même est supprimée du graphique, cette propriété reprend sa valeur par défaut.
Si series est nul, cette propriété reprend sa valeur par défaut. La valeur par défaut est la première série ajoutée ou zéro si aucune série n’a été ajoutée au graphique.
Remarque : fonctionde définition pour la propriété primarySeries.
Voir également primarySeries().
void Q3DBars::setRowAxis(QCategory3DAxis *axis)
Définit l'axe de la ligne active sur ` axis`. Appelle implicitement la fonction ` addAxis()` pour transférer la propriété de l'axe à ce graphique.
Si axis est null, un axe temporaire par défaut sans étiquettes est créé. Cet axe temporaire est détruit si un autre axe est explicitement défini avec la même orientation.
Remarque : fonctionde définition de la propriété rowAxis.
Voir également rowAxis(), addAxis() et releaseAxis().
© 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.
