TapHandler QML Type

Manipulador de toques y clics. Más...

• Lista de todos los miembros, incluidos los heredados

Propiedades

• acceptedButtons : flags
• acceptedDevices : flags
• acceptedModifiers : flags
• acceptedPointerTypes : flags
• active : bool
• cursorShape : Qt::CursorShape
• dragThreshold : int
• enabled : bool
• exclusiveSignals : enumeration (since 6.5)
• gesturePolicy : enumeration
• grabPermissions : flags
• longPressThreshold : real
• margin : real
• parent : Item
• point : handlerPoint
• pressed : bool
• tapCount : int
• target : Item
• timeHeld : real

Señales

• canceled(eventPoint point)
• doubleTapped(eventPoint eventPoint, Qt::MouseButton button)
• grabChanged(PointerDevice::GrabTransition transition, eventPoint point)
• longPressed()
• singleTapped(eventPoint eventPoint, Qt::MouseButton button)
• tapCountChanged()
• tapped(eventPoint eventPoint, Qt::MouseButton button)

Descripción Detallada

TapHandler es un manejador para toques en una pantalla táctil o clics en un ratón.

La detección de un gesto de toque válido depende de gesturePolicy. El valor por defecto es DragThreshold, que requiere que la pulsación y la liberación estén próximas en el espacio y en el tiempo. En este caso, TapHandler es capaz de funcionar utilizando sólo un agarre pasivo, y por lo tanto no interfiere con la entrega de eventos a cualquier otro Elemento o Manejador de Entrada. Así que la opción por defecto gesturePolicy es útil cuando se quiere modificar el comportamiento de un control o Item existente añadiendo un TapHandler con bindings y/o callbacks JavaScript.

Tenga en cuenta que los botones (como QPushButton) a menudo se implementan sin tener en cuenta si la pulsación y la liberación se producen juntas: si pulsa el botón y luego cambia de opinión, necesita arrastrar todo el borde del botón para cancelar la pulsación. Para este caso, configure gesturePolicy en TapHandler.ReleaseWithinBounds.

import QtQuick

Rectangle {
    id: button
    signal clicked
    property alias text: buttonLabel.text

    height: Math.max(Screen.pixelDensity * 7, buttonLabel.implicitHeight * 1.2)
    width: Math.max(Screen.pixelDensity * 11, buttonLabel.implicitWidth * 1.3)
    radius: 3
    property color dark: Qt.darker(palette.button, 1.3)
    gradient: Gradient {
        GradientStop { position: 0.0; color: tapHandler.pressed ? dark : palette.button }
        GradientStop { position: 1.0; color: dark }
    }

    TapHandler {
        id: tapHandler
        gesturePolicy: TapHandler.ReleaseWithinBounds
        onTapped: button.clicked()
    }

    Text {
        id: buttonLabel
        text: "Click Me"
        color: palette.buttonText
        anchors.centerIn: parent
    }
}

Para los gestos multitoque (doble toque, triple toque, etc.), la distancia recorrida no debe superar QStyleHints::mouseDoubleClickDistance() con el ratón y QStyleHints::touchDoubleTapDistance() con el tacto, y el tiempo entre los toques no debe superar QStyleHints::mouseDoubleClickInterval().

Véase también MouseArea y Qt Quick Ejemplos - Manejadores de puntero.

Documentación de propiedades

acceptedButtons : flags

Los botones del ratón que pueden activar este manejador de puntero.

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 de otros botones.

Por ejemplo, se puede hacer que un control responda a los clicks izquierdo y derecho de diferentes maneras, con dos manejadores:

Item {
    TapHandler {
        onTapped: console.log("left clicked")
    }
    TapHandler {
        acceptedButtons: Qt.RightButton
        onTapped: console.log("right clicked")
    }
}

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, se ignorarán 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]

Esto se mantiene true siempre que este Manejador de Entrada haya tomado la responsabilidad exclusiva de manejar uno o más eventPoints, tomando con éxito un agarre exclusivo de esos puntos. Esto significa que está manteniendo sus propiedades actualizadas de acuerdo con los movimientos de esos eventPoints y manipulando activamente su target (si existe).

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.

exclusiveSignals : enumeration [since 6.5]

Determina la exclusividad de las señales singleTapped() y doubleTapped().

Esta propiedad se introdujo en Qt 6.5.

gesturePolicy : enumeration

La restricción espacial para que se reconozca un gesto de toque o pulsación larga, además de la restricción de que la liberación debe producirse antes de que haya transcurrido longPressThreshold. Si estas restricciones no se cumplen, la señal tapped no se emite y tapCount no se incrementa. Si se viola la restricción espacial, pressed pasa inmediatamente de verdadero a falso, independientemente del tiempo retenido.

gesturePolicy también afecta al comportamiento de la cuchara, como se describe a continuación.

Item {
    width: 120; height: 80

    component Button : Rectangle {
        TapHandler {
            id: tapHandler
            gesturePolicy: TapHandler.DragThreshold // the default
            onTapped: tapFlash.start()
        }
    }

    Button { x: 10; y: 10 }
    Button { x: 30; y: 30 }
}

