Gestos en widgets y la vista gráfica
Qt incluye un marco de trabajo para la programación de gestos que permite crear gestos a partir de una serie de eventos, independientemente de los métodos de entrada utilizados. Un gesto puede ser un movimiento concreto del ratón, una acción en una pantalla táctil o una serie de eventos procedentes de cualquier otra fuente. La naturaleza de la entrada, la interpretación del gesto y la acción que se lleva a cabo dependen de la elección del desarrollador.
Descripción general
QGesture es la clase central del marco de gestos de Qt, que proporciona un contenedor para la información sobre los gestos realizados por el usuario. ` QGesture ` expone propiedades que proporcionan información general común a todos los gestos, y estas pueden ampliarse para ofrecer información adicional específica de cada gesto. Los gestos comunes de desplazamiento, pellizco y deslizamiento están representados por clases especializadas: ` QPanGesture`, ` QPinchGesture ` y ` QSwipeGesture`.
Los desarrolladores también pueden implementar nuevos gestos creando subclases y ampliando la clase ` QGestureRecognizer `. Añadir compatibilidad con un nuevo gesto implica implementar código para reconocer el gesto a partir de los eventos de entrada. Esto se describe en la sección «Creación de tu propio reconocedor de gestos ».
Uso de gestos estándar con widgets
Los gestos se pueden habilitar para instancias de las subclases de QWidget y QGraphicsObject. Un objeto que acepta entradas de gestos se denomina «objeto de destino» a lo largo de toda la documentación.
Para habilitar un gesto en un objeto de destino, llama a su función ` QWidget::grabGesture()` o ` QGraphicsObject::grabGesture()` con un argumento que describa el tipo de gesto requerido. Los tipos estándar se definen mediante la enumeración ` Qt::GestureType ` e incluyen muchos gestos de uso común.
for (Qt::GestureType gesture : gestures)
grabGesture(gesture);En el código anterior, los gestos se configuran en el constructor del propio objeto de destino.
Gestión de eventos
Cuando el usuario realiza un gesto, se envían eventos QGestureEvent al objeto de destino, y estos pueden gestionarse reimplementando la función de gestión QWidget::event() para widgets o QGraphicsItem::sceneEvent() para objetos gráficos.
Dado que un objeto de destino puede suscribirse a más de un tipo de gesto, el objeto ` QGestureEvent ` puede contener más de un ` QGesture`, lo que indica que hay varios gestos posibles activos al mismo tiempo. En ese caso, corresponde al widget determinar cómo gestionar esos múltiples gestos y decidir si algunos deben cancelarse en favor de otros.
Cada QGesture contenido en un objeto QGestureEvent puede aceptarse (accept()) o ignorarse (ignore()) de forma individual o en su conjunto. Además, se pueden consultar los objetos de datos QGesture individuales (el estado) mediante varios métodos getter.
Procedimiento estándar para la gestión de eventos
Un ` QGesture ` se acepta por defecto cuando llega a tu widget. Sin embargo, es una buena práctica aceptar o rechazar siempre explícitamente un gesto. La regla general es que, si aceptas un gesto, lo estás utilizando. Si lo ignoras, significa que no te interesa. Ignorar un gesto puede implicar que se ofrezca a otro objeto de destino o que se cancele.
Cada « QGesture » pasa por varios estados; existe una forma bien definida de cambiar de estado; normalmente, la entrada del usuario es la causa de los cambios de estado (al iniciar y detener la interacción, por ejemplo), pero el widget también puede provocar cambios de estado.
La primera vez que se envía un « QGesture » concreto a un widget o a un elemento gráfico, se encontrará en el estado « Qt::GestureStarted ». La forma en que se gestione el gesto en este momento determina si se podrá interactuar con él más adelante.
- Aceptar el gesto significa que el widget actúa sobre él y que le seguirán gestos con el estado «Qt::GestureUpdated».
- Ignorar el gesto significará que nunca se te volverá a ofrecer. Se ofrecerá también a un widget o elemento padre.
- Llamar a `setGestureCancelPolicy()` sobre el gesto cuando se encuentra en su estado inicial y, además, ha sido aceptado, puede provocar que se cancelen otros gestos.
El uso de ` QGesture::CancelAllInContext ` para cancelar un gesto provocará que se cancelen todos los gestos, independientemente de su estado, a menos que se hayan aceptado explícitamente. Esto significa que se cancelarán los gestos activos en los elementos hijos. También significa que los gestos entregados en el mismo ` QGestureEvent ` se cancelarán si el widget los ignora. Esto puede ser una forma útil de filtrar todos los gestos excepto aquel que te interese.
Ejemplo de gestión de eventos
Para mayor comodidad, el ejemplo «Image Gestures» reimplementa la función general de gestión event() y delega los eventos de gestos a una función especializada gestureEvent():
bool ImageWidget::event(QEvent *event)
{
if (event->type() == QEvent::Gesture)
return gestureEvent(static_cast<QGestureEvent*>(event));
return QWidget::event(event);
}Los eventos de gestos entregados al objeto de destino pueden examinarse individualmente y tratarse de forma adecuada:
bool ImageWidget::gestureEvent(QGestureEvent *event)
{
qCDebug(lcExample) << "gestureEvent():" << event;
if (QGesture *swipe = event->gesture(Qt::SwipeGesture))
swipeTriggered(static_cast<QSwipeGesture *>(swipe));
else if (QGesture *pan = event->gesture(Qt::PanGesture))
panTriggered(static_cast<QPanGesture *>(pan));
if (QGesture *pinch = event->gesture(Qt::PinchGesture))
pinchTriggered(static_cast<QPinchGesture *>(pinch));
return true;
}Responder a un gesto es tan sencillo como obtener el objeto ` QGesture ` entregado en el ` QGestureEvent ` enviado al objeto de destino y examinar la información que contiene.
void ImageWidget::swipeTriggered(QSwipeGesture *gesture)
{
if (gesture->state() == Qt::GestureFinished) {
if (gesture->swipeAngle() < 45 || gesture->swipeAngle() > 225) {
// swipe direction right or down
qCDebug(lcExample) << "swipeTriggered(): angle"
<< gesture->swipeAngle() << "; swipe to next";
goNextImage();
} else {
// swipe direction left or up
qCDebug(lcExample) << "swipeTriggered(): angle"
<< gesture->swipeAngle() << "; swipe to previous";
goPrevImage();
}
update();
}
}En este caso, examinamos la dirección en la que el usuario ha deslizado el dedo sobre el widget y modificamos su contenido en consecuencia.
Creación de tu propio reconocedor de gestos
Añadir compatibilidad con un nuevo gesto implica crear y registrar un nuevo reconocedor de gestos. Dependiendo del proceso de reconocimiento del gesto, también puede implicar la creación de un nuevo objeto de gesto.
Para crear un nuevo reconocedor, debes crear una subclase de ` QGestureRecognizer ` con el fin de crear una clase de reconocedor personalizada. Hay una función virtual que debes reimplementar y otras dos que pueden reimplementarse según sea necesario.
Filtrado de eventos de entrada
La función recognize() debe reimplementarse. Esta función gestiona y filtra los eventos de entrada que llegan para los objetos de destino y determina si se corresponden o no con el gesto que busca el reconocedor.
Aunque la lógica para el reconocimiento de gestos se implementa en esta función, posiblemente utilizando una máquina de estados basada en las enumeraciones de ` Qt::GestureState `, puedes almacenar información persistente sobre el estado del proceso de reconocimiento en el objeto ` QGesture ` proporcionado.
Tu función ` recognize()` debe devolver un valor de ` QGestureRecognizer::Result ` que indique el estado del reconocimiento para un gesto y un objeto de destino determinados. Esto determina si un evento de gesto se enviará o no a un objeto de destino.
Gestos personalizados
Si decides representar un gesto mediante una subclase personalizada de ` QGesture `, tendrás que reimplementar la función ` create()` para crear instancias de tu clase de gestos en lugar de instancias estándar de ` QGesture `. Como alternativa, puedes utilizar instancias estándar de ` QGesture `, pero añadiéndoles propiedades dinámicas adicionales para expresar detalles específicos del gesto que deseas gestionar.
Restablecimiento de gestos
Si utilizas objetos de gestos personalizados que deben restablecerse o gestionarse de forma especial cuando se cancela un gesto, debes reimplementar la función reset() para realizar estas tareas especiales.
Ten en cuenta que los objetos ` QGesture ` solo se crean una vez para cada combinación de objeto de destino y tipo de gesto, y pueden reutilizarse cada vez que el usuario intente realizar el mismo tipo de gesto en el objeto de destino. Por ello, puede resultar útil reimplementar la función ` reset()` para limpiar los datos tras cada intento anterior de reconocimiento de un gesto.
Uso de un nuevo reconocedor de gestos
Para utilizar un reconocedor de gestos, cree una instancia de su subclase de ` QGestureRecognizer ` y regístrela en la aplicación mediante ` QGestureRecognizer::registerRecognizer()`. Un reconocedor para un tipo de gesto determinado puede eliminarse con ` QGestureRecognizer::unregisterRecognizer()`.
Más información
El ejemplo «Image Gestures » muestra cómo habilitar gestos para un widget en una sencilla aplicación de visualización de imágenes.
Los gestos en Qt Quick
Qt Quick no dispone de un reconocedor de gestos global genérico; en su lugar, los componentes individuales pueden responder a los eventos táctiles a su manera. Por ejemplo, ` PinchArea ` gestiona los gestos con dos dedos, ` Flickable ` sirve para desplazar contenido con un solo dedo y ` MultiPointTouchArea ` puede gestionar un número arbitrario de puntos táctiles y permite al desarrollador de la aplicación escribir código personalizado de reconocimiento de gestos.
© 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.