Q3DGraphsWidgetItem Class

属性文档

activeTheme : QGraphsTheme*

该属性存储图的当前主题。

将 `activeTheme ` 设置为图所使用的活动主题。该操作会隐式调用 `addTheme()` 方法，将主题的所有权转移至该图。

如果activeTheme 为 null，则会创建一个临时的默认主题。如果后续显式设置了任何主题，该临时主题将被销毁。即使在设置主题之后，仍可修改其属性，且修改会立即生效。

访问函数：

通知器信号：

ambientLightStrength : float

该属性控制整个图表的环境光强度。

该值决定了图表中颜色的显示效果——无论光源位置如何，颜色都能均匀且明亮地呈现。

该值必须介于0.0f 和1.0f 之间。

访问函数：

通知信号：

aspectRatio : qreal

该属性保存了图形缩放中水平平面上最长轴与y轴之间的比例。

默认值为2.0 。

访问函数：

通知信号：

另请参阅 horizontalAspectRatio 。

cameraPreset : QtGraphs3D::CameraPreset

摄像机当前使用的预设位置。该值可设置为 CameraPreset 枚举中的任意一个值。此属性可用于设置观察图形的预定义摄像机角度。

默认情况下，摄像机预设设置为CameraPreset::FrontLow 。

访问函数：

通知器信号：

cameraTargetPosition : QVector3D

该属性以向量或顶点的形式存储摄像机目标位置在3D空间中的坐标。

默认值为QVector3D(0.0, 0.0, 0.0) 。

有效的坐标值范围为-1.0...1.0 ，其中边界值表示相应轴范围的边界。超出此范围的任何值都会被限制在边界上。

访问函数：

通知信号：

cameraXRotation : float

该属性存储了相机围绕目标点进行的X轴旋转角度（单位：度）。

访问函数：

通知信号：

cameraYRotation : float

该属性存储了相机围绕目标点进行的 Y 轴旋转角度（单位为度）。

访问函数：

通知信号：

cameraZoomLevel : float

该属性以百分比形式存储摄像机的变焦级别。

100.0f 的默认值表示相机中未设置任何缩放。该值受minCameraZoomLevel 和maxCameraZoomLevel 属性的限制。

访问函数：

通知信号：

另请参阅 minCameraZoomLevel 和maxCameraZoomLevel 。

[read-only] currentFps : int

该属性保存了过去一秒内的渲染结果。

当启用帧率（FPS）测量时，结果会存储在此只读属性中。在测量激活后，该值至少需要一秒钟才会更新。

访问函数：

通知信号：

另请参阅 measureFps 。

[since 6.11] cutoffMargin : qreal

该属性存储用于确定轴限值之间间距以及图形元素被剔除的位置的数值。

该枚举在 Qt 6.11 中引入。

访问函数：

通知器信号：

[since 6.12] dragMode : QtGraphs3D::DragMode

确定如何解释图形上的拖动事件，取值为QtGraphs3D::DragMode 枚举中的一个值。

默认值为QtGraphs3D::DragMode::Rotate 。

该枚举在 Qt 6.12 中引入。

访问函数：

通知器信号：

另请参阅 panEnabled 。

gridLineType : QtGraphs3D::GridLineType

无论网格线类型是QtGraphs3D::GridLineType::Shader 还是QtGraphs3D::GridLineType::Geometry ，此属性均有效。

此值将影响所有网格线。

访问函数：

通知信号：

另请参阅 QtGraphs3D::GridLineType 。

horizontalAspectRatio : qreal

该属性存储了图形中 x 轴与 z 轴之间的缩放比例。

0.0 的值表示根据坐标轴范围自动缩放。默认值为0.0 。

此属性对Q3DBarsWidgetItem 无影响，后者通过barThickness 和barSpacing 属性处理水平面的缩放。极坐标图也会忽略此属性。

访问函数：

通知信号：

另请参阅 aspectRatio 、polar 、Q3DBarsWidgetItem::barThickness 和Q3DBarsWidgetItem::barSpacing 。

labelMargin : float

此属性用于指定坐标轴标签的放置边距。

负值将标签放置在绘图区域内，而正值将标签放置在绘图区域外。当该值为负时，标签的自动旋转功能将被禁用。默认值为0.1

访问函数：

通知信号：

另请参阅 QAbstract3DAxis::labelAutoAngle 。

lightColor : QColor

该属性用于存储环境光和镜面光の色。

该值会影响在Q3DScene 中指定的光照。

