TapHandler QML Type

Gestionnaire des tapotements et des clics. En savoir plus...

• 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 des tapotements sur un écran tactile ou des clics de souris.

La détection d’un geste de tap valide dépend de la valeur de ` gesturePolicy`. La valeur par défaut est `DragThreshold`, qui exige que la pression et le relâchement soient proches l’un de l’autre, tant dans l’espace que dans le temps. Dans ce cas, TapHandler peut fonctionner en utilisant uniquement une capture passive et n’interfère donc pas avec la transmission d’événements à d’autres éléments ou gestionnaires d’entrée. L’ 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 liaisons et/ou des callbacks JavaScript.

Notez que les boutons (tels que QPushButton) sont souvent implémentés de manière à ne pas tenir compte de la proximité entre l’appui et le relâchement : si vous appuyez sur le bouton puis changez d’avis, vous devez faire glisser votre doigt jusqu’au bord du bouton pour annuler le clic. Pour ce cas d’utilisation, définissez l’ 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
    }
}

Pour les gestes à tapotements multiples (double tapotement, triple tapotement, etc.), la distance parcourue ne doit pas dépasser QStyleHints::mouseDoubleClickDistance() avec la souris et QStyleHints::touchDoubleTapDistance() avec le tactile, et le délai entre les tapotements ne doit pas dépasser QStyleHints::mouseDoubleClickInterval().

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

Documentation sur les propriétés

acceptedButtons : flags

Les boutons de la souris pouvant 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 des autres boutons.

Par exemple, un contrôle peut être configuré pour réagir différemment aux clics gauche et droit, à l’aide de deux gestionnaires :

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

acceptedDevices : flags

Les types de périphériques de pointage pouvant activer ce gestionnaire de pointeur.

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

Par exemple, un contrôle pourrait être configuré pour répondre d’une certaine manière aux clics de souris et de stylet, et d’une autre manière aux tapotements sur un écran tactile, à l’aide de 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, les événements liés au pointeur ne seront pris en compte que si les touches de modification spécifiées sont enfoncées ; dans le cas contraire, ils seront ignorés.

Si cette propriété est définie sur « Qt.KeyboardModifierMask » (valeur par défaut), l’ PointerHandler ignore les touches de modification.

Item Par exemple, une pourrait comporter deux gestionnaires du même type, dont l’un n’est activé que si les touches de modification requises sont enfoncées :

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

Si vous définissez « acceptedModifiers » sur 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 touches de modification disponibles sont les suivantes :

Si vous avez besoin d'un comportement encore plus complexe que celui pouvant être obtenu avec des combinaisons de plusieurs gestionnaires et de plusieurs indicateurs de modificateurs, 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.) pouvant 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 périphériques non correspondants devices.

Par exemple, un contrôle pourrait être configuré pour réagir d'une certaine manière aux clics de souris, aux touches tactiles et aux clics de stylet, mais s’effacer s’il est touché avec un outil « gomme » sur une tablette graphique, grâce à 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]

Cette propriété prend la valeur « true » dès lors que ce gestionnaire d’entrée a pris la responsabilité exclusive de la gestion d’un ou plusieurs « eventPoints », en ayant réussi à les «saisir» de manière exclusive. Cela signifie qu’il maintient ses propriétés à jour en fonction des mouvements de ces «eventPoints» et qu’il manipule activement ses « target » (le cas échéant).

cursorShape : Qt::CursorShape

Cette propriété définit la forme du curseur qui s'affichera chaque fois que la souris survolera l'élément parent, à condition que active soit défini sur true.

Les formes de curseur disponibles sont les suivantes :

• Qt.ArrowCursor
• Qt.UpArrowCursor
• Qt.CrossCursor
• Qt.WaitCursor
• Qt.IBeamCursor
• Qt.SizeVerCursor
• Qt.CursorTailleHoriz
• Qt.SizeBDiagCursor
• Qt.SizeFDiagCursor
• Qt.SizeAllCursor
• Qt.CurseurVide
• Qt.CursorDiviséVertical
• Qt.CursorDiviséHorizontal
• Qt.CursorMainPointante
• Qt.CursorInterdit
• Qt.Cursor« Qu'est-ce que c'est ? »
• Qt.Curseur-occupé
• Qt.CursorMainOuverte
• Qt.CurseurMainFermée
• Qt.CurseurGlisserCopier
• Qt.CurseurGlisserDéplacer
• Qt.DragLinkCursor

La valeur par défaut n'est pas définie, ce qui permet d'afficher l'élément « cursor » de l'parent. Cette propriété peut être réinitialisée à son état initial en lui attribuant la valeur « undefined ».

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

dragThreshold : int

Distance en pixels sur laquelle l'utilisateur doit faire glisser un élément « eventPoint » pour que ce mouvement soit interprété comme un geste de glissement.

La valeur par défaut dépend de la plateforme et de la résolution de l'écran. Elle peut être réinitialisée à sa valeur par défaut en la définissant sur « undefined ». Le comportement lors du 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'une PointerHandler est définie sur « disabled », le gestionnaire sera également désactivé de fait, même si la propriété « enabled » reste définie sur « 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 s’ajoute à la contrainte selon laquelle le relâchement doit avoir lieu avant l’expiration de ` longPressThreshold `. Si ces contraintes ne sont pas respectées, le signal ` tapped ` n’est pas émis et ` tapCount ` n’est pas incrémenté. En cas de violation de la contrainte spatiale, ` pressed ` passe immédiatement de `true` à `false`, quelle que soit la durée de maintien.

L’ gesturePolicy e influe également sur le comportement de la prise, 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"
}

La section « Exemples d’Qt Quick s – Gestionnaires de pointeur » présente quelques cas d’utilisation de ces fonctionnalités.

