Auf dieser Seite

Q3DBarsWidgetItem Class

Die Klasse „Q3DBarsWidgetItem“ bietet Methoden zur Darstellung von 3D-Balkendiagrammen. Mehr...

Kopfzeile: #include <Q3DBarsWidgetItem>
CMake: find_package(Qt6 REQUIRED COMPONENTS GraphsWidgets)
target_link_libraries(mytarget PRIVATE Qt6::GraphsWidgets)
qmake: QT += graphswidgets
Erbt von: Q3DGraphsWidgetItem

Eigenschaften

Öffentliche Funktionen

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
QValue3DAxis *valueAxis() const

Öffentliche Slots

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)

Signale

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)

Ausführliche Beschreibung

Diese Klasse ermöglicht es Entwicklern, 3D-Balkendiagramme darzustellen und diese durch freies Drehen der Szene zu betrachten. Das Drehen erfolgt durch Gedrückthalten der rechten Maustaste und Bewegen der Maus, während das Zoomen über das Mausrad erfolgt. Falls aktiviert, erfolgt die Auswahl mit der linken Maustaste. Die Szene kann durch Klicken auf das Mausrad auf die Standard-Kameraansicht zurückgesetzt werden. Auf Touch-Geräten erfolgt die Drehung durch Tippen und Ziehen, die Auswahl durch Tippen und Halten und das Zoomen durch Zusammenziehen der Finger.

Wenn für `Q3DBarsWidgetItem` keine Achsen explizit festgelegt sind, werden temporäre Standardachsen ohne Beschriftungen erstellt. Diese Standardachsen können über Achsen-Zugriffsmethoden geändert werden; sobald jedoch eine Achse für die jeweilige Ausrichtung explizit festgelegt wird, wird die Standardachse für diese Ausrichtung gelöscht.

Q3DBarsWidgetItem unterstützt mehr als eine sichtbare Reihe gleichzeitig. Nicht alle Reihen müssen dieselbe Anzahl an Zeilen und Spalten aufweisen. Zeilen- und Spaltenbeschriftungen werden aus der zuerst hinzugefügten Reihe übernommen, sofern sie nicht explizit für die Zeilen- und Spaltenachsen definiert wurden.

Q3DBarsWidgetItem unterstützt Transparenz. Mit dieser Funktion können Sie die Deckkraft der Balken anpassen und sie teilweise durchscheinend, vollständig transparent oder undurchsichtig machen.

So erstellen Sie ein minimales Q3DBarsWidgetItem-Diagramm

Erstellen Sie zunächst eine Instanz von Q3DBarsWidgetItem:

QQuickWidget quickWidget;
Q3DBarsWidgetItem bars;
bars.setWidget(&quickWidget);
bars.widget()->setMinimumSize(QSize(256, 256));

Nach der Erstellung von `Q3DBarsWidgetItem` können Sie das Datenfenster festlegen, indem Sie den Bereich auf der Zeilen- und Spaltenachse ändern. Dies ist nicht zwingend erforderlich, da das Datenfenster standardmäßig alle Daten der Reihe anzeigt. Bei großen Datenmengen ist es in der Regel vorteilhaft, nur einen Teil davon anzuzeigen. Legen wir beispielsweise das Datenfenster so fest, dass die ersten fünf Zeilen und Spalten angezeigt werden:

bars.rowAxis()->setRange(0, 4);
bars.columnAxis()->setRange(0, 4);

Nun ist `Q3DBarsWidgetItem` bereit, Daten zur Darstellung zu empfangen. Erstellen Sie eine Reihe mit einer Zeile aus 5 Werten:

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);

Hinweis: Wir haben das Datenfenster auf 5 × 5 eingestellt, fügen aber nur eine Datenzeile hinzu. Das ist in Ordnung; die übrigen Zeilen bleiben einfach leer.

Abschließend müssen Sie es als sichtbar festlegen:

bars.widget()->show();

Der vollständige Code zum Erstellen und Anzeigen dieses Diagramms lautet:

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

Und das ist das Ergebnis dieser wenigen Codezeilen:

3D-Balkendiagramm mit grünen Balken unterschiedlicher Höhe

