Q3DBarsWidgetItem Class
La classe Q3DBarsWidgetItem fournit des méthodes de rendu des graphiques à barres 3D. Plus d'informations...
| En-tête : | #include <Q3DBarsWidgetItem> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS GraphsWidgets)target_link_libraries(mytarget PRIVATE Qt6::GraphsWidgets) |
| qmake : | QT += graphswidgets |
| Héritages : | Q3DGraphsWidgetItem |
- Liste de tous les membres, y compris les membres hérités
- Q3DBarsWidgetItem fait partie de Qt Graphs C++ Classes for Widgets.
Propriétés
|
|
Fonctions publiques
| Q3DBarsWidgetItem(QObject *parent = nullptr) | |
| virtual | ~Q3DBarsWidgetItem() override |
| 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) |
(since 6.10) void | renderSliceToImage(int requestedIndex, QtGraphs3D::SliceCaptureType sliceType) |
| QCategory3DAxis * | rowAxis() const |
| QBar3DSeries * | selectedSeries() const |
| QList<QBar3DSeries *> | seriesList() const |
| void | setBarSeriesMargin(QSizeF margin) |
| void | setBarSpacing(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(QSizeF margin) |
| void | barSpacingChanged(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) |
(since 6.10) void | sliceImageChanged(const QImage &image) |
| 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 librement la scène. La rotation est réalisée en maintenant le bouton droit de la souris enfoncé et en déplaçant la souris, tandis que le zoom est réalisé à l'aide de la molette de la souris. Si elle est activée, la sélection 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 s'effectue 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 pour Q3DBarsWidgetItem, 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.
Q3DBarsWidgetItem supporte plus d'une série visible en même temps. Toutes les séries n'ont pas besoin d'avoir le même nombre de lignes et de colonnes. Les étiquettes des lignes et des colonnes sont tirées de la première série ajoutée, à moins qu'elles ne soient explicitement définies pour les axes des lignes et des colonnes.
Q3DBarsWidgetItem prend en charge la transparence. Cette fonctionnalité vous permet d'ajuster l'opacité des barres, en les rendant partiellement transparentes, totalement transparentes ou opaques.
Comment construire un graphique minimal de Q3DBarsWidgetItem ?
Commencez par construire une instance de Q3DBarsWidgetItem :
QQuickWidget quickWidget; Q3DBarsWidgetItem bars; bars.setWidget(&quickWidget); bars.widget()->setMinimumSize(QSize(256, 256));
Après avoir construit Q3DBarsWidgetItem, 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. Par exemple, paramétrons 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);
Le Q3DBarsWidgetItem est maintenant prêt à recevoir les données à afficher. Créez une série avec une ligne de 5 valeurs :
QBar3DSeries series; QBarDataRow data; data << QBarDataItem(1.0f) << QBarDataItem(3.0f) << QBarDataItem(7.5f) << QBarDataItem(5.0f) << QBarDataItem(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.widget()->show();
Le code complet nécessaire à la création et à l'affichage de ce graphique est le suivant :
#include <QtGraphs> #include <QtGraphsWidgets/q3dbarswidgetitem.h> #include <QtWidgets/qapplication.h> int main(int argc, char **argv) { QApplication app(argc, argv); QQuickWidget quickWidget; Q3DBarsWidgetItem bars; bars.setWidget(&quickWidget); bars.widget()->setMinimumSize(QSize(256, 256)); bars.rowAxis()->setRange(0, 4); bars.columnAxis()->setRange(0, 4); QBar3DSeries series; QBarDataRow data; data << QBarDataItem(1.0f) << QBarDataItem(3.0f) << QBarDataItem(7.5f) << QBarDataItem(5.0f) << QBarDataItem(2.2f); series.dataProxy()->addRow(data); bars.addSeries(&series); bars.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 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 simple.
Voir également Q3DScatterWidgetItem, Q3DSurfaceWidgetItem, et Qt Graphs C++ Classes for 3D.
Documentation sur les propriétés
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.
Fonctions d'accès :
| QSizeF | barSeriesMargin() const |
| void | setBarSeriesMargin(QSizeF margin) |
Signal de notification :
| void | barSeriesMarginChanged(QSizeF margin) |
Voir également 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(QSizeF spacing) |
Signal de notification :
| void | barSpacingChanged(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.
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.
Fonctions d'accès :
| QCategory3DAxis * | columnAxis() const |
| void | setColumnAxis(QCategory3DAxis *axis) |
Signal Notifier :
| void | columnAxisChanged(QCategory3DAxis *axis) |
Voir aussi addAxis() et releaseAxis().
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é définit la série primaire du graphique.
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.
Fonctions d'accès :
| QBar3DSeries * | primarySeries() const |
| void | setPrimarySeries(QBar3DSeries *series) |
Signal Notificateur :
| void | primarySeriesChanged(QBar3DSeries *series) |
rowAxis : QCategory3DAxis*
Cette propriété contient l'axe attaché à la ligne active.
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.
Fonctions d'accès :
| QCategory3DAxis * | rowAxis() const |
| void | setRowAxis(QCategory3DAxis *axis) |
Signal Notifier :
| void | rowAxisChanged(QCategory3DAxis *axis) |
Voir aussi addAxis() et releaseAxis().
[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] Q3DBarsWidgetItem::Q3DBarsWidgetItem(QObject *parent = nullptr)
Construit un nouveau graphique à barres 3D avec l'option parent.
[override virtual noexcept] Q3DBarsWidgetItem::~Q3DBarsWidgetItem()
Détruit le graphique à barres en 3D.
void Q3DBarsWidgetItem::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 Q3DBarsWidgetItem::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 pour 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 Q3DGraphsWidgetItem::hasSeries().
QList<QAbstract3DAxis *> Q3DBarsWidgetItem::axes() const
Renvoie la liste de tous les axes ajoutés.
Voir aussi addAxis().
void Q3DBarsWidgetItem::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 Q3DGraphsWidgetItem::hasSeries().
void Q3DBarsWidgetItem::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 aussi addAxis(), setValueAxis(), setRowAxis() et setColumnAxis().
void Q3DBarsWidgetItem::removeSeries(QBar3DSeries *series)
Supprime le site series du graphique.
Voir aussi Q3DGraphsWidgetItem::hasSeries().
[since 6.10] void Q3DBarsWidgetItem::renderSliceToImage(int requestedIndex, QtGraphs3D::SliceCaptureType sliceType)
Exporte la vue de la tranche demandée vers une image. La tranche exportée est une barre de ligne ou de 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, &Q3DBarsWidgetItem::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<QBar3DSeries *> Q3DBarsWidgetItem::seriesList() const
Renvoie la liste des séries ajoutées à ce graphique.
Voir également Q3DGraphsWidgetItem::hasSeries().
[signal, since 6.10] void Q3DBarsWidgetItem::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.