En esta página

Ejemplo de controles deslizantes

El ejemplo de controles deslizantes muestra cómo utilizar los diferentes tipos de controles deslizantes disponibles en Qt: QSlider, QScrollBar y QDial.

Qt ofrece tres tipos de widgets similares a controles deslizantes: QSlider, QScrollBar y QDial. Todos ellos heredan la mayor parte de su funcionalidad de QAbstractSlider y, en teoría, pueden sustituirse entre sí en una aplicación, ya que las diferencias solo se refieren a su aspecto y comportamiento. Este ejemplo muestra cómo son, cómo funcionan y cómo se puede modificar su comportamiento y apariencia a través de sus propiedades.

El ejemplo también muestra cómo se pueden utilizar las señales y las ranuras para sincronizar el comportamiento de dos o más widgets, y cómo sobrescribir resizeEvent() para implementar un diseño adaptativo.

Galería de diferentes controles deslizantes, barras de desplazamiento y diales

Captura de pantalla del ejemplo «Sliders»

El ejemplo «Sliders» consta de dos clases:

  • SlidersGroup es un widget personalizado. Combina un ` QSlider`, un ` QScrollBar ` y un ` QDial`.
  • Window es el widget principal que combina un QGroupBox y un SlidersGroup. El QGroupBox contiene varios widgets que controlan el comportamiento de los widgets tipo deslizador.

En primer lugar, repasaremos la clase ` Window ` y, a continuación, analizaremos la clase ` SlidersGroup `.

Definición de la clase «Window»

class Window : public QWidget
{
    Q_OBJECT

public:
    Window(QWidget *parent = nullptr);

private:
    void createControls(const QString &title);
    void resizeEvent(QResizeEvent *e);

    SlidersGroup *slidersGroup;

    QGroupBox *controlsGroup;
    QLabel *minimumLabel;
    QLabel *maximumLabel;
    QLabel *valueLabel;
    QCheckBox *invertedAppearance;
    QCheckBox *invertedKeyBindings;
    QSpinBox *minimumSpinBox;
    QSpinBox *maximumSpinBox;
    QSpinBox *valueSpinBox;
    QBoxLayout *layout;
};

La clase ` Window ` hereda de ` QWidget`. Muestra los controles deslizantes y permite al usuario establecer sus valores mínimo, máximo y actual, así como personalizar su apariencia, las combinaciones de teclas y la orientación. Utilizamos una función privada ` createControls() ` para crear los controles que proporcionan estos mecanismos de control y para conectarlos a los controles deslizantes.

Implementación de la clase `Window`

Window::Window(QWidget *parent)
    : QWidget(parent)
{
    slidersGroup = new SlidersGroup(tr("Sliders"));

    createControls(tr("Controls"));

En el constructor, primero creamos el widget ` SlidersGroup `, que muestra los widgets deslizantes. Con ` createControls() ` creamos los widgets de control y los conectamos a los deslizadores.

    layout = new QBoxLayout(QBoxLayout::LeftToRight);
    layout->addWidget(controlsGroup);
    layout->addWidget(slidersGroup);
    setLayout(layout);

    minimumSpinBox->setValue(0);
    maximumSpinBox->setValue(20);
    valueSpinBox->setValue(5);

    setWindowTitle(tr("Sliders"));
}

Colocamos los grupos de widgets de control y los controles deslizantes en un diseño horizontal antes de inicializar los valores mínimo, máximo y actual. La inicialización del valor actual se propagará a los widgets de control deslizante a través de la conexión que hemos establecido entre los widgets « valueSpinBox » y « SlidersGroup ». Los valores mínimo y máximo se propagan a través de las conexiones que hemos creado con « createControls() ».

