1// Copyright (C) 2017 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5\page qtquick-input-mouseevents.html
8\brief handling mouse events in Qt Quick
12A more modern way of handling events from all pointing devices, including
13mouse and touchscreen, is via \l {Qt Quick Input Handlers}{Input Handlers}.
14This page describes the original Qt Quick \l MouseArea type, which was
15initially designed to handle mouse input, and later began handling single-touch
16events (in the form of synthetic mouse events) in simple touch-oriented user
23\li \l{MouseEvent} object
26\section1 Mouse Event Handling
28QML uses \l{qtqml-syntax-signals.html}{signals and handlers} to
29deliver mouse interactions. Specifically, Qt Quick provides the \l MouseArea
30and \l MouseEvent types that allow developers to define JavaScript callbacks
31(also called signal handlers), which accept mouse events within a defined area.
33\section1 Defining a Mouse Area
35The \l MouseArea type receives events within a defined area. One quick way
36to define this area is to anchor the \c MouseArea to its parent's area using the
37\c anchors.fill property. If the parent is a \l Rectangle (or any \l Item
38component), then the MouseArea will fill the area defined by the parent's
39dimensions. Alternatively, an area smaller or larger than the parent is
41\snippet qml/mousearea/mousearea-snippet.qml anchor fill
43\section1 Receiving Events
45The MouseArea type emits
46\l{qtqml-syntax-signals.html}{signals} in response to different
47mouse events. The \l MouseArea type documentation describes these
48gestures in greater detail:
62These signals can have callbacks that are invoked when the signals are emitted.
63\snippet qml/mousearea/mousearea-snippet.qml signal handlers
65\section1 Enabling Gestures
66Some mouse gestures and button clicks need to be enabled before they send or
67receive events. Certain \l MouseArea and \l MouseEvent properties enable these
70To listen to (or explicitly ignore) a certain mouse button, set the appropriate
71mouse button to the \l {MouseArea::acceptedButtons}{acceptedButtons} property.
73Naturally, the mouse events, such as button presses and mouse positions, are
74sent during a mouse click. For example, the \c containsMouse property will only
75retrieve its correct value during a mouse press. The
76\l {MouseArea::hoverEnabled}{hoverEnabled} will enable mouse events and
77positioning even when there are no mouse button presses. Setting the
78\c hoverEnabled property to \c true, in turn will enable the \c entered,
79\c exited, and \c positionChanged signal and their respective signal handlers.
81\snippet qml/mousearea/mousearea-snippet.qml enable handlers
82Additionally, to disable the whole mouse area, set the MouseArea
83\c enabled property to \c false.
85\section1 MouseEvent Object
87Signals and their callbacks receive a \l MouseEvent object as a parameter.
88The \c mouse object contains information about the mouse event. For example,
89the mouse button that started the event is queried through the
90\l {MouseEvent::button}{mouse.button} property.
92The \c MouseEvent object can also ignore a mouse event using its \c accepted
95\section2 Accepting Further Signals
96Many of the signals are sent multiple times to reflect various mouse events
97such as double clicking. To facilitate the classification of mouse clicks, the
98MouseEvent object has an \c accepted property to disable the event propagation.
100To learn more about QML's event system, please read the
101\l{qtqml-syntax-signals.html}{signals and handlers, and event system} document.