En esta página

QScroller Class

La clase QScroller permite el desplazamiento cinético en cualquier widget de desplazamiento o elemento gráfico. Más información...

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

Tipos públicos

enum Input { InputPress, InputMove, InputRelease }
enum ScrollerGestureType { TouchGesture, LeftMouseButtonGesture, MiddleMouseButtonGesture, RightMouseButtonGesture }
enum State { Inactive, Pressed, Dragging, Scrolling }

Propiedades

Funciones públicas

QPointF finalPosition() const
bool handleInput(QScroller::Input input, const QPointF &position, qint64 timestamp = 0)
QPointF pixelPerMeter() const
QScrollerProperties scrollerProperties() const
void setSnapPositionsX(const QList<qreal> &positions)
void setSnapPositionsX(qreal first, qreal interval)
void setSnapPositionsY(const QList<qreal> &positions)
void setSnapPositionsY(qreal first, qreal interval)
QScroller::State state() const
void stop()
QObject *target() const
QPointF velocity() const

Ranuras públicas

void ensureVisible(const QRectF &rect, qreal xmargin, qreal ymargin)
void ensureVisible(const QRectF &rect, qreal xmargin, qreal ymargin, int scrollTime)
void resendPrepareEvent()
void scrollTo(const QPointF &pos)
void scrollTo(const QPointF &pos, int scrollTime)
void setScrollerProperties(const QScrollerProperties &prop)

Señales

void scrollerPropertiesChanged(const QScrollerProperties &newProperties)
void stateChanged(QScroller::State newState)

Miembros públicos estáticos

QList<QScroller *> activeScrollers()
Qt::GestureType grabGesture(QObject *target, QScroller::ScrollerGestureType scrollGestureType = TouchGesture)
Qt::GestureType grabbedGesture(QObject *target)
bool hasScroller(QObject *target)
QScroller *scroller(QObject *target)
const QScroller *scroller(const QObject *target)
void ungrabGesture(QObject *target)

Descripción detallada

Con el desplazamiento cinético, el usuario puede empujar el widget en una dirección determinada y este seguirá desplazándose en esa dirección hasta que lo detenga el usuario o la fricción. Se pueden modificar aspectos como la inercia, la fricción y otros conceptos físicos para ajustar con precisión una experiencia de usuario intuitiva.

El objeto QScroller es el que almacena la posición actual y la velocidad de desplazamiento, y se encarga de las actualizaciones. QScroller puede activarse mediante un gesto de deslizamiento

    QWidget *w = ...;
    QScroller::grabGesture(w, QScroller::LeftMouseButtonGesture);

o directamente de esta manera:

    QWidget *w = ...;
    QScroller *scroller = QScroller::scroller(w);
    scroller->scrollTo(QPointF(100, 100));

Los QObjects que se desplazan reciben un « QScrollPrepareEvent » cada vez que el control de desplazamiento necesita actualizar su información geométrica y un « QScrollEvent » cada vez que el contenido del objeto debe desplazarse realmente.

El control de desplazamiento utiliza el temporizador global ` QAbstractAnimation ` para generar sus eventos `QScrollEvent`. Esto se puede modificar mediante ` QScrollerProperties::FrameRate ` de forma independiente para cada `QScroller`.

Aunque este control de desplazamiento cinético dispone de un gran número de ajustes a través de ` QScrollerProperties`, recomendamos dejar todos los valores en sus valores predeterminados, optimizados para la plataforma. Antes de modificarlos, puede probar el ejemplo ` plot ` que se encuentra en el directorio de ejemplos de scroller.

Véase también QScrollEvent, QScrollPrepareEvent y QScrollerProperties.

Documentación sobre tipos de miembros

enum QScroller::Input

Esta enumeración ofrece una visión independiente del dispositivo de entrada de los eventos de entrada que son relevantes para QScroller.

ConstanteValorDescripción
QScroller::InputPress1El usuario pulsó el dispositivo de entrada (p. ej., QEvent::MouseButtonPress, QEvent::GraphicsSceneMousePress, QEvent::TouchBegin)
QScroller::InputMove2El usuario ha movido el dispositivo de entrada (p. ej., QEvent::MouseMove, QEvent::GraphicsSceneMouseMove, QEvent::TouchUpdate)
QScroller::InputRelease3El usuario ha soltado el dispositivo de entrada (p. ej., QEvent::MouseButtonRelease, QEvent::GraphicsSceneMouseRelease, QEvent::TouchEnd)