TapHandler {
    id: tapHandler
    gesturePolicy: TapHandler.WithinBounds
    onTapped: tapFlash.start()
}

TapHandler {
    id: tapHandler
    gesturePolicy: TapHandler.ReleaseWithinBounds
    onTapped: tapFlash.start()
}

TapHandler {
    id: menuPopupHandler
    gesturePolicy: TapHandler.DragWithinBounds
    onPressedChanged:
        if (pressed) {
            menu.x = point.position.x - menu.width / 2
            menu.y = point.position.y - menu.height / 2
        } else {
            feedback.text = menu.highlightedMenuItem
            selectFlash.start()
        }
    onCanceled: feedback.text = "canceled"
}

En Qt Quick Examples - Pointer Handlers se muestran algunos casos de uso.

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.

longPressThreshold : real

El tiempo en segundos que debe pulsarse un punto eventPoint para desencadenar un gesto de pulsación larga y emitir la señal longPressed(), si el valor es superior a 0. Si el punto se suelta antes de este límite de tiempo, puede detectarse una pulsación si se cumple la restricción gesturePolicy. Si longPressThreshold es 0, el temporizador se desactiva y no se emite la señal. Si longPressThreshold es undefined, se utiliza en su lugar el valor por defecto, que puede leerse desde esta propiedad.

El valor por defecto es QStyleHints::mousePressAndHoldInterval() convertido a segundos.

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

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

pressed : bool [read-only]

Se mantiene como verdadero siempre que se pulsa el ratón o el punto táctil, y cualquier movimiento desde la pulsación es conforme con la actual gesturePolicy. Cuando se suelte eventPoint o se infrinja la política, presionado cambiará a falso.

tapCount : int [read-only]

El número de toques que se han producido dentro de las limitaciones de tiempo y espacio para ser considerado un solo gesto. El contador se pone a 1 si el botón ha cambiado. Por ejemplo, para detectar un triple toque, puede escribir:

Rectangle {
    width: 100; height: 30
    signal tripleTap
    TapHandler {
        acceptedButtons: Qt.AllButtons
        onTapped: if (tapCount == 3) tripleTap()
    }
}

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.

timeHeld : real [read-only]

La cantidad de tiempo en segundos que un punto pulsado se ha mantenido, sin moverse más allá del umbral de arrastre. Se actualizará al menos una vez por fotograma renderizado, lo que permite renderizar una animación mostrando el progreso hacia una acción que será disparada por una pulsación larga. También es posible desencadenar una de una serie de acciones dependiendo del tiempo que se mantenga pulsado.

Un valor inferior a cero significa que no se mantiene ningún punto dentro de este manejador Item.

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.

doubleTapped(eventPoint eventPoint, Qt::MouseButton button)

Esta señal se emite cuando el elemento parent se pulsa dos veces en un breve espacio de tiempo (QStyleHints::mouseDoubleClickInterval()) y distancia (QStyleHints::mouseDoubleClickDistance() o QStyleHints::touchDoubleTapDistance()). Esta señal se produce siempre después de singleTapped, tapped, y tapCountChanged. El parámetro de la señal eventPoint contiene información del evento de liberación sobre el punto que fue pulsado, y button es el mouse button que fue pulsado, o NoButton en una pantalla táctil.

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:

longPressed()

Esta señal se emite cuando se pulsa y se mantiene pulsado el elemento parent durante un periodo de tiempo superior a longPressThreshold. Es decir, si se pulsa y se mantiene pulsado un punto táctil o un botón, mientras que cualquier movimiento no supera el umbral de arrastre, entonces la señal longPressed se emitirá en el momento en que timeHeld supere longPressThreshold.

singleTapped(eventPoint eventPoint, Qt::MouseButton button)

Esta señal se emite cuando el elemento parent se toca una vez. Después de un tiempo superior a QStyleHints::mouseDoubleClickInterval, se puede volver a tocar; pero si el tiempo hasta la siguiente pulsación es inferior, tapCount aumentará. El parámetro de señal eventPoint contiene información del evento de liberación sobre el punto que fue tocado, y button es el mouse button que fue pulsado, o NoButton en una pantalla táctil.

tapCountChanged()

Esta señal se emite cuando el elemento parent se toca una o más veces (dentro de un intervalo de tiempo y distancia especificados) y cuando el tapCount actual difiere del tapCount anterior.

tapped(eventPoint eventPoint, Qt::MouseButton button)

Esta señal se emite cada vez que se pulsa el elemento parent.

Es decir, si se pulsa y suelta un punto táctil o botón en un periodo de tiempo inferior a longPressThreshold, mientras que cualquier movimiento no supere el umbral de arrastre, entonces se emitirá la señal tapped en el momento de la liberación. El parámetro de la señal eventPoint contiene información del evento de liberación sobre el punto que fue pulsado, y button es el mouse button que fue pulsado, o NoButton en una pantalla táctil.

import QtQuick

Rectangle {
    width: 100
    height: 100

    TapHandler {
        acceptedButtons: Qt.LeftButton | Qt.RightButton
        onTapped: (eventPoint, button)=> console.log("tapped", eventPoint.device.name,
                                             "button", button,
                                             "@", eventPoint.scenePosition)
    }
}