访问函数：

通知信号：

lightStrength : float

该属性存储整个图的镜面光强度。

该值必须在0.0f 和10.0f 之间。

该值会影响Q3DScene 中指定的光。

访问函数：

通知信号：

locale : QLocale

此属性用于存储格式化各种数字标签时所使用的区域设置。

默认值为"C" 区域设置。

访问函数：

通知信号：

另请参阅 QValue3DAxis::labelFormat 。

margin : qreal

该属性指定可绘制图形区域边缘与图形背景边缘之间留白的绝对值。

如果边距值为负数，则边距将自动确定，并可能根据数据系列中各数据点的大小以及图表类型而有所不同。如果图表的纵横比未从默认值进行更改，则该值将被解释为 y 轴范围的百分比。默认值为-1.0 。

访问函数：

通知信号：

maxCameraXRotation : float

该属性存储了摄像机围绕目标点进行的X轴旋转的最大角度（单位为度）。默认值为180.0

访问函数：

通知信号：

maxCameraYRotation : float

该属性保存了摄像机围绕目标点进行的 Y 轴旋转的最大角度（单位为度）。默认值为90.0

访问函数：

通知信号：

maxCameraZoomLevel : float

该属性存储相机允许的最大变焦级别。

如果将最大级别设置为一个低于现有最小级别的新的值，则最小级别也会相应调整为新的最大级别。如果当前的cameraZoomLevel 超出了新的范围，它也会被相应调整。默认值为500.0f 。

访问函数：

通知器信号：

另请参阅 cameraZoomLevel 和minCameraZoomLevel 。

measureFps : bool

该属性控制渲染是连续进行的，还是按需进行的。

如果true ，则渲染为连续模式，且currentFps 属性的值会随之更新。默认值为false 。

访问函数：

通知器信号：

另请参阅 currentFps 。

minCameraXRotation : float

该属性存储摄像机绕目标点旋转的最小X轴旋转角度（单位为度）。默认值为-180.0

访问函数：

通知信号：

minCameraYRotation : float

该属性存储了相机围绕目标点进行的 Y 轴旋转的最小角度（单位为度）。默认值为0.0

访问函数：

通知信号：

minCameraZoomLevel : float

该属性用于指定允许的最小相机缩放级别。

如果将最小级别设置为高于现有最大级别的新值，则最大级别也会相应调整为新的最小级别。如果当前的变焦级别超出了新范围，也会进行相应调整。minCameraZoomLevel 不能设置为低于1.0f 。默认值为10.0f 。

访问函数：

通知信号：

另请参阅 cameraZoomLevel 和maxCameraZoomLevel 。

msaaSamples : int

该属性存储MSAA中使用的采样数。

将使用的 MSAA 采样数设置为samples 。采样数可以是 0、2、4 或 8。

访问函数：

通知信号：

optimizationHint : QtGraphs3D::OptimizationHint

指定渲染优化时使用默认模式还是传统模式。

默认模式采用实例化渲染，在大多数系统上能以最佳性能提供全功能集。静态模式可优化图的渲染，非常适合大型且数据不变的集合。但在数据动态变化和项目旋转时，其运行速度较慢。由于选择操作未经过优化，因此不建议在海量数据集上使用静态模式。 静态优化仅适用于散点图。传统模式会单独渲染图中的所有项目，不进行实例化。仅当默认模式无法正常工作时（即目标系统不支持实例化）才应使用该模式。默认值为QtGraphs3D::OptimizationHint::Default 。

访问函数：

通知器信号：

另请参阅 QAbstract3DSeries::mesh 。

orthoProjection : bool

该属性用于指定是否使用正射投影来显示图形。

默认值为false 。

访问函数：

通知信号：

另请参阅 QAbstract3DAxis::labelAutoAngle 。

[since 6.12] panEnabled : bool

该属性用于指定此输入处理程序是否允许平移图表。

默认值为true 。

该枚举类型在 Qt 6.12 中引入。

访问函数：

通知器信号：

另请参阅 dragMode 和setPanButton()。

polar : bool

无论水平坐标轴是否转换为极坐标轴，此属性均保持不变。

如果true ，则x轴变为角度轴，z轴变为半径轴。条形图不支持极坐标模式。

默认值为false 。

访问函数：

通知信号：

另请参阅 orthoProjection 和radialLabelOffset 。

[read-only] queriedGraphPosition : QVector3D

该属性存储了沿每个轴查询到的最新图坐标值。

