Dial QML Type
Dial circular que se gira para ajustar un valor. Más...
| Import Statement: | import QtQuick.Controls |
| Inherits: |
Propiedades
- 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
Señales
Métodos
Descripción detallada
El control «Dial» es similar a un mando giratorio tradicional que se encuentra en dispositivos como equipos de música o maquinaria industrial. Permite al usuario especificar un valor dentro de un rango.
El valor del dial se establece mediante la propiedad ` value `. El rango se establece mediante las propiedades ` from ` y ` to `. Para activar o desactivar el ajuste automático, utilice la propiedad ` wrap `.
El dial se puede manejar con el teclado. Admite las siguientes acciones:
| Acción | Tecla |
|---|---|
| Disminuir el valor de « value » en stepSize | Qt.Key_Left |
| Disminuir el valor de « value » en stepSize | Qt.Key_Down |
| Establecer « value » en from | Qt.Key_Home |
| Aumentar « value » en stepSize | Qt.Key_Right |
| Aumentar « value » en stepSize | Qt.Key_Up |
| Establecer « value » en to | Qt.Key_End |
El dial admite tres modos de entrada de « input modes »: « Dial.Circular », « Dial.Horizontal » y « Dial.Vertical ». El modo de entrada circular funciona con un sistema de entrada absoluto, en el que la posición del cursor dentro del dial refleja directamente su valor. Los modos de entrada horizontal y vertical utilizan un sistema de entrada relativo, en el que los cambios en la posición del cursor se «suman» al valor del dial.
La siguiente imagen ilustra las direcciones en las que los distintos modos de entrada siguen el movimiento:

Véase también Personalización de los controles dedial y de entrada.
Documentación de propiedades
angle : real [read-only]
Esta propiedad indica el ángulo de la manivela en el sentido de las agujas del reloj, expresado en grados.
El ángulo es cero en la posición de las 12 en punto y el rango va desde startAngle hasta endAngle.
Véanse también position, startAngle y endAngle.
endAngle : real [since 6.6]
Esta propiedad contiene el ángulo final del dial en grados.
Se trata del « angle » que tendrá el dial en su valor máximo, es decir, to. El valor de «endAngle» debe ser mayor que el de « startAngle », menor que 720 y menor o igual que el de « startAngle » más 360 grados.
Esta propiedad se introdujo en Qt 6.6.
Véase también startAngle y angle.
from : real
Esta propiedad contiene el valor inicial del rango. El valor por defecto es 0.0.
handle : Item
Esta propiedad contiene el identificador del dial.
El controlador actúa como indicador visual de la posición del dial.
Véase también «Personalización del dial».
inputMode : enumeration [since QtQuick.Controls 2.5 (Qt 5.12)]
Esta propiedad almacena el modo de entrada.
El dial admite tres modos de entrada: Dial.Circular, Dial.Horizontal y Dial.Vertical. El modo de entrada circular funciona con un sistema de entrada absoluto, en el que la posición del cursor dentro del dial refleja directamente su valor. Los modos de entrada horizontal y vertical utilizan un sistema de entrada relativo, en el que los cambios en la posición del cursor se «suman» al valor del dial.
La siguiente imagen ilustra las direcciones en las que los distintos modos de entrada siguen el movimiento:

