Q3DBarsWidgetItem Class
Q3DBarsWidgetItem 클래스는 3D 막대 그래프를 렌더링하는 메서드를 제공합니다. 더 보기...
| 헤더: | #include <Q3DBarsWidgetItem> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS GraphsWidgets) target_link_libraries(mytarget PRIVATE Qt6::GraphsWidgets) |
| qmake: | QT += graphswidgets |
| 상속: | Q3DGraphsWidgetItem |
- 상속된 멤버를 포함한 모든 멤버 목록
- Q3DBarsWidgetItem은 Qt Graphs 의 위젯용 C++ 클래스 세트에 포함됩니다.
속성
|
|
공개 함수
| 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 |
공개 슬롯
| 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) |
신호
| 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) |
상세 설명
이 클래스를 사용하면 개발자가 3D 막대 그래프를 렌더링하고, 장면을 자유롭게 회전시켜 볼 수 있습니다. 회전은 마우스 오른쪽 버튼을 누른 상태에서 마우스를 움직여 수행되며, 확대/축소는 마우스 휠을 사용하여 수행됩니다. 활성화된 경우, 선택은 마우스 왼쪽 버튼으로 수행됩니다. 마우스 휠을 클릭하면 장면을 기본 카메라 뷰로 재설정할 수 있습니다. 터치 기기에서는 탭하고 드래그하여 회전하고, 탭하고 길게 눌러 선택하며, 핀치 제스처로 확대/축소합니다.
Q3DBarsWidgetItem에 축이 명시적으로 설정되지 않은 경우, 레이블이 없는 임시 기본 축이 생성됩니다. 이러한 기본 축은 축 액세서를 통해 수정할 수 있지만, 방향에 대해 축이 명시적으로 설정되는 즉시 해당 방향의 기본 축은 삭제됩니다.
Q3DBarsWidgetItem은 동시에 여러 개의 가시적 시리즈를 지원합니다. 모든 시리즈의 행과 열 수가 동일할 필요는 없습니다. 행 및 열 축에 대해 명시적으로 정의되지 않은 경우, 행 및 열 레이블은 가장 먼저 추가된 시리즈에서 가져옵니다.
Q3DBarsWidgetItem은 투명도 기능을 지원합니다. 이 기능을 사용하면 막대의 불투명도를 조정하여 부분적으로 비치거나, 완전히 투명하게, 또는 불투명하게 만들 수 있습니다.
최소한의 Q3DBarsWidgetItem 그래프를 생성하는 방법
먼저, Q3DBarsWidgetItem의 인스턴스를 생성합니다:
QQuickWidget quickWidget;
Q3DBarsWidgetItem bars;
bars.setWidget(&quickWidget);
bars.widget()->setMinimumSize(QSize(256, 256));Q3DBarsWidgetItem을 생성한 후, 행 및 열 축의 범위를 변경하여 데이터 창을 설정할 수 있습니다. 데이터 창은 기본적으로 시리즈의 모든 데이터를 표시하므로, 이 설정은 필수는 아닙니다. 데이터 양이 많은 경우, 일반적으로 데이터의 일부만 표시하는 것이 좋습니다. 예를 들어, 데이터 창을 첫 5개의 행과 열만 표시하도록 설정해 보겠습니다:
bars.rowAxis()->setRange(0, 4);
bars.columnAxis()->setRange(0, 4);이제 Q3DBarsWidgetItem은 렌더링할 데이터를 수신할 준비가 되었습니다. 5개의 값으로 구성된 행 하나짜리 시리즈를 생성해 봅시다:
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);참고: 데이터 창을 5 x 5로설정했지만 , 데이터는 한 행만 추가하고 있습니다. 이는 문제가 되지 않으며, 나머지 행은 비어 있게 됩니다.
마지막으로 이 위젯을 표시하도록 설정해야 합니다:
bars.widget()->show();이 그래프를 생성하고 표시하는 데 필요한 전체 코드는 다음과 같습니다:
#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();
}그리고 이 몇 줄의 코드가 만들어내는 결과는 다음과 같습니다:

