En esta página

QTouchEvent Class

La clase QTouchEvent contiene parámetros que describen un evento táctil. Más información...

Cabecera: #include <QTouchEvent>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui
Heredado de: QPointerEvent

Funciones públicas

QTouchEvent(QEvent::Type eventType, const QPointingDevice *device = nullptr, Qt::KeyboardModifiers modifiers = Qt::NoModifier, const QList<QEventPoint> &touchPoints = {})
QObject *target() const
QEventPoint::States touchPointStates() const

Funciones públicas reimplementadas

virtual bool isBeginEvent() const override
virtual bool isEndEvent() const override
virtual bool isUpdateEvent() const override

Funciones protegidas

QTouchEvent(QTouchEvent &&)
QTouchEvent &operator=(QTouchEvent &&)
QTouchEvent &operator=(const QTouchEvent &other)

Descripción detallada

Habilitación de eventos táctiles

Los eventos táctiles se producen al pulsar, soltar o mover uno o más puntos táctiles en un dispositivo táctil (como una pantalla táctil o un trackpad). Para recibir eventos táctiles, los widgets deben tener el atributo « Qt::WA_AcceptTouchEvents » activado y los elementos gráficos deben tener el atributo « acceptTouchEvents » establecido en «true».

Al utilizar widgets basados en « QAbstractScrollArea », debes habilitar el atributo « Qt::WA_AcceptTouchEvents » en el « viewport » del área de desplazamiento.

De forma similar a ` QMouseEvent`, Qt captura automáticamente cada punto de contacto en la primera pulsación dentro de un widget, y el widget recibirá todas las actualizaciones de ese punto de contacto hasta que se suelte. Ten en cuenta que es posible que un widget reciba eventos de numerosos puntos de contacto, y que varios widgets puedan estar recibiendo eventos táctiles al mismo tiempo.

Gestión de eventos

Todos los eventos táctiles son de tipo QEvent::TouchBegin, QEvent::TouchUpdate, QEvent::TouchEnd o QEvent::TouchCancel. Reimplementa QWidget::event() o QAbstractScrollArea::viewportEvent() para los widgets y QGraphicsItem::sceneEvent() para los elementos de una vista gráfica a fin de recibir eventos táctiles.

A diferencia de los widgets, las ventanas QWindows reciben eventos táctiles siempre; no es necesario activarlos. Cuando se trabaja directamente con una ventana « QWindow », basta con reimplementar QWindow::touchEvent().

Los eventos « QEvent::TouchUpdate » y « QEvent::TouchEnd » se envían al widget o elemento que haya aceptado el evento « QEvent::TouchBegin ». Si el evento « QEvent::TouchBegin » no se acepta ni se filtra mediante un filtro de eventos, no se enviarán más eventos táctiles hasta el siguiente « QEvent::TouchBegin ».

Algunos sistemas pueden enviar un evento de tipo « QEvent::TouchCancel ». Al recibir este evento, se solicita a las aplicaciones que ignoren toda la secuencia táctil activa. Por ejemplo, en un sistema compuesto, el compositor puede decidir tratar ciertos gestos como gestos de todo el sistema. Siempre que se tome dicha decisión (se reconozca el gesto), se notificará a los clientes mediante un evento « QEvent::TouchCancel » para que puedan actualizar su estado en consecuencia.

Las funciones pointCount() y point() pueden utilizarse para acceder a los puntos táctiles individuales e iterar sobre ellos.

La función points() devuelve una lista de todos los puntos táctiles contenidos en el evento. Ten en cuenta que esta lista puede estar vacía, por ejemplo, en el caso de un evento QEvent::TouchCancel. Cada punto es una instancia de la clase QEventPoint. La enumeración QEventPoint::State describe los diferentes estados que puede tener un punto táctil.

Nota: La lista de points() nunca será parcial: un evento táctil siempre contendrá un punto táctil por cada contacto físico existente dirigido a la ventana o al widget al que se envía el evento. Por ejemplo, suponiendo que todos los toques tengan como objetivo la misma ventana o el mismo widget, un evento con la condición points().count()==2 garantiza que el número de dedos que tocan la pantalla táctil o el panel táctil sea exactamente dos.

Entrega y propagación de eventos

Por defecto, ` QGuiApplication ` convierte el primer punto de contacto de un `QTouchEvent` en un ` QMouseEvent`. Esto permite habilitar eventos táctiles en widgets existentes que normalmente no gestionan `QTouchEvent`. Consulta más abajo la información sobre algunas consideraciones especiales que hay que tener en cuenta al hacerlo.

QEvent::TouchBegin es el primer evento táctil enviado a un widget. El evento ` QEvent::TouchBegin ` contiene un indicador de aceptación especial que indica si el receptor desea el evento. Por defecto, el evento se acepta. Debe llamar a ` ignore()` si su widget no gestiona el evento táctil. El evento « QEvent::TouchBegin » se propaga hacia arriba por la cadena de widgets padres hasta que un widget lo acepta con « accept()» o hasta que un filtro de eventos lo consume. En el caso de los «QGraphicsItems», el evento « QEvent::TouchBegin » se propaga a los elementos situados bajo el ratón (de forma similar a la propagación de eventos de ratón para los «QGraphicsItems»).

