MouseArea QML Type

Permet une utilisation simple de la souris. En savoir plus...

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

Propriétés

• acceptedButtons : Qt::MouseButtons
• containsMouse : bool
• containsPress : bool
• cursorShape : Qt::CursorShape
• drag
  • drag.active : bool
  • drag.axis : enumeration
  • drag.filterChildren : bool
  • drag.maximumX : real
  • drag.maximumY : real
  • drag.minimumX : real
  • drag.minimumY : real
  • drag.smoothed : bool
  • drag.target : Item
  • drag.threshold : real
• enabled : bool
• hoverEnabled : bool
• mouseX : real
• mouseY : real
• pressAndHoldInterval : int
• pressed : bool
• pressedButtons : MouseButtons
• preventStealing : bool
• propagateComposedEvents : bool
• scrollGestureEnabled : bool

Signaux

• canceled()
• clicked(MouseEvent mouse)
• doubleClicked(MouseEvent mouse)
• entered()
• exited()
• positionChanged(MouseEvent mouse)
• pressAndHold(MouseEvent mouse)
• pressed(MouseEvent mouse)
• released(MouseEvent mouse)
• wheel(WheelEvent wheel)

Description détaillée

Une MouseArea est un élément invisible généralement utilisé en association avec un élément visible afin de permettre la gestion de la souris pour cet élément. En agissant effectivement comme un proxy, la logique de gestion de la souris peut être contenue au sein d'un élément MouseArea.

La propriété « enabled » permet d’activer ou de désactiver la gestion des événements de souris pour l’élément représenté. Lorsqu’elle est désactivée, la zone de souris devient transparente aux événements de souris.

MouseArea est un élément invisible, mais il dispose d’une propriété « visible ». Lorsqu’elle est définie sur « false », la zone de souris devient transparente aux événements de souris.

La propriété en lecture seule ` pressed ` indique si l'utilisateur maintient ou non un bouton de souris enfoncé au-dessus de la zone de souris. Cette propriété est souvent utilisée dans les liaisons entre propriétés d'une interface utilisateur. La propriété en lecture seule ` containsMouse ` indique la présence du curseur de souris au-dessus de la zone de souris, mais, par défaut, uniquement lorsqu'un bouton de souris est maintenu enfoncé ; voir la documentation sur les liaisons de propriété ( containsMouse ) pour plus de détails.

Les informations relatives à la position de la souris et aux clics sur les boutons sont fournies via des signaux pour lesquels des propriétés de gestion d’événements sont définies. Les plus couramment utilisées concernent la gestion des pressions et des clics de souris : onClicked, onDoubleClicked, onPressed, onReleased et onPressAndHold. Il est également possible de gérer les événements liés à la molette de la souris via le signal onWheel.

Si une MouseArea chevauche la zone d’autres éléments MouseArea, vous pouvez choisir de propager les événements « clicked », « doubleClicked » et « pressAndHold » à ces autres éléments en définissant « propagateComposedEvents » sur « true » et en rejetant les événements qui doivent être propagés. Consultez la documentation propagateComposedEvents pour plus de détails.

Par défaut, les éléments MouseArea signalent uniquement les clics de souris et non les changements de position du curseur. La définition de la propriété hoverEnabled garantit que les gestionnaires définis pour onPositionChanged, onEntered et onExited sont utilisés et que la propriété containsMouse est mise à jour même lorsqu’aucun bouton de souris n’est enfoncé.

Exemple d'utilisation

L’exemple suivant utilise une MouseArea dans une Rectangle qui change la couleur de l’ Rectangle en rouge lorsqu’on clique dessus :

import QtQuick

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

    MouseArea {
        anchors.fill: parent
        onClicked: { parent.color = 'red' }
    }
}

De nombreux signaux de MouseArea transmettent un paramètre « mouse » contenant des informations supplémentaires sur l'événement de souris, telles que la position, le bouton et les éventuels modificateurs de touche.

