En esta página

PointHandler QML Type

Manejador para responder a un único punto de contacto. Más...

Import Statement: import QtQuick
Inherits:

SinglePointHandler

Propiedades

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

para 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:

ConstanteDescripción
NoModifierNo se permite ninguna tecla modificadora.
ShiftModifierSe debe pulsar la tecla Mayús del teclado.
ControlModifierSe debe pulsar la tecla Ctrl del teclado.
AltModifierSe debe pulsar la tecla Alt del teclado.
MetaModifierSe debe pulsar la tecla «Meta» del teclado.
KeypadModifierSe debe pulsar una tecla del teclado numérico.
GroupSwitchModifierSolo 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.
KeyboardModifierMaskAl 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.

ConstanteDescripción
PointerHandler.TakeOverForbiddenEste controlador no toma ni concede permiso de control a ningún tipo de elemento o controlador.
PointerHandler.CanTakeOverFromHandlersOfSameTypeEste controlador puede hacerse con el control exclusivo de otro controlador de la misma clase.
PointerHandler.CanTakeOverFromHandlersOfDifferentTypeEste controlador puede tomar el control exclusivo de cualquier tipo de controlador.
PointerHandler.CanTakeOverFromItemsEste controlador puede tomar el control exclusivo de cualquier tipo de elemento.
PointerHandler.CanTakeOverFromAnythingEste controlador puede tomar el control exclusivo de cualquier tipo de elemento o controlador.
PointerHandler.ApprovesTakeOverByHandlersOfSameTypeEste controlador concede permiso a otro controlador de la misma clase para que adquiera el control.
PointerHandler.ApprovesTakeOverByHandlersOfDifferentTypeEste controlador concede permiso a cualquier tipo de controlador para que adquiera el control.
PointerHandler.ApprovesTakeOverByItemsEste controlador permite que cualquier tipo de elemento adquiera el control exclusivo.
PointerHandler.ApprovesCancellationEste controlador permitirá que su control se establezca en nulo.
PointerHandler.ApprovesTakeOverByAnythingEste 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:

ConstanteDescripción
PointerDevice.GrabExclusiveEste controlador ha asumido la responsabilidad principal de gestionar el point.
PointerDevice.UngrabExclusiveEste controlador ha renunciado a su control exclusivo anterior.
PointerDevice.CancelGrabExclusiveEl control exclusivo de este controlador ha sido asumido o cancelado.
PointerDevice.GrabPassiveEste controlador ha adquirido un control pasivo para supervisar el point.
PointerDevice.UngrabPassiveEste gestor ha cedido su control pasivo anterior.
PointerDevice.CancelGrabPassiveEl 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.