Back to Qt.io
Contact Us Blog Download Qt
Sur cette page

Q3DBars Class

La classe Q3DBars fournit des méthodes de rendu des graphiques à barres 3D. Plus d'informations...

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 : QAbstract3DGraph

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 de rendre des graphiques à barres en 3D et de les visualiser en faisant pivoter la scène librement. La rotation se fait en maintenant le bouton droit de la souris enfoncé et en déplaçant la souris. Le zoom est effectué à 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 ramenée à la vue par défaut de la caméra en cliquant sur la molette de la souris. Sur les appareils tactiles, la rotation se fait par tapotement et déplacement, la sélection par tapotement et maintien et le zoom par pincement.

Si aucun axe n'est défini explicitement sur Q3DBars, 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.

Q3DBars prend en charge plusieurs séries visibles en même temps. Il n'est pas nécessaire que toutes les séries aient le même nombre de lignes et de colonnes. Les étiquettes des lignes et des colonnes proviennent de la première série ajoutée, à moins qu'elles ne soient explicitement définies pour les axes des lignes et des colonnes.

Comment construire un graphique Q3DBars minimal ?

Commencez par construire une instance de Q3DBars. Comme nous exécutons le graphique en tant que fenêtre de premier niveau 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 construit Q3DBars, vous pouvez définir la fenêtre de données en modifiant la plage sur les axes des lignes et des colonnes. Ce n'est pas obligatoire, car la fenêtre de données affichera par défaut toutes les données de la série. Si la quantité de données est importante, il est généralement préférable de n'en afficher qu'une partie. Pour l'exemple, réglons 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 maintenant prêt à recevoir des données à rendre. Créez une série avec 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 réglé 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 seront simplement vides.

Enfin, vous devrez la rendre visible :

bars.show();

Le code complet nécessaire à la création et à l'affichage de 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 ce que ces quelques lignes de code produisent :

La scène peut être tournée, zoomée et une barre peut être sélectionnée pour voir sa valeur, 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 le graphique à barres.

Voir aussi Q3DScatter, Q3DSurface, et Qt Data Visualization C++ Classes.

Documentation sur les propriétés

[since 6.3] barSeriesMargin : QSizeF

Marge entre les colonnes de la série dans les dimensions X et Z. Les valeurs acceptables se situent dans l'intervalle [0,1].

La valeur par défaut est (0.0, 0.0). Cette propriété permet d'afficher des barres de différentes séries côte à côte, mais avec un espace entre les colonnes.

Cette propriété a été introduite dans Qt 6.3.

Fonctions d'accès :

QSizeF barSeriesMargin() const
void setBarSeriesMargin(const QSizeF &margin)

Signal Notifier :

void barSeriesMarginChanged(const QSizeF &margin)

Voir aussi barSpacing.

barSpacing : QSizeF

Espacement des barres dans les dimensions X et Z.

La valeur par défaut est (1.0, 1.0). L'espacement est affecté 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 aussi barSpacingRelative, multiSeriesUniform, et barSeriesMargin.

barSpacingRelative : bool

Cette propriété indique si l'espacement est absolu ou relatif à l'épaisseur des barres.

S'il s'agit de true, la valeur de 0.0 signifie que les barres sont placées côte à côte, 1.0 signifie qu'un espace aussi large que l'épaisseur d'une barre est laissé entre les barres, et ainsi de suite. Préréglé sur true.

Fonctions d'accès :

bool isBarSpacingRelative() const
void setBarSpacingRelative(bool relative)

Signal de notification :

void barSpacingRelativeChanged(bool relative)

barThickness : float

Cette propriété indique le rapport d'épaisseur des barres entre les dimensions X et Z. La valeur signifie que les barres sont aussi larges que profondes.

La valeur 1.0 signifie que les barres sont aussi larges que profondes, tandis que 0.5 les rend deux fois plus profondes que larges. 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 attaché à 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é contient le niveau de l'étage pour le graphique à barres en coordonnées de données de l'axe Y. Le niveau réel de l'étage sera limité par les valeurs minimum et maximum de l'axe Y.