Voici une extension de l'exemple précédent qui génère une couleur différente lorsque l'on clique avec le bouton droit de la souris sur la zone :

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

    MouseArea {
        anchors.fill: parent
        acceptedButtons: Qt.LeftButton | Qt.RightButton
        onClicked: (mouse)=> {
            if (mouse.button == Qt.RightButton)
                parent.color = 'blue';
            else
                parent.color = 'red';
        }
    }
}

Voir également MouseEvent, l'exemple MouseArea et les concepts importants dans Qt Quick - Entrées utilisateur.

Documentation sur les propriétés

acceptedButtons : Qt::MouseButtons

Cette propriété définit les boutons de souris auxquels la zone de souris réagit.

Pour spécifier que l'MouseArea e doit réagir à plusieurs boutons, les valeurs des indicateurs d'Qt::MouseButtons sont combinées à l'aide de l'opérateur « | » (ou) :

MouseArea { acceptedButtons: Qt.LeftButton | Qt.RightButton }

Pour indiquer que tous les boutons de souris possibles doivent être acceptés, la valeur spéciale « Qt.AllButtons » peut être utilisée :

MouseArea { acceptedButtons: Qt.AllButtons }

La valeur par défaut est « Qt.LeftButton ».

containsMouse : bool [read-only]

Cette propriété indique si le curseur de la souris se trouve actuellement dans la zone de détection.

containsPress : bool [read-only]

Il s'agit d'une propriété de commodité équivalente à pressed && containsMouse, c'est-à-dire qu'elle est vraie si l'une des touches acceptedButtons est actuellement enfoncée et que la souris se trouve actuellement dans la zone MouseArea.

Cette propriété est particulièrement utile pour mettre en surbrillance un élément lorsque le bouton de la souris est enfoncé à l’intérieur de ses limites.

Voir également pressed et containsMouse.

cursorShape : Qt::CursorShape

Cette propriété définit la forme du curseur pour cette zone de la souris. Notez que sur les plateformes qui n'affichent pas de curseur de souris, cela peut ne produire aucun effet.

Les formes de curseur disponibles sont les suivantes :

• Qt.ArrowCursor
• Qt.UpArrowCursor
• Qt.CrossCursor
• Qt.WaitCursor
• Qt.IBeamCursor
• Qt.CursorTailleVerticale
• Qt.CursorTailleHoriz
• Qt.SizeBDiagCursor
• Qt.SizeFDiagCursor
• Qt.SizeAllCursor
• Qt.CurseurVide
• Qt.CursorDiviséVertical
• Qt.Cursor à division horizontale
• Qt.CursorMainPointant
• Qt.CurseurInterdit
• Qt.Cursor « Qu'est-ce que c'est ? »
• Qt.Curseur-occupé
• Qt.CursorMainOuverte
• Qt.CurseurMainFermée
• Qt.CurseurGlisserCopier
• Qt.CurseurGlisserDéplacer
• Qt.DragLinkCursor

Pour définir uniquement la forme du curseur de la souris pour une région sans réagir aux événements de la souris, définissez l'acceptedButtons sur « none » :

MouseArea { cursorShape: Qt.IBeamCursor; acceptedButtons: Qt.NoButton }

La valeur par défaut est « Qt.ArrowCursor ».

Voir aussi Qt::CursorShape.

drag group

drag offre un moyen pratique de rendre un élément déplaçable.

• drag.target Spécifie l'identifiant de l'élément à faire glisser.
• drag.active indique si l'élément cible est en cours de glissement.
• drag.axis indique si le glissement peut s'effectuer horizontalement (Drag.XAxis), verticalement (Drag.YAxis) ou dans les deux sens (Drag.XAndYAxis)
• drag.minimum et drag.maximum limitent la distance sur laquelle la cible peut être déplacée le long des axes correspondants.

