En esta página

QScrollBar Class

El widget QScrollBar ofrece una barra de desplazamiento vertical u horizontal. Más...

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

Funciones públicas

QScrollBar(QWidget *parent = nullptr)
QScrollBar(Qt::Orientation orientation, QWidget *parent = nullptr)
virtual ~QScrollBar()
(since 6.10) QMenu *createStandardContextMenu(QPoint position)

Funciones públicas reimplementadas

virtual bool event(QEvent *event) override
virtual QSize sizeHint() const override

Funciones protegidas

virtual void initStyleOption(QStyleOptionSlider *option) const

Funciones protegidas reimplementadas

virtual void contextMenuEvent(QContextMenuEvent *event) override
virtual void hideEvent(QHideEvent *) override
virtual void mouseMoveEvent(QMouseEvent *e) override
virtual void mousePressEvent(QMouseEvent *e) override
virtual void mouseReleaseEvent(QMouseEvent *e) override
virtual void paintEvent(QPaintEvent *) override
virtual void sliderChange(QAbstractSlider::SliderChange change) override
virtual void wheelEvent(QWheelEvent *event) override

Descripción detallada

Una barra de desplazamiento es un control que permite al usuario acceder a partes de un documento cuyo tamaño supera el del widget utilizado para mostrarlo. Proporciona una indicación visual de la posición actual del usuario dentro del documento y de la parte del documento que está visible. Las barras de desplazamiento suelen ir acompañadas de otros controles que permiten una navegación más precisa. Qt muestra las barras de desplazamiento de forma adecuada para cada plataforma.

Si necesitas proporcionar una vista desplazable en otro widget, puede resultar más conveniente utilizar la clase ` QScrollArea `, ya que esta proporciona un widget de ventana de visualización y barras de desplazamiento. QScrollBar resulta útil si necesitas implementar una funcionalidad similar para widgets especializados utilizando ` QAbstractScrollArea`; por ejemplo, si decides crear una subclase de ` QAbstractItemView`. Para la mayoría de las demás situaciones en las que se utiliza un control deslizante para obtener un valor dentro de un rango determinado, la clase ` QSlider ` puede ser más adecuada para tus necesidades.

Los elementos de la barra de desplazamiento, como el control deslizante, las flechas de desplazamiento y el control de página

Las barras de desplazamiento suelen incluir cuatro controles independientes: un control deslizante, flechas de desplazamiento y un control de página.
  • a. El control deslizante permite desplazarse rápidamente a cualquier parte del documento, pero no permite una navegación precisa dentro de documentos extensos.
  • b. Las flechas de desplazamiento son botones que pueden utilizarse para navegar con precisión hasta un lugar concreto del documento. En el caso de una barra de desplazamiento vertical conectada a un editor de texto, suelen desplazar la posición actual una «línea» hacia arriba o hacia abajo y ajustar la posición del control deslizante en una pequeña cantidad. En editores y cuadros de lista, una «línea» puede referirse a una línea de texto; en un visor de imágenes, puede referirse a 20 píxeles.
  • c. El control de página es el área sobre la que se arrastra el control deslizante (el fondo de la barra de desplazamiento). Al hacer clic aquí, la barra de desplazamiento se desplaza hacia el punto del clic una «página». Este valor suele ser igual a la longitud del control deslizante.

Cada barra de desplazamiento tiene un valor que indica a qué distancia se encuentra el control deslizante del inicio de la barra; este valor se obtiene con value() y se establece con setValue(). Este valor siempre se encuentra dentro del rango de valores definido para la barra de desplazamiento, desde minimum() hasta maximum() ambos inclusive. El rango de valores admisibles se puede establecer con ` setMinimum()` y ` setMaximum()`. En el valor mínimo, el borde superior del control deslizante (en el caso de una barra de desplazamiento vertical) o el borde izquierdo (en el caso de una barra de desplazamiento horizontal) se situará en el extremo superior (o izquierdo) de la barra de desplazamiento. En el valor máximo, el borde inferior (o derecho) del control deslizante se situará en el extremo inferior (o derecho) de la barra de desplazamiento.

La longitud del control deslizante suele estar relacionada con el valor del paso de página y, por lo general, representa la proporción del área del documento que se muestra en una vista de desplazamiento. El «paso de página» es la cantidad en la que cambia el valor cuando el usuario pulsa las teclas « Page Up » y « Page Down », y se establece con ` setPageStep()`. Los cambios más pequeños en el valor, definidos por el «paso de línea», se realizan mediante las teclas de cursor, y esta cantidad se establece con ` setSingleStep()`.

Ten en cuenta que el rango de valores utilizado es independiente del tamaño real del control de barra de desplazamiento. No es necesario tener esto en cuenta a la hora de elegir los valores para el rango y el paso por página.

El rango de valores especificado para la barra de desplazamiento suele determinarse de forma diferente al de un control de desplazamiento ( QSlider ), ya que hay que tener en cuenta la longitud del control deslizante. Si tenemos un documento de 100 líneas y solo podemos mostrar 20 líneas en un widget, es posible que queramos crear una barra de desplazamiento con un paso por página de 20, un valor mínimo de 0 y un valor máximo de 80. Esto nos daría una barra de desplazamiento con cinco «páginas».

