Dial QML Type

通过旋转圆形拨盘来设置数值。更多...

• 所有成员的列表，包括继承的成员

属性

• angle : real
• endAngle : real (since 6.6)
• from : real
• handle : Item
• inputMode : enumeration (since QtQuick.Controls 2.5 (Qt 5.12))
• live : bool (since QtQuick.Controls 2.2 (Qt 5.9))
• position : real
• pressed : bool
• snapMode : enumeration
• startAngle : real (since 6.6)
• stepSize : real
• to : real
• value : real
• wrap : bool

信号

• moved() (since QtQuick.Controls 2.2 (Qt 5.9))
• wrapped(Dial.WrapDirection direction) (since 6.6)

方法

• void decrease()
• void increase()

详细说明

“旋钮”控件类似于立体声设备或工业设备上常见的传统旋钮，允许用户在指定范围内设置数值。

旋钮的数值通过value 属性设置。范围则通过from 和to 属性设置。要启用或禁用循环，请使用wrap 属性。

可通过键盘操作旋钮。它支持以下操作：

旋钮支持三种input modes ：Dial.Circular 、Dial.Horizontal 和Dial.Vertical 。圆形输入模式采用绝对输入系统，此时光标在旋钮中的位置直接反映其数值。水平和垂直输入模式采用相对输入系统，此时光标位置的变化会“加到”旋钮的数值上。

下图说明了各种输入模式跟踪移动的方向：

另请参阅 《自定义旋钮和输入控件》。

属性文档

angle : real [read-only]

该属性存储手柄的顺时针角度（单位：度）。

该角度在12点钟位置时为零，取值范围为startAngle 至endAngle 。

另请参阅 position 、startAngle 以及endAngle 。

endAngle : real [since 6.6]

该属性存储表盘的终点角度（单位为度）。

这是刻度盘最大值对应的angle ，即to 。endAngle必须大于startAngle ，小于720，且小于或等于startAngle + 360度。

该属性在 Qt 6.6 中引入。

另请参阅 startAngle 和angle 。

from : real

该属性保存范围的起始值。默认值为0.0 。

另请参阅 to 和value 。

handle : Item

该属性保存了刻度盘的句柄。

该控件用作拨盘位置的视觉指示器。

另请参阅 “自定义刻度盘”。

inputMode : enumeration [since QtQuick.Controls 2.5 (Qt 5.12)]

该属性用于存储输入模式。

旋钮支持三种输入模式：Dial.Circular 、Dial.Horizontal 和Dial.Vertical 。圆形输入模式采用绝对输入系统，此时光标在旋钮内的位置直接反映其数值。水平和垂直输入模式采用相对输入系统，此时光标位置的变化会“叠加”到旋钮的数值上。

下图说明了各种输入模式跟踪移动的方向：

默认值为Dial.Circular 。

该属性在 QtQuick.Controls 2.5（Qt 5.12）中引入。

live : bool [since QtQuick.Controls 2.2 (Qt 5.9)]

该属性用于指定在拖动控件时，该旋钮是否为value 属性提供实时更新。

默认值为true 。

该属性在 QtQuick.Controls 2.2（Qt 5.9）中引入。

另请参阅 value 。

position : real [read-only]

该属性保存手柄的逻辑位置。

该位置以控件角度范围（即控件手柄可移动的范围）内的一段比例表示，该范围为0.0 - 1.0 。

另请参阅 value 和angle 。

pressed : bool

该属性控制旋钮是否处于按下状态。

当鼠标悬停在旋钮上并被点击，或者按住Qt.Key_Left 等键时，旋钮会被按下。如果您不希望旋钮在按下键盘按键时被按下（例如出于样式考虑），可以使用Keys attached property ：

Dial {
    Keys.onLeftPressed: {}
}

这样一来，只有在点击鼠标时，`pressed` 状态才会设置为 `true `。

snapMode : enumeration

此属性用于设置对齐模式。

对齐模式与“stepSize ”配合使用，使控制柄能够对齐到刻度盘上的特定点。

可能的取值：

另请参阅 stepSize 。

startAngle : real [since 6.6]

该属性存储表盘的起始角度（单位为度）。

这是旋钮的angle （即其最小值），例如from 。startAngle 必须小于endAngle ，大于 -360，且大于或等于endAngle - 360 度。

该属性于 Qt 6.6 中引入。

另请参阅 endAngle 和angle 。

stepSize : real

该属性用于存储步长。

步长决定了通过键盘与旋钮交互时，其值的增减幅度。例如，当步长设置为0.2 时，旋钮的值将以0.2 为增量进行增减。

只有当snapMode 设置为Dial.NoSnap 以外的值时，该步长在触摸和鼠标交互中才会生效。

默认值为0.0 ，这将导致键盘交互时的有效步长为0.1 。

另请参阅 snapMode 、increase() 以及decrease()。

to : real

该属性存储范围的结束值。默认值为1.0 。

另请参阅 from 和value 。

value : real

该属性的取值范围为from -to 。默认值为0.0 。

另请参阅 position 和live 。

wrap : bool

该属性控制在拖动时刻度盘是否会循环显示。

例如，当此属性设置为true 时，将旋钮拖动至to 位置之外，将导致控点定位在from 位置，反之亦然：

当此属性设置为false 时，无法将旋钮拖动到“from”和“to”值之外。

默认值为false 。

信号文档

[since QtQuick.Controls 2.2 (Qt 5.9)] moved()

当用户通过触摸、鼠标或键盘交互式地移动控件时，会发出此信号。

该信号于 QtQuick.Controls 2.2（Qt 5.9）中引入。

[since 6.6] wrapped(Dial.WrapDirection direction)

当刻度盘完成一圈旋转（即从最大值转到最小值，或反之）时，会发出此信号。该信号仅在wrap 的值为true 时触发。direction 参数指定完整旋转的方向，其取值应为以下选项之一：

该信号在 Qt 6.6 中引入。

方法文档

void decrease()

将该值减去stepSize ；如果未定义stepSize ，则减去0.1 。

另请参阅 stepSize 。

void increase()

将该值增加stepSize ；若未定义stepSize ，则增加0.1 。

另请参阅 stepSize 。