L’exemple suivant affiche un Rectangle pouvant être déplacé le long de l’axe X. L’opacité du rectangle diminue lorsqu’il est déplacé vers la droite.

Rectangle {
    id: container
    width: 600; height: 200

    Rectangle {
        id: rect
        width: 50; height: 50
        color: "red"
        opacity: (600.0 - rect.x) / 600

        MouseArea {
            anchors.fill: parent
            drag.target: rect
            drag.axis: Drag.XAxis
            drag.minimumX: 0
            drag.maximumX: container.width - rect.width
        }
    }
}

Si drag.filterChildren est défini sur true, un glissement peut remplacer les MouseAreas descendantes. Cela permet, par exemple, à une MouseArea parente de gérer les glissements tandis que les descendantes gèrent les clics :

import QtQuick

Rectangle {
    width: 480
    height: 320
    Rectangle {
        x: 30; y: 30
        width: 300; height: 240
        color: "lightsteelblue"

        MouseArea {
            anchors.fill: parent
            drag.target: parent;
            drag.axis: "XAxis"
            drag.minimumX: 30
            drag.maximumX: 150
            drag.filterChildren: true

            Rectangle {
                color: "yellow"
                x: 50; y : 50
                width: 100; height: 100
                MouseArea {
                    anchors.fill: parent
                    onClicked: console.log("Clicked")
                }
            }
        }
    }
}

drag.threshold détermine le seuil en pixels à partir duquel l’opération de glisser-déposer doit commencer. Par défaut, cette valeur est liée à une valeur propre à la plateforme. Cette propriété a été ajoutée dans Qt Quick 2.2.

Si la propriété « drag.smoothed » est définie sur « true », la cible ne sera déplacée qu’une fois l’opération de glisser-déposer lancée. Si elle est définie sur « false », la cible sera déplacée directement à la position actuelle de la souris. Par défaut, cette propriété est définie sur « true ». Cette propriété a été ajoutée dans la version 2.4 d’« Qt Quick ».

Consultez la propriété associée « Drag » et la page DropArea si vous souhaitez effectuer un dépôt.

enabled : bool

Cette propriété indique si l'élément accepte les événements de souris.

Par défaut, cette propriété est définie sur true.

hoverEnabled : bool

Cette propriété détermine si les événements de survol sont gérés.

Par défaut, les événements de souris ne sont gérés qu'en réponse à un événement de bouton ou lorsqu'un bouton est enfoncé. La propriété « hover » active la gestion de tous les événements de souris, même lorsqu'aucun bouton de la souris n'est enfoncé.

Cette propriété affecte la propriété « containsMouse » ainsi que les signaux « onEntered », « onExited » et « onPositionChanged ».

Ces propriétés contiennent les coordonnées du curseur de la souris.

Si la propriété « hoverEnabled » est définie sur « false », ces propriétés ne seront valides que tant qu'un bouton est enfoncé, et le resteront tant que le bouton est maintenu enfoncé, même si la souris est déplacée en dehors de la zone.

Par défaut, cette propriété est définie sur « false ».

Si la propriété « hoverEnabled » est définie sur « true », ces propriétés seront valides lorsque :

• aucun bouton n’est enfoncé, mais que la souris se trouve dans la zone d’ MouseArea (la propriété «containsMouse » est définie sur « true »).
• un bouton est enfoncé et maintenu enfoncé, même si la souris a depuis quitté la zone.

Les coordonnées sont relatives à l'MouseArea.

pressAndHoldInterval : int

Cette propriété remplace le délai écoulé en millisecondes avant l'émission de l'événement « pressAndHold ».

Si elle n'est pas explicitement définie – ou après une réinitialisation –, la valeur suit celle de ` QStyleHints::mousePressAndHoldInterval`.

En général, il suffit de définir cette propriété globalement à l’aide de l’indicateur de style de l’application. Cette propriété doit être utilisée lorsque des intervalles variables sont nécessaires pour certaines zones de souris (MouseAreas).

