MouseArea QML Type

Permet une gestion simple de la souris. Plus d'informations...

• 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 qui est généralement utilisé en conjonction avec un élément visible afin d'assurer la gestion de la souris pour cet élément. En agissant comme un proxy, la logique de gestion de la souris peut être contenue dans un élément MouseArea.

La propriété enabled permet d'activer et de désactiver la gestion de la souris pour l'élément mandataire. Lorsqu'elle est désactivée, la zone de la souris devient transparente aux événements de la souris.

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

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

Les informations relatives à la position de la souris et aux clics sur les boutons sont fournies par des signaux pour lesquels des propriétés de gestion d'événements sont définies. Les plus couramment utilisés 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 roulette de la souris via le signal onWheel.

Si une zone de souris chevauche la zone d'autres éléments de la zone de souris, vous pouvez choisir de propager les événements clicked, doubleClicked et pressAndHold à ces autres éléments en attribuant la valeur true à propagateComposedEvents et en rejetant les événements qui devraient être propagés. Voir la documentation propagateComposedEvents pour plus de détails.

Par défaut, les éléments MouseArea ne signalent que 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 si aucun bouton de la souris n'est enfoncé.

Exemple d'utilisation

L'exemple suivant utilise une MouseArea dans une page Rectangle qui change la couleur de la page Rectangle en rouge lorsqu'elle est cliquée :

import QtQuick

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

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

De nombreux signaux MouseArea transmettent un paramètre mouse qui contient des informations supplémentaires sur l'événement de la souris, telles que la position, le bouton et tout modificateur de touche.

Voici une extension de l'exemple précédent qui produit une couleur différente lorsque la zone est cliquée avec le bouton droit de la souris :

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 de Qt Quick - User Input.

Documentation sur les propriétés

acceptedButtons : Qt::MouseButtons

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

Pour spécifier que le site MouseArea réagira à plusieurs boutons, les valeurs du drapeau 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 la souris se trouve actuellement à l'intérieur de la zone de la souris.

containsPress : bool [read-only]

Il s'agit d'une propriété de commodité équivalente à pressed && containsMouse, c'est-à-dire qu'elle indique si l'un des éléments acceptedButtons est actuellement enfoncé et si la souris se trouve actuellement à l'intérieur de l'élément MouseArea.

Cette propriété est particulièrement utile pour mettre en évidence un élément lorsque la souris est appuyée à 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 plates-formes qui n'affichent pas de curseur de souris, cette propriété peut n'avoir aucun effet.

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

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 la valeur de acceptedButtons sur none :

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

La valeur par défaut est Qt.ArrowCursor.

Voir également Qt::CursorShape.

drag group

drag fournit 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 spécifie si l'élément cible est en train d'être déplacé.
• drag.axis spécifie si le glissement peut se faire horizontalement (Drag.XAxis), verticalement (Drag.YAxis), ou les deux (Drag.XAndYAxis)
• drag.minimum et drag.maximum limitent la distance à laquelle la cible peut être déplacée le long des axes correspondants.

L'exemple suivant affiche un Rectangle qui peut être déplacé le long de l'axe X. L'opacité du rectangle est de 0,5 %. L'opacité du rectangle est réduite 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 comme vrai, un glissement peut remplacer les zones de souris descendantes. Cela permet à un parent MouseArea de gérer les glissements, par exemple, tandis que les descendants 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 glissement doit commencer. Par défaut, cette propriété est liée à une valeur dépendant de la plate-forme. Cette propriété a été ajoutée dans Qt Quick 2.2.

Si drag.smoothed est true, la cible ne sera déplacée qu'après le début de l'opération de glissement. Si la valeur est false, la cible sera déplacée directement à la position actuelle de la souris. Par défaut, cette propriété est true. Cette propriété a été ajoutée dans Qt Quick 2.4

Voir la propriété attachée Drag et 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é vaut true (vrai).

hoverEnabled : bool

Cette propriété indique si les événements de survol sont traités.

Par défaut, les événements souris ne sont traités qu'en réponse à un événement bouton, ou lorsqu'un bouton est enfoncé. Le survol permet de gérer tous les événements liés à la souris, même si aucun bouton n'est enfoncé.

Cette propriété affecte la propriété containsMouse et 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 false, ces propriétés ne seront valables que lorsqu'un bouton est enfoncé et resteront valables 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 fausse.

