PointHandler QML Type

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

• Lista de todos los miembros, incluidos los heredados

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 de contacto o la posición del ratón, o para reaccionar de otra manera 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á "tomado" en ese momento: si la pulsación se produce dentro de los límites de PointerHandler::parent, y ningún PointHandler hermano dentro del mismo PointerHandler::parent ha adquirido aún un agarre pasivo en ese punto, y si se cumplen las demás restricciones como acceptedButtons, acceptedDevices etc., es elegible, y el PointHandler adquiere entonces un agarre pasivo. De este modo, PointerHandler::parent actúa como un grupo exclusivo: puede haber múltiples instancias de PointHandler, y el conjunto de puntos de contacto pulsados se distribuirá entre ellas. Cada PointHandler que ha elegido un punto para rastrear tiene su propiedad active true . A continuación, seguirá rastreando el punto elegido hasta su liberación: las propiedades de point se mantendrán actualizadas. Cualquier objeto puede vincularse a estas propiedades y seguir así los movimientos del punto.

Al ser sólo un agarrador pasivo, tiene la capacidad de mantener una supervisión independiente de todos los movimientos. El agarre pasivo no puede ser robado o anulado incluso cuando se detectan otros gestos y se producen agarres exclusivos.

Si su objetivo es la vigilancia ortogonal de eventpoints, una alternativa más antigua era QObject::installEventFilter(), pero eso nunca ha sido una característica incorporada en QtQuick: requiere algo de código C++, como una subclase de QQuickItem. PointHandler es más eficiente que eso, porque sólo los eventos de puntero le serán entregados, durante el curso de la entrega normal de eventos en QQuickWindow; mientras que un filtro de eventos necesita filtrar todos los QEvents de todos los tipos, y por lo tanto se establece como un potencial cuello de botella en la entrega de eventos.

Un posible caso de uso es añadir este manejador a un Item transparente que esté por encima del resto de la escena (por tener un alto valor z ), de forma que cuando un punto sea pulsado recientemente, será entregado a ese Item y a sus manejadores primero, proporcionando la oportunidad de tomar el agarre pasivo tan pronto como sea posible. Un elemento de este tipo (como un panel de vidrio sobre toda la interfaz de usuario) puede ser un padre conveniente para otros elementos que visualizan el tipo de retroalimentación reactiva que siempre debe estar en la parte superior; y del mismo modo puede ser el padre de ventanas emergentes, popovers, diálogos y así sucesivamente. Si se va a utilizar de esta forma, puede ser útil para tu main.cpp utilizar QQmlContext::setContextProperty() para hacer el "panel de cristal" accesible por ID a toda la UI, de forma que otros Items y PointHandlers puedan ser reparentados a él.

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
            }
        }
    }
}

Como todos los manejadores de entrada, un PointHandler tiene una propiedad target, que puede ser utilizada como un lugar conveniente para poner un elemento de seguimiento de puntos; pero PointHandler no manipulará automáticamente el elemento target de ninguna manera. Es necesario utilizar bindings para que reaccione a point.

Vea también MultiPointTouchArea, HoverHandler, y Qt Quick Ejemplos - Manejadores de Puntero.

Documentación de propiedades

acceptedButtons : flags

Los botones del ratón que pueden activar este PointHandler.

Por defecto, esta propiedad se establece en Qt.LeftButton. Puede establecerse en 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 establece en Qt.NoButton, significa que no le importan los botones en absoluto, e ignora los eventos sintéticos del ratón que provengan de cualquier dispositivo para el que ya esté manejando 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
    }
}

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 este PointHandler.

Por defecto, esta propiedad está establecida en PointerDevice.AllDevices. Si la establece en una combinación OR de tipos de dispositivos, ignorará los eventos de los que no coincidan 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 dados para reaccionar a PointerEvents, y en caso contrario los ignora.

Si esta propiedad está establecida a Qt.KeyboardModifierMask (el valor por defecto), entonces PointHandler ignora las teclas modificadoras.

Por ejemplo, un Item podría tener dos manejadores, uno de los cuales se activa sólo 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 configuras acceptedModifiers con una combinación OR de teclas modificadoras, significa que todos esos modificadores deben estar pulsados para activar el manejador.

Los modificadores disponibles son los siguientes

Véase también Qt::KeyboardModifier.

