Back to Qt.io
Contact Us Blog Download Qt

Bars3D QML Type

3D棒グラフ。詳細...

Import Statement: import QtGraphs
Inherits:

GraphsItem3D

プロパティ

信号

方法

詳細説明

この型は、Qt Quick を用いて棒グラフを 3D で描画することを可能にします。

この型を使用するにはQt Graphs モジュールをインポートする必要があります：

import QtGraphs

その後、qmlファイルでBars3Dを使用することができます：

import QtQuick
import QtGraphs

Item {
    width: 640
    height: 480

    Bars3D {
        width: parent.width
        height: parent.height

        Bar3DSeries {
            itemLabelFormat: "@colLabel, @rowLabel: @valueLabel"

            ItemModelBarDataProxy {
                itemModel: dataModel
                // Mapping model roles to bar series rows, columns, and values.
                rowRole: "year"
                columnRole: "city"
                valueRole: "expenses"
            }
        }
    }

    ListModel {
        id: dataModel
        ListElement{ year: "2022"; city: "Oulu";     expenses: "4200"; }
        ListElement{ year: "2022"; city: "Rauma";    expenses: "2100"; }
        ListElement{ year: "2022"; city: "Helsinki"; expenses: "7040"; }
        ListElement{ year: "2022"; city: "Tampere";  expenses: "4330"; }
        ListElement{ year: "2023"; city: "Oulu";     expenses: "3960"; }
        ListElement{ year: "2023"; city: "Rauma";    expenses: "1990"; }
        ListElement{ year: "2023"; city: "Helsinki"; expenses: "7230"; }
        ListElement{ year: "2023"; city: "Tampere";  expenses: "4650"; }
    }
}

より詳細な使用例については、シンプルな棒グラフを参照してください。

Bar3DSeries,ItemModelBarDataProxy,Scatter3D,Surface3D,Qt Graphs C++ Classes for 3Dも参照してください 。

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

ambientLightStrength : real

グラフ全体の環境光の強さ。この値によって、光の位置に関係なく、グラフ全体の色がどれだけ均等に明るく表示されるかが決まります。値は0.0 から1.0 の間でなければなりません。


aspectRatio : real

水平面上の最長軸と Y 軸の間のグラフのスケー リ ング比。デフォルトは2.0 です。

注: Bars3D には影響しません。

horizontalAspectRatioも参照してください 。


barSeriesMargin : size

XおよびZ寸法における系列列間のマージン。デフォルトでは(0.0, 0.0) に設定されている。適切な値は [0,1] の範囲。


barSpacing : size

X および Z 次元におけるバーの間隔。

デフォルトでは(1.0, 1.0) に設定されている。間隔はbarSpacingRelative プロパティの影響を受けます。


barSpacingRelative : bool

スペーシングが絶対的か、バーの太さに対する相対的か。

true の場合、0.0 の値はバーが横並びに配置されることを意味し、1.0 はバー間にバーの太さと同じ幅のスペースが空けられることを意味します。プリセットはtrue 。


barThickness : real

X寸法とZ寸法のバーの太さの比率。値1.0 は、バーの幅が奥行きと同じであることを意味し、0.5 は、バーの奥行きが幅の2倍になることを意味します。


cameraPreset : Graphs3D.CameraPreset

現在アクティブなカメラのプリセット。Graphs3D.CameraPreset のいずれかです。プリセットがアクティブでない場合、値はGraphs3D.CameraPreset.NoPreset です。


cameraTargetPosition : vector3d

vector3d としてのカメラターゲット。デフォルトはvector3d(0.0, 0.0, 0.0) 。

有効な座標値は-1.0...1.0 の間です。 こ こ で端の値は、 対応する軸範囲の端を示 し ます。こ の範囲外の値は、 その端に ク ラ ンプ さ れます。


cameraXRotation : float

現在のベース位置を起点 と し た、 タ ーゲ ッ ト ポ イ ン ト 回 り のカ メ ラ の X 回転角度を度単位で表 し た もの。


cameraYRotation : float

ターゲットポイント周りのカメラの Y 回転角度。


cameraZoomLevel : float