void Window::createControls(const QString &title)
{
    controlsGroup = new QGroupBox(title);

    minimumLabel = new QLabel(tr("Minimum value:"));
    maximumLabel = new QLabel(tr("Maximum value:"));
    valueLabel = new QLabel(tr("Current value:"));

    invertedAppearance = new QCheckBox(tr("Inverted appearance"));
    invertedKeyBindings = new QCheckBox(tr("Inverted key bindings"));

En la función privada ` createControls() `, hacemos que un ` QGroupBox ` (`controlsGroup`) muestre los widgets de control. Un cuadro de grupo puede proporcionar un marco, un título y un atajo de teclado, y muestra otros widgets en su interior. El grupo de widgets de control está compuesto por dos casillas de selección y tres cuadros giratorios con etiquetas.

Tras crear las etiquetas, creamos las dos casillas de selección. Las casillas de selección se utilizan habitualmente para representar funciones de una aplicación que pueden activarse o desactivarse. Cuando se activa la opción « invertedAppearance », los valores del control deslizante se invierten. La tabla siguiente muestra el aspecto de los diferentes controles similares a controles deslizantes:

QSliderQScrollBarQDial
NormalInvertidoNormalInvertidoNormalInvertido
Qt::HorizontalDe izquierda a derechaDe derecha a izquierdaDe izquierda a derechaDe derecha a izquierdaEn el sentido de las agujas del relojEn sentido antihorario
Qt::VerticalDe abajo hacia arribaDe arriba abajoDe arriba abajoDe abajo hacia arribaEn el sentido de las agujas del relojEn sentido antihorario

Es habitual invertir la apariencia de un control deslizante vertical ( QSlider). Un control deslizante vertical que controla el volumen, por ejemplo, suele desplazarse de abajo hacia arriba (la apariencia no invertida), mientras que un control deslizante vertical que controla la posición de un objeto en la pantalla puede desplazarse de arriba hacia abajo, ya que las coordenadas de la pantalla van de arriba hacia abajo.

Cuando la opción « invertedKeyBindings » está activada (lo que se corresponde con la propiedad « QAbstractSlider::invertedControls »), se invierten los eventos de la rueda y de las teclas del control deslizante. Con las asignaciones de teclas normales, al desplazar la rueda del ratón «hacia arriba» o al usar teclas como «Av Pág», el valor actual del control deslizante aumentará hacia su máximo. Al estar invertidos, los mismos eventos de la rueda y de las teclas moverán el valor hacia el mínimo del control deslizante. Esto puede resultar útil si la apariencia de un control deslizante está invertida: algunos usuarios podrían esperar que las teclas siguieran funcionando de la misma manera sobre el valor, mientras que otros podrían esperar que « PageUp » signifique «arriba» en la pantalla.

Ten en cuenta que, en el caso de las barras de desplazamiento horizontales y verticales, las asignaciones de teclas están invertidas por defecto: « PageDown » aumenta el valor actual, y « PageUp » lo disminuye.

    minimumSpinBox = new QSpinBox;
    minimumSpinBox->setRange(-100, 100);
    minimumSpinBox->setSingleStep(1);

    maximumSpinBox = new QSpinBox;
    maximumSpinBox->setRange(-100, 100);
    maximumSpinBox->setSingleStep(1);

    valueSpinBox = new QSpinBox;
    valueSpinBox->setRange(-100, 100);
    valueSpinBox->setSingleStep(1);

A continuación, creamos los cuadros de selección. QSpinBox permite al usuario elegir un valor haciendo clic en los botones de subir y bajar o pulsando las teclas Up y Down del teclado para modificar el valor que se muestra actualmente. El usuario también puede introducir el valor manualmente. Los cuadros de selección controlan los valores mínimo, máximo y actual de los widgets QSlider, QScrollBar y QDial.

    connect(slidersGroup, &SlidersGroup::valueChanged,
            valueSpinBox, &QSpinBox::setValue);
    connect(valueSpinBox, &QSpinBox::valueChanged,
            slidersGroup, &SlidersGroup::setValue);
    connect(minimumSpinBox, &QSpinBox::valueChanged,
            slidersGroup, &SlidersGroup::setMinimum);
    connect(maximumSpinBox, &QSpinBox::valueChanged,
            slidersGroup, &SlidersGroup::setMaximum);
    connect(invertedAppearance, &QCheckBox::toggled,
            slidersGroup, &SlidersGroup::invertAppearance);
    connect(invertedKeyBindings, &QCheckBox::toggled,
            slidersGroup, &SlidersGroup::invertKeyBindings);

    QGridLayout *controlsLayout = new QGridLayout;
    controlsLayout->addWidget(minimumLabel, 0, 0);
    controlsLayout->addWidget(maximumLabel, 1, 0);
    controlsLayout->addWidget(valueLabel, 2, 0);
    controlsLayout->addWidget(minimumSpinBox, 0, 1);
    controlsLayout->addWidget(maximumSpinBox, 1, 1);
    controlsLayout->addWidget(valueSpinBox, 2, 1);
    controlsLayout->addWidget(invertedAppearance, 0, 2);
    controlsLayout->addWidget(invertedKeyBindings, 1, 2);
    controlsGroup->setLayout(controlsLayout);

}