acceptedPointerTypes : flags

Los tipos de instrumentos señaladores (dedo, lápiz óptico, goma de borrar, etc.) que pueden activar este PointHandler.

Por defecto, esta propiedad se establece en PointerDevice.AllPointerTypes. Si se establece en una combinación OR de tipos de dispositivos, se ignorarán los eventos de los 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"
    }
}

El Qt Quick Ejemplos - Manejadores de Puntero incluye un ejemplo más complejo para dibujar en un Lienzo con una tableta gráfica.

active : bool [read-only]

Esto se mantiene true siempre que se satisfagan las restricciones y este PointHandler esté reaccionando. Esto significa que está manteniendo sus propiedades actualizadas de acuerdo a los movimientos del eventPoints que satisfacen las restricciones.

cursorShape : Qt::CursorShape

Esta propiedad contiene la forma del cursor que aparecerá siempre que el ratón se sitúe sobre el elemento parent mientras active esté true.

Las formas de cursor disponibles son:

• Qt.ArrowCursor
• Qt.UpArrowCursor
• Qt.CrossCursor
• Qt.WaitCursor
• Qt.IBeamCursor
• Qt.SizeVerCursor
• Qt.SizeHorCursor
• Qt.SizeBDiagCursor
• Qt.SizeFDiagCursor
• Qt.SizeAllCursor
• Qt.BlankCursor
• Qt.SplitVCursor
• Qt.SplitHCursor
• Qt.PointingHandCursor
• Qt.ForbiddenCursor
• Qt.WhatsThisCursor
• Qt.BusyCursor
• Qt.OpenHandCursor
• Qt.CursorManoCerrada
• Qt.DragCopyCursor
• Qt.DragMoveCursor
• Qt.DragLinkCursor

El valor por defecto no está establecido, lo que permite que aparezca el elemento cursor de parent. Esta propiedad puede restablecerse a la misma condición inicial estableciéndola a undefined.

Véase también Qt::CursorShape, QQuickItem::cursor(), y HoverHandler::cursorShape.

enabled : bool

Si un PointerHandler está desactivado, rechazará todos los eventos y no se emitirá ninguna señal.

Si un PointerHandler's parent es disabled, el manejador también será efectivamente desactivado, incluso cuando la propiedad enabled permanezca true.

grabPermissions : flags

Esta propiedad especifica los permisos cuando la lógica de este manejador decide hacerse cargo de la toma exclusiva, o cuando se le pide que apruebe la toma o cancelación de la toma por parte de otro manejador.

El valor predeterminado es PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything que permite la mayoría de los escenarios de toma, pero evita, por ejemplo, dos PinchHandlers luchando por los mismos puntos de contacto.

margin : real

El margen más allá de los límites del elemento parent dentro del cual un eventPoint puede activar este manejador.

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 manejador; el Item en el que fue declarado. El manejador manejará eventos en nombre de este Item, lo que significa que un evento de puntero es relevante si al menos uno de sus eventPoints ocurre dentro del interior del Item. Inicialmente target() es el mismo, pero puede ser reasignado.

Véase también target y QObject::parent().

point : handlerPoint [read-only]

El eventPoint que se está manejando actualmente. Cuando no se está gestionando ningún punto, este objeto se restablece a los valores por defecto (todas las coordenadas son 0).

target : real

Una propiedad que puede contener convenientemente un Item para ser manipulado o para mostrar retroalimentación. A diferencia de otros Manejadores de Puntero, PointHandler no hace nada con target por sí mismo: normalmente necesitas crear enlaces reactivos a propiedades como SinglePointHandler::point y PointHandler::active. Si declaras una instancia de Item aquí, necesitas establecer explícitamente su parent, porque PointHandler no es un Item.

Por defecto, es el mismo que parent, el elemento dentro del cual se declara el controlador.

Documentación sobre señales

canceled(eventPoint point)

Si este manejador ya ha agarrado el point dado, esta señal es emitida cuando el agarre es robado por un Manejador de Punteros o Item diferente.

grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

Esta señal se emite cuando la cuchara ha cambiado de alguna manera que es relevante para este controlador.

El transition (verbo) dice lo que ha pasado. El point (objeto) es el punto que fue agarrado o no agarrado.

Los valores válidos para transition son: