PointHandler QML Type
Manejador para responder a un único punto de contacto. Más...
| Import Statement: | import QtQuick |
| Inherits: |
Propiedades
- acceptedButtons : flags
- acceptedDevices : flags
- acceptedModifiers : flags
- acceptedPointerTypes : flags
- active : bool
- cursorShape : Qt::CursorShape
- enabled : bool
- grabPermissions : flags
- margin : real
- parent : Item
- point : handlerPoint
- target : real
Señales
- canceled(eventPoint point)
- grabChanged(PointerDevice::GrabTransition transition, eventPoint point)
Descripción detallada
PointHandler se puede utilizar para mostrar información sobre un punto táctil o la posición del ratón, o para reaccionar de cualquier otra forma a los eventos del puntero.
Cuando se produce un evento de pulsación, cada instancia de PointHandler elige un único punto que aún no esté «ocupado» en ese momento: si la pulsación se produce dentro de los límites del « PointerHandler::parent » y ningún PointHandler «hermano» dentro del mismo « PointerHandler::parent » ha adquirido aún un «passive grab» sobre ese punto, y si se cumplen las demás restricciones, como « acceptedButtons », « acceptedDevices », etc., dicho punto es elegible y el PointHandler adquiere entonces un «passive grab». De este modo, el « PointerHandler::parent » actúa como un grupo exclusivo: puede haber varias instancias de «PointHandler», y el conjunto de puntos táctiles pulsados se distribuirá entre ellas. Cada «PointHandler» que haya elegido un punto para seguirlo tiene su propiedad « active » true. A continuación, continúa siguiendo el punto elegido hasta que se suelte: las propiedades de « point » se mantendrán actualizadas. Cualquier elemento (Item) puede vincularse a estas propiedades y, de este modo, seguir los movimientos del punto.
Al ser únicamente un «grabber» pasivo, tiene la capacidad de mantener una supervisión independiente de todos los movimientos. El «grab» pasivo no puede ser robado ni anulado, incluso cuando se detectan otros gestos y se producen «grabs» exclusivos.
Si tu objetivo es la vigilancia ortogonal de puntos de evento, una alternativa anterior era QObject::installEventFilter(), pero eso nunca ha sido una característica integrada de QtQuick: requiere algo de código C++, como una subclase de QQuickItem. PointHandler es más eficiente que eso, ya que solo se le enviarán eventos de puntero durante el proceso normal de entrega de eventos en QQuickWindow; mientras que un filtro de eventos necesita filtrar todos los QEvents de todos los tipos y, por lo tanto, se convierte en un posible cuello de botella en la entrega de eventos.
Un posible caso de uso es añadir este controlador a un «Item» transparente que se encuentre sobre el resto de la escena (al tener un valor alto de « z »), de modo que, cuando se pulse un punto por primera vez, se envíe primero a ese «Item» y a sus controladores, lo que brinda la oportunidad de realizar la captura pasiva lo antes posible. Dicho «Item» (como un panel de cristal que cubre toda la interfaz de usuario) puede ser un «parent» conveniente para otros «Items» que visualizan el tipo de respuesta reactiva que debe estar siempre en primer plano; y, del mismo modo, puede ser el «parent» de ventanas emergentes, popovers, cuadros de diálogo, etc. Si se va a utilizar de esa manera, puede resultar útil que tu archivo main.cpp utilice ` QQmlContext::setContextProperty()` para que el «panel de cristal» sea accesible por ID desde toda la interfaz de usuario, de modo que otros elementos y `PointHandlers` puedan asignarse a él como elemento padre.
import QtQuick
Window {
width: 480
height: 320
visible: true
Item {
id: glassPane
z: 10000
anchors.fill: parent
PointHandler {
id: handler
acceptedDevices: PointerDevice.TouchScreen | PointerDevice.TouchPad
target: Rectangle {
parent: glassPane
color: "red"
visible: handler.active
x: handler.point.position.x - width / 2
y: handler.point.position.y - height / 2
width: 20; height: width; radius: width / 2
}
}
}
}Al igual que todos los controladores de entrada, un «PointHandler» tiene una propiedad « target », que puede utilizarse como un lugar conveniente para colocar un «Item» de seguimiento de puntos; pero el «PointHandler» no manipulará automáticamente el elemento « target » de ninguna manera. Es necesario utilizar enlaces para que reaccione a « point ».
Nota: En macOS, PointHandler no reacciona de forma predeterminada a varios dedos en el trackpad, aunque sí reacciona a un punto pulsado (posición del ratón). Esto se debe a que macOS puede proporcionar reconocimiento nativo de gestos o puntos táctiles sin procesar, pero no ambos. Preferimos utilizar el evento de gestos nativo en PinchHandler, por lo que no queremos desactivarlo al habilitar el tacto. Sin embargo, MultiPointTouchArea sí habilita el tacto, desactivando así el reconocimiento de gestos nativo en toda la ventana; por lo tanto, es una alternativa si solo quieres reaccionar a todos los puntos táctiles, pero no necesitas la experiencia fluida de los gestos nativos.
Véase también MultiPointTouchArea, HoverHandler y Qt Quick Ejemplos: controladores de puntero.
Documentación de propiedades
acceptedButtons : flags
Los botones del ratón que pueden activar esta función PointHandler.
Por defecto, esta propiedad está configurada como « Qt.LeftButton ». Se puede configurar como una combinación OR de botones del ratón e ignorará los eventos en los que se pulsen o mantengan pulsados otros botones. Si se configura como « Qt.NoButton », significa que no tiene en cuenta los botones en absoluto e ignora los eventos sintéticos del ratón que provengan de cualquier dispositivo para el que ya esté gestionando un « eventPoint » auténtico.
import QtQuick
Item {
width: 480; height: 320
Rectangle {
color: handler.active ? "tomato" : "wheat"
x: handler.point.position.x - width / 2
y: handler.point.position.y - height / 2
width: 20; height: width; radius: width / 2
}
PointHandler {
id: handler
acceptedButtons: Qt.MiddleButton | Qt.RightButton
}
}Nota: En una pantalla táctil no hay botones, por lo que esta propiedad no impide que PointHandler reaccione a los puntos táctiles.
Nota: Por defecto, cuando esta propiedad tiene el valor « Qt.LeftButton », si se permite que un « PointerDevice » que no sea un ratón (como una pantalla táctil o el lápiz óptico de una tableta gráfica) genere eventos sintéticos de ratón, estos suelen indicar que se ha pulsado el botón izquierdo del ratón, y dichos eventos pueden desactivar temporalmente el « PointHandler » que ya estaba reaccionando a un « eventPoint » auténtico procedente del dispositivo. Resulta útil declarar
acceptedButtons: \c Qt.NoButtonpara evitar este problema. Véase también Qt::AA_SynthesizeMouseForUnhandledTouchEvents y Qt::AA_SynthesizeMouseForUnhandledTabletEvents.
acceptedDevices : flags
Los tipos de dispositivos señaladores que pueden activar esta PointHandler.
De forma predeterminada, esta propiedad está configurada en PointerDevice.AllDevices. Si la configuras con una combinación «O» de tipos de dispositivos, ignorará los eventos de los dispositivos que no coincidan con devices:
PointHandler {
id: handler
acceptedDevices: PointerDevice.TouchScreen | PointerDevice.TouchPad
target: Rectangle {
parent: glassPane
color: "red"
visible: handler.active
x: handler.point.position.x - width / 2
y: handler.point.position.y - height / 2
width: 20; height: width; radius: width / 2
}
}acceptedModifiers : flags
Si se establece esta propiedad, PointHandler requiere que se pulsen los modificadores de teclado indicados para responder a PointerEvents; en caso contrario, los ignora.
Si esta propiedad se establece en Qt.KeyboardModifierMask (el valor por defecto), entonces PointHandler ignora las teclas modificadoras.
Por ejemplo, un « Item » podría tener dos controladores, uno de los cuales solo se activaría si se pulsa el modificador de teclado requerido:
import QtQuick
Item {
id: feedbackPane
width: 480; height: 320
PointHandler {
id: control
acceptedModifiers: Qt.ControlModifier
cursorShape: Qt.PointingHandCursor
target: Rectangle {
parent: feedbackPane
color: control.active ? "indianred" : "khaki"
x: control.point.position.x - width / 2
y: control.point.position.y - height / 2
width: 20; height: width; radius: width / 2
}
}
PointHandler {
id: shift
acceptedModifiers: Qt.ShiftModifier | Qt.MetaModifier
cursorShape: Qt.CrossCursor
target: Rectangle {
parent: feedbackPane
color: shift.active ? "darkslateblue" : "lightseagreen"
x: shift.point.position.x - width / 2
y: shift.point.position.y - height / 2
width: 30; height: width; radius: width / 2
}
}
}Si se establece « acceptedModifiers » en una combinación «O» de teclas modificadoras, significa que deben pulsarse todas esas teclas modificadoras para activar el controlador.
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. |
Véase también Qt::KeyboardModifier.
acceptedPointerTypes : flags
Los tipos de instrumentos de selección (dedo, lápiz óptico, borrador, etc.) que pueden activar este PointHandler.
De forma predeterminada, esta propiedad está configurada en PointerDevice.AllPointerTypes. Si la configuras en una combinación «O» de tipos de dispositivos, ignorará los eventos de los dispositivos que no coincidan devices:
import QtQuick
Canvas {
id: canvas
width: 800
height: 600
antialiasing: true
renderTarget: Canvas.FramebufferObject
property var points: []
onPaint: {
if (points.length < 2)
return
var ctx = canvas.getContext('2d');
ctx.save()
ctx.strokeStyle = stylusHandler.active ? "blue" : "white"
ctx.lineCap = "round"
ctx.beginPath()
ctx.moveTo(points[0].x, points[0].y)
for (var i = 1; i < points.length; i++)
ctx.lineTo(points[i].x, points[i].y)
ctx.lineWidth = 3
ctx.stroke()
points = points.slice(points.length - 2, 1)
ctx.restore()
}
PointHandler {
id: stylusHandler
acceptedPointerTypes: PointerDevice.Pen
onPointChanged: {
canvas.points.push(point.position)
canvas.requestPaint()
}
}
PointHandler {
id: eraserHandler
acceptedPointerTypes: PointerDevice.Eraser
onPointChanged: {
canvas.points.push(point.position)
canvas.requestPaint()
}
}
Rectangle {
width: 10; height: 10
color: stylusHandler.active ? "green" : eraserHandler.active ? "red" : "beige"
}
}La sección «Qt Quick Examples - Pointer Handlers» incluye un ejemplo más complejo para dibujar en un Canvas con una tableta gráfica.
active : bool [read-only]
Esto se cumple true siempre que se satisfagan las restricciones y este PointHandler esté reaccionando. Esto significa que mantiene sus propiedades actualizadas en función de los movimientos del eventPoints que satisfacen las restricciones.
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 », siempre que « active » sea « true ».
Las formas de cursor disponibles son:
- Qt.ArrowCursor
- Qt.UpArrowCursor
- Qt.CrossCursor
- Qt.WaitCursor
- Qt.IBeamCursor
- Qt.CursorTamañoVertical
- Qt.CursorDeTamañoHorizontal
- Qt.SizeBDiagCursor
- Qt.SizeFDiagCursor
- Qt.SizeAllCursor
- Qt.Cursor en blanco
- Qt.CursorDivisiónVertical
- Qt.Cursor de división horizontal
- Qt.CursorManoSeñalando
- Qt.CursorProhibido
- Qt.CursorDeAyuda
- Qt.CursorOcupado
- Qt.Cursor de mano abierta
- Qt.Cursor de mano cerrada
- Qt.CursorDeArrastrarYCopiar
- Qt.Cursor de arrastrar y mover
- 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 ».
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 forma efectiva, 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 del mismo.
| 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 hacerse con 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 exclusivo. |
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.
El valor por defecto es 0.
import QtQuick
Item {
width: 480; height: 320
Rectangle {
anchors.fill: handlingContainer
anchors.margins: -handler.margin
color: "beige"
}
Rectangle {
id: handlingContainer
width: 200; height: 200
anchors.centerIn: parent
border.color: "green"
color: handler.active ? "lightsteelblue" : "khaki"
Text {
text: "X"
x: handler.point.position.x - width / 2
y: handler.point.position.y - height / 2
visible: handler.active
}
PointHandler {
id: handler
margin: 30
}
}
}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 «Item». Inicialmente, « target() » es el mismo, pero se puede reasignar.
Véase también target y QObject::parent().
point : handlerPoint [read-only]
El objeto « eventPoint » que se está gestionando actualmente. Cuando no se está gestionando ningún punto, este objeto se restablece a sus valores por defecto (todas las coordenadas son 0).
target : real
Una propiedad que permite alojar cómodamente un «Item» para manipularlo o mostrar información de respuesta. A diferencia de otros «Pointer Handlers», « PointHandler » no realiza ninguna acción por sí mismo con el « target »: normalmente es necesario crear enlaces reactivos a propiedades como « SinglePointHandler::point » y « PointHandler::active ». Si se declara aquí una instancia de «Item», es necesario establecer explícitamente su « parent », ya que « PointHandler » no es un «Item».
Por defecto, es el mismo que el parent, es decir, el Item en el que se declara el controlador.
Documentación de Signal
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 manejador 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 controlador ha sido asumido o cancelado. |
PointerDevice.GrabPassive | Este controlador ha adquirido un control pasivo para supervisar el point. |
PointerDevice.UngrabPassive | Este gestor 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.