A continuación, conectamos slidersGroup y valueSpinBox entre sí, de modo que los widgets deslizadores y el widget de control se comporten de forma sincronizada cuando cambie el valor actual de uno de ellos. La señal valueChanged() se emite con el nuevo valor como argumento. La ranura setValue() establece el valor actual del widget en el nuevo valor y emite valueChanged() si el nuevo valor es diferente del anterior.

Sincronizamos el comportamiento de los widgets de control y los widgets deslizantes a través de sus señales y ranuras. Conectamos cada widget de control tanto al grupo horizontal como al vertical de widgets deslizantes. También conectamos orientationCombo a QStackedWidget, para que se muestre la «página» correcta. Por último, distribuimos los widgets de control en un QGridLayout dentro del cuadro de grupo controlsGroup.

void Window::resizeEvent(QResizeEvent *)
{
    if (width() == 0 || height() == 0)
        return;

    const double aspectRatio = double(width()) / double(height());

    if (aspectRatio < 1.0) {
        layout->setDirection(QBoxLayout::TopToBottom);
        slidersGroup->setOrientation(Qt::Horizontal);
    } else if (aspectRatio > 1.0) {
        layout->setDirection(QBoxLayout::LeftToRight);
        slidersGroup->setOrientation(Qt::Vertical);
    }
}

Por último, sobrescribimos resizeEvent() de QWidget. Nos aseguramos de que no se divida por cero y, por lo demás, calculamos la relación de aspecto del widget. Si la ventana tiene formato vertical, configuramos el diseño para organizar los grupos de widgets de control y controles deslizantes de forma vertical, y damos a los controles deslizantes una orientación horizontal. Si la ventana tiene un formato apaisado, cambiamos el diseño para mostrar los controles deslizantes y los widgets de control uno al lado del otro, y asignamos a los controles deslizantes una orientación vertical.

Definición de la clase `SlidersGroup`

class SlidersGroup : public QGroupBox
{
    Q_OBJECT

public:
    SlidersGroup(const QString &title, QWidget *parent = nullptr);

signals:
    void valueChanged(int value);

public slots:
    void setValue(int value);
    void setMinimum(int value);
    void setMaximum(int value);
    void invertAppearance(bool invert);
    void invertKeyBindings(bool invert);
    void setOrientation(Qt::Orientation orientation);

private:
    QSlider *slider;
    QScrollBar *scrollBar;
    QDial *dial;
    QBoxLayout *slidersLayout;
};

La clase « SlidersGroup » hereda de « QGroupBox ». Proporciona un marco y un título, y contiene un « QSlider », un « QScrollBar » y un « QDial ».

Proporcionamos una señal « valueChanged() » y una ranura pública « setValue() » con una funcionalidad equivalente a las de « QAbstractSlider » y « QSpinBox ». Además, implementamos varias ranuras públicas más para establecer los valores mínimo y máximo, invertir la apariencia de los widgets deslizadores, así como las combinaciones de teclas, y establecer la orientación.

Implementación de la clase `SlidersGroup`

