PinchHandler QML Type

Gestor de gestos de pellizco. Más...

• Lista de todos los miembros, incluidos los heredados
• Miembros obsoletos

Propiedades

• acceptedDevices : flags
• acceptedModifiers : flags
• acceptedPointerTypes : flags
• active : bool
• activeRotation : real
• activeScale : real
• activeTranslation : point
• centroid : QtQuick::handlerPoint
• cursorShape : Qt::CursorShape
• dragThreshold : int
• enabled : bool
• grabPermissions : flags
• margin : real
• parent : Item
• persistentRotation : real
• persistentScale : real
• persistentTranslation : point
• rotationAxis
  • rotationAxis.activeValue : real
  • rotationAxis.enabled : bool
  • rotationAxis.maximum : real
  • rotationAxis.minimum : real
• scaleAxis
  • scaleAxis.activeValue : real
  • scaleAxis.enabled : bool
  • scaleAxis.maximum : real
  • scaleAxis.minimum : real
• target : Item
• xAxis
  • xAxis.activeValue : real
  • xAxis.enabled : bool
  • xAxis.maximum : real
  • xAxis.minimum : real
• yAxis
  • yAxis.activeValue : real
  • yAxis.enabled : bool
  • yAxis.maximum : real
  • yAxis.minimum : real

Señales

• canceled(eventPoint point)
• grabChanged(PointerDevice::GrabTransition transition, eventPoint point)
• rotationChanged(qreal delta)
• scaleChanged(qreal delta)
• translationChanged(QVector2D delta)

Descripción detallada

PinchHandler es un manejador que interpreta un gesto con varios dedos para rotar, hacer zoom y arrastrar interactivamente un Item. Como otros Manejadores de Entrada, por defecto es completamente funcional, y manipula su target, que es el Item dentro del cual es declarado.

import QtQuick

Rectangle {
    width: 400
    height: 300
    color: "lightsteelblue"
    PinchHandler { }
}

Tiene propiedades para restringir el rango de arrastre, rotación y zoom.

Si se declara dentro de un elemento pero se le asigna un target diferente, maneja los eventos dentro de los límites del elemento exterior pero manipula el elemento target en su lugar:

import QtQuick

Item {
    width: 640
    height: 480

    Rectangle {
        id: map
        color: "aqua"
        width: 400
        height: 300
    }

    PinchHandler {
        target: map
    }
}

Una tercera forma de utilizarlo es establecer target a null y reaccionar a los cambios de propiedades de alguna otra manera:

import QtQuick

Window {
    width: 320; height: 240
    visible: true
    title: handler.persistentRotation.toFixed(1) + "° " +
           handler.persistentTranslation.x.toFixed(1) + ", " +
           handler.persistentTranslation.y.toFixed(1) + " " +
           (handler.persistentScale * 100).toFixed(1) + "%"

    PinchHandler {
        id: handler
        target: null
        persistentScale: 0.25
        onTranslationChanged: (delta) => {
            image.x -= delta.x
            image.y -= delta.y
        }
    }

    Image {
        id: image
        source: "images/album-cover.jpg"
        scale: handler.persistentScale
        x: -600; y: -450
    }
}

Véase también PinchArea, QPointerEvent::pointCount(), QNativeGestureEvent::fingerCount(), y Qt Quick Ejemplos - Manejadores de puntero.

Documentación de propiedades

acceptedDevices : flags

Los tipos de dispositivos señaladores que pueden activar este Manejador de Punteros.

Por defecto, esta propiedad se establece en PointerDevice.AllDevices. Si se establece en una combinación OR de tipos de dispositivos, se ignorarán los eventos de los dispositivos que no coincidan.

Por ejemplo, se puede hacer que un control responda a los clics del ratón y del lápiz de una manera, y a los toques de la pantalla táctil de otra, con dos manejadores:

Item {
   TapHandler {
       acceptedDevices: PointerDevice.Mouse | PointerDevice.TouchPad | PointerDevice.Stylus
       onTapped: console.log("clicked")
   }
   TapHandler {
       acceptedDevices: PointerDevice.TouchScreen
       onTapped: console.log("tapped")
   }
}

acceptedModifiers : flags