Si hoverEnabled est vrai, ces propriétés seront valides lorsque

• aucun bouton n'est enfoncé, mais la souris se trouve à l'intérieur de la zone MouseArea (containsMouse est vrai).
• un bouton est enfoncé et maintenu, même s'il est sorti de la zone depuis.

Les coordonnées sont relatives à MouseArea.

pressAndHoldInterval : int

Cette propriété remplace le temps écoulé en millisecondes avant l'émission de pressAndHold.

Si elle n'est pas explicitement définie - ou après réinitialisation - la valeur suit QStyleHints::mousePressAndHoldInterval.

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

Voir également pressAndHold.

pressed : bool [read-only]

Cette propriété indique si l'une des adresses acceptedButtons est actuellement activée.

pressedButtons : MouseButtons [read-only]

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

Elle contient une combinaison bit à bit de :

• 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 aussi acceptedButtons.

preventStealing : bool

Cette propriété indique si les événements de souris peuvent être volés à cette MouseArea.

Si un MouseArea est placé dans un élément qui filtre les événements souris des enfants, tel que Flickable, les événements souris peuvent être volés au MouseArea si un geste est reconnu par l'élément parent, par exemple un geste de flick. Si la valeur "preventStealing" est fixée à "true", aucun élément ne volera les événements de la souris.

Notez que le fait de définir preventStealing à true une fois qu'un élément a commencé à voler des événements n'aura aucun effet jusqu'au prochain événement de pression.

Par défaut, cette propriété est fixée à false (faux).

propagateComposedEvents : bool

Cette propriété indique si les événements de souris composés se propagent automatiquement à d'autres MouseAreas qui se chevauchent avec ce site MouseArea, mais qui se situent plus bas dans l'ordre d'empilement visuel. Par défaut, cette propriété vaut false (faux).

MouseArea contient plusieurs événements composés : clicked, doubleClicked et pressAndHold. Ceux-ci sont composés d'événements souris de base, comme pressed, et peuvent être propagés différemment par rapport aux événements de base.

Si la valeur "propagateComposedEvents" est fixée à true, les événements composés sont automatiquement propagés aux autres MouseAreas situées au même endroit dans la scène. Chaque événement est propagé au enabled MouseArea suivant dans l'ordre d'empilement, se propageant vers le bas de cette hiérarchie visuelle jusqu'à ce qu'un MouseArea accepte l'événement. Contrairement aux événements pressed, les événements composés ne sont pas automatiquement acceptés si aucun gestionnaire n'est présent.

Par exemple, voici un Rectangle jaune qui contient un Rectangle bleu. Le rectangle bleu est l'élément le plus élevé dans la hiérarchie de l'ordre d'empilement visuel ; il sera rendu visuellement au-dessus du rectangle jaune. Étant donné que le rectangle bleu attribue la valeur true à propagateComposedEvents et la valeur false à MouseEvent::accepted pour tous les événements clicked reçus, tous les événements clicked qu'il reçoit sont propagés au 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
            }
        }
    }
}

En cliquant sur le rectangle bleu, le gestionnaire onClicked de son enfant MouseArea sera invoqué ; l'événement sera ensuite propagé à MouseArea du rectangle jaune, ce qui entraînera l'invocation de son propre gestionnaire onClicked.

Cette propriété simplifie grandement le cas où vous souhaitez que des MouseAreas superposées gèrent ensemble les événements composés. Par exemple : si vous voulez qu'une zone MouseArea traite les signaux clicked et l'autre pressAndHold, ou si vous voulez qu'une zone MouseArea traite clicked la plupart du temps, mais la transmette lorsque certaines conditions sont remplies.

scrollGestureEnabled : bool

Cette propriété détermine si le site MouseArea réagit aux gestes de défilement provenant de périphériques autres que la souris, tels que le geste de pichenette à deux doigts sur un trackpad. S'il est défini sur false, le signal wheel n'est émis que lorsque l'événement de roue provient d'une souris réelle dotée d'une roue, tandis que les événements de gestes de défilement sont transmis à tout autre élément capable de les gérer. Par exemple, l'utilisateur peut effectuer un geste de pichenette lorsque le curseur se trouve au-dessus d'un élément contenant un MouseArea, dans l'intention d'interagir avec un Flickable qui se trouve en dessous. En définissant cette propriété sur false, le site PinchArea pourra gérer la molette de la souris ou le geste de pincement, tandis que le Flickable gérera le geste de pichenette.