Agrupación de puntos táctiles

Como se ha mencionado anteriormente, es posible que varios widgets reciban eventos `QTouchEvent` al mismo tiempo. Sin embargo, Qt se asegura de no enviar nunca eventos ` QEvent::TouchBegin ` duplicados al mismo widget, lo que teóricamente podría ocurrir durante la propagación si, por ejemplo, el usuario tocara dos widgets distintos en un ` QGroupBox ` y ambos widgets ignoraran el evento ` QEvent::TouchBegin `.

Para evitarlo, Qt agrupará los nuevos puntos de contacto siguiendo estas reglas:

  • Cuando se detecta el primer punto de contacto, el widget de destino se determina, en primer lugar, por la ubicación en la pantalla y, en segundo lugar, por las reglas de propagación.
  • Cuando se detectan puntos de contacto adicionales, Qt comprueba primero si hay algún punto de contacto activo en algún antepasado o descendiente del widget situado debajo del nuevo punto de contacto. Si los hay, el nuevo punto de contacto se agrupa con el primero, y el nuevo punto de contacto se enviará en un único QTouchEvent al widget que gestionó el primer punto de contacto. (El widget situado bajo el nuevo punto táctil no recibirá ningún evento).

Esto permite que los widgets hermanos gestionen los eventos táctiles de forma independiente, al tiempo que garantiza que la secuencia de QTouchEvents sea siempre correcta.

Eventos de ratón y síntesis de eventos táctiles

La entrega de QTouchEvent es independiente de la de QMouseEvent. Los indicadores de la aplicación Qt::AA_SynthesizeTouchForUnhandledMouseEvents y Qt::AA_SynthesizeMouseForUnhandledTouchEvents pueden utilizarse para habilitar o deshabilitar la síntesis automática de eventos táctiles en eventos de ratón y de eventos de ratón en eventos táctiles.

Advertencias

  • Como se ha mencionado anteriormente, habilitar los eventos táctiles significa que varios widgets pueden recibir eventos táctiles simultáneamente. En combinación con el manejo predeterminado de QWidget::event() para los QTouchEvents, esto te ofrece una gran flexibilidad a la hora de diseñar interfaces de usuario táctiles. Ten en cuenta las implicaciones. Por ejemplo, es posible que el usuario esté moviendo un QSlider con un dedo y pulsando un QPushButton con otro. Las señales emitidas por estos widgets se entremezclarán.
  • No se admite la recursión en el bucle de eventos mediante uno de los métodos exec() (por ejemplo, QDialog::exec() o QMenu::exec()) en un controlador de eventos QTouchEvent. Dado que hay varios receptores de eventos, la recursión puede causar problemas, entre los que se incluyen, entre otros, la pérdida de eventos y una recursión infinita inesperada.
  • Los QTouchEvents no se ven afectados por un mouse grab ni por un active pop-up widget. El comportamiento de los QTouchEvents es indefinido al abrir una ventana emergente o al capturar el ratón mientras hay más de un punto táctil activo.

Véase también QEventPoint, QEventPoint::State, Qt::WA_AcceptTouchEvents y QGraphicsItem::acceptTouchEvents().

Documentación de las funciones de miembro

[explicit] QTouchEvent::QTouchEvent(QEvent::Type eventType, const QPointingDevice *device = nullptr, Qt::KeyboardModifiers modifiers = Qt::NoModifier, const QList<QEventPoint> &touchPoints = {})

Crea un objeto `QTouchEvent` con los valores proporcionados de ` eventType`, ` device`, ` touchPoints` y el teclado actual ` modifiers ` en el momento del evento.

[protected delete] QTouchEvent::QTouchEvent(QTouchEvent &&)

Crea una instancia de ` QTouchEvent`. Esta función se ha eliminado.

[override virtual] bool QTouchEvent::isBeginEvent() const

Devuelve «true» si este evento incluye al menos un punto táctil pulsado recientemente.

[override virtual] bool QTouchEvent::isEndEvent() const

Devuelve «true» si este evento incluye al menos un punto de contacto publicado recientemente.

[override virtual] bool QTouchEvent::isUpdateEvent() const

Devuelve «true» si este evento no incluye puntos táctiles que se hayan pulsado o soltado recientemente.

QObject *QTouchEvent::target() const

Devuelve el objeto de destino dentro de la ventana en la que se produjo el evento. Normalmente se trata de un ` QWidget ` o un ` QQuickItem`. Puede ser 0 cuando no haya ningún destino específico disponible.

QEventPoint::States QTouchEvent::touchPointStates() const

Devuelve el OR bit a bit de todos los estados de los puntos táctiles para este evento.

[protected delete] QTouchEvent &QTouchEvent::operator=(QTouchEvent &&)

Asigna mediante «move» other a esta instancia de QTouchEvent. Esta función se elimina.

[noexcept protected default] QTouchEvent &QTouchEvent::operator=(const QTouchEvent &other)

Asigna por copia other a esta instancia de QTouchEvent.

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