Si se establece esta propiedad, requerirá que se pulsen los modificadores de teclado dados para reaccionar a los eventos de puntero, y en caso contrario los ignorará.

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

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

Item {
   TapHandler {
       acceptedModifiers: Qt.ControlModifier | Qt.AltModifier | Qt.ShiftModifier
       onTapped: console.log("control-alt-shift-tapped")
   }
}

Los modificadores disponibles son los siguientes:

Si necesita un comportamiento aún más complejo que el que se puede conseguir con combinaciones de múltiples manejadores con múltiples indicadores de modificador, puede 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 señaladores (dedo, stylus, borrador, etc.) que pueden activar este Manejador de Punteros.

Por defecto, esta propiedad se establece en PointerDevice.AllPointerTypes. Si se establece en una combinación OR de tipos de dispositivos, ignorará los eventos de los que no coincidan devices.

Por ejemplo, se puede hacer que un control responda de alguna manera a los clics del ratón, el tacto y el lápiz óptico, pero que se borre si se toca con una herramienta de borrado en una tableta gráfica, con dos manejadores:

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]

Esta propiedad es true cuando se satisfacen todas las restricciones (especialmente minimumPointCount y maximumPointCount) y se manipula el target, si existe.

activeRotation : real [read-only]

La rotación del gesto de pellizcar en grados, con valores positivos en el sentido de las agujas del reloj. Es 0 cuando comienza el gesto. Si target no es nulo, se añadirá automáticamente a su rotation. De lo contrario, se pueden utilizar bindings para hacer cosas arbitrarias con este valor.

Véase también QtQuick::PinchHandler::rotationAxis.activeValue.

activeScale : real [read-only]

El factor de escala mientras se realiza el gesto de pellizcar. Es 1,0 cuando comienza el gesto, aumenta a medida que los puntos de contacto se separan y disminuye a medida que los puntos de contacto se juntan. Si target no es nulo, su scale se multiplicará automáticamente por este valor. En caso contrario, se pueden utilizar bindings para hacer cosas arbitrarias con este valor.

Véase también QtQuick::PinchHandler::scaleAxis.activeValue.

activeTranslation : point [read-only]

La traslación del grupo de puntos mientras se realiza el gesto de pellizcar. Es 0, 0 cuando comienza el gesto, y aumenta a medida que eventPoint(s) se arrastra hacia abajo y hacia la derecha. Una vez finalizado el gesto, se mantiene igual; y cuando comienza el siguiente gesto de pellizco, se restablece a 0, 0 de nuevo.

centroid : QtQuick::handlerPoint [read-only]

Un punto situado exactamente en el centro de los puntos táctiles pulsados en ese momento. target girará en torno a este punto.

cursorShape : Qt::CursorShape

Esta propiedad contiene la forma del cursor que aparecerá siempre que el ratón pase por encima del 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.

dragThreshold : int

La distancia en píxeles que el usuario debe arrastrar un eventPoint para que se trate como un gesto de arrastre.

El valor por defecto depende de la plataforma y de la resolución de pantalla. Se puede restablecer al valor por defecto estableciéndolo como indefinido. El comportamiento cuando comienza un gesto de arrastre varía en los distintos manejadores.

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. Por ejemplo, en un PinchHandler en el que el target es también el parent, es útil establecerlo a una distancia de al menos la mitad de la anchura 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 pellizcar siga siendo posible. O, si se coloca un botón basado en TapHandler cerca del borde de la pantalla, puede utilizarse para cumplir 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.

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().

persistentRotation : real

La rotación que se aplicará a target si no es nula. En caso contrario, se pueden utilizar bindings para hacer cosas arbitrarias con este valor. Mientras se realiza el gesto de pellizcar, activeRotation se añade continuamente; una vez finalizado el gesto, permanece igual; y cuando comienza el siguiente gesto de pellizcar, comienza a modificarse de nuevo por activeRotation.

Es posible establecer esta propiedad, como una forma de sincronizar la rotación de la base con una rotación que fue establecida de alguna otra manera, por ejemplo por otro manejador. Si estableces esta propiedad directamente, activeRotation no cambia, y se emite rotationChanged(0).

persistentScale : real