Die Szene kann gedreht und vergrößert werden, und ein Balken kann ausgewählt werden, um seinen Wert anzuzeigen; weitere Interaktionen sind in diesem minimalen Codebeispiel jedoch nicht enthalten. Weitere Informationen finden Sie in den bereitgestellten Beispielen, wie zum Beispiel dem „Simple Bar Graph“.

Siehe auch „ Q3DScatterWidgetItem“ , „ Q3DSurfaceWidgetItem “ und „Qt Graphs “ – C++-Klassen für 3D.

Dokumentation zu den Eigenschaften

barSeriesMargin : QSizeF

Abstand zwischen den Spalten der Reihen in der X- und Z-Richtung. Sinnvolle Werte liegen im Bereich [0,1).

Standardmäßig auf „ (0.0, 0.0) “ voreingestellt. Diese Eigenschaft ermöglicht die nebeneinanderliegende Darstellung von Balken verschiedener Reihen, jedoch mit Abstand zwischen den Spalten.

Zugriffsfunktionen:

QSizeF barSeriesMargin() const
void setBarSeriesMargin(QSizeF margin)

Benachrichtigungssignal:

void barSeriesMarginChanged(QSizeF margin)

Siehe auch „ barSpacing “.

barSpacing : QSizeF

Abstand der Balken in der X- und Z-Richtung.

Standardmäßig auf „ (1.0, 1.0) “ voreingestellt. Der Abstand wird durch die Eigenschaft „ barSpacingRelative “ beeinflusst.

Zugriffsfunktionen:

QSizeF barSpacing() const
void setBarSpacing(QSizeF spacing)

Benachrichtigungssignal:

void barSpacingChanged(QSizeF spacing)

Siehe auch „ barSpacingRelative “, „ multiSeriesUniform “ und „ barSeriesMargin “.

barSpacingRelative : bool

Diese Eigenschaft gilt unabhängig davon, ob der Abstand absolut oder relativ zur Balkenstärke ist.

Wenn der Wert „ true “ ist, bedeutet der Wert „ 0.0 “, dass die Balken nebeneinander platziert werden, „ 1.0 “ bedeutet, dass zwischen den Balken ein Abstand in der Breite einer Balkenstärke gelassen wird, und so weiter. Voreingestellt auf „ true “.

Zugriffsfunktionen:

bool isBarSpacingRelative() const
void setBarSpacingRelative(bool relative)

Benachrichtigungssignal:

void barSpacingRelativeChanged(bool relative)

barThickness : float

Diese Eigenschaft legt das Verhältnis der Stabdicke zwischen der X- und der Z-Achse fest.

Der Wert „ 1.0 “ bedeutet, dass die Stäbe genauso breit wie tief sind, während „ 0.5 “ sie doppelt so tief wie breit macht. Standardmäßig auf „ 1.0 “ voreingestellt.

Zugriffsfunktionen:

float barThickness() const
void setBarThickness(float thicknessRatio)

Benachrichtigungssignal:

void barThicknessChanged(float thicknessRatio)

columnAxis : QCategory3DAxis*

Diese Eigenschaft enthält die Achse, die der aktiven Spalte zugeordnet ist.

Setzt die Achse der aktiven Spalte auf „ axis “. Ruft implizit „ addAxis()“ auf, um die Eigentumsrechte an der Achse auf dieses Diagramm zu übertragen.

Ist ` axis ` null, wird eine temporäre Standardachse ohne Beschriftungen erstellt. Diese temporäre Achse wird gelöscht, wenn eine andere Achse explizit auf dieselbe Ausrichtung gesetzt wird.

Zugriffsfunktionen:

QCategory3DAxis *columnAxis() const
void setColumnAxis(QCategory3DAxis *axis)

Notifier-Signal:

void columnAxisChanged(QCategory3DAxis *axis)

Siehe auch ` addAxis()` und ` releaseAxis()`.

floorLevel : float

Diese Eigenschaft legt das Untergrenze des Balkendiagramms in den Datenkoordinaten der Y-Achse fest.

Die tatsächliche Bodenhöhe wird durch die Minimal- und Maximalwerte der Y-Achse begrenzt. Der Standardwert ist Null.

Zugriffsfunktionen:

float floorLevel() const
void setFloorLevel(float level)

Benachrichtigungssignal:

