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
- scrollerProperties : QScrollerProperties
- state : State
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
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.
| Constante | Valor | Descripción |
|---|---|---|
QScroller::InputPress | 1 | El usuario pulsó el dispositivo de entrada (p. ej., QEvent::MouseButtonPress, QEvent::GraphicsSceneMousePress, QEvent::TouchBegin) |
QScroller::InputMove | 2 | El usuario ha movido el dispositivo de entrada (p. ej., QEvent::MouseMove, QEvent::GraphicsSceneMouseMove, QEvent::TouchUpdate) |
QScroller::InputRelease | 3 | El 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.
| Constante | Valor | Descripción |
|---|---|---|
QScroller::TouchGesture | 0 | El 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::LeftMouseButtonGesture | 1 | El reconocedor de gestos solo se activará ante eventos del botón izquierdo del ratón. |
QScroller::MiddleMouseButtonGesture | 3 | El reconocedor de gestos solo se activará ante eventos del botón central del ratón. |
QScroller::RightMouseButtonGesture | 2 | El 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.
| Constante | Valor | Descripción |
|---|---|---|
QScroller::Inactive | 0 | El control de desplazamiento no se está desplazando y no se ha pulsado nada. |
QScroller::Pressed | 1 | Se 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::Dragging | 2 | El área de desplazamiento está siguiendo actualmente el punto de contacto o el ratón. |
QScroller::Scrolling | 3 | El á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); }); 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); }); 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); }); 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); }); [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.