Voir également pressAndHold.

pressed : bool [read-only]

Cette propriété indique si l'une des touches de la série « acceptedButtons » est actuellement enfoncée.

pressedButtons : MouseButtons [read-only]

Cette propriété contient les boutons de souris actuellement enfoncés.

Elle contient une combinaison binaire des éléments suivants :

• Qt.LeftButton
• Qt.RightButton
• Qt.MiddleButton

Le code ci-dessous affiche « right » lorsque le bouton droit de la souris est enfoncé :

Text {
    text: mouseArea.pressedButtons & Qt.RightButton ? "right" : ""
    horizontalAlignment: Text.AlignHCenter
    verticalAlignment: Text.AlignVCenter

    MouseArea {
        id: mouseArea
        anchors.fill: parent
        acceptedButtons: Qt.LeftButton | Qt.RightButton
    }
}

Voir également acceptedButtons.

preventStealing : bool

Cette propriété détermine si les événements de souris peuvent être interceptés à partir de cet « MouseArea ».

Si un élément « MouseArea » est placé au sein d’un élément filtrant les événements de souris de ses enfants, tel que « Flickable », les événements de souris peuvent être interceptés par l’élément « MouseArea » si un geste est reconnu par l’élément parent, par exemple un geste de balayage. Si « preventStealing » est défini sur « true », aucun élément n’interceptera les événements de souris.

Notez que le fait de définir preventStealing sur « true » une fois qu’un élément a commencé à intercepter des événements n’aura aucun effet avant le prochain événement de pression.

Par défaut, cette propriété est définie sur « false ».

propagateComposedEvents : bool

Cette propriété détermine si les événements de souris composés se propagent automatiquement vers d’autres zones de souris (MouseAreas) qui chevauchent cette zone de souris ( MouseArea ) mais se trouvent à un niveau inférieur dans l’ordre d’empilement visuel. Par défaut, cette propriété est définie sur « false ».

MouseArea Elle contient plusieurs événements composés : ` clicked`, ` doubleClicked ` et ` pressAndHold`. Ceux-ci sont composés d’événements de souris de base, tels que ` pressed`, et peuvent se propager différemment des événements de base.

Si `propagateComposedEvents` est défini sur `true`, les événements composés seront automatiquement propagés vers d’autres `MouseAreas` situées au même emplacement dans la scène. Chaque événement est propagé à l’ enabled MouseArea suivante située en dessous dans l’ordre d’empilement, en descendant cette hiérarchie visuelle jusqu’à ce qu’une MouseArea accepte l’événement. Contrairement aux événements pressed, les événements composés ne seront pas automatiquement acceptés en l’absence de gestionnaire.

Par exemple, voici un Rectangle jaune qui contient un Rectangle bleu. Le rectangle bleu est l’élément le plus haut dans la hiérarchie de l’ordre d’empilement visuel ; il s’affichera visuellement au-dessus du rectangle jaune. Comme le rectangle bleu définit `propagateComposedEvents` sur `true` et ` MouseEvent::accepted ` sur `false` pour tous les événements ` clicked ` reçus, tous les événements ` clicked ` qu’il reçoit sont propagés vers le ` MouseArea ` du rectangle jaune situé en dessous.

import QtQuick 2.0

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

    MouseArea {
        anchors.fill: parent
        onClicked: console.log("clicked yellow")
    }

    Rectangle {
        color: "blue"
        width: 50; height: 50

        MouseArea {
            anchors.fill: parent
            propagateComposedEvents: true
            onClicked: (mouse)=> {
                console.log("clicked blue")
                mouse.accepted = false
            }
        }
    }
}

Un clic sur le rectangle bleu entraînera l’appel du gestionnaire ` onClicked ` de son enfant ` MouseArea ` ; l’événement sera ensuite propagé vers le ` MouseArea ` du rectangle jaune, ce qui provoquera l’appel de son propre gestionnaire ` onClicked `.