カメラのズームレベル。デフォルト値の100.0 は、カメラにズームインまたはズームアウトが設定されていないことを意味します。この値はminCameraZoomLevel およびmaxCameraZoomLevel プロパティによって制限されます。

minCameraZoomLevel およびmaxCameraZoomLevelも参照してください 。


columnAxis : Category3DAxis

アクティブな列軸。

軸が指定されない場合、ラベルのない一時的なデフォルト軸が作成されます。この一時的な軸は、別の軸が明示的に同じ方向に設定されると破棄される。


currentFps : int

FPS 測定が有効なときは、最後の 1 秒の結果がこの読み取り専用プロパティに格納される。測定が有効になってからこの値が更新されるまでに、少なくとも1秒かかります。

measureFpsも参照 。


customItemList : list<Custom3DItem>

グラフに追加されたCustom3DItem アイテムのリスト。グラフは追加された項目の所有権を持つ。


floorLevel : real

Y軸データ座標での棒グラフのフロアレベル。

実際のフロアレベルは、Y 軸の最小値と最大値によって制限されます。デフォルトはゼロ。


gridLineType : Graphs3D.GridLineType

グリッド線のタイプをGraphs3D.GridLineType.Shader またはGraphs3D.GridLineType.Geometry のいずれにするかを定義します。

この値はすべてのグリッド線に影響します。

Graphs3D.GridLineTypeも参照してください 。


horizontalAspectRatio : real

X 軸と Z 軸間のグラフのスケー リ ング比。値0.0 は、 軸範囲に従っ た自動ス ケー リ ン グ を示す。デフォルトは0.0 。

注 ： barThickness とbarSpacing プ ロパテ ィ を通 じ て水平面上の拡縮を扱 うBars3D には影響 し ません。極座標グラフもこのプロパティを無視します。

aspectRatio,polar,Bars3D::barThickness, およびBars3D::barSpacingも参照してください 。


labelMargin : real

このプロパティは、軸ラベルの配置のマージンを指定します。

負の値はラベルをプロット領域内に配置し、正の値はラベルをプロット領域外に配置する。値が負の場合、ラベルの自動回転は無効になる。デフォルトは0.1

QAbstract3DAxis::labelAutoAngleも参照 。


lightColor : color

Scene3D で定義されている環境光と鏡面光の色。


lightStrength : real

グラフ全体の鏡面光強度。この値は0.0 と10.0 の間でなければなりません。

こ の値は、Scene3D で指定 し た光に影響を与え ます。


locale : locale

各種数値ラベルの書式設定に用いるロケールを設定します。デ フ ォ ル ト は"C" ロ ケールです。

Value3DAxis::labelFormatも参照。


margin : real

margin（余白） グラフの余白を、プロット可能なグラフ領域の端とグラフの背景の端との間に残されたスペースに用いる絶対値。

marginの値が負の場合、余白は自動的に決定され、シリーズ内のアイテムのサイズやグラフの種類によって変化する。グラフのアスペクト比がデフォルト値から変更されていない場合、値はY軸範囲の分数として解釈される。デフォルトは-1.0 。

注： 散布図グラフの余白を自動的に決定される余白より小さく設定すると、グラフの端の散布項目がグラフの背景と重なることがあります。

注 ：散布図およびサーフェス グラフでは、軸ラベルのサイズに比べてマージンが小さい場合、軸のエッジ ラベルの位置は、隣接する軸のエッジ ラベルと重ならないように調整されます。


maxCameraZoomLevel : float

カメラのズーム・レベルの最大許容値を設定します。新しい最大レベルが既存の最小レベルより低い場合は、最小レベルも新しい最大レベルに調整されます。現在のcameraZoomLevel が新しい境界の外側にある場合は、それも調整されます。デフォルトは500.0f です。

cameraZoomLevel およびminCameraZoomLevelも参照 。


measureFps : bool

true の場合、レンダリングはオンデマンドではなく連続的に行われ、currentFps プロパティの値が更新されます。デフォルトはfalse です。

currentFpsも参照して ください。


minCameraZoomLevel : float

最小許容カ メ ラ ズーム レベルを設定 し ます。新しい最小レベルが既存の最大レベルより高い場合、最大レベルも新しい最小レベルに調整されます。現在のcameraZoomLevel が新しい範囲外の場合は、それも調整されます。minCameraZoomLevel を1.0 以下に設定することはできません。デフォルトは10.0 。

