En esta página

Dial QML Type

Dial circular que se gira para ajustar un valor. Más...

Import Statement: import QtQuick.Controls
Inherits:

Control

Propiedades

Señales

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

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ónTecla
Disminuir el valor de « value » en stepSizeQt.Key_Left
Disminuir el valor de « value » en stepSizeQt.Key_Down
Establecer « value » en fromQt.Key_Home
Aumentar « value » en stepSizeQt.Key_Right
Aumentar « value » en stepSizeQt.Key_Up
Establecer « value » en toQt.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:

Tres diales que muestran los modos de introducción de datos circular, horizontal y vertical

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.

Véase también to y value.

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:

Tres diales que muestran los modos de entrada circular, horizontal y vertical

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.

Véase también value y angle.

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:

ConstanteDescripción
Dial.NoSnapEl dial no se ajusta (valor predeterminado).
Dial.SnapAlwaysEl dial se ajusta mientras se arrastra el controlador.
Dial.SnapOnReleaseEl 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.

Véase también from y value.

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:

ConstanteDescripción
Dial.ClockwiseEl dial gira en sentido horario.
Dial.CounterClockwiseEl 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.