MouseArea Class Reference

The MouseArea item enables simple mouse handling. More...

Inheritance diagram for MouseArea:

Detailed Description

The MouseArea item enables simple mouse handling.

Since

4.7

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.

For basic key handling, see the Keys attached property.

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.

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 below for further 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.

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

{class="float-right"}

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

import QtQuick 1.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:

        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

MouseEvent, {declarative/touchinteraction/mousearea}{MouseArea example}

---

The documentation for this class was generated from the following file:

• /src/declarative/graphicsitems/qdeclarativemousearea.cpp