En esta página

QDial Class

La clase QDial ofrece un control de rango redondeado (como un velocímetro o un potenciómetro). Más información...

Encabezado: #include <QDial>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
Heredado de: QAbstractSlider

Propiedades

Funciones públicas

QDial(QWidget *parent = nullptr)
virtual ~QDial()
int notchSize() const
qreal notchTarget() const
bool notchesVisible() const
void setNotchTarget(double target)
bool wrapping() const

Funciones públicas reimplementadas

virtual QSize minimumSizeHint() const override
virtual QSize sizeHint() const override

Ranuras públicas

void setNotchesVisible(bool visible)
void setWrapping(bool on)

Funciones protegidas

virtual void initStyleOption(QStyleOptionSlider *option) const

Funciones protegidas reimplementadas

virtual bool event(QEvent *e) override
virtual void mouseMoveEvent(QMouseEvent *e) override
virtual void mousePressEvent(QMouseEvent *e) override
virtual void mouseReleaseEvent(QMouseEvent *e) override
virtual void paintEvent(QPaintEvent *pe) override
virtual void resizeEvent(QResizeEvent *e) override
virtual void sliderChange(QAbstractSlider::SliderChange change) override

Descripción detallada

Esfera redonda con muescas

QDial se utiliza cuando el usuario necesita controlar un valor dentro de un rango definible por el programa, y dicho rango es cíclico (por ejemplo, con ángulos medidos de 0 a 359 grados) o bien el diseño del cuadro de diálogo requiere un widget cuadrado.

Dado que QDial hereda de ` QAbstractSlider`, el dial se comporta de manera similar a un ` slider`. Cuando ` wrapping()` es `false` (el valor por defecto), no hay ninguna diferencia real entre un control deslizante y un dial. Ambos comparten las mismas señales, ranuras y funciones miembro. La elección de uno u otro depende de las expectativas de los usuarios y del tipo de aplicación.

El dial emite inicialmente la señal « valueChanged()» de forma continua mientras se mueve el control deslizante; puedes hacer que emita la señal con menos frecuencia desactivando la propiedad « tracking ». La señal « sliderMoved()» se emite de forma continua incluso cuando el seguimiento está desactivado.

El dial también emite las señales « sliderPressed()» y « sliderReleased()» al pulsar y soltar el botón del ratón. Ten en cuenta que el valor del dial puede cambiar sin que se emitan estas señales, ya que también se pueden utilizar el teclado y la rueda del ratón para modificar el valor.

A diferencia del control deslizante, QDial intenta dibujar un número «adecuado» de muescas en lugar de una por cada paso de línea. Si es posible, el número de muescas dibujadas es de una por paso de línea, pero si no hay suficientes píxeles para dibujarlas todas, QDial omitirá algunas muescas para intentar dibujar un conjunto uniforme (por ejemplo, dibujando cada segunda o tercera muesca).

Al igual que el control deslizante, el dial pone a disposición la función QAbstractSlider setValue () como una ranura.

La interfaz de teclado del dial es bastante sencilla: las teclas de flecha left/up y right/down ajustan el valor value del dial según los valores definidos singleStep, Page Up y Page Down según los valores definidos pageStep, y las teclas Home y End establecen el valor en los valores definidos minimum y maximum.

Si se utiliza la rueda del ratón para ajustar el dial, el valor de incremento viene determinado por el menor de los siguientes valores: wheelScrollLines multiplicado por singleStep y pageStep.

Véase también QScrollBar, QSpinBox, QSlider y el ejemplo de controles deslizantes.

Documentación de propiedades

[read-only] notchSize : int

Esta propiedad almacena el tamaño actual de la muesca

El tamaño de la muesca se expresa en unidades de control de rango, no en píxeles, y se calcula como un múltiplo de singleStep() que da como resultado un tamaño de muesca en pantalla cercano a notchTarget().

Funciones de acceso:

int notchSize() const

Véanse también notchTarget() y singleStep().

notchTarget : qreal

Esta propiedad establece el número objetivo de píxeles entre muescas

El objetivo de muesca es el número de píxeles que QDial intenta colocar entre cada muesca.

El tamaño real puede diferir del tamaño objetivo.

El valor predeterminado del objetivo de muesca es de 3,7 píxeles.

Funciones de acceso:

qreal notchTarget() const
void setNotchTarget(double target)

notchesVisible : bool

Esta propiedad se mantiene independientemente de si se muestran las marcas

Si la propiedad es « true », se dibujan una serie de marcas alrededor del dial para indicar el rango de valores disponibles; de lo contrario, no se muestran marcas.

Por defecto, esta propiedad está desactivada.

Funciones de acceso:

bool notchesVisible() const
void setNotchesVisible(bool visible)

wrapping : bool

Esta propiedad indica si está activado el ajuste de línea

Si el valor es «true», el ajuste de línea está activado; en caso contrario, se inserta un espacio en la parte inferior del dial para separar los extremos del rango de valores válidos.

Si está habilitada, la flecha puede orientarse en cualquier ángulo del dial. Si está deshabilitada, la flecha quedará restringida a la parte superior del dial; si se gira hacia el espacio situado en la parte inferior del dial, quedará fijada al extremo más cercano del rango de valores válidos.

Por defecto, esta propiedad está e false.

Funciones de acceso:

bool wrapping() const
void setWrapping(bool on)

Documentación de funciones de miembro

[explicit] QDial::QDial(QWidget *parent = nullptr)

Crea un dial.

El argumento « parent » se envía al constructor « QAbstractSlider ».

[virtual noexcept] QDial::~QDial()

Destruye la esfera.

[override virtual protected] bool QDial::event(QEvent *e)

Reimplementa: QAbstractSlider::event(QEvent *e).

[virtual protected] void QDial::initStyleOption(QStyleOptionSlider *option) const

Inicializa ` option ` con los valores de esta página: QDial. Este método resulta útil para las subclases cuando necesitan un ` QStyleOptionSlider`, pero no quieren introducir toda la información ellas mismas.

Véase también QStyleOption::initFrom().

[override virtual] QSize QDial::minimumSizeHint() const

Reimplementa una función de acceso para la propiedad: QWidget::minimumSizeHint.

[override virtual protected] void QDial::mouseMoveEvent(QMouseEvent *e)

Reimplementa: ` QWidget::mouseMoveEvent(QMouseEvent *event)`.

[override virtual protected] void QDial::mousePressEvent(QMouseEvent *e)

Reimplementa: ` QWidget::mousePressEvent(QMouseEvent *event)`.

[override virtual protected] void QDial::mouseReleaseEvent(QMouseEvent *e)

Reimplementa: ` QWidget::mouseReleaseEvent(QMouseEvent *event)`.

[override virtual protected] void QDial::paintEvent(QPaintEvent *pe)

Reimplementa: QWidget::paintEvent(QPaintEvent *event).

[override virtual protected] void QDial::resizeEvent(QResizeEvent *e)

Reimplementa: ` QWidget::resizeEvent(QResizeEvent *event)`.

[override virtual] QSize QDial::sizeHint() const

Reimplementa una función de acceso para la propiedad: QWidget::sizeHint.

[override virtual protected] void QDial::sliderChange(QAbstractSlider::SliderChange change)

Reimplementa: QAbstractSlider::sliderChange(QAbstractSlider::SliderChange change).

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