Le niveau réel sera limité par les valeurs minimales et maximales de l'axe des 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é indique si les barres doivent être mises à l'échelle avec des proportions définies pour une barre de série unique, même si plusieurs séries sont affichées.

Si elle est définie sur true, bar spacing ne sera correctement appliquée qu'à l'axe des 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 primaire 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 attaché à 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 l'indicateur SelectionMultiSeries est activé dans SelectionMode, cette propriété contient la série qui possède 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 des valeurs actives (l'axe Y) à axis. Appelle implicitement addAxis() pour transférer la propriété de axis à 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 *valueAxis() const
void setValueAxis(QValue3DAxis *axis)

Signal Notifier :

void valueAxisChanged(QValue3DAxis *axis)

Voir également addAxis() et releaseAxis().

Documentation des fonctions membres

[explicit] Q3DBars::Q3DBars(const QSurfaceFormat *format = nullptr, QWindow *parent = nullptr)

Construit un nouveau graphique à barres en 3D avec la fenêtre parent et la surface format.

[virtual noexcept] Q3DBars::~Q3DBars()

Détruit le graphique à barres en 3D.

void Q3DBars::addAxis(QAbstract3DAxis *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(), setValueAxis(), setRowAxis() et setColumnAxis().

void Q3DBars::addSeries(QBar3DSeries *series)

Ajoute le site series au graphique. Un graphique peut contenir plusieurs séries, mais un seul ensemble d'axes, de sorte que les lignes et les colonnes de toutes les séries doivent correspondre pour que les données visualisées soient significatives. Si le graphique contient plusieurs séries visibles, seule la série principale génère les étiquettes de ligne ou de colonne sur les axes dans les cas où les étiquettes ne sont pas explicitement définies sur les axes. Si la série nouvellement ajoutée a spécifié une barre sélectionnée, celle-ci 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 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 le series à la position index dans la liste des séries. Si la série series a déjà été ajoutée à la liste, elle est déplacée vers la nouvelle index.

Remarque : lorsqu'une série est déplacée vers un nouveau index situé après son ancien index, la nouvelle position dans la liste est calculée comme si la série se trouvait toujours dans son ancien index, de sorte que l'index final est en fait le index décrémenté d'une unité.

Voir aussi addSeries(), seriesList() et QAbstract3DGraph::hasSeries().

void Q3DBars::releaseAxis(QAbstract3DAxis *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(), setValueAxis(), setRowAxis() et setColumnAxis().

void Q3DBars::removeSeries(QBar3DSeries *series)

Supprime le site series du graphique.

Voir aussi QAbstract3DGraph::hasSeries().

QList<QBar3DSeries *> Q3DBars::seriesList() const

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

Voir également QAbstract3DGraph::hasSeries().

void Q3DBars::setColumnAxis(QCategory3DAxis *axis)

Définit l'axe de la colonne active à axis. 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 est créé. Cet axe temporaire est détruit si un autre axe est défini explicitement avec la même orientation.

Remarque : fonction de définition de la propriété columnAxis.

Voir aussi columnAxis(), addAxis() et releaseAxis().

void Q3DBars::setPrimarySeries(QBar3DSeries *series)

Définit series comme série primaire du graphique. La série primaire détermine les étiquettes des axes des lignes et des colonnes lorsque les étiquettes ne sont pas explicitement définies pour 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 primaire l'ajoutera implicitement au graphique.

Si la série primaire elle-même est supprimée du graphique, cette propriété reprend sa valeur par défaut.

Si series est nul, cette propriété est réinitialisée par défaut. La valeur par défaut est la première série ajoutée ou zéro si aucune série n'est ajoutée au graphique.

Remarque : fonction de définition de la propriété primarySeries.

Voir également primarySeries().

void Q3DBars::setRowAxis(QCategory3DAxis *axis)

Définit l'axe de la ligne active à axis. 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 est créé. Cet axe temporaire est détruit si un autre axe est défini explicitement avec la même orientation.

Remarque : fonction de définition de la propriété rowAxis.

Voir aussi 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.