MultiPointHandler QML Type
Manejador abstracto para eventos de puntero multipunto. Más información...
| Import Statement: | import QtQuick |
| Inherits: | |
| Inherited By: | |
| Status: | Technology preview |
Este tipo se encuentra en fase de vista previa tecnológica y está sujeto a cambios.
Propiedades
- acceptedButtons : flags
- acceptedDevices : flags
- acceptedModifiers : flags
- acceptedPointerTypes : flags
- active : bool
- centroid : QtQuick::handlerPoint
- cursorShape : Qt::CursorShape
- dragThreshold : int
- enabled : bool
- grabPermissions : flags
- margin : real
- maximumPointCount : int
- minimumPointCount : int
- parent : Item
- target : Item
Señales
- canceled(eventPoint point)
- grabChanged(PointerDevice::GrabTransition transition, eventPoint point)
Descripción detallada
Una clase intermedia (no registrada como tipo QML) para cualquier tipo de controlador que requiera y actúe sobre un número específico de puntos táctiles múltiples.
Documentación de propiedades
acceptedButtons : flags
Los botones del ratón que pueden activar este controlador de puntero.
Por defecto, esta propiedad está configurada como « Qt.LeftButton ». Se puede configurar con una combinación OR de botones del ratón, y ignorará los eventos de los demás botones.
Por ejemplo, se podría hacer que un control respondiera de forma diferente a los clics con el botón izquierdo y con el derecho, mediante dos controladores:
Item {
TapHandler {
onTapped: console.log("left clicked")
}
TapHandler {
acceptedButtons: Qt.RightButton
onTapped: console.log("right clicked")
}
}Nota: Tocar una pantalla táctil o pulsar con el lápiz óptico en una tableta gráfica emula el clic con el botón izquierdo del ratón. Este comportamiento se puede modificar mediante « acceptedDevices » o « acceptedPointerTypes ».
acceptedDevices : flags
Los tipos de dispositivos señaladores que pueden activar este gestor de puntero.
De forma predeterminada, esta propiedad está establecida en « PointerDevice.AllDevices ». Si se establece en una combinación «O» de tipos de dispositivos, ignorará los eventos procedentes de dispositivos que no coincidan.
Por ejemplo, se podría hacer que un control respondiera a los clics del ratón y del lápiz óptico de una forma, y a los toques en la pantalla táctil de otra, con dos controladores:
Item {
TapHandler {
acceptedDevices: PointerDevice.Mouse | PointerDevice.TouchPad | PointerDevice.Stylus
onTapped: console.log("clicked")
}
TapHandler {
acceptedDevices: PointerDevice.TouchScreen
onTapped: console.log("tapped")
}
}Nota: Todavíano todas las plataformas son capaces de distinguir entre ratón y panel táctil; y en aquellas que sí lo hacen, a menudo se desea que el comportamiento del ratón y del panel táctil sea el mismo.
acceptedModifiers : flags
Si se establece esta propiedad, será necesario pulsar los modificadores de teclado indicados para que la aplicación reaccione a los eventos del puntero; de lo contrario, los ignorará.
Si esta propiedad se establece en « Qt.KeyboardModifierMask » (el valor por defecto), el « PointerHandler » ignorará las teclas modificadoras.
Por ejemplo, un « Item » podría tener dos controladores del mismo tipo, uno de los cuales solo se activaría si se pulsan los modificadores de teclado requeridos:
Item {
TapHandler {
acceptedModifiers: Qt.ControlModifier
onTapped: console.log("control-tapped")
}
TapHandler {
acceptedModifiers: Qt.NoModifier
onTapped: console.log("tapped")
}
}Si se establece « acceptedModifiers » en una combinación «O» de teclas modificadoras, significa que deben pulsarse todas esas teclas para activar el controlador:
Item {
TapHandler {
acceptedModifiers: Qt.ControlModifier | Qt.AltModifier | Qt.ShiftModifier
onTapped: console.log("control-alt-shift-tapped")
}
}Los modificadores disponibles son los siguientes:
| Constante | Descripción |
|---|---|
NoModifier | No se permite ninguna tecla modificadora. |
ShiftModifier | Se debe pulsar la tecla Mayús del teclado. |
ControlModifier | Se debe pulsar la tecla Ctrl del teclado. |
AltModifier | Se debe pulsar la tecla Alt del teclado. |
MetaModifier | Se debe pulsar la tecla Meta del teclado. |
KeypadModifier | Se debe pulsar una tecla del teclado numérico. |
GroupSwitchModifier | Solo en X11 (a menos que se active en Windows mediante un argumento de línea de comandos). Se debe pulsar una tecla Mode_switch del teclado. |
KeyboardModifierMask | Al controlador no le importa qué modificadores se pulsen. |
Si necesitas un comportamiento aún más complejo del que se puede lograr con combinaciones de varios controladores con múltiples indicadores modificadores, puedes comprobar los modificadores en código JavaScript:
Item {
TapHandler {
onTapped:
switch (point.modifiers) {
case Qt.ControlModifier | Qt.AltModifier:
console.log("CTRL+ALT");
break;
case Qt.ControlModifier | Qt.AltModifier | Qt.MetaModifier:
console.log("CTRL+META+ALT");
break;
default:
console.log("other modifiers", point.modifiers);
break;
}
}
}Véase también Qt::KeyboardModifier.
acceptedPointerTypes : flags
Los tipos de instrumentos de señalación (dedo, lápiz óptico, borrador, etc.) que pueden activar este gestor de puntero.
Por defecto, esta propiedad está configurada en « PointerDevice.AllPointerTypes ». Si se configura con una combinación «OR» de tipos de dispositivos, ignorará los eventos procedentes de « devices » que no coincidan.
Por ejemplo, se podría hacer que un control respondiera de alguna manera a los clics del ratón, táctiles y del lápiz óptico, pero que se borrara a sí mismo si se le tocara con una herramienta de borrado en una tableta gráfica, mediante dos controladores:
Rectangle {
id: rect
TapHandler {
acceptedPointerTypes: PointerDevice.Generic | PointerDevice.Finger | PointerDevice.Pen
onTapped: console.log("clicked")
}
TapHandler {
acceptedPointerTypes: PointerDevice.Eraser
onTapped: rect.destroy()
}
}active : bool [read-only]
Esto se cumple true siempre que este gestor de entrada haya asumido la responsabilidad exclusiva de gestionar uno o varios « eventPoints », al haber conseguido una captura exclusiva de dichos puntos. Esto significa que mantiene sus propiedades actualizadas de acuerdo con los movimientos de esos «eventPoints» y que manipula activamente sus « target » (si los hay).
centroid : QtQuick::handlerPoint [read-only]
Un punto situado exactamente en el centro de los puntos táctiles pulsados en ese momento. Si solo hay un punto pulsado, coincide con ese punto. Un controlador que tenga un « target » normalmente lo transformará en relación con este punto.
cursorShape : Qt::CursorShape
Esta propiedad define la forma del cursor que aparecerá cada vez que el ratón se sitúe sobre el elemento « parent » mientras « active » tenga el valor « true ».
Las formas de cursor disponibles son:
- Qt.ArrowCursor
- Qt.UpArrowCursor
- Qt.CrossCursor
- Qt.WaitCursor
- Qt.IBeamCursor
- Qt.CursorVerticalDeTamaño
- Qt.CursorDeTamañoHorizontal
- Qt.SizeBDiagCursor
- Qt.SizeFDiagCursor
- Qt.SizeAllCursor
- Qt.Cursor en blanco
- Qt.CursorDivisiónVertical
- Qt.CursorDivisiónHorizontal
- Qt.CursorManoSeñalando
- Qt.CursorProhibido
- Qt.Cursor de ayuda
- Qt.CursorOcupado
- Qt.Cursor de mano abierta
- Qt.CursorManoCerrada
- Qt.CursorDeArrastrarYCopiar
- Qt.CursorArrastrarMover
- Qt.DragLinkCursor
El valor por defecto no está establecido, lo que permite que aparezca el « cursor » del elemento « parent ». Esta propiedad se puede restablecer a su estado inicial asignándole el valor «undefined».
Nota: Cuando esta propiedad no se ha establecido, o se ha establecido en ` undefined`, si se lee el valor, devolverá ` Qt.ArrowCursor`.
Véase también Qt::CursorShape, QQuickItem::cursor() y HoverHandler::cursorShape.
dragThreshold : int
La distancia en píxeles que el usuario debe arrastrar un « eventPoint » para que se considere un gesto de arrastre.
El valor por defecto depende de la plataforma y de la resolución de la pantalla. Se puede restablecer al valor por defecto estableciéndolo en «undefined». El comportamiento al iniciar un gesto de arrastre varía según los distintos controladores.
enabled : bool
Si se desactiva un « PointerHandler », rechazará todos los eventos y no se emitirá ninguna señal.
Si la propiedad « parent » de un « PointerHandler » tiene el valor « disabled », el controlador también quedará desactivado de hecho, incluso cuando la propiedad « enabled » siga teniendo el valor « true ».
Nota: HoverHandler se comporta de forma diferente: consulta la documentación de su propiedad enabled para obtener más información.
grabPermissions : flags
Esta propiedad especifica los permisos cuando la lógica de este controlador decide hacerse cargo del control exclusivo, o cuando otro controlador le solicita que apruebe la toma de control o la cancelación de dicho control.
| Constante | Descripción |
|---|---|
PointerHandler.TakeOverForbidden | Este controlador no toma ni concede permiso de control a ningún tipo de elemento o controlador. |
PointerHandler.CanTakeOverFromHandlersOfSameType | Este controlador puede tomar el control exclusivo de otro controlador de la misma clase. |
PointerHandler.CanTakeOverFromHandlersOfDifferentType | Este controlador puede tomar el control exclusivo de cualquier tipo de controlador. |
PointerHandler.CanTakeOverFromItems | Este controlador puede tomar el control exclusivo de cualquier tipo de elemento. |
PointerHandler.CanTakeOverFromAnything | Este controlador puede tomar el control exclusivo de cualquier tipo de elemento o controlador. |
PointerHandler.ApprovesTakeOverByHandlersOfSameType | Este controlador concede permiso a otro controlador de la misma clase para que adquiera el control. |
PointerHandler.ApprovesTakeOverByHandlersOfDifferentType | Este controlador concede permiso a cualquier tipo de controlador para que adquiera el control. |
PointerHandler.ApprovesTakeOverByItems | Este controlador permite que cualquier tipo de elemento adquiera el control. |
PointerHandler.ApprovesCancellation | Este controlador permitirá que su control se establezca en nulo. |
PointerHandler.ApprovesTakeOverByAnything | Este controlador permite que cualquier tipo de elemento o controlador tome el control. |
El valor por defecto es « PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything », lo que permite la mayoría de los casos de toma de control, pero evita, por ejemplo, que dos «PinchHandlers» compitan por los mismos puntos táctiles.
margin : real
El margen más allá de los límites del elemento « parent », dentro del cual un « eventPoint » puede activar este controlador. Por ejemplo, en un « PinchHandler » en el que el « target » es también el « parent », resulta útil establecer este valor en una distancia equivalente, como mínimo, a la mitad del ancho del dedo de un usuario típico, de modo que, si el « parent » se ha reducido a un tamaño muy pequeño, el gesto de pellizco siga siendo posible. O bien, si se coloca un botón basado en TapHandler cerca del borde de la pantalla, puede utilizarse para cumplir con la Ley de Fitts: reaccionar a los clics del ratón en el borde de la pantalla aunque el botón esté visualmente separado del borde por unos pocos píxeles.
El valor por defecto es 0.