Cette propriété simplifie considérablement les cas d'utilisation où vous souhaitez que des zones de clic (MouseAreas) qui se chevauchent gèrent ensemble les événements composés. Par exemple : si vous souhaitez qu’une zone de clic ( MouseArea ) gère les signaux « clicked » et l’autre les signaux « pressAndHold », ou si vous souhaitez qu’une zone de clic ( MouseArea ) gère « clicked » la plupart du temps, mais qu’elle transmette l’événement lorsque certaines conditions sont remplies.

scrollGestureEnabled : bool

Cette propriété détermine si cet « MouseArea » réagit aux gestes de défilement provenant de périphériques autres que la souris, tels que le geste de balayage à deux doigts sur un pavé tactile. Si elle est définie sur « false », le signal « wheel » ne sera émis que lorsque l’événement de molette provient d’une véritable souris dotée d’une molette, tandis que les événements de geste de défilement seront transmis à tout autre « Item » capable de les gérer. Par exemple, l’utilisateur peut effectuer un geste de balayage alors que le curseur se trouve sur un élément contenant un ` MouseArea`, dans le but d’interagir avec un `Flickable` situé en dessous. Définir cette propriété sur `false` permettra à l’` PinchArea ` de gérer la molette de la souris ou le geste de pincement, tandis que le `Flickable` gérera le geste de balayage.

Par défaut, cette propriété est définie sur « true ».

Documentation sur les signaux

canceled()

Ce signal est émis lorsque des événements de souris ont été annulés, car un autre élément a pris le contrôle du traitement de ces événements.

Ce signal est destiné à un usage avancé : il est utile lorsqu’il existe plusieurs éléments « MouseArea » gérant les entrées, ou lorsqu’un élément « MouseArea » se trouve à l’intérieur d’un élément « Flickable ». Dans ce dernier cas, si vous exécutez une logique dans le gestionnaire de signal onPressed puis que vous commencez à faire glisser, l'Flickable prendra le relais de la gestion de la souris à la place de l'MouseArea. Dans ces cas-là, pour réinitialiser la logique lorsque l'MouseArea a perdu la gestion de la souris au profit de l'Flickable, il convient de gérer canceled en plus de released.

clicked(MouseEvent mouse)