此只读属性包含Q3DScene::graphPositionQuery 的查询结果。这些值已归一化到[-1, 1] 的范围内。如果查询的位置超出图表边界，则这些值不会反映实际位置，而是指示[-1, 1] 范围之外的未定义位置。在进行查询之前，该值将为未定义。

由于没有单一正确的 3D 坐标能与特定的屏幕位置完全对应，因此为了保持一致性，查询始终针对包围图表的不可见框体的内侧进行。

访问函数：

通知信号：

另请参阅 Q3DScene::graphPositionQuery 。

radialLabelOffset : float

该属性存储径向极坐标轴上轴标注的归一化水平偏移量。

值0.0 表示应将标签绘制在 0 角度的极坐标轴网格线旁。值1.0 表示标签应绘制在图表背景边缘的常规位置。默认值为1.0 。

如果polar 属性值为false ，则该属性将被忽略。

访问函数：

通知信号：

另请参阅 polar 。

rotationEnabled : bool

该属性用于指定此输入处理程序是否允许图形旋转。

默认值为true 。

访问函数：

通知器信号：

[read-only] scene : Q3DScene* const

该属性保存了一个Q3DScene 指针，可用于操作场景并访问场景元素。

该属性为只读。

访问函数：

[read-only] selectedElement : QtGraphs3D::ElementType

该属性存储图中选中的元素。

该属性可用于查询所选元素的类型。该类型在图中进行新选择并发出selectedElementChanged 信号之前一直有效。

例如，该信号可用于实现自定义输入处理程序，具体示例请参见“图形库”中“Scatter Graph ”选项卡下的示例。

访问函数：

通知信号：

另请参阅 selectedLabelIndex()、selectedAxis()、selectedCustomItemIndex()、selectedCustomItem()、Q3DBarsWidgetItem::selectedSeries()、Q3DScatterWidgetItem::selectedSeries()、Q3DSurfaceWidgetItem::selectedSeries()，以及Q3DScene::setSelectionQueryPosition()。

selectionEnabled : bool

该属性用于指定此输入处理程序是否允许从图中进行选择。

默认值为true 。

访问函数：

通知器信号：

selectionMode : QtGraphs3D::SelectionFlags

项目选择模式。

`SelectionFlags` 的组合。默认值为 `Item`。不同类型的图支持不同的选择模式。

访问函数：

通知信号：

另请参见 QtGraphs3D::SelectionFlags 。

shadowQuality : QtGraphs3D::ShadowQuality

该属性用于指定阴影的质量。

ShadowQuality 枚举值之一。默认值为Medium 。

访问函数：

通知信号：

另请参阅 QtGraphs3D::ShadowQuality 。

shadowStrength : float

该属性控制整个图形的阴影强度。

数值越大，阴影越深。该值必须介于0.0 和100.0 之间。

该值会影响Q3DScene 中指定的光照效果。

访问函数：

通知信号：

[since 6.9] transparencyTechnique : QtGraphs3D::TransparencyTechnique

指定要使用的透明度处理方式。默认值为Default 。渲染透明曲面图时，请使用Approximate 或Accurate 。对于其他图类型，应使用Default 。

此枚举在 Qt 6.9 中引入。

访问函数：

通知器信号：

另请参阅 QtGraphs3D::TransparencyTechnique 。

wrapCameraXRotation : bool

该属性控制 X 轴旋转的最小值和最大值的行为。

若设置为true ，摄像机的X轴旋转将从最小值循环至最大值，再从最大值循环回最小值。若设置为false ，摄像机的X轴旋转将限定在由最小值和最大值确定的扇区内。默认设置为true 。

访问函数：

通知信号：

wrapCameraYRotation : bool

此属性控制 Y 轴旋转的最小值和最大值限制的行为。

若true ，摄像机的Y轴旋转将从最小值循环至最大值，再从最大值循环至最小值。若false ，摄像机的Y轴旋转将限制在由最小值和最大值确定的扇区内。默认设置为true 。

访问函数：

通知信号：

zoomAtTargetEnabled : bool

该属性用于控制缩放操作是否应更改相机目标，以便在缩放后，图表中被缩放的点仍保持在原位置。

默认值为true 。

访问函数：

通知信号：

zoomEnabled : bool

该属性用于指定此输入处理程序是否允许对图表进行缩放。

默认值为true 。

访问函数：

通知信号：

QQuickWidget quickwidget;
Q3DBarsWidgetItem graph;
graph.setWidget(&quickwidget);