void floorLevelChanged(float level)

multiSeriesUniform : bool

Diese Eigenschaft legt fest, ob die Balken anhand der Proportionen eines einzelnen Serienbalkens skaliert werden sollen, auch wenn mehrere Serien angezeigt werden.

Bei der Einstellung „ true “ wird die Option „ bar spacing “ korrekt nur auf die X-Achse angewendet. Standardmäßig ist „ false “ voreingestellt.

Zugriffsfunktionen:

bool isMultiSeriesUniform() const
void setMultiSeriesUniform(bool uniform)

Benachrichtigungssignal:

void multiSeriesUniformChanged(bool uniform)

primarySeries : QBar3DSeries*

Diese Eigenschaft enthält die primäre Reihe des Diagramms.

Legt „ series “ als primäre Reihe des Diagramms fest. Die primäre Reihe bestimmt die Beschriftungen der Zeilen- und Spaltenachsen, wenn diese nicht explizit für die Achsen festgelegt wurden.

Wenn die angegebene Reihe noch nicht zum Diagramm hinzugefügt wurde, wird sie durch die Festlegung als primäre Reihe implizit zum Diagramm hinzugefügt.

Wird die primäre Reihe selbst aus dem Diagramm entfernt, wird diese Eigenschaft auf den Standardwert zurückgesetzt.

Ist „ series “ null, wird diese Eigenschaft auf den Standardwert zurückgesetzt. Der Standardwert ist die zuerst hinzugefügte Reihe oder Null, wenn dem Diagramm keine Reihen hinzugefügt wurden.

Zugriffsfunktionen:

QBar3DSeries *primarySeries() const
void setPrimarySeries(QBar3DSeries *series)

Benachrichtigungssignal:

void primarySeriesChanged(QBar3DSeries *series)

rowAxis : QCategory3DAxis*

Diese Eigenschaft enthält die Achse, die der aktiven Zeile zugeordnet ist.

Setzt die Achse der aktiven Zeile auf „ axis “. Ruft implizit „ addAxis()“ auf, um die Eigentumsrechte an der Achse auf dieses Diagramm zu übertragen.

Ist ` axis ` null, wird eine temporäre Standardachse ohne Beschriftungen erstellt. Diese temporäre Achse wird gelöscht, wenn eine andere Achse explizit auf dieselbe Ausrichtung gesetzt wird.

Zugriffsfunktionen:

QCategory3DAxis *rowAxis() const
void setRowAxis(QCategory3DAxis *axis)

Notifier-Signal:

void rowAxisChanged(QCategory3DAxis *axis)

Siehe auch ` addAxis()` und ` releaseAxis()`.

[read-only] selectedSeries : QBar3DSeries*

Diese Eigenschaft enthält die ausgewählte Serie oder einen Nullwert.

Wenn für „selectionMode“ das Flag „ SelectionMultiSeries “ gesetzt ist, enthält diese Eigenschaft die Reihe, zu der der ausgewählte Balken gehört.

Zugriffsfunktionen:

QBar3DSeries *selectedSeries() const

Notifier-Signal:

void selectedSeriesChanged(QBar3DSeries *series)

valueAxis : QValue3DAxis*

Setzt die aktive Werteachse (die Y-Achse) auf „ axis “. Ruft implizit die Funktion „ addAxis()“ auf, um die Eigentumsrechte an „ axis “ auf dieses Diagramm zu übertragen.

Ist ` axis ` null, wird eine temporäre Standardachse ohne Beschriftungen und mit automatisch angepasstem Bereich erstellt. Diese temporäre Achse wird gelöscht, wenn eine andere Achse explizit auf dieselbe Ausrichtung gesetzt wird.

Zugriffsfunktionen:

QValue3DAxis *valueAxis() const
void setValueAxis(QValue3DAxis *axis)

Notifier-Signal:

void valueAxisChanged(QValue3DAxis *axis)

Siehe auch „ addAxis()“ und „ releaseAxis()“.

Dokumentation der Mitgliedsfunktionen

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

Erstellt ein neues 3D-Balkendiagramm mit dem optionalen Parameter „ parent “.

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

Löscht das 3D-Balkendiagramm.

void Q3DBarsWidgetItem::addAxis(QAbstract3DAxis *axis)