enum QScroller::ScrollerGestureType

Esta enumeración contiene los diferentes tipos de gestos compatibles con el reconocedor de gestos de QScroller.

ConstanteValorDescripción
QScroller::TouchGesture0El reconocedor de gestos solo se activará ante eventos táctiles. Concretamente, reaccionará ante puntos de contacto únicos cuando se utilice una pantalla táctil y ante puntos de contacto dobles cuando se utilice un panel táctil.
QScroller::LeftMouseButtonGesture1El reconocedor de gestos solo se activará ante eventos del botón izquierdo del ratón.
QScroller::MiddleMouseButtonGesture3El reconocedor de gestos solo se activará ante eventos del botón central del ratón.
QScroller::RightMouseButtonGesture2El reconocedor de gestos solo se activará ante eventos del botón derecho del ratón.

enum QScroller::State

Esta enumeración contiene los diferentes estados de QScroller.

ConstanteValorDescripción
QScroller::Inactive0El control de desplazamiento no se está desplazando y no se ha pulsado nada.
QScroller::Pressed1Se ha recibido un evento táctil o se ha pulsado el botón del ratón, pero el área de desplazamiento no se está arrastrando en este momento.
QScroller::Dragging2El área de desplazamiento está siguiendo actualmente el punto de contacto o el ratón.
QScroller::Scrolling3El área de desplazamiento se está moviendo por sí sola.

Documentación de propiedades

scrollerProperties : QScrollerProperties

Esta propiedad contiene las propiedades de este control de desplazamiento. El control de desplazamiento ( QScroller ) utiliza estas propiedades para determinar su comportamiento de desplazamiento.

Funciones de acceso:

QScrollerProperties scrollerProperties() const
void setScrollerProperties(const QScrollerProperties &prop)

Señal de notificador:

void scrollerPropertiesChanged(const QScrollerProperties &newProperties)

[read-only] state : State

Esta propiedad contiene el estado del control de desplazamiento

Funciones de acceso:

QScroller::State state() const

Señal de notificación:

void stateChanged(QScroller::State newState)

Véase también QScroller::State.

Documentación de las funciones de miembro

[static] QList<QScroller *> QScroller::activeScrollers()

Devuelve una lista, válida para toda la aplicación, de los objetos ` QScroller ` que están activos en ese momento. Los objetos ` QScroller ` activos se encuentran en un ` state()` que no es ` QScroller::Inactive`. Esta función resulta útil a la hora de crear tu propio reconocedor de gestos.

[slot] void QScroller::ensureVisible(const QRectF &rect, qreal xmargin, qreal ymargin)

Comienza a desplazarse de manera que el rectángulo rect quede visible dentro de la ventana de visualización, con los márgenes adicionales especificados en píxeles en xmargin y ymargin alrededor del rectángulo.

En los casos en los que no sea posible encajar el rectángulo más los márgenes dentro de la ventana de visualización, el contenido se desplaza de manera que se vea la mayor parte posible de rect.

La velocidad de desplazamiento se calcula de modo que se alcance la posición indicada tras un intervalo de tiempo definido por la plataforma.

Esta función realiza el desplazamiento propiamente dicho llamando a scrollTo().

Nota: Esta ranura está sobrecargada. Para conectarse a esta ranura:

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        scroller, qOverload(&QScroller::ensureVisible));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        scroller, [receiver = scroller](const QRectF &rect, qreal xmargin, qreal ymargin) { receiver->ensureVisible(rect, xmargin, ymargin); });
Para ver más ejemplos y enfoques, consulta «Conexión a ranuras sobrecargadas».

Véase también scrollTo().

[slot] void QScroller::ensureVisible(const QRectF &rect, qreal xmargin, qreal ymargin, int scrollTime)

Esta versión alcanzará su posición de destino en scrollTime milisegundos.

Nota: Esta ranura está sobrecargada. Para conectarse a esta ranura:

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        scroller, qOverload(&QScroller::ensureVisible));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        scroller, [receiver = scroller](const QRectF &rect, qreal xmargin, qreal ymargin, int scrollTime) { receiver->ensureVisible(rect, xmargin, ymargin, scrollTime); });
Para ver más ejemplos y métodos, consulta «Conexión a ranuras sobrecargadas».