이 장면을 회전하거나 확대할 수 있으며, 막대를 선택하여 해당 값을 확인할 수 있지만, 이 최소한의 코드 예제에는 그 외의 상호작용 기능은 포함되어 있지 않습니다. ‘Simple Bar Graph’와 같은 제공된 예제를 살펴보시면 더 자세히 알아보실 수 있습니다.
Q3DScatterWidgetItem, Q3DSurfaceWidgetItem, Qt Graphs 3D용 C++ 클래스도 참조하십시오 .
속성 문서
barSeriesMargin : QSizeF
X 및 Z 차원에서 시리즈 열 간의 여백입니다. 적절한 값은 [0, 1) 범위 내에 있습니다.
기본값은 (0.0, 0.0) 로 설정되어 있습니다. 이 속성을 사용하면 서로 다른 시리즈의 막대를 나란히 표시하되, 열 사이에 간격을 둘 수 있습니다.
액세스 함수:
| QSizeF | barSeriesMargin() const |
| void | setBarSeriesMargin(QSizeF margin) |
알림 신호:
| void | barSeriesMarginChanged(QSizeF margin) |
barSpacing도 참조하십시오 .
barSpacing : QSizeF
X 및 Z 방향의 막대 간격.
기본값은 (1.0, 1.0) 로 설정되어 있습니다. 간격은 ' barSpacingRelative ' 속성의 영향을 받습니다.
액세스 함수:
| QSizeF | barSpacing() const |
| void | setBarSpacing(QSizeF spacing) |
알림 신호:
| void | barSpacingChanged(QSizeF spacing) |
barSpacingRelative, multiSeriesUniform 및 barSeriesMargin도 참조하십시오 .
barSpacingRelative : bool
이 속성은 간격이 절대값이든 막대 두께를 기준으로 한 상대값이든 상관없이 적용됩니다.
true 인 경우, ` 0.0 `의 값은 막대들이 나란히 배치됨을 의미하고, ` 1.0 `는 막대들 사이에 막대 한 개의 두께만큼의 간격이 남음을 의미하며, 이와 같은 방식으로 적용됩니다. 기본값은 ` true`입니다.
액세스 함수:
| bool | isBarSpacingRelative() const |
| void | setBarSpacingRelative(bool relative) |
알림 신호:
| void | barSpacingRelativeChanged(bool relative) |
barThickness : float
이 속성은 X 축과 Z 축 치수 간의 막대 두께 비율을 지정합니다.
1.0 값은 바의 너비와 깊이가 같음을 의미하며, 0.5 값은 바의 깊이가 너비의 두 배가 됨을 의미합니다. 기본값은 1.0 로 설정되어 있습니다.
액세스 함수:
| float | barThickness() const |
| void | setBarThickness(float thicknessRatio) |
알림 신호:
| void | barThicknessChanged(float thicknessRatio) |
columnAxis : QCategory3DAxis*
이 속성은 활성 열에 연결된 축을 저장합니다.
활성 열의 축을 ` axis`로 설정합니다. 축의 소유권을 이 그래프로 이전하기 위해 ` addAxis()`를 암시적으로 호출합니다.
axis 가 null인 경우, 레이블이 없는 임시 기본 축이 생성됩니다. 이 임시 축은 다른 축이 명시적으로 동일한 방향으로 설정되면 소멸됩니다.
액세스 함수:
| QCategory3DAxis * | columnAxis() const |
| void | setColumnAxis(QCategory3DAxis *axis) |
알림 신호:
| void | columnAxisChanged(QCategory3DAxis *axis) |
addAxis() 및 releaseAxis()도 참조하십시오 .
floorLevel : float
이 속성은 Y축 데이터 좌표계에서 막대 그래프의 바닥 높이를 지정합니다.
실제 바닥 높이는 Y축의 최소값과 최대값에 의해 제한됩니다. 기본값은 0입니다.
액세스 함수:
| float | floorLevel() const |
| void | setFloorLevel(float level) |
알림 신호:
| void | floorLevelChanged(float level) |
multiSeriesUniform : bool
이 속성은 여러 시리즈가 표시되어 있는 경우에도 막대의 비율을 단일 시리즈 막대에 맞춰 조정할지 여부를 결정합니다.
true 로 설정된 경우, bar spacing 는 X축에만 올바르게 적용됩니다. 기본값은 false 입니다.
액세스 함수:
| bool | isMultiSeriesUniform() const |
| void | setMultiSeriesUniform(bool uniform) |
알림 신호:
| void | multiSeriesUniformChanged(bool uniform) |
primarySeries : QBar3DSeries*
이 속성은 그래프의 기본 시리를 지정합니다.
series 를 그래프의 기본 시계열로 설정합니다. 기본 시계열은 축 레이블이 명시적으로 설정되지 않은 경우, 행 및 열 축 레이블을 결정합니다.
지정된 시리가 아직 그래프에 추가되지 않은 경우, 이를 주 시리로 설정하면 암시적으로 그래프에 추가됩니다.
주 시리즈 자체가 그래프에서 제거되면 이 속성은 기본값으로 재설정됩니다.
series 가 null인 경우, 이 속성은 기본값으로 재설정됩니다. 기본값은 가장 먼저 추가된 시계열이며, 그래프에 시계열이 추가되지 않은 경우 0입니다.
액세스 함수:
| QBar3DSeries * | primarySeries() const |
| void | setPrimarySeries(QBar3DSeries *series) |
알림 신호:
| void | primarySeriesChanged(QBar3DSeries *series) |
rowAxis : QCategory3DAxis*
이 속성은 활성 행에 연결된 축을 저장합니다.
활성 행의 축을 ` axis`로 설정합니다. 축의 소유권을 이 그래프로 이전하기 위해 ` addAxis()`를 암시적으로 호출합니다.
axis 가 null인 경우, 레이블이 없는 임시 기본 축이 생성됩니다. 이 임시 축은 다른 축이 명시적으로 동일한 방향으로 설정되면 소멸됩니다.
액세스 함수:
| QCategory3DAxis * | rowAxis() const |
| void | setRowAxis(QCategory3DAxis *axis) |
알림 신호:
| void | rowAxisChanged(QCategory3DAxis *axis) |
addAxis() 및 releaseAxis()도 참조하십시오 .
[read-only] selectedSeries : QBar3DSeries*
이 속성은 선택된 시리즈를 반환하거나 null 값을 가집니다.
selectionMode에 ' SelectionMultiSeries ' 플래그가 설정된 경우, 이 속성은 선택된 막대를 소유한 시리즈를 저장합니다.
액세스 함수:
| QBar3DSeries * | selectedSeries() const |
알림 신호:
| void | selectedSeriesChanged(QBar3DSeries *series) |
valueAxis : QValue3DAxis*
활성 값 축(Y축)을 ` axis`로 설정합니다. ` addAxis()`를 암시적으로 호출하여 ` axis `의 소유권을 이 그래프로 이전합니다.
axis 가 null인 경우, 레이블이 없고 범위가 자동으로 조정되는 임시 기본 축이 생성됩니다. 이 임시 축은 다른 축이 명시적으로 동일한 방향으로 설정되면 소멸됩니다.
액세스 함수:
| QValue3DAxis * | valueAxis() const |
| void | setValueAxis(QValue3DAxis *axis) |
알림 신호:
| void | valueAxisChanged(QValue3DAxis *axis) |
addAxis() 및 releaseAxis()도 참조하십시오 .
멤버 함수 문서
[explicit] Q3DBarsWidgetItem::Q3DBarsWidgetItem(QObject *parent = nullptr)
선택 사항인 parent 를 사용하여 새로운 3D 막대 그래프를 생성합니다.
[override virtual noexcept] Q3DBarsWidgetItem::~Q3DBarsWidgetItem()
3D 막대 그래프를 삭제합니다.
void Q3DBarsWidgetItem::addAxis(QAbstract3DAxis *axis)
그래프에 ` axis `를 추가합니다. `addAxis`를 통해 추가된 축은 아직 사용되지 않으며, `addAxis`는 단순히 ` axis `의 소유권을 그래프에 부여하기 위해 사용됩니다. ` axis `는 null이거나 다른 그래프에 추가되어서는 안 됩니다.
releaseAxis(), setValueAxis(), setRowAxis(), setColumnAxis()도 참조하십시오 .
void Q3DBarsWidgetItem::addSeries(QBar3DSeries *series)
series 를 그래프에 추가합니다. 그래프에는 여러 개의 시계가 포함될 수 있지만 축은 하나만 가질 수 있으므로, 시각화된 데이터가 의미를 가지려면 모든 시계의 행과 열이 일치해야 합니다. 그래프에 표시된 시계가 여러 개 있는 경우, 축에 대한 레이블이 명시적으로 설정되지 않은 상태에서는 기본 시계만 축에 행 또는 열 레이블을 생성합니다. 새로 추가된 시계에 선택된 막대가 지정된 경우, 해당 막대가 강조 표시되고 기존 선택 사항은 모두 해제됩니다. 추가된 시계 중 하나만 활성 선택 상태를 가질 수 있습니다.
seriesList(), primarySeries 및 Q3DGraphsWidgetItem::hasSeries()도 참조하십시오 .
QList<QAbstract3DAxis *> Q3DBarsWidgetItem::axes() const
추가된 모든 축의 목록을 반환합니다.
addAxis()도 참조하십시오 .
void Q3DBarsWidgetItem::insertSeries(int index, QBar3DSeries *series)
series 를 시리즈 목록의 index 위치에 삽입합니다. series 가 이미 목록에 추가된 경우, 해당 항목은 새로운 index 로 이동됩니다.
참고: 시리즈를 기존 인덱스보다 뒤쪽의 새로운 index 로 이동할경우 , 목록 내의 새로운 위치는 시리즈가 여전히 기존 인덱스에 있는 것처럼 계산되므로, 최종 인덱스는 실제로 index 에서 1을 뺀 값이 됩니다.
addSeries(), seriesList(), Q3DGraphsWidgetItem::hasSeries()도 참조하십시오 .
void Q3DBarsWidgetItem::releaseAxis(QAbstract3DAxis *axis)
axis 가 이 그래프에 추가된 경우, 해당 축의 소유권을 호출자에게 반환합니다. 반환된 axis 가 사용 중인 경우, 새로운 기본 축이 생성되어 활성 상태로 설정됩니다.
기본 축이 해제되었다가 나중에 다시 추가되면, 다른 축과 동일하게 동작합니다.
addAxis(), setValueAxis(), setRowAxis(), setColumnAxis()도 참조하십시오 .
void Q3DBarsWidgetItem::removeSeries(QBar3DSeries *series)
그래프에서 ‘ series ’를 제거합니다.
Q3DGraphsWidgetItem::hasSeries()도 참조하십시오 .
[since 6.10] void Q3DBarsWidgetItem::renderSliceToImage(int requestedIndex, QtGraphs3D::SliceCaptureType sliceType)
요청된 슬라이스 뷰를 이미지로 내보냅니다. 내보내진 슬라이스는 sliceType 로 정의된 행 또는 열의 막대 형태로, 지정된 requestedIndex 에서 생성됩니다.
sliceImageChanged 신호는 이미지가 준비되면 발생하며, 다음과 같이 수신할 수 있습니다:
connect(item, &Q3DBarsWidgetItem::sliceImageChanged, this, [](const QImage &image) {
// ~~~
});
item->renderSliceToImage(sliceType, index);이미지는 현재 앤티앨리어싱 설정으로 렌더링됩니다.
이 함수는 Qt 6.10에서 도입되었습니다.
QQuickItem::grabToImage() 및 sliceImageChanged()도 참조하십시오 .
QList<QBar3DSeries *> Q3DBarsWidgetItem::seriesList() const
이 그래프에 추가된 시리즈 목록을 반환합니다.
Q3DGraphsWidgetItem::hasSeries()도 참조하십시오 .
[signal, since 6.10] void Q3DBarsWidgetItem::sliceImageChanged(const QImage &image)
renderSliceToImage 가 image 를 준비했을 때 발생합니다.
이 함수는 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.