Fügt „ axis “ zum Diagramm hinzu. Die über „addAxis“ hinzugefügten Achsen werden noch nicht verwendet; „addAxis“ dient lediglich dazu, die Zuständigkeit für die „ axis “ dem Diagramm zuzuweisen. Die „ axis “ darf nicht null sein oder bereits einem anderen Diagramm hinzugefügt worden sein.

Siehe auch „ releaseAxis()“, „ setValueAxis()“, „ setRowAxis()“ und „ setColumnAxis()“.

void Q3DBarsWidgetItem::addSeries(QBar3DSeries *series)

Fügt die „ series “ zum Diagramm hinzu. Ein Diagramm kann mehrere Reihen enthalten, jedoch nur einen Achsenpaar; daher müssen die Zeilen und Spalten aller Reihen übereinstimmen, damit die visualisierten Daten aussagekräftig sind. Wenn das Diagramm mehrere sichtbare Reihen enthält, erzeugt nur die primäre Reihe die Zeilen- oder Spaltenbeschriftungen auf den Achsen, sofern diese nicht explizit für die Achsen festgelegt wurden. Wenn für die neu hinzugefügte Reihe ein Balken ausgewählt wurde, wird dieser hervorgehoben und eine eventuell vorhandene Auswahl wird aufgehoben. Nur eine der hinzugefügten Reihen kann eine aktive Auswahl haben.

Siehe auch seriesList(), primarySeries und Q3DGraphsWidgetItem::hasSeries().

QList<QAbstract3DAxis *> Q3DBarsWidgetItem::axes() const

Gibt die Liste aller hinzugefügten Achsen zurück.

Siehe auch „ addAxis()“.

void Q3DBarsWidgetItem::insertSeries(int index, QBar3DSeries *series)

Fügt den „ series “ an der Position „ index “ in die Serienliste ein. Falls der „ series “ bereits zur Liste hinzugefügt wurde, wird er an die neue Position „ index “ verschoben.

Hinweis: Beim Verschieben einer Serie an eine neue Position „ index “, die hinter ihrem alten Index liegt, wird die neue Position in der Liste so berechnet, als befände sich die Serie noch an ihrem alten Index; der endgültige Index entspricht also tatsächlich dem Wert „ index “ minus eins.

Siehe auch addSeries(), seriesList() und Q3DGraphsWidgetItem::hasSeries().

void Q3DBarsWidgetItem::releaseAxis(QAbstract3DAxis *axis)

Gibt die Eigentumsrechte an der „ axis “ an den Aufrufer zurück, sofern diese dem Graphen hinzugefügt wurde. Wird die freigegebene „ axis “ gerade verwendet, wird eine neue Standardachse erstellt und als aktiv gesetzt.

Wird die Standardachse freigegeben und später wieder hinzugefügt, verhält sie sich wie jede andere Achse.

Siehe auch „ addAxis()“, „ setValueAxis()“, „ setRowAxis()“ und „ setColumnAxis()“.

void Q3DBarsWidgetItem::removeSeries(QBar3DSeries *series)

Entfernt den „ series “ aus dem Diagramm.

Siehe auch „ Q3DGraphsWidgetItem::hasSeries()“.

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

Exportiert die angeforderte Schnittansicht in ein Bild. Der exportierte Schnitt besteht aus Zeilen- oder Spaltenbalken, die durch „ sliceType “ definiert sind, bei einem vorgegebenen „ requestedIndex “.

Das Signal „ sliceImageChanged “ wird ausgegeben, sobald das Bild fertig ist, und kann wie folgt abgefangen werden:

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

item->renderSliceToImage(sliceType, index);

Das Bild wird mit den aktuellen Antialiasing-Einstellungen gerendert.

Diese Funktion wurde in Qt 6.10 eingeführt.

Siehe auch QQuickItem::grabToImage() und sliceImageChanged().

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

Gibt die Liste der zu diesem Diagramm hinzugefügten Reihen zurück.

Siehe auch „ Q3DGraphsWidgetItem::hasSeries()“.

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

Wird ausgelöst, wenn „ renderSliceToImage “ die Funktion „ image “ vorbereitet hat.

Diese Funktion wurde in Qt 6.10 eingeführt.

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