QPointF QScroller::finalPosition() const

Devuelve la posición final estimada para el movimiento de desplazamiento actual. Devuelve la posición actual si el estado del control de desplazamiento no es «Scrolling». El resultado es indefinido cuando el estado del control de desplazamiento es «Inactive».

La posición de destino se expresa en píxeles.

Véase también pixelPerMeter() y scrollTo().

[static] Qt::GestureType QScroller::grabGesture(QObject *target, QScroller::ScrollerGestureType scrollGestureType = TouchGesture)

Registra un reconocedor de gestos de desplazamiento personalizado, lo asocia a ` target ` y devuelve el tipo de gesto resultante. Si ` scrollGestureType ` se establece en ` TouchGesture `, el gesto se activa con eventos táctiles. Si se establece en uno de los siguientes valores: ` LeftMouseButtonGesture`, ` RightMouseButtonGesture ` o ` MiddleMouseButtonGesture `, se activa con eventos del ratón del botón correspondiente.

Solo puede haber un gesto de desplazamiento activo en un mismo objeto al mismo tiempo. Si se llama a esta función dos veces en el mismo objeto, se desactivará el gesto existente antes de activar el nuevo.

Nota: Para evitar efectos secundarios no deseados, los eventos del ratón se consumen mientras se activa el gesto. Dado que el evento inicial de pulsación del ratón no se consume, el gesto envía un evento falso de liberación del ratón en la posición global (INT_MIN, INT_MIN). Esto garantiza que los estados internos del widget que recibió la pulsación original del ratón sean coherentes.

Véase también ungrabGesture() y grabbedGesture().

[static] Qt::GestureType QScroller::grabbedGesture(QObject *target)

Devuelve el tipo de gesto capturado actualmente para ` target ` o 0 si no hay ningún gesto capturado.

Véase también grabGesture() y ungrabGesture().

bool QScroller::handleInput(QScroller::Input input, const QPointF &position, qint64 timestamp = 0)

Los reconocedores de gestos utilizan esta función para informar al control de desplazamiento de un nuevo evento de entrada. El control de desplazamiento modifica su valor interno de ` state()` en función del evento de entrada y de las propiedades asociadas al control. El control de desplazamiento no distingue el tipo de dispositivo de entrada del que procede el evento. Por lo tanto, el evento debe dividirse en el tipo « input », un « position » y un « timestamp » en milisegundos. El « position » debe estar en el sistema de coordenadas del destino.

El valor de retorno es true si el evento debe ser consumido por el filtro que lo invoca, o false si el evento debe reenviarse al control.

Nota: El uso de ` grabGesture()` debería ser suficiente para la mayoría de los casos de uso.

[static] bool QScroller::hasScroller(QObject *target)

Devuelve ` true ` si ya se ha creado un objeto ` QScroller ` para ` target`; en caso contrario, devuelve ` false `.

Véase también scroller().

QPointF QScroller::pixelPerMeter() const

Devuelve la medida de píxeles por metro para el widget desplazado.

El valor se indica por separado para los ejes x e y mediante un ` QPointF`.

Nota: Ten en cuenta que este valor debe ser físicamente correcto. Es posible que el sistema de ventanas subyacente, por ejemplo en macOS, informe erróneamente de forma intencionada de la configuración real de DPI que Qt devuelve para la pantalla.

[slot] void QScroller::resendPrepareEvent()

Esta función reenvía el evento « QScrollPrepareEvent ». Al llamar a «resendPrepareEvent», se activa un evento « QScrollPrepareEvent » desde el control de desplazamiento. Esto permite al receptor restablecer la posición y el tamaño del contenido mientras se desplaza. Llamar a esta función mientras se está en el estado «Inactive» no sirve de nada, ya que el evento «prepare» se envía de nuevo antes de que comience el desplazamiento.

[slot] void QScroller::scrollTo(const QPointF &pos)

Inicia el desplazamiento del widget de modo que el punto pos quede en la posición superior izquierda de la ventana de visualización.

El comportamiento al desplazarse fuera del área de desplazamiento válida es indefinido. En este caso, el control de desplazamiento podría sobrepasar o no el límite.

La velocidad de desplazamiento se calculará de modo que se alcance la posición indicada tras un intervalo de tiempo definido por la plataforma.

pos Se especifica en coordenadas de la ventana gráfica.