cameraZoomLevel およびmaxCameraZoomLevelも参照 。


msaaSamples : int

renderingMode がIndirect の場合、 マルチサンプルアンチエイリアシングで使用されるサンプル数。renderingMode がDirectToBackground の場合、 こ のプ ロ パテ ィ 値は読み取 り 専用で、 ウ ィ ン ド ウ 表面形式で指定 さ れたサンプル数を返 し ます。デフォルトは4 です。

renderingModeも参照。


multiSeriesUniform : bool

複数の系列が表示されている場合でも、単一の系列バーに対して比率を設定してバーをスケーリングするかどうかを定義する。true に設定すると、bar spacing は X 軸にのみ正しく適用されます。デフォルトではfalse に設定されている。


optimizationHint : Graphs3D.OptimizationHint

レンダリングの最適化にデフォルトモードとレガシーモードのどちらを使用するかを指定します。

デフォルトモードはインスタンス化されたレンダリングを使用し、ほとんどのシステムで最高のパフォーマンスレベルで全機能セットを提供します。静的モードはグラフ描画を最適化し、変化のない大規模なデータセットに最適です。動的なデータの変化やアイテムの回転があると遅くなります。選択は最適化されないため、大規模なデータセットで静的モードを使用することはお勧めできません。レガシーモードは、インスタンス化せずに、グラフ内のすべての項目を個別にレンダリングします。これは、デフォルト・モードが機能しない場合にのみ使用されるべきで、ターゲット・システムがインスタンス化をサポートしていない場合と同じです。デフォルトはDefault 。

注意： 環境によっては、静的最適化を使用した大きなグラフが描画されないことがあります。これは、すべてのアイテムが1回の描画呼び出しで描画されるためで、グラフィックドライバによって、呼び出しごとにサポートされる最大頂点数が異なるからです。これは主に32ビットおよびOpenGL ES2プラットフォームでの問題です。この問題を回避するには、頂点数の少ないアイテムメッシュを選択するか、ポイントメッシュを使用します。

Abstract3DSeries::mesh およびGraphs3D.OptimizationHintも参照して ください。


orthoProjection : bool

true の場合、グラフの表示に正射投影が使用されます。デフォルトはfalse です。

注意： true に設定すると、影は無効になります。


polar : bool

true に設定すると、水平軸が極軸に変更されます。x 軸は角度軸になり、z 軸は半径軸になります。棒グラフでは極軸モードは利用できない。

デフォルトはfalse 。

orthoProjection およびradialLabelOffsetも参照 。


primarySeries : Bar3DSeries

グラフの主系列。ラベルが軸に明示的に設定されていない場合に、行軸と列軸のラベルを決定するために使用される。

指定された系列がまだグラフに追加されていない場合、それを主系列として設定すると、暗黙的にグラフにも追加される。

主系列自体がグラフから削除されると、このプロパティはデフォルトにリセットされる。

系列がNULLの場合、このプロパティはデフォルトにリセットされる。デフォルトは、最初に追加された系列か、グラフに系列が追加されていない場合はゼロである。


queriedGraphPosition : vector3d [read-only]

この読み取り専用プロパティには、Scene3D::graphPositionQuery を使用してクエリされた各軸に沿った最新のグラフ位置値が含まれます。値は[-1, 1] の範囲に正規化されます。クエリされた位置がグラフ境界の外側であった場合、値は実際の位置を反映せず、代わりに範囲外の未定義の位置[-1, 1] になります。この値は、問い合わせが行われるまで未定義となる。

特定の画面位置に一致する唯一の正しい3D座標は存在しないため、一貫性を保つために、クエリは常にグラフを囲む不可視のボックスの内側に対して行われます。

注： 棒グラフでは、グラフのフロアレベルでしかグラフの位置を問い合わせることができないため、棒グラフではy値は常に0であり、有効な問い合わせはグラフのフロアを含む画面位置でのみ行うことができます。

Scene3D::graphPositionQueryも参照のこと 。


radialLabelOffset : real