El factor de escala que se establecerá automáticamente en target si no es nulo. En caso contrario, se pueden utilizar bindings para hacer cosas arbitrarias con este valor. Mientras se realiza el gesto de pellizcar, se multiplica continuamente por activeScale; una vez finalizado el gesto, permanece igual; y cuando comienza el siguiente gesto de pellizcar, comienza a multiplicarse de nuevo por activeScale.

Es posible establecer esta propiedad, como una forma de sincronizar la escala base con una escala que fue establecida de alguna otra forma, por ejemplo por otro manejador. Si estableces esta propiedad directamente, activeScale no cambia, y se emite scaleChanged(1).

persistentTranslation : point

La traducción que se aplicará a target si no es null. En caso contrario, se pueden utilizar bindings para hacer cosas arbitrarias con este valor. Mientras se realiza el gesto de pellizcar, activeTranslation se le añade continuamente; una vez finalizado el gesto, permanece igual.

Es posible establecer esta propiedad, como una forma de sincronizar la traducción base con una traducción que fue establecida de alguna otra manera, por ejemplo por otro manejador. Si estableces esta propiedad directamente, activeTranslation no cambia, y se emite translationChanged({0, 0}).

rotationAxis group

rotationAxis controla las restricciones para establecer la rotation del elemento target en función de la rotación del grupo de puntos de contacto.

minimum es la rotación mínima aceptable. maximum es la rotación máxima aceptable. Si enabled es verdadero, la rotación está permitida. activeValue es lo mismo que QtQuick::PinchHandler::activeRotation.

La señal activeValueChanged se emite cuando cambia activeValue, para proporcionar el incremento por el que ha cambiado. Esto está pensado para ajustar incrementalmente una propiedad a través de múltiples manejadores.

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"; antialiasing: true

    PinchHandler {
        id: handler
        target: null
        xAxis.onActiveValueChanged: (delta) => parent.radius -= delta
        yAxis.onActiveValueChanged: (delta) => parent.border.width += delta
        rotationAxis.onActiveValueChanged: (delta) => parent.rotation += delta // add
        scaleAxis.onActiveValueChanged: (delta) => parent.scale *= delta // multiply
    }

    WheelHandler {
        acceptedModifiers: Qt.NoModifier
        property: "rotation"
    }

    WheelHandler {
        acceptedModifiers: Qt.ControlModifier
        property: "scale"
    }
}

scaleAxis group

scaleAxis controla las restricciones para establecer la scale del elemento target en función de la distancia entre los puntos de contacto.

minimum es la escala mínima aceptable. maximum es la escala máxima aceptable. Si enabled es verdadero, la escala está permitida. activeValue es lo mismo que QtQuick::PinchHandler::activeScale.

La señal activeValueChanged se emite cuando cambia activeValue, para proporcionar el multiplicador del cambio incremental. Esto está pensado para ajustar incrementalmente una propiedad a través de múltiples manejadores.

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"; antialiasing: true

    PinchHandler {
        id: handler
        target: null
        xAxis.onActiveValueChanged: (delta) => parent.radius -= delta
        yAxis.onActiveValueChanged: (delta) => parent.border.width += delta
        rotationAxis.onActiveValueChanged: (delta) => parent.rotation += delta // add
        scaleAxis.onActiveValueChanged: (delta) => parent.scale *= delta // multiply
    }

    WheelHandler {
        acceptedModifiers: Qt.NoModifier
        property: "rotation"
    }

    WheelHandler {
        acceptedModifiers: Qt.ControlModifier
        property: "scale"
    }
}

target : Item

Elemento que manipulará este controlador.

Por defecto, es el mismo que parent, el Item dentro del cual se declara el manejador. Sin embargo, a veces puede ser útil establecer el objetivo a un elemento diferente, con el fin de manejar eventos dentro de un elemento pero manipular otro; o a null, para desactivar el comportamiento por defecto y hacer otra cosa en su lugar.

xAxis group

xAxis controla las restricciones para la traslación horizontal del elemento target.

minimum es la coordenada x mínima aceptable de la traslación. maximum es la coordenada x máxima aceptable de la traslación. Si enabled es verdadero, se permite el arrastre horizontal.