Par défaut, cette propriété vaut true.

Documentation sur les signaux

canceled()

Ce signal est émis lorsque les événements de la souris ont été annulés, parce qu'un autre élément a volé la gestion de l'événement de la souris.

Ce signal est destiné à un usage avancé : il est utile lorsque plusieurs MouseArea gèrent les entrées ou lorsqu'un MouseArea se trouve à l'intérieur d'un Flickable. Dans ce dernier cas, si vous exécutez une certaine logique dans le gestionnaire de signal onPressed et que vous commencez ensuite à faire glisser la souris, le Flickable volera la gestion de la souris au MouseArea. Dans ce cas, pour réinitialiser la logique lorsque le MouseArea a perdu la gestion de la souris au profit du Flickable, le canceled doit être géré en plus du released.

clicked(MouseEvent mouse)

Ce signal est émis lorsqu'il y a un clic. Un clic est défini comme une pression suivie d'un relâchement, tous deux à l'intérieur de MouseArea (une pression, un déplacement à l'extérieur de MouseArea, puis un retour à l'intérieur et un relâchement sont également considérés comme un clic).

Le paramètre mouse fournit des informations sur le clic, y compris la position x et y du relâchement du clic et si le clic a été maintenu.

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

doubleClicked(MouseEvent mouse)

Ce signal est émis lors d'un double-clic (une pression suivie d'un relâchement suivi d'une pression). Le paramètre mouse fournit des informations sur le clic, y compris la position x et y de la libération du clic et si le clic a été maintenu.

Lors de la gestion de ce signal, si la propriété accepted du paramètre mouse est définie sur false, les signaux pressé/relâché/cliqué seront émis pour le deuxième clic ; sinon, ils sont supprimés. La valeur par défaut de la propriété accepted est true.

entered()

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

Par défaut, ce signal n'est émis que si un bouton est enfoncé. Attribuez la valeur true à hoverEnabled pour que ce signal soit émis même si aucun bouton de la souris n'est enfoncé.

Voir également hoverEnabled.

exited()

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

Par défaut, ce signal n'est émis que si un bouton est enfoncé. Attribuez la valeur true à hoverEnabled pour que ce signal soit émis même si aucun bouton de la souris n'est enfoncé.

L'exemple ci-dessous montre une relation assez typique entre deux MouseAreas, avec mouseArea2 au-dessus de mouseArea1. Le déplacement de la souris dans mouseArea2 à partir de mouseArea1 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 donnez aux deux MouseAreas une relation parent-enfant, le déplacement de la souris sur mouseArea2 à partir de mouseArea1 n' entraînera pas l'émission du signal exited par mouseArea1. Au lieu de cela, les deux zones seront considérées comme ayant été survolées simultanément.

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, y compris la position x et y, et tout bouton actuellement enfoncé.

Par défaut, ce signal n'est émis que si un bouton est enfoncé. Attribuez la valeur true à hoverEnabled pour que ce signal soit émis même si 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 lors d'un appui long (actuellement 800 ms). Le paramètre mouse fournit des informations sur l'appui, notamment la position x et y de l'appui et le bouton 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 true.

pressed(MouseEvent mouse)

Ce signal est émis en cas de pression. Le paramètre mouse fournit des informations sur l'appui, y compris la position x et y et le bouton qui a été appuyé.

Lorsque vous traitez ce signal, utilisez la propriété accepted du paramètre mouse pour contrôler si ce MouseArea traite l'appui et tous les événements de souris ultérieurs jusqu'à ce qu'il soit relâché. Par défaut, l'événement est accepté et les zones de souris inférieures ne sont pas autorisées à le gérer. Si la valeur " accepted " est fixée à "false", aucun autre événement ne sera envoyé à cette page MouseArea jusqu'à la prochaine pression sur le bouton.

released(MouseEvent mouse)

Ce signal est émis lorsqu'il y a relâchement. Le paramètre mouse fournit des informations sur le clic, y compris la position x et y de la libération du clic et si le clic a été maintenu.

Lors du traitement 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 de la molette de la souris et du pavé tactile.

Le paramètre wheel fournit des informations sur l'événement, notamment la position x et y, tout bouton actuellement enfoncé et des informations sur le mouvement de la roulette, notamment angleDelta et pixelDelta.