このプロパティは、半径極軸の軸ラベルの正規化された水平オフセットを指定します。値0.0 は、ラベルが0角度の角度軸グリッド線の隣に描画されるべきであることを示します。値1.0 は、ラベルがグラフ背景の端の通常の場所に描画されることを示す。このプロパティは、polar プロパティ値がfalse の場合は無視されます。デフォルトは1.0 。

polarも参照してください 。


renderingMode : Graphs3D.RenderingMode

グラフの描画方法。デフォルトはIndirect 。

注: グラフのantialiasing プロパティを設定しても何も起こりません。ただし、現在のレンダリングモードがアンチエイリアスを使用している場合は、グラフ自体によって設定されます。

msaaSamples およびGraphs3D.RenderingModeも参照のこと 。


rotationEnabled : bool

こ の入力ハン ド ラ がグ ラ フ回転を許すかど う か。

デフォルトはtrue です。


rowAxis : Category3DAxis

アクティブな行軸。

軸が与えられない場合、ラベルのない一時的なデフォルト軸が作成されます。こ の一時軸は、 別の軸が明示的に同 じ 向きに設定 さ れる と 破棄 さ れます。


scene : Scene3D [read-only]

シーンの操作とシーン要素へのアクセスに使用できるScene3D ポインタ。

このプロパティは読み取り専用です。


selectedElement : Graphs3D.ElementType [read-only]

グラフ内で選択されている要素。

このプロパティは、選択された要素のタイプを問い合わせるために使用することができる。このタイプは、グラフ内で新しい選択が行われ、selectedElementChanged シグナルが発せられるまで有効である。

このシグナルは、例えば、カスタマイズされた入力処理を実装するために使用することができます。

selectedLabelIndex(),selectedAxis(),selectedCustomItemIndex(),selectedCustomItem(),Bars3D::selectedSeries,Scatter3D::selectedSeries,Scene3D::selectionQueryPosition,Graphs3D.ElementTypeも参照のこと 。


selectedSeries : Bar3DSeries [read-only]

null selectionMode に フラグが設定されている場合、このプロパティは選択されたバーを所有する系列を保持する。SelectionMultiSeries


selectionEnabled : bool

この入力ハンドラがグラフからの選択を許可するかどうか。

デフォルトはtrue 。


selectionMode : Graphs3D.SelectionMode

グラフのアクティブな選択モード。Graphs3D.SelectionFlag 列挙値のいずれか。


seriesList : list<Bar3DSeries> [default]

グラフの系列。デフォルトでは、このプロパティには空のリストが含まれます。系列を設定するには、addSeries() 関数を使用するか、グラフの子として定義します。


shadowQuality : Graphs3D.ShadowQuality

影の質。Graphs3D.ShadowQuality enum値の1つ。


shadowStrength : real

グラフ全体の影の強さ。数値が大きいほど影が濃くなる。こ の値は0.0 と100.0 の間でなければな り ません。

こ の値は、Scene3D で指定 し た光に影響を与え ます。


theme : GraphsTheme

グラフのアクティブテーマ。

GraphsThemeも参照してください 。


valueAxis : ValueAxis3D

アクティブ値軸。

軸が与えられない場合、ラベルと自動調整範囲を持たない一時的なデフォルト軸が作成されます。この一時軸は、別の軸が明示的に同じ方向に設定されると破棄されます。


wrapCameraXRotation : bool

X回転の最小および最大限界の動作。デフォルトでは、X 回転は最小値から最大値へ、最大値から最小値へ折り返す。

true に設定すると、カメラの X 回転は最小値から最大値へ、最大値から最小値へと折り返されます。false に設定すると、カメラの X 回転は、最小値と最大値によって決定されるセクタに制限されます。


wrapCameraYRotation : bool

Y 回転での最小および最大制限の動作。デフォルトでは、Y 回転は最小値と最大値の間に制限され、折り返しはありません。

true の場合、 カ メ ラ の Y 回転は最小か ら 最大へ、 最大か ら 最小へ折 り 返 さ れます。false の場合、カメラの Y 回転は、最小値と最大値によって決定されるセクタに制限されます。


zoomAtTargetEnabled : bool

デ フ ォル ト ： 。 グ ラ フ のズーム さ れた点が、 ズーム後同 じ 位置に留ま る よ う に、 ズームでカ メ ラ タ ーゲ ッ ト を変え る かど う か。

