このページでは

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(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行と5列を表示するように設定してみましょう:

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

これで、Q3DBarsWidgetItemはレンダリング用のデータを受け入れる準備が整いました。5つの値からなる1行のシリーズを作成します:

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×5に設定しましたが 、追加するのは1行分のデータのみです。これは問題ありません。残りの行は空白になります。

最後に、これを表示するように設定する必要があります:

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

そして、この数行のコードによって次のような結果が得られます:

高さの異なる緑色の棒からなる3D棒グラフ

シーンの回転やズームインが可能で、棒グラフを選択してその値を表示することもできますが、この最小限のコード例にはそれ以外のインタラクションは含まれていません。詳細については、「Simple Bar Graph」などの提供されているサンプルを参照して理解を深めてください。

関連項目: Q3DScatterWidgetItem 、Q3DSurfaceWidgetItem 、およびQt Graphs C++ Classes for 3D。

プロパティのドキュメント

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 はバーの間にバー1本分の厚さ分のスペースが空くことを意味します。初期値はtrue です。

アクセス関数:

bool isBarSpacingRelative() const
void setBarSpacingRelative(bool relative)

通知シグナル:

void barSpacingRelativeChanged(bool relative)

barThickness : float

このプロパティは、X方向とZ方向の寸法間のバーの厚さ比を指定します。

値「1.0 」は、バーの幅と深さが同じであることを意味し、一方「0.5 」は、バーの深さが幅の2倍になることを意味します。デフォルトでは「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 をグラフに追加します。グラフには複数の系列を含めることができますが、軸は1組のみであるため、可視化されたデータに意味を持たせるには、すべての系列の行と列が一致している必要があります。 グラフに複数の可視シリーズが存在する場合、軸のラベルが明示的に設定されていないときは、プライマリシリーズのみが軸上の行ラベルまたは列ラベルを生成します。新しく追加されたシリーズで選択バーが指定されている場合、そのシリーズが強調表示され、既存の選択は解除されます。アクティブな選択状態にあるのは、追加されたシリーズのうち1つだけです。

関連項目: 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.