Back to Doc.qt.io
Contact Us Blog Download Qt

C

MouseArea QML Type

Enables simple touch handling. More...

Import Statement: import QtQuick
Since: Qt Quick Ultralite 1.0
Inherits:

Item

Properties

Signals

Detailed Description

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

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

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

The pressed read-only property indicates whether or not the user is pressing down over the mouse area. This property is often used in bindings between properties in a user interface.

Information about the touch position and pressed status are provided via signals for which event handler properties are defined. The most commonly used involve handling touch presses: onClicked, onPressed, onReleased and onPressAndHold.

If a MouseArea overlaps with the area of other MouseArea items, only the top area will receive events.

Example Usage

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

import QtQuick 2.15

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 touch event, such as the position.

Here is an extension of the previous example that produces a different color when the press is long enough:

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

    MouseArea {
        anchors.fill: parent
        onClicked: {
            if (mouse.wasHeld)
                parent.color = 'blue';
            else
                parent.color = 'red';
        }
    }
}

See also MouseEvent.

Property Documentation

mouseX : real

mouseY : real

These properties hold the coordinates of the touch.

These properties will only be valid while there is a press, and will remain valid as long as the touch persists, even if it moves outside the area.

The coordinates are relative to the MouseArea.


pressAndHoldInterval : int

This property overrides the elapsed time in milliseconds before pressAndHold is emitted.

By default, the value is 800ms.

See also pressAndHold.


[since Qt Quick Ultralite 1.1] pressed : bool

This property holds whether any touch is currently happening.

This property was introduced in Qt Quick Ultralite 1.1.


Signal Documentation

[since Qt Quick Ultralite 1.1] canceled()

This signal is emitted when touch events have been canceled, because another item stole the touch event handling.

This signal is for advanced use: it is useful when there is more than one MouseArea that is handling input, or when there is a MouseArea inside a Flickable. In the latter case, if you execute some logic in the onPressed signal handler and then start dragging, the Flickable will steal the touch handling from the MouseArea. In these cases, to reset the logic when the MouseArea has lost the touch handling to the Flickable, canceled should be handled in addition to released.

Note: The corresponding handler is onCanceled.

This signal was introduced in Qt Quick Ultralite 1.1.


clicked(MouseEvent mouse)

This signal is emitted when there is a click. A click is defined as a press followed by a release, both inside the MouseArea (pressing, moving outside the MouseArea, and then moving back inside and releasing is also considered a click).

The mouse parameter provides information about the click, including the x and y position of the release of the click, and whether the click was held.

When handling this signal, changing the accepted property of the mouse parameter has no effect.

Note: The corresponding handler is onClicked.


positionChanged(MouseEvent mouse)

This signal is emitted when the touch position changes.

The mouse parameter provides information about the touch, including the x and y position.

This signal is only emitted if there is a press.

When handling this signal, changing the accepted property of the mouse parameter has no effect.

Note: The corresponding handler is onPositionChanged.


[since Qt Quick Ultralite 1.1] pressAndHold(MouseEvent mouse)

This signal is emitted when there is a long press (currently 800ms). The mouse parameter provides information about the press, including the x and y position of the press.

When handling this signal, changing the accepted property of the mouse parameter has no effect.

Note: The corresponding handler is onPressAndHold.

This signal was introduced in Qt Quick Ultralite 1.1.


[since Qt Quick Ultralite 1.1] pressed(MouseEvent mouse)

This signal is emitted when there is a press. The mouse parameter provides information about the press, including the x and y position.

When handling this signal, use the accepted property of the mouse parameter to control whether this MouseArea handles the press and all future touch events until release. The default is to accept the event and not allow other MouseAreas beneath this one to handle the event. If accepted is set to false, no further events will be sent to this MouseArea until the button is next pressed.

Note: The corresponding handler is onPressed.

This signal was introduced in Qt Quick Ultralite 1.1.


[since Qt Quick Ultralite 1.1] released(MouseEvent mouse)

This signal is emitted when there is a release. The mouse parameter provides information about the click, including the x and y position of the release of the click, and whether the click was held.

When handling this signal, changing the accepted property of the mouse parameter has no effect.

Note: The corresponding handler is onReleased.

This signal was introduced in Qt Quick Ultralite 1.1.

See also canceled.


Available under certain Qt licenses.
Find out more.