デフォルトはtrue 。


zoomEnabled : bool

この入力ハンドラがグラフのズームを許すかどうか。

デフォルトはtrue 。


シグナル ドキュメント

barSeriesMarginChanged(size margin)

このシグナルは、barSeriesMargin がmargin に変わったときに発せられる。

注意: 対応するハンドラはonBarSeriesMarginChanged です。


barSpacingChanged(size spacing)

このシグナルは、barSpacing がspacing に変更されたときに発せられます。

注 : 対応するハンドラはonBarSpacingChanged です。


barSpacingRelativeChanged(bool relative)

このシグナルはbarSpacingRelative がrelative に変更されたときに発せられる。

注： 対応するハンドラはonBarSpacingRelativeChanged です。


barThicknessChanged(real thicknessRatio)

このシグナルはbarThickness がthicknessRatio に変更されたときに発せられる。

注： 対応するハンドラはonBarThicknessChanged です。


columnAxisChanged(Category3DAxis axis)

このシグナルはcolumnAxis がaxis に変更されたときに発せられる。

注： 対応するハンドラはonColumnAxisChanged です。


doubleTapped(QEventPoint eventPoint, Qt::MouseButton button)

このシグナルは、グラフ項目が短い時間内に2回タップされたときに発せられる。eventPoint シグナル・パラメータには、タップされたポイントに関するリリース・イベントの情報が含まれ、button はクリックされたmouse button であり、タッチスクリーンではNoButton です。

注： 対応するハンドラはonDoubleTapped です。

QEventPoint 、Qt::MouseButtons 、TapHandler::doubleTappedも参照してください 。


dragged(QVector2D delta)

このシグナルは、ピンチ・ジェスチャーの実行中にグラフ上の点群の移動が変更されたときに発行されます。delta ベクトルは並進の変化を示します。

注： 対応するハンドラはonDragged です。

PinchHandler::translationChangedも参照してください 。


floorLevelChanged(real level)

このシグナルは、floorLevel がlevel に変更されたときに発せられます。

注： 対応するハンドラはonFloorLevelChanged です。


longPressed()

このシグナルは、parent アイテムが押され、TapHandler::longPressThreshold を超える時間保持されたときに発せられる。

注 ：対応するハンドラはonLongPressed です。

TapHandler::longPressedも参照 。


mouseMove(QPoint mousePos)

このシグナルは、グラフが mouseMove イベントを受信したときに発行されます。mousePos 値は、マウスが移動している間のマウスの位置を示します。

注： 対応するハンドラはonMouseMove です。

QQuickItem::mouseMoveEventも参照して ください。


multiSeriesUniformChanged(bool uniform)

このシグナルは、multiSeriesUniform がuniform に変わったときに発せられる。

注： 対応するハンドラはonMultiSeriesUniformChanged です。


pinch(qreal delta)

このシグナルは、ピンチジェスチャーの実行中にグラフのスケールファクターが変更されたときに発行されます。delta の値は、スケールの乗法的な変化を示します。

注: 対応するハンドラはonPinch です。

PinchHandler::scaleChangedも参照してください 。


primarySeriesChanged(Bar3DSeries series)

このシグナルは、primarySeries がseries に変更されたときに発行されます。

注： 対応するハンドラはonPrimarySeriesChanged 。


rowAxisChanged(Category3DAxis axis)

このシグナルは、rowAxis がaxis に変わったときに発せられる。

注 : 対応するハンドラはonRowAxisChanged です。


selectedSeriesChanged(Bar3DSeries series)

このシグナルはselectedSeries がseries に変更されたときに発せられる。

注： 対応するハンドラはonSelectedSeriesChanged です。


tapped(QEventPoint eventPoint, Qt::MouseButton button)

このシグナルは、グラフ・アイテムが一度タップされたときに発せられる。eventPoint シグナルパラメータには、タップされたポイントに関するリリースイベントの情報が含まれ、button はクリックされたmouse button 、タッチスクリーンの場合はNoButton です。

注： 対応するハンドラはonTapped です。

QEventPoint 、Qt::MouseButtons 、TapHandler::singleTappedも参照 。


valueAxisChanged(ValueAxis3D axis)