Ce signal est émis lorsqu'un clic est effectué. Un clic est défini comme une pression suivie d'un relâchement, tous deux à l'intérieur de l'MouseArea (le fait d'appuyer, de sortir de l'MouseArea, puis de revenir à l'intérieur et de relâcher est également considéré comme un clic).

Le paramètre « mouse » fournit des informations sur le clic, notamment les coordonnées x et y du point de relâchement du clic, ainsi que le fait que le clic ait été maintenu ou non.

Lors du traitement de ce signal, la modification de la propriété ` accepted ` du paramètre ` mouse ` n’a aucun effet, sauf si la propriété ` propagateComposedEvents ` est définie sur ` true`.

doubleClicked(MouseEvent mouse)

Ce signal est émis lorsqu'un double-clic est effectué (une pression suivie d'un relâchement, puis d'une nouvelle pression). Le paramètre ` mouse ` fournit des informations sur le clic, notamment les coordonnées x et y du relâchement du clic, ainsi que le fait que le clic ait été maintenu ou non.

Lors de la gestion de ce signal, si la propriété accepted du paramètre mouse est définie sur false, les signaux pressed/released/clicked seront émis pour le deuxième clic ; dans le cas contraire, ils sont supprimés. La propriété accepted est définie par défaut sur true.

entered()

Ce signal est émis lorsque la souris entre dans la zone de détection.

Par défaut, ce signal n'est émis que si un bouton est actuellement enfoncé. Définissez hoverEnabled sur true pour émettre ce signal même lorsqu'aucun bouton de la souris n'est enfoncé.

Voir également hoverEnabled.

exited()

Ce signal est émis lorsque la souris quitte la zone de détection.

Par défaut, ce signal n'est émis que si un bouton est enfoncé. Définissez ` hoverEnabled ` sur `true` pour émettre ce signal même lorsqu'aucun bouton de la souris n'est enfoncé.

L'exemple ci-dessous illustre une relation assez courante entre deux zones de souris (MouseAreas), « mouseArea2 » se trouvant au-dessus de « mouseArea1 ». Déplacer la souris depuis « mouseArea1 » vers « mouseArea2 » entraînera l'émission du signal « exited » par « mouseArea1 ».

Rectangle {
    width: 400; height: 400
    MouseArea {
        id: mouseArea1
        anchors.fill: parent
        hoverEnabled: true
    }
    MouseArea {
        id: mouseArea2
        width: 100; height: 100
        anchors.centerIn: parent
        hoverEnabled: true
    }
}

Si, au contraire, vous établissez une relation parent-enfant entre les deux zones de souris, le fait de déplacer la souris sur mouseArea2 depuis mouseArea1 ne provoquera pas l'émission du signal exited par mouseArea1. Au lieu de cela, les deux zones seront considérées comme étant simultanément survolées.

Voir également hoverEnabled.

positionChanged(MouseEvent mouse)

Ce signal est émis lorsque la position de la souris change.

Le paramètre « mouse » fournit des informations sur la souris, notamment sa position en x et en y, ainsi que les boutons actuellement enfoncés.

Par défaut, ce signal n'est émis que si un bouton est enfoncé. Définissez hoverEnabled sur true pour émettre ce signal même lorsqu'aucun bouton de la souris n'est enfoncé.

Lors de la gestion de ce signal, la modification de la propriété « accepted » du paramètre « mouse » n’a aucun effet.

pressAndHold(MouseEvent mouse)

Ce signal est émis lorsqu'un appui long (actuellement de 800 ms) est détecté. Le paramètre « mouse » fournit des informations sur cet appui, notamment les coordonnées x et y du point d'appui, ainsi que le bouton sur lequel on a appuyé.

Lors du traitement de ce signal, la modification de la propriété ` accepted ` du paramètre ` mouse ` n’a aucun effet, sauf si la propriété ` propagateComposedEvents ` est définie sur ` true`.

pressed(MouseEvent mouse)

Ce signal est émis lorsqu'une pression est détectée. Le paramètre « mouse » fournit des informations sur la pression, notamment les coordonnées x et y ainsi que le bouton sur lequel on a appuyé.

Lors du traitement de ce signal, utilisez la propriété « accepted » du paramètre « mouse » pour déterminer si cette « MouseArea » doit gérer la pression et tous les événements de souris futurs jusqu’à ce que le bouton soit relâché. Par défaut, l’événement est accepté et les autres « MouseAreas » situées en dessous de celle-ci ne sont pas autorisées à le gérer. Si la valeur « accepted » est définie sur « false », aucun autre événement ne sera envoyé à cette « MouseArea » jusqu’à la prochaine pression sur le bouton.

released(MouseEvent mouse)

Ce signal est émis lorsqu'un clic est relâché. Le paramètre « mouse » fournit des informations sur le clic, notamment les coordonnées x et y du point de relâchement du clic, ainsi que le fait que le clic ait été maintenu ou non.

Lors de la gestion de ce signal, la modification de la propriété ` accepted ` du paramètre ` mouse ` n'a aucun effet.

Voir également canceled.

wheel(WheelEvent wheel)

Ce signal est émis en réponse aux gestes de défilement effectués à la fois avec la molette de la souris et avec le pavé tactile.

Le paramètre « wheel » fournit des informations sur l’événement, notamment les coordonnées x et y, les boutons actuellement enfoncés, ainsi que des informations sur le mouvement de la molette, notamment « angleDelta » et « pixelDelta ».