La señal activeValueChanged se emite cuando cambia activeValue, para proporcionar el incremento por el que ha cambiado. Esto está pensado para ajustar incrementalmente una propiedad a través de múltiples manejadores.

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"; antialiasing: true

    PinchHandler {
        id: handler
        target: null
        xAxis.onActiveValueChanged: (delta) => parent.radius -= delta
        yAxis.onActiveValueChanged: (delta) => parent.border.width += delta
        rotationAxis.onActiveValueChanged: (delta) => parent.rotation += delta // add
        scaleAxis.onActiveValueChanged: (delta) => parent.scale *= delta // multiply
    }

    WheelHandler {
        acceptedModifiers: Qt.NoModifier
        property: "rotation"
    }

    WheelHandler {
        acceptedModifiers: Qt.ControlModifier
        property: "scale"
    }
}

yAxis group

yAxis controla las restricciones para la traslación vertical del elemento target.

minimum es la coordenada y mínima aceptable de la traslación. maximum es la coordenada y máxima aceptable de la traslación. Si enabled es verdadero, se permite el arrastre vertical.

La señal activeValueChanged se emite cuando cambia activeValue, para proporcionar el incremento por el que ha cambiado. Esto está pensado para ajustar incrementalmente una propiedad a través de múltiples manejadores.

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"; antialiasing: true

    PinchHandler {
        id: handler
        target: null
        xAxis.onActiveValueChanged: (delta) => parent.radius -= delta
        yAxis.onActiveValueChanged: (delta) => parent.border.width += delta
        rotationAxis.onActiveValueChanged: (delta) => parent.rotation += delta // add
        scaleAxis.onActiveValueChanged: (delta) => parent.scale *= delta // multiply
    }

    WheelHandler {
        acceptedModifiers: Qt.NoModifier
        property: "rotation"
    }

    WheelHandler {
        acceptedModifiers: Qt.ControlModifier
        property: "scale"
    }
}

Documentación de 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:

rotationChanged(qreal delta)

La señal rotationChanged se emite cuando cambia activeRotation (y por tanto persistentRotation). El valor delta da el cambio aditivo en la rotación. Por ejemplo, si el usuario mueve los dedos para cambiar la distancia de pellizco de forma que activeRotation cambia de 10 a 30 grados, se emitirá rotationChanged(20). Puedes utilizarlo para cambiar incrementalmente la rotación de un elemento:

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"

    PinchHandler {
        id: handler
        target: null
        onRotationChanged: (delta) => parent.rotation += delta // add
        onScaleChanged: (delta) => parent.scale *= delta // multiply
    }
}

scaleChanged(qreal delta)

La señal scaleChanged se emite cuando cambia activeScale (y por tanto persistentScale). El valor delta da el cambio multiplicativo en la escala. Por ejemplo, si el usuario mueve los dedos para cambiar la distancia de pellizco de modo que activeScale cambie de 2 a 2,5, se emitirá scaleChanged(1.25). Puedes utilizarlo para cambiar incrementalmente la escala de un elemento:

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"

    PinchHandler {
        id: handler
        target: null
        onRotationChanged: (delta) => parent.rotation += delta // add
        onScaleChanged: (delta) => parent.scale *= delta // multiply
    }
}

translationChanged(QVector2D delta)

La señal translationChanged se emite cuando cambia activeTranslation (y por tanto persistentTranslation). El vector delta da el cambio en la traslación. Puedes usarlo para cambiar incrementalmente la posición de un elemento:

import QtQuick

Window {
    width: 320; height: 240
    visible: true
    title: handler.persistentRotation.toFixed(1) + "° " +
           handler.persistentTranslation.x.toFixed(1) + ", " +
           handler.persistentTranslation.y.toFixed(1) + " " +
           (handler.persistentScale * 100).toFixed(1) + "%"

    PinchHandler {
        id: handler
        target: null
        persistentScale: 0.25
        onTranslationChanged: (delta) => {
            image.x -= delta.x
            image.y -= delta.y
        }
    }

    Image {
        id: image
        source: "images/album-cover.jpg"
        scale: handler.persistentScale
        x: -600; y: -450
    }
}