MouseArea QML Type▲

  • Import Statement: import QtQuick 2.13

  • Inherits: Item

  • Group: MouseArea is part of qtquick-input

Detailed Description▲

A MouseArea is an invisible item that is typically used in conjunction with a visible item in order to provide mouse handling for that item. By effectively acting as a proxy, the logic for mouse handling can be contained within a MouseArea item.

The enabled property is used to enable and disable mouse handling for the proxied item. When disabled, the mouse area becomes transparent to mouse events.

MouseArea is an invisible Item, but it has a visible property. When set to false, the mouse area becomes transparent to mouse events.

The pressed read-only property indicates whether or not the user is holding down a mouse button over the mouse area. This property is often used in bindings between properties in a user interface. The containsMouse read-only property indicates the presence of the mouse cursor over the mouse area but, by default, only when a mouse button is held down; see the containsMouse documentation for details.

Information about the mouse position and button clicks are provided via signals for which event handler properties are defined. The most commonly used involved handling mouse presses and clicks: onClicked, onDoubleClicked, onPressed, onReleased and onPressAndHold. It's also possible to handle mouse wheel events via the onWheel signal.

If a MouseArea overlaps with the area of other MouseArea items, you can choose to propagate clicked, doubleClicked and pressAndHold events to these other items by setting propagateComposedEvents to true and rejecting events that should be propagated. See the propagateComposedEvents documentation for details.

By default, MouseArea items only report mouse clicks and not changes to the position of the mouse cursor. Setting the hoverEnabled property ensures that handlers defined for onPositionChanged, onEntered and onExited are used and that the containsMouse property is updated even when no mouse buttons are pressed.

Example Usage▲

Image non disponible

The following example uses a MouseArea in a Rectangle that changes the Rectangle color to red when clicked:

 
Sélectionnez
import QtQuick 2.0

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

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

Many MouseArea signals pass a mouse parameter that contains additional information about the mouse event, such as the position, button, and any key modifiers.

Here is an extension of the previous example that produces a different color when the area is right clicked:

 
Sélectionnez
Rectangle {
    width: 100; height: 100
    color: "green"

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

See Also▲

See also MouseEvent, MouseArea example, Important Concepts In Qt Quick - User Input

Property Documentation▲

 

mouseX : real▲

mouseY : real

These properties hold the coordinates of the mouse cursor.

If the hoverEnabled property is false then these properties will only be valid while a button is pressed, and will remain valid as long as the button is held down even if the mouse is moved outside the area.

By default, this property is false.

If hoverEnabled is true then these properties will be valid when:

  • no button is pressed, but the mouse is within the MouseArea (containsMouse is true).

  • a button is pressed and held, even if it has since moved out of the area.

The coordinates are relative to the MouseArea.

acceptedButtons : Qt::MouseButtons▲

This property holds the mouse buttons that the mouse area reacts to.

To specify that the MouseArea will react to multiple buttons, Qt::MouseButtons flag values are combined using the "|" (or) operator:

 
Sélectionnez
MouseArea { acceptedButtons: Qt.LeftButton | Qt.RightButton }

To indicate that all possible mouse buttons are to be accepted, the special value 'Qt.AllButtons' may be used:

 
Sélectionnez
MouseArea { acceptedButtons: Qt.AllButtons }

The default value is Qt.LeftButton.

containsMouse : bool▲

This property holds whether the mouse is currently inside the mouse area.

If hoverEnabled is false, containsMouse will only be valid when the mouse is pressed while the mouse cursor is inside the MouseArea.

[since 5.4] containsPress : bool▲

This is a convenience property equivalent to pressed && containsMouse, i.e. it holds whether any of the acceptedButtons are currently pressed and the mouse is currently within the MouseArea.

This property is particularly useful for highlighting an item while the mouse is pressed within its bounds.

This property was introduced in Qt 5.4.

See Also▲

See also pressed, containsMouse

cursorShape : Qt::CursorShape▲