TapHandler QML Type

Gestionnaire pour les taps et les clics. Plus d'informations...

• Liste de tous les membres, y compris les membres hérités

Propriétés

• 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

Signaux

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

Description détaillée

TapHandler est un gestionnaire de tapotements sur un écran tactile ou de clics sur une souris.

La détection d'un geste de tapotement valide dépend de gesturePolicy. La valeur par défaut est DragThreshold, qui exige que la pression et le relâchement soient proches à la fois dans l'espace et dans le temps. Dans ce cas, TapHandler peut fonctionner en utilisant uniquement une saisie passive et n'interfère donc pas avec la transmission d'événements à d'autres éléments ou gestionnaires d'entrée. Le site gesturePolicy par défaut est donc utile lorsque vous souhaitez modifier le comportement d'un contrôle ou d'un élément existant en ajoutant un TapHandler avec des liens et/ou des rappels JavaScript.

Notez que les boutons (tels que QPushButton) sont souvent implémentés sans se soucier de savoir si la pression et le relâchement sont rapprochés : si vous appuyez sur le bouton et que vous changez ensuite d'avis, vous devez faire glisser le bouton jusqu'à son bord pour annuler le clic. Pour ce cas d'utilisation, réglez le site gesturePolicy sur 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
    }
}

), la distance parcourue ne doit pas dépasser QStyleHints::mouseDoubleClickDistance() avec la souris et QStyleHints::touchDoubleTapDistance() avec le toucher, et le temps entre les tapes ne doit pas dépasser QStyleHints::mouseDoubleClickInterval().

Voir également MouseArea et Qt Quick Exemples - Gestionnaires de pointeurs.

Documentation sur les propriétés

acceptedButtons : flags

Les boutons de la souris qui peuvent activer ce gestionnaire de pointeur.

Par défaut, cette propriété est définie sur Qt.LeftButton. Elle peut être définie sur une combinaison OU de boutons de souris, et ignorera les événements provenant d'autres boutons.

Par exemple, un contrôle peut être conçu pour répondre aux clics gauche et droit de manière différente, avec deux gestionnaires :

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

acceptedDevices : flags

Types de dispositifs de pointage pouvant activer ce gestionnaire de pointeurs.

Par défaut, cette propriété est définie sur PointerDevice.AllDevices. Si vous la définissez sur une combinaison OU de types de périphériques, elle ignorera les événements provenant de périphériques non correspondants.

Par exemple, un contrôle peut répondre aux clics de souris et de stylet d'une certaine manière, et aux pressions sur l'écran tactile d'une autre manière, avec deux gestionnaires :

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

acceptedModifiers : flags

Si cette propriété est définie, il faudra appuyer sur les modificateurs de clavier donnés pour réagir aux événements de pointeur, et les ignorer dans le cas contraire.

Si la valeur de cette propriété est Qt.KeyboardModifierMask (valeur par défaut), PointerHandler ignore les touches de modification.

Par exemple, un site Item peut avoir deux gestionnaires du même type, dont l'un n'est activé que si les modificateurs de clavier requis sont enfoncés :

Item {
   TapHandler {
       acceptedModifiers: Qt.ControlModifier
       onTapped: console.log("control-tapped")
   }
   TapHandler {
       acceptedModifiers: Qt.NoModifier
       onTapped: console.log("tapped")
   }
}

Si vous attribuez à acceptedModifiers une combinaison OU de touches de modification, cela signifie que toutes ces touches doivent être enfoncées pour activer le gestionnaire :

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

Les modificateurs disponibles sont les suivants :

Si vous avez besoin d'un comportement encore plus complexe que celui que l'on peut obtenir en combinant plusieurs gestionnaires avec plusieurs indicateurs de modification, vous pouvez vérifier les modificateurs dans le code 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;
            }
    }
}

Voir également Qt::KeyboardModifier.

acceptedPointerTypes : flags

Les types d'instruments de pointage (doigt, stylet, gomme, etc.) qui peuvent activer ce gestionnaire de pointeur.

Par défaut, cette propriété est définie sur PointerDevice.AllPointerTypes. Si vous la définissez sur une combinaison OU de types de périphériques, elle ignorera les événements provenant de devices qui ne correspondent pas.

Par exemple, un contrôle pourrait répondre aux clics de la souris, du toucher et du stylet d'une certaine manière, mais s'effacer s'il est tapé avec une gomme sur une tablette graphique, avec deux gestionnaires :

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]