maximumPointCount : int
El número máximo de puntos de contacto que puede utilizar este controlador.
Si hay un número mayor de puntos táctiles en contacto con el elemento « parent », se seleccionarán los puntos necesarios en el orden en que se hayan pulsado, y se ignorarán los puntos restantes.
Cualquier punto ignorado puede activar otros controladores de entrada que tengan restricciones diferentes, ya sea en el mismo elemento o en otros elementos.
El valor por defecto es el mismo que el de « minimumPointCount ».
minimumPointCount : int
El número mínimo de puntos de contacto necesarios para activar este controlador.
Si el número de puntos de contacto que están en contacto con el « parent » es menor, se ignorarán.
Cualquier punto ignorado puede activar otros controladores de entrada que tengan restricciones diferentes, tanto en el mismo elemento como en otros elementos.
El valor por defecto es 2.
parent : Item
El ` Item `, que es el ámbito del controlador; el `Item` en el que se declaró. El controlador gestionará los eventos en nombre de este `Item`, lo que significa que un evento de puntero es relevante si al menos uno de sus ` eventPoints ` tiene lugar dentro del interior del `Item`. Inicialmente, ` target() ` es el mismo, pero se puede reasignar.
Véase también target y QObject::parent().
target : Item
El elemento que este controlador manipulará.
Por defecto, es el mismo que el ` parent`, es decir, el elemento en el que se declara el controlador. Sin embargo, a veces puede resultar útil establecer el destino en un elemento diferente, con el fin de gestionar eventos en un elemento pero manipular otro; o bien en ` null`, para desactivar el comportamiento predeterminado y realizar otra acción en su lugar.
Documentación sobre señales
canceled(eventPoint point)
Si este gestor ya ha capturado el point indicado, esta señal se emite cuando otro gestor de punteros o elemento le arrebata la captura.
Nota: El controlador correspondiente es onCanceled.
grabChanged(PointerDevice::GrabTransition transition, eventPoint point)
Esta señal se emite cuando el «grab» ha sufrido algún cambio relevante para este controlador.
El verbo « transition » indica lo que ha ocurrido. El objeto « point » es el punto que se ha seleccionado o deseleccionado.
Los valores válidos para « transition » son:
| Constante | Descripción |
|---|---|
PointerDevice.GrabExclusive | Este controlador ha asumido la responsabilidad principal de gestionar el point. |
PointerDevice.UngrabExclusive | Este controlador ha renunciado a su control exclusivo anterior. |
PointerDevice.CancelGrabExclusive | El control exclusivo de este gestor ha sido asumido o cancelado. |
PointerDevice.GrabPassive | Este controlador ha adquirido un control pasivo para supervisar el point. |
PointerDevice.UngrabPassive | Este controlador ha cedido su control pasivo anterior. |
PointerDevice.CancelGrabPassive | El control pasivo anterior de este controlador ha finalizado de forma anómala. |
Nota: El controlador correspondiente es onGrabChanged.
© 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.