Nota: Esta ranura está sobrecargada. Para conectarse a esta ranura:

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        scroller, qOverload(&QScroller::scrollTo));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        scroller, [receiver = scroller](const QPointF &pos) { receiver->scrollTo(pos); });
Para ver más ejemplos y métodos, consulta «Conexión a ranuras sobrecargadas».

Véase también ` ensureVisible()`.

[slot] void QScroller::scrollTo(const QPointF &pos, int scrollTime)

Esta versión llegará a su posición de destino en scrollTime milisegundos.

Nota: Esta ranura está sobrecargada. Para conectarse a esta ranura:

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        scroller, qOverload(&QScroller::scrollTo));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        scroller, [receiver = scroller](const QPointF &pos, int scrollTime) { receiver->scrollTo(pos, scrollTime); });
Para ver más ejemplos y métodos, consulta «Conexión a ranuras sobrecargadas».

[static] QScroller *QScroller::scroller(QObject *target)

Devuelve el control de desplazamiento correspondiente a la dirección target indicada. Mientras el objeto exista, esta función siempre devolverá la misma instancia de QScroller. Si no existe ninguna dirección QScroller para la dirección target, se creará una de forma implícita. En ningún momento habrá más de un control de desplazamiento QScroller activo en un objeto.

Véase también hasScroller() y target().

[static] const QScroller *QScroller::scroller(const QObject *target)

Esta es la versión «const» de scroller().

Se trata de una función sobrecargada.

[signal] void QScroller::scrollerPropertiesChanged(const QScrollerProperties &newProperties)

QScroller Emite esta señal cada vez que cambian las propiedades de su scroller. newProperties son las nuevas propiedades del scroller.

Nota: Señalde notificador para la propiedad scrollerProperties.

Véase también scrollerProperties.

void QScroller::setSnapPositionsX(const QList<qreal> &positions)

Establece las posiciones de ajuste para el eje horizontal en una lista de positions. Esto sobrescribe todas las posiciones de ajuste establecidas anteriormente, así como cualquier intervalo de ajuste previamente definido. El ajuste se puede desactivar estableciendo una lista vacía de posiciones.

void QScroller::setSnapPositionsX(qreal first, qreal interval)

Establece las posiciones de ajuste para el eje horizontal en intervalos regulares. La primera posición de ajuste se encuentra en first. La siguiente, en first + interval. Esto se puede utilizar para implementar un encabezado de lista. Esto sobrescribe todas las posiciones de ajuste establecidas anteriormente, así como cualquier intervalo de ajuste previamente definido. El ajuste se puede desactivar estableciendo un intervalo de 0,0.

void QScroller::setSnapPositionsY(const QList<qreal> &positions)

Establece las posiciones de ajuste para el eje vertical en una lista de positions. Esto anula todas las posiciones de ajuste establecidas anteriormente, así como cualquier intervalo de ajuste previamente definido. El ajuste se puede desactivar estableciendo una lista vacía de posiciones.

void QScroller::setSnapPositionsY(qreal first, qreal interval)

Establece las posiciones de ajuste para el eje vertical en intervalos regulares. La primera posición de ajuste se encuentra en first. La siguiente, en first + interval. Esto sobrescribe todas las posiciones de ajuste establecidas anteriormente, así como cualquier intervalo de ajuste previamente definido. El ajuste se puede desactivar estableciendo un intervalo de 0,0.

[signal] void QScroller::stateChanged(QScroller::State newState)

QScroller emite esta señal cada vez que cambia el estado. ` newState ` es el nuevo estado.

Nota: Señalde notificador para la propiedad state.

Véase también state.

void QScroller::stop()

Detiene el control de desplazamiento y restablece su estado a «Inactivo».

QObject *QScroller::target() const

Devuelve el objeto de destino de este control de desplazamiento.

Véase también hasScroller() y scroller().

[static] void QScroller::ungrabGesture(QObject *target)

Libera el gesto capturado en target. No realiza ninguna acción si no hay ningún gesto capturado.

Véase también « grabGesture()» y « grabbedGesture()».

QPointF QScroller::velocity() const

Devuelve la velocidad de desplazamiento actual en metros por segundo cuando el estado es «Desplazamiento» o «Arrastrar». En caso contrario, devuelve una velocidad igual a cero.

La velocidad se indica por separado para los ejes x e y mediante el uso de QPointF.

Véase también pixelPerMeter().

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