SlidersGroup::SlidersGroup(const QString &title, QWidget *parent)
    : QGroupBox(title, parent)
{
    slider = new QSlider;
    slider->setFocusPolicy(Qt::StrongFocus);
    slider->setTickPosition(QSlider::TicksBothSides);
    slider->setTickInterval(10);
    slider->setSingleStep(1);

    scrollBar = new QScrollBar;
    scrollBar->setFocusPolicy(Qt::StrongFocus);

    dial = new QDial;
    dial->setFocusPolicy(Qt::StrongFocus);

En primer lugar, creamos los widgets tipo control deslizante con las propiedades adecuadas. En concreto, configuramos la política de foco para cada widget. ` Qt::FocusPolicy ` es un tipo de enumeración que define las distintas políticas que puede tener un widget con respecto a la obtención del foco del teclado. La política ` Qt::StrongFocus ` significa que el widget acepta el foco tanto al desplazarse con la tecla Tab como al hacer clic.

    connect(slider, &QSlider::valueChanged, scrollBar, &QScrollBar::setValue);
    connect(scrollBar, &QScrollBar::valueChanged, dial, &QDial::setValue);
    connect(dial, &QDial::valueChanged, slider, &QSlider::setValue);
    connect(dial, &QDial::valueChanged, this, &SlidersGroup::valueChanged);

A continuación, conectamos los widgets entre sí, de modo que permanezcan sincronizados cuando cambie el valor actual de uno de ellos.

Conectamos la señal « valueChanged() » de « dial » a la señal « valueChanged() » de « SlidersGroup », para notificar a los demás widgets de la aplicación (es decir, los widgets de control) el cambio de valor.


    slidersLayout = new QBoxLayout(QBoxLayout::LeftToRight);
    slidersLayout->addWidget(slider);
    slidersLayout->addWidget(scrollBar);
    slidersLayout->addWidget(dial);
    setLayout(slidersLayout);
}

Por último, creamos el diseño de los widgets deslizadores dentro del cuadro de grupo. Comenzamos con una disposición horizontal de los deslizadores.

void SlidersGroup::setValue(int value)
{
    slider->setValue(value);
}

La ranura « setValue() » establece el valor de « QSlider ». No es necesario llamar explícitamente a « setValue()» en los widgets « QScrollBar » y « QDial », ya que « QSlider » emitirá la señal « valueChanged()» cuando cambie su valor, lo que desencadenará un efecto dominó.

void SlidersGroup::setMinimum(int value)
{
    slider->setMinimum(value);
    scrollBar->setMinimum(value);
    dial->setMinimum(value);
}

void SlidersGroup::setMaximum(int value)
{
    slider->setMaximum(value);
    scrollBar->setMaximum(value);
    dial->setMaximum(value);
}

La clase ` Window ` utiliza las ranuras ` setMinimum() ` y ` setMaximum() ` para establecer el rango de los widgets ` QSlider`, ` QScrollBar` y ` QDial `.

void SlidersGroup::invertAppearance(bool invert)
{
    slider->setInvertedAppearance(invert);
    scrollBar->setInvertedAppearance(invert);
    dial->setInvertedAppearance(invert);
}

void SlidersGroup::invertKeyBindings(bool invert)
{
    slider->setInvertedControls(invert);
    scrollBar->setInvertedControls(invert);
    dial->setInvertedControls(invert);
}

Las ranuras « invertAppearance() » y « invertKeyBindings() » controlan las propiedades « invertedAppearance » y « invertedControls » de los widgets hijos.

void SlidersGroup::setOrientation(Qt::Orientation orientation)
{
    slidersLayout->setDirection(orientation == Qt::Horizontal
                                ? QBoxLayout::TopToBottom
                                : QBoxLayout::LeftToRight);
    scrollBar->setOrientation(orientation);
    slider->setOrientation(orientation);
}

La ranura setOrientation() controla la dirección del diseño y la orientación de los controles deslizantes. En un grupo horizontal, los controles deslizantes tienen una orientación horizontal y se disponen uno encima de otro. En un grupo vertical, los controles deslizantes tienen una orientación vertical y se disponen uno al lado del otro.

Proyecto de ejemplo en @ code.qt.io

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