このシグナルは、valueAxis がaxis に変わったときに発せられる。

注： 対応するハンドラはonValueAxisChanged 。


wheel(QQuickWheelEvent *event)

このシグナルは、グラフがQWheelEvent 型のevent を受け取るたびに発行されます : つまり、ホイールが動かされたり、スクロールジェスチャが更新されたりするたびに発行されます。

注： 対応するハンドラはonWheel です。

WheelEvent およびWheelHandler::wheelも参照して ください。


メソッド・ドキュメント

qsizetype addCustomItem(Custom3DItem item)

Custom3DItem item をグラフに追加します。グラフは追加されたアイテムの所有権を持ちます。

add が成功した場合は追加されたアイテムのインデックスを返し、null アイテムを追加しようとした場合は -1、既に追加されたアイテムを追加しようとした場合はそのアイテムのインデックスを返します。

removeCustomItems(),removeCustomItem(),removeCustomItemAt()も参照 。


void addSeries(Bar3DSeries series)

グラフにseries を追加する。グラフは複数の系列を含むことができるが、軸は1セットのみであるため、可視化されたデータが意味を持つためには、すべての系列の行と列が一致していなければならない。グラフに複数の可視系列がある場合、軸にラベルが明示的に設定されていない場合は、最初に追加された系列だけが軸の行ラベルまたは列ラベルを生成する。新しく追加された系列が選択されたバーを指定している場合は、そのバーが強調表示され、既存の選択はクリアされます。アクティブな選択を持つことができるのは、追加された 1 つの系列だけです。

GraphsItem3D::hasSeries()も参照 。


void clearSelection()

追加されたすべての系列から選択をクリアします。


bool hasSeries(Abstract3DSeries series)

series がすでにグラフに追加されているかどうかを返します。


void insertSeries(int index, Bar3DSeries series)

series を系列リストのindex の位置に挿入します。series がすでにリストに追加されている場合は、新しいindex に移動する。

index 注： 古いインデックスの後にある新しいindex に系列を移動させる場合、リスト内の新しい位置は、系列がまだ古いインデックスにあるものとして計算される。

GraphsItem3D::hasSeries()も参照のこと 。


void releaseCustomItem(Custom3DItem item)

item の所有権を取り戻し、グラフからitem を削除する。

注意： 同じアイテムがグラフに追加された場合、テクスチャファイルを再設定する必要があります。

Custom3DItem::textureFileも参照してください 。


void removeCustomItem(Custom3DItem item)

カスタムitem を削除します。それに割り当てられているリソースを削除します。


void removeCustomItemAt(vector3d position)

position のカスタム アイテムをすべて削除します。それらに割り当てられているリソースを削除します。


void removeCustomItems()

すべてのカスタム項目を削除します。それらに割り当てられているリソースを削除します。


void removeSeries(Bar3DSeries series)

グラフからseries を削除する。

GraphsItem3D::hasSeries()も参照してください 。


Abstract3DAxis selectedAxis()

任意のラベル・タイプでselectedElementChanged シグナルを受信した後、選択された軸を取得するために使用できる。選択は、次のselectedElementChanged シグナルまで有効です。

選択された軸、または NULL を返します。

selectedElementも参照してください 。


Custom3DItem selectedCustomItem()

ElementType.CustomItem タイプでselectedElementChanged シグナルを受信した後、選択されたカスタム項目を取得するために使用できます。項目の所有権はグラフに残ります。選択は、次のselectedElementChanged シグナルまで有効です。

選択されたカスタム項目、または null を返します。

selectedElementも参照してください 。


qsizetype selectedCustomItemIndex()

ElementType.CustomItem 型のselectedElementChanged シグナルを受信した後、選択されたカスタム項目のインデックスを照会するために使用できます。選択は次のselectedElementChanged シグナルまで有効である。

選択されたカスタム項目のインデックス、または -1 を返します。

selectedElementも参照 。


int selectedLabelIndex()

任意のラベル・タイプでselectedElementChanged シグナルを受信した後、選択されたラベルのインデックスを問い合わせるために使用できる。選択は次のselectedElementChanged シグナルが来るまで有効である。

選択されたラベルのインデックスか -1 を返します。

selectedElement も参照 。


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