Il s'agit de true chaque fois que ce gestionnaire d'entrée a pris l'entière responsabilité de la transmission d'un ou de plusieurs eventPoints, en s'emparant avec succès de ces points de manière exclusive. Cela signifie qu'il tient ses propriétés à jour en fonction des mouvements de ces eventPoints et qu'il manipule activement son site target (le cas échéant).

cursorShape : Qt::CursorShape

Cette propriété définit la forme du curseur qui apparaîtra lorsque la souris survolera l'élément parent alors que active est true.

Les formes de curseur disponibles sont les suivantes :

• 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.ClosedHandCursor
• Qt.DragCopyCursor
• Qt.DragMoveCursor
• Qt.DragLinkCursor

La valeur par défaut n'est pas définie, ce qui permet à l'élément cursor de parent d'apparaître. Cette propriété peut être ramenée à la même condition initiale en lui attribuant la valeur undefined.

Voir également Qt::CursorShape, QQuickItem::cursor() et HoverHandler::cursorShape.

dragThreshold : int

La distance en pixels sur laquelle l'utilisateur doit faire glisser une page eventPoint pour que cela soit considéré comme un geste de glissement.

La valeur par défaut dépend de la plate-forme et de la résolution de l'écran. Elle peut être ramenée à la valeur par défaut en lui attribuant la valeur undefined. Le comportement au début d'un geste de glissement varie selon les gestionnaires.

enabled : bool

Si un PointerHandler est désactivé, il rejettera tous les événements et aucun signal ne sera émis.

Si la propriété parent d'un PointerHandler est disabled, le gestionnaire sera également désactivé, même si la propriété enabled reste true.

exclusiveSignals : enumeration [since 6.5]

Détermine l'exclusivité des signaux singleTapped() et doubleTapped().

Cette propriété a été introduite dans Qt 6.5.

gesturePolicy : enumeration

La contrainte spatiale pour qu'un geste de tapotement ou d'appui long soit reconnu, en plus de la contrainte selon laquelle le relâchement doit se produire avant que longPressThreshold ne se soit écoulé. Si ces contraintes ne sont pas satisfaites, le signal tapped n'est pas émis et tapCount n'est pas incrémenté. Si la contrainte spatiale n'est pas respectée, pressed passe immédiatement de vrai à faux, quel que soit le temps écoulé.

L'adresse gesturePolicy affecte également le comportement de la benne comme décrit ci-dessous.

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

Le site Qt Quick Examples - Pointer Handlers présente quelques cas d'utilisation.

grabPermissions : flags

Cette propriété spécifie les autorisations lorsque la logique de ce gestionnaire décide de prendre en charge la saisie exclusive, ou lorsqu'il lui est demandé d'approuver la prise en charge ou l'annulation de la saisie par un autre gestionnaire.

La valeur par défaut est PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything, ce qui permet la plupart des scénarios de prise en charge mais évite, par exemple, que deux PinchHandler ne se disputent les mêmes points de contact.

longPressThreshold : real

Temps en secondes pendant lequel un eventPoint doit être pressé pour déclencher un geste de pression longue et émettre le signal longPressed(), si la valeur est supérieure à 0. Si le point est relâché avant cette limite de temps, un tapotement peut être détecté si la contrainte gesturePolicy est satisfaite. Si longPressThreshold est 0, la minuterie est désactivée et le signal n'est pas émis. Si longPressThreshold est défini sur undefined, la valeur par défaut est utilisée à la place et peut être lue à partir de cette propriété.

La valeur par défaut est QStyleHints::mousePressAndHoldInterval() convertie en secondes.

margin : real

La marge au-delà des limites de l'élément parent dans laquelle un eventPoint peut activer ce gestionnaire. Par exemple, sur un site PinchHandler où le site target est également le site parent, il est utile de fixer cette distance à au moins la moitié de la largeur du doigt d'un utilisateur typique, de sorte que si le site parent a été réduit à une taille très petite, le geste de pincement reste possible. Par ailleurs, si un bouton basé sur TapHandler est placé près du bord de l'écran, il peut être utilisé pour respecter la loi de Fitts : réagir aux clics de souris sur le bord de l'écran même si le bouton est visuellement éloigné du bord de quelques pixels.

La valeur par défaut est 0.

parent : Item

Le Item qui est la portée du gestionnaire ; l'élément dans lequel il a été déclaré. Le gestionnaire traitera les événements au nom de cet élément, ce qui signifie qu'un événement de pointeur est pertinent si au moins l'un de ses eventPoints se produit à l'intérieur de l'élément. Initialement, target() est le même, mais il peut être réaffecté.

Voir également target et QObject::parent().