grabPermissions : flags

Cette propriété définit les autorisations lorsque la logique de ce gestionnaire décide de prendre le contrôle exclusif, ou lorsqu'il est sollicité pour approuver la prise de contrôle ou l'annulation de celle-ci par un autre gestionnaire.

La valeur par défaut est « PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything », ce qui autorise la plupart des scénarios de prise de contrôle tout en évitant, par exemple, que deux PinchHandlers se disputent les mêmes points de contact.

longPressThreshold : real

Durée en secondes pendant laquelle une eventPoint doit être maintenue enfoncée pour déclencher un geste de pression prolongée et émettre le signal longPressed(), si la valeur est supérieure à 0. Si la est relâchée avant l'expiration de ce délai, un tap peut être détecté si la contrainte gesturePolicy est respectée. Si longPressThreshold vaut 0, le chronomètre est désactivé et le signal ne sera 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 située au-delà des limites de l'élément « parent », à l'intérieur de laquelle un « eventPoint » peut activer ce gestionnaire. Par exemple, sur une « PinchHandler » où le « target » correspond également à l’« parent », il est utile de définir cette distance à au moins la moitié de la largeur du doigt d’un utilisateur type, afin que, si la « parent » a été réduite à une très petite taille, le geste de pincement reste possible. De même, si un bouton basé sur l’ TapHandler est placé près du bord de l’écran, cela permet de respecter la loi de Fitts : réagir aux clics de souris au bord de l’écran même si le bouton est visuellement espacé de quelques pixels par rapport à ce bord.

La valeur par défaut est 0.

parent : Item

L'objet « Item », qui correspond à la portée du gestionnaire ; l'« Item » dans lequel il a été déclaré. Le gestionnaire traitera les événements pour le compte de cet « Item », 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'« Item ». Au départ, target() est identique, mais il peut être réattribué.

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

point : handlerPoint [read-only]

L'eventPoint e actuellement sélectionné. Lorsqu'aucun point n'est sélectionné, cet objet est réinitialisé à ses valeurs par défaut (toutes les coordonnées sont égales à 0).

pressed : bool [read-only]

Cette valeur reste vraie tant que le bouton de la souris ou le point de contact est enfoncé et que tout mouvement effectué depuis cet enfoncement respecte la politique actuelle gesturePolicy. Lorsque le bouton eventPoint est relâché ou que la politique n'est plus respectée, la valeur « pressed » passe à « false ».

tapCount : int [read-only]

Nombre de tapotements survenus dans les limites de temps et d'espace définies 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 va manipuler.

Par défaut, il s’agit de l’ parent, c’est-à-dire l’élément au sein duquel le gestionnaire est déclaré. Cependant, il peut parfois être utile de définir la cible sur un autre élément, afin de gérer les événements au sein d’un élément tout en manipulant un autre ; ou de l’ null, pour désactiver le comportement par défaut et effectuer une autre action à la place.

timeHeld : real [read-only]

Durée, exprimée en secondes, pendant laquelle un point sélectionné a été maintenu enfoncé, sans dépasser le seuil de glissement. Cette valeur est mise à jour au moins une fois par image rendue, ce qui permet de générer une animation illustrant la progression vers une action qui sera déclenchée par un appui prolongé. Il est également possible de déclencher l’une des actions d’une série en fonction de la durée de l’appui.

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

Documentation sur les signaux

canceled(eventPoint point)

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

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 à une courte distance (QStyleHints::mouseDoubleClickDistance() ou QStyleHints::touchDoubleTapDistance()). Ce signal se produit toujours après singleTapped, tapped et tapCountChanged. Le paramètre de signal « eventPoint » contient des informations issues de l'événement de relâchement concernant le point qui a été touché, et « button » correspond à l'élément « mouse button » sur lequel on a cliqué, ou à « NoButton » sur un écran tactile.

grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

Ce signal est émis lorsque le « grab » a subi une modification pertinente pour ce gestionnaire.

Le verbe « transition » indique ce qui s'est passé. L'objet « point » correspond au point qui a été sélectionné ou désélectionné.

Les valeurs valides pour « transition » sont :

longPressed()

Ce signal est émis lorsque l'élément « parent » est maintenu enfoncé pendant une durée supérieure à longPressThreshold. Autrement dit, si vous maintenez enfoncé un point tactile ou un bouton, sans que le mouvement ne dépasse le seuil de glissement, le signal « longPressed » sera émis dès que timeHeld dépassera longPressThreshold.

singleTapped(eventPoint eventPoint, Qt::MouseButton button)

Ce signal est émis lorsqu'on appuie une fois sur l'élément « parent ». Après un délai supérieur à QStyleHints::mouseDoubleClickInterval, il est possible d'appuyer à nouveau ; mais si le délai jusqu'au prochain appui est inférieur, tapCount augmentera. Le paramètre de signal eventPoint contient des informations issues de l'événement de relâchement concernant le point sur lequel on a appuyé, et button correspond à l'mouse button sur laquelle on a cliqué, ou à NoButton sur un écran tactile.

tapCountChanged()

Ce signal est émis lorsque l'élément « parent » est touché une ou plusieurs fois (dans un intervalle de temps et de distance spécifiés) et lorsque l'tapCount actuelle diffère de la précédente tapCount.

tapped(eventPoint eventPoint, Qt::MouseButton button)

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

Autrement dit, si vous appuyez puis relâchez un point tactile ou un bouton dans un délai inférieur à longPressThreshold, sans que le mouvement ne dépasse le seuil de glissement, le signal tapped sera émis au moment du relâchement. Le paramètre du signal eventPoint contient des informations issues de l'événement de relâchement concernant le point sur lequel on a appuyé, et button correspond à l'mouse button sur lequel on a 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)
    }
}