El valor por defecto es Dial.Circular.
Esta propiedad se introdujo en QtQuick.Controls 2.5 (Qt 5.12).
live : bool [since QtQuick.Controls 2.2 (Qt 5.9)]
Esta propiedad indica si el dial ofrece actualizaciones en tiempo real para la propiedad value mientras se arrastra el control.
El valor por defecto es true.
Esta propiedad se introdujo en QtQuick.Controls 2.2 (Qt 5.9).
Véase también value.
position : real [read-only]
Esta propiedad indica la posición lógica del mando.
La posición se expresa como una fracción del rango angular del control (el rango dentro del cual se puede mover el controlador) en el intervalo 0.0 - 1.0.
pressed : bool
Esta propiedad indica si se ha pulsado el dial.
El dial se pulsará cuando se haga clic con el ratón sobre él o se mantenga pulsada una tecla como « Qt.Key_Left ». Si prefieres que el dial no se pulse al pulsar teclas (por motivos de estilo, por ejemplo), puedes utilizar la propiedad « Keys attached property »:
Dial {
Keys.onLeftPressed: {}
}De este modo, el estado «pressed» solo se activará al pulsar con el ratón sobre « true ».
snapMode : enumeration
Esta propiedad controla el modo de ajuste.
El modo de ajuste funciona con el « stepSize » para permitir que el controlador se ajuste a determinados puntos a lo largo del dial.
Valores posibles:
| Constante | Descripción |
|---|---|
Dial.NoSnap | El dial no se ajusta (valor predeterminado). |
Dial.SnapAlways | El dial se ajusta mientras se arrastra el controlador. |
Dial.SnapOnRelease | El dial no se ajusta mientras se arrastra, sino solo después de soltar el controlador. |
Véase también stepSize.
startAngle : real [since 6.6]
Esta propiedad almacena el ángulo inicial del dial en grados.
Se trata del e angle o que tendrá el dial como valor mínimo, es decir, from. El valor de startAngle debe ser menor que el endAngle, mayor que -360 y mayor o igual que el endAngle - 360 grados.
Esta propiedad se introdujo en Qt 6.6.
Véase también endAngle y angle.
stepSize : real
Esta propiedad define el tamaño del paso.
El tamaño de paso determina la cantidad en la que aumenta o disminuye el valor del dial cuando se interactúa con él mediante el teclado. Por ejemplo, un tamaño de paso de « 0.2 » hará que el valor del dial aumente y disminuya en incrementos de « 0.2 ».
El tamaño del paso solo se tiene en cuenta para la interacción táctil y con el ratón cuando snapMode está establecido en un valor distinto de Dial.NoSnap.
El valor por defecto es ` 0.0`, lo que da lugar a un tamaño de paso efectivo de ` 0.1 ` para la interacción con el teclado.
Véase también snapMode, increase() y decrease().
to : real
Esta propiedad contiene el valor final del rango. El valor por defecto es 1.0.
value : real
Esta propiedad toma valores comprendidos entre from y to. El valor por defecto es 0.0.
Véase también position y live.
wrap : bool
Esta propiedad determina si el dial se desplaza al arrastrarlo.
Por ejemplo, cuando esta propiedad se establece en « true », al arrastrar el dial más allá de la posición to, el controlador se situará en la posición from, y viceversa:
Cuando esta propiedad está configurada como « false », no es posible arrastrar el dial más allá de los valores «from» y «to».
El valor por defecto es false.
Documentación de Signal
[since QtQuick.Controls 2.2 (Qt 5.9)] moved()
Esta señal se emite cuando el usuario ha movido el control de forma interactiva, ya sea mediante el tacto, el ratón o las teclas.
Nota: El controlador correspondiente es onMoved.
Esta señal se introdujo en QtQuick.Controls 2.2 (Qt 5.9).
[since 6.6] wrapped(Dial.WrapDirection direction)
Esta señal se emite cuando el dial da una vuelta completa, es decir, cuando pasa de su valor máximo al mínimo, o viceversa. Solo se emite cuando ` wrap ` es ` true`. El argumento ` direction ` especifica la dirección de la rotación completa y puede tomar uno de los siguientes valores:
| Constante | Descripción |
|---|---|
Dial.Clockwise | El dial gira en sentido horario. |
Dial.CounterClockwise | El dial gira en sentido antihorario. |
Nota: El controlador correspondiente es onWrapped.
Esta señal se introdujo en Qt 6.6.
Documentación del método
void decrease()
Reduce el valor en « stepSize », o en « 0.1 » si no se ha definido « stepSize ».
Véase también stepSize.
void increase()
Aumenta el valor en stepSize, o en 0.1 si stepSize no está definido.
Véase también stepSize.
© 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.