point : handlerPoint [read-only]

Le site eventPoint en cours de traitement. Si aucun point n'est en cours de traitement, cet objet est réinitialisé aux valeurs par défaut (toutes les coordonnées sont à 0).

pressed : bool [read-only]

La valeur est maintenue à vrai lorsque la souris ou le point de contact est enfoncé et que tout mouvement effectué depuis l'enfoncement est conforme à la politique en vigueur gesturePolicy. Lorsque l'adresse eventPoint est relâchée ou que la politique est enfreinte, la mention "pressé " passe à "faux".

tapCount : int [read-only]

Le nombre d'appuis qui se sont produits dans les contraintes de temps et d'espace pour être considérés comme un seul geste. Le compteur est remis à 1 si le bouton a changé. Par exemple, pour détecter un triple tapotement, vous pouvez écrire :

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

target : Item

L'élément que ce gestionnaire manipulera.

Par défaut, il est identique à parent, l'élément dans lequel le gestionnaire est déclaré. Cependant, il peut parfois être utile de définir la cible sur un élément différent, afin de gérer des événements dans un élément mais d'en manipuler un autre ; ou de null, pour désactiver le comportement par défaut et faire quelque chose d'autre à la place.

timeHeld : real [read-only]

Temps en secondes pendant lequel un point appuyé a été maintenu, sans dépasser le seuil de déplacement. Il sera mis à jour au moins une fois par image rendue, ce qui permet de rendre une animation montrant la progression vers une action qui sera déclenchée par un appui long. Il est également possible de déclencher une série d'actions en fonction de la durée de l'appui.

Une valeur inférieure à zéro signifie qu'aucun point n'est maintenu dans le cadre de ce gestionnaire Item.

Documentation sur les signaux

canceled(eventPoint point)

Si ce gestionnaire a déjà saisi l'objet donné point, ce signal est émis lorsque la saisie est volée par un autre gestionnaire de pointeurs ou un autre objet.

doubleTapped(eventPoint eventPoint, Qt::MouseButton button)

Ce signal est émis lorsque l'élément parent est touché deux fois dans un court laps de temps (QStyleHints::mouseDoubleClickInterval()) et sur une courte distance (QStyleHints::mouseDoubleClickDistance() ou QStyleHints::touchDoubleTapDistance()). Ce signal est toujours émis après singleTapped, tapped et tapCountChanged. Le paramètre de signal eventPoint contient des informations sur l'événement de relâchement concernant le point qui a été tapé, et button est le mouse button qui a été cliqué, ou NoButton sur un écran tactile.

grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

Ce signal est émis lorsque le grab a changé d'une manière ou d'une autre, ce qui est pertinent pour ce gestionnaire.

Le transition (verbe) indique ce qui s'est passé. Le point (objet) est le point qui a été saisi ou désaisi.

Les valeurs valides pour transition sont les suivantes

longPressed()

Ce signal est émis lorsque l'élément parent est pressé et maintenu pendant une période supérieure à longPressThreshold. En d'autres termes, si vous pressez et maintenez un point de contact ou un bouton, alors que tout mouvement ne dépasse pas le seuil de glissement, le signal longPressed sera émis au moment où timeHeld dépassera longPressThreshold.

singleTapped(eventPoint eventPoint, Qt::MouseButton button)

Ce signal est émis lorsque l'élément parent est touché une fois. Après un temps supérieur à QStyleHints::mouseDoubleClickInterval, il peut être tapé à nouveau ; mais si le temps avant le prochain tapage est inférieur, tapCount augmentera. Le paramètre de signal eventPoint contient des informations sur l'événement de relâchement concernant le point qui a été touché, et button est le mouse button qui a été cliqué, ou NoButton sur un écran tactile.

tapCountChanged()

Ce signal est émis lorsque l'élément parent est tapé une ou plusieurs fois (dans un intervalle de temps et de distance spécifié) et lorsque l'élément actuel tapCount diffère de l'élément précédent tapCount.

tapped(eventPoint eventPoint, Qt::MouseButton button)

Ce signal est émis chaque fois que l'élément parent est touché.

En d'autres termes, si vous appuyez sur un point de contact ou un bouton et que vous le relâchez dans un délai inférieur à longPressThreshold, sans que le mouvement ne dépasse le seuil de traînée, le signal tapped sera émis au moment du relâchement. Le paramètre de signal eventPoint contient des informations sur l'événement de relâchement concernant le point qui a été touché, et button est le mouse button qui a été cliqué, ou NoButton sur un écran tactile.

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