Qt Quick Ejemplos: controladores de puntero
Muestra cómo utilizar los controladores de entrada deQt Quick en componentes interactivos.
Qt Quick Controls contiene componentes predefinidos que son suficientes para muchos tipos de interfaces de usuario; sin embargo, en ocasiones puede que necesites escribir dichos componentes «desde cero». En ese caso, tendrás que hacer un uso intensivo de los controladores de puntero. Esta es una recopilación de pequeños ejemplos que muestran cómo implementar algunos patrones de interacción comunes y otros menos habituales.
Si compilas el ejemplo como un ejecutable, podrás seleccionar páginas desde un « ListView » de nivel superior. Los componentes « TouchpointFeedbackSprite » y « MouseFeedbackSprite » muestran cómo utilizar « PointHandler » para proporcionar información sobre lo que el usuario está haciendo con los dispositivos de puntero: estos componentes permanecen visibles en todo momento a lo largo del ejemplo y no interfieren con la interacción en ningún otro lugar. Estos componentes resultan muy útiles para reutilizarlos si alguna vez necesitas realizar un vídeo o una demostración en directo de una interfaz de usuario.
Como alternativa, algunos de los archivos QML individuales se pueden ejecutar desde la línea de comandos con la herramienta qml, a modo de recordatorio rápido para ver cómo se puede crear un tipo concreto de componente.
TapHandler

La página «tap» muestra cómo detectar toques en pantallas táctiles, pulsaciones prolongadas y clics del ratón con diferentes botones. También puedes probar los diferentes valores de « gesturePolicy ».
Botones de pulsación múltiple
En esta página hay tres componentes « Button » personalizados, con diferentes valores de « gesturePolicy »: un botón requiere que mantengas el dedo o el ratón dentro del botón durante todo el tiempo, desde que lo pulsas hasta que lo sueltas; otro se ejecutará incluso si arrastras fuera del botón y luego vuelves a arrastrar hacia dentro antes de soltarlo; y otro saldrá de su estado pulsado si arrastras un poco más allá de « system-wide drag threshold ». Si pruebas este ejemplo en una pantalla táctil, deberías poder interactuar con los tres botones al mismo tiempo con diferentes dedos.

Menú circular
Esta página muestra cómo crear un menú circular adaptado a pantallas táctiles que aparece con una animación al activarlo mediante una pulsación prolongada. Puedes seleccionar un elemento del menú arrastrando desde la posición central hacia uno de los sectores y soltando. Si arrastras fuera del menú, o sueltas en medio del mismo, no se selecciona nada. Si arrastras fuera del área de visualización gris, el menú se cancela.

PointHandler
En la página «single point handler», PointHandler proporciona información sobre algunas de las propiedades que se pueden encontrar en SinglePointHandler::point y handlerPoint::device. Si has compilado el ejemplo como un ejecutable, verás esta información al mismo tiempo que la de los PointHandlers del archivo principal pointerhandlers.qml.

La página «tablet canvas» utiliza PointHandler para detectar de forma única los distintos types of pointing devices, de modo que, si tienes una tableta gráfica conectada al ordenador, puedes dibujar en el elemento Canvas con diferentes tipos de lápiz óptico: bolígrafo, aerógrafo o rotulador. Puedes «borrar» trazos con el borrador del lápiz óptico (lo que aquí se consigue dibujando encima con el color de fondo). Varios « HoverHandlers » proporcionan información sobre qué tipo de lápiz óptico o borrador se ha detectado.
HoverHandler
La página «barra lateral de hover» muestra cómo detectar cuándo el ratón se sitúa sobre un componente de botón y su contenedor al mismo tiempo. La propagación se puede desactivar configurando la propiedad HoverHandler::blocking. Puedes probar aquí todas las combinaciones de HoverHandler y MouseArea para comparar cómo gestionan la detección de hover. Y se utiliza otro HoverHandler para mostrar la posición actual del ratón en coordenadas de escena.
También puedes comprobar que se activa el evento « HoverHandler » en la «plataforma» animada cada vez que esta se desliza por debajo del cursor del ratón.
DragHandler
La página «joystick» simplemente tiene un DragHandler que arrastra un Image. Un State con AnchorChanges desbloquea los anclajes para que sea posible arrastrar; y un AnchorAnimation anima el retorno del mando a la posición central al soltarlo.

La página «fling animation» muestra un uso de la propiedad DragHandler::centroid::velocity, que simplemente hace que el valor de QEventPoint::velocity() esté disponible en QML. El componente MomentumAnimation que se utiliza en este ejemplo muestra una forma de simular la física (impulso y fricción) sin recurrir a soluciones más complejas.

PinchHandler
La página «pinch» muestra varios PinchHandlers: algunos requieren dos dedos y otros tres, para realizar las operaciones habituales de escalado, rotación y traslación, con restricciones gestionadas a través de las propiedades «axis min» y «axis max» de ` PinchHandler`. Una de las instancias de ` PinchHandler ` se utiliza para manipular diferentes propiedades de ` Rectangle ` en lugar de la posición, la escala y la rotación. Diversas propiedades de ` PinchHandler ` se vinculan de diversas formas. Deberías poder manipular cada instancia de forma independiente. Algunos elementos también cuentan con DragHandlers y TapHandlers.

Interoperabilidad
Controladores deslizantes
La página «mixer» muestra el uso de varios controladores dentro de un delegado ListView. Puedes interactuar con varios componentes Slider simultáneamente y puedes deslizar el ListView lateralmente.
- Un ` DragHandler ` permite comenzar a arrastrar en cualquier punto a lo largo de la «pista» por la que puede deslizarse el control deslizante. Dado que el valor predeterminado de ` snapMode ` es `
DragHandler.SnapAuto`, el control se ajustará a una posición centrada bajo el ratón o el punto de contacto una vez que se haya arrastrado más allá de ` system-wide drag threshold`. - Un « WheelHandler » ajusta directamente la propiedad «
y» del control deslizante « Image ». - Un « BoundaryRule » impide que ni « DragHandler » ni « WheelHandler » arrastren el mando demasiado lejos.
- Un « TapHandler » ofrece un gesto más de lo que tendría un componente «
Slider» típico: puedes pulsar sobre el mando.

Mapa
La página «map» muestra cómo arrastrar, transformar y cambiar la escala de un ImageSVG. Deberías poder ampliar una ubicación concreta del mapa; y si el nivel de zoom cambia de forma significativa, se modifica Image::sourceSize para solicitar que el SVG se vuelva a renderizar con una resolución diferente. Al arrastrar verticalmente con dos dedos se activa un DragHandler que manipula una transformación Rotation para inclinar el mapa.

Fake Flickable
La página «Fake Flickable» recoge un intento de reproducir gran parte de la funcionalidad de Flickable mediante controladores de puntero discretos y animaciones. Flickable es un componente complejo, pero aquí puedes ver una forma de separar los comportamientos individuales que ofrece, por si deseas disponer solo de parte de la funcionalidad sin la complejidad.
También hay un componente «cajón» deslizable que contiene algunos controles más controlados mediante manejadores de puntero.

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