En esta página

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

Demostración de TapHandler con casillas de selección para los clics del ratón aceptados y opciones de política de gestos

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.

Tres botones con diferentes valores de «gesturePolicy» que lanzan globos, misiles y cazas

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.

Área táctil gris con la indicación de mantener pulsado para abrir el menú contextual

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.

Menú principal con una lista de doce demostraciones de controladores de puntero, entre las que se incluyen «tap», «multibuttons», «pieMenu», «single point handler», «hover sidebar» y «joystick».

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.

Mango rojo de un joystick que se arrastra con el dedo sobre una carcasa metálica oscura

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.

Dos bolas rojas con valores de velocidad que se muestran sobre un fondo negro

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.

Varios rectángulos con instrucciones sobre el gesto de pellizcar que muestran los valores de escala, rotación y traslación

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.

Mezclador de audio con cinco controles deslizantes verticales etiquetados como «Canal 1» a «Canal 5»

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.

Mapa del mundo en el que se muestran los continentes con información sobre la escala superpuesta

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.

Visor de código QML con control deslizante de tamaño de fuente que muestra el código de DragHandler y BoundaryRule

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.