La longitud del documento, el rango de desplazamiento y el paso por página de una barra de desplazamientoLa relación entre la longitud de un documento, el rango de valores utilizado en una barra de desplazamiento y el paso por página es sencilla en muchas situaciones habituales. El rango de valores de la barra de desplazamiento se determina restando el paso por página elegido de un valor que represente la longitud del documento. En tales casos, resulta útil la siguiente ecuación: longitud del documento = maximum() - minimum() + pageStep().

QScrollBar solo admite rangos de números enteros. Ten en cuenta que, aunque QScrollBar maneja números muy grandes, las barras de desplazamiento de las pantallas actuales no pueden representar de forma útil rangos superiores a unos 100 000 píxeles. Más allá de ese límite, al usuario le resulta difícil controlar el control deslizante, ya sea con el teclado o con el ratón, y las flechas de desplazamiento tendrán un uso limitado.

ScrollBar hereda un amplio conjunto de señales de QAbstractSlider:

  • valueChanged() se emite cuando el valor de la barra de desplazamiento ha cambiado. La propiedad tracking determina si esta señal se emite durante la interacción del usuario.
  • rangeChanged() se emite cuando ha cambiado el rango de valores de la barra de desplazamiento.
  • sliderPressed() se emite cuando el usuario comienza a arrastrar el control deslizante.
  • sliderMoved() se emite cuando el usuario arrastra el control deslizante.
  • sliderReleased() se emite cuando el usuario suelta el control deslizante.
  • actionTriggered() se emite cuando la barra de desplazamiento cambia por la interacción del usuario o mediante la función triggerAction().

Una barra de desplazamiento se puede controlar con el teclado, pero tiene un valor predeterminado para ` focusPolicy()` de ` Qt::NoFocus`. Utiliza ` setFocusPolicy()` para habilitar la interacción del teclado con la barra de desplazamiento:

  • Izquierda/Derecha: desplaza una barra de desplazamiento horizontal un solo paso.
  • Las teclas «Arriba» y «Abajo» desplazan una barra de desplazamiento vertical un solo paso.
  • «PageUp» avanza una página.
  • «PageDown» avanza una página.
  • «Inicio» se desplaza al principio (mínimo).
  • Fin: se desplaza hasta el final (máximo).

El control deslizante en sí mismo se puede controlar utilizando la función triggerAction() para simular la interacción del usuario con los controles de la barra de desplazamiento. Esto resulta útil si tienes muchos widgets diferentes que utilizan un rango común de valores.

La mayoría de los estilos de interfaz gráfica de usuario utilizan el valor de ` pageStep()` para calcular el tamaño del control deslizante.

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

Documentación de las funciones de miembro

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

Crea una barra de desplazamiento vertical.

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

El valor predeterminado de ` minimum ` es 0, el de ` maximum ` es 99, con un tamaño de ` singleStep ` de 1 y un tamaño de ` pageStep ` de 10, y un valor inicial de ` value ` de 0.

[explicit] QScrollBar::QScrollBar(Qt::Orientation orientation, QWidget *parent = nullptr)

Crea una barra de desplazamiento con el objeto ` orientation` indicado.

El argumento ` parent ` se pasa al constructor ` QWidget `.

El valor predeterminado de ` minimum ` es 0, el de ` maximum ` es 99, con un tamaño de ` singleStep ` de 1 y un tamaño de ` pageStep ` de 10, y un valor inicial de ` value ` de 0.

[virtual noexcept] QScrollBar::~QScrollBar()

Elimina la barra de desplazamiento.

[override virtual protected] void QScrollBar::contextMenuEvent(QContextMenuEvent *event)

Reimplementa: ` QWidget::contextMenuEvent(QContextMenuEvent *event)`.

Muestra el menú contextual estándar creado con createStandardContextMenu().

Si no deseas que la barra de desplazamiento tenga un menú contextual, puedes establecer su contextMenuPolicy en Qt::NoContextMenu. Un estilo también puede controlar este comportamiento mediante la sugerencia SH_ScrollBar_ContextMenu.

Si desea personalizar el menú contextual, vuelva a implementar esta función. Si desea ampliar el menú contextual estándar, vuelva a implementar esta función, llame a createStandardContextMenu() y amplíe el menú devuelto. Almacene el objeto QMenu devuelto para reutilizarlo más adelante o establezca el atributo WA_DeleteOnClose.

La información sobre el evento se pasa en el objeto ` event `.

[since 6.10] QMenu *QScrollBar::createStandardContextMenu(QPoint position)

Crea el menú contextual estándar, que se muestra cuando el usuario hace clic con el botón derecho del ratón en la barra de desplazamiento. Se invoca desde el controlador predeterminado ` contextMenuEvent()` y toma como parámetro ` position `, que indica la posición del clic del ratón en las coordenadas locales de este widget. La propiedad del menú emergente se transfiere a quien realiza la llamada.

Esta función se introdujo en Qt 6.10.

[override virtual] bool QScrollBar::event(QEvent *event)

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

[override virtual protected] void QScrollBar::hideEvent(QHideEvent *)

Reimplementa: QWidget::hideEvent(QHideEvent *event).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[override virtual protected] void QScrollBar::wheelEvent(QWheelEvent *event)

Reimplementa: ` QAbstractSlider::wheelEvent(QWheelEvent *e)`.

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