mouse.qdoc

Go to the documentation of this file.

// Copyright (C) 2017 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
\page qtquick-input-mouseevents.html
\ingroup QML Features
\title Mouse Events
\brief handling mouse events in Qt Quick
 
\tableofcontents
 
A more modern way of handling events from all pointing devices, including
mouse and touchscreen, is via \l {Qt Quick Input Handlers}{Input Handlers}.
This page describes the original Qt Quick \l MouseArea type, which was
initially designed to handle mouse input, and later began handling single-touch
events (in the form of synthetic mouse events) in simple touch-oriented user
interfaces.
 
\section1 Mouse Types
 
\list
\li \l{MouseArea} type
\li \l{MouseEvent} object
\endlist
 
\section1 Mouse Event Handling
 
QML uses \l{qtqml-syntax-signals.html}{signals and handlers} to
deliver mouse interactions. Specifically, Qt Quick provides the \l MouseArea
and \l MouseEvent types that allow developers to define JavaScript callbacks
(also called signal handlers), which accept mouse events within a defined area.
 
\section1 Defining a Mouse Area
 
The \l MouseArea type receives events within a defined area. One quick way
to define this area is to anchor the \c MouseArea to its parent's area using the
\c anchors.fill property. If the parent is a \l Rectangle (or any \l Item
component), then the MouseArea will fill the area defined by the parent's
dimensions. Alternatively, an area smaller or larger than the parent is
definable.
\snippet qml/mousearea/mousearea-snippet.qml anchor fill
 
\section1 Receiving Events
 
The MouseArea type emits
\l{qtqml-syntax-signals.html}{signals} in response to different
mouse events. The \l MouseArea type documentation describes these
gestures in greater detail:
 
\list
\li canceled
\li clicked
\li doubleClicked
\li entered
\li exited
\li positionChanged
\li pressAndHold
\li pressed
\li released
\endlist
 
These signals can have callbacks that are invoked when the signals are emitted.
\snippet qml/mousearea/mousearea-snippet.qml signal handlers
 
\section1 Enabling Gestures
Some mouse gestures and button clicks need to be enabled before they send or
receive events. Certain \l MouseArea and \l MouseEvent properties enable these
gestures.
 
To listen to (or explicitly ignore) a certain mouse button, set the appropriate
mouse button to the \l {MouseArea::acceptedButtons}{acceptedButtons} property.
 
Naturally, the mouse events, such as button presses and mouse positions, are
sent during a mouse click. For example, the \c containsMouse property will only
retrieve its correct value during a mouse press. The
\l {MouseArea::hoverEnabled}{hoverEnabled} will enable mouse events and
positioning even when there are no mouse button presses. Setting the
\c hoverEnabled property to \c true, in turn will enable the \c entered,
\c exited, and \c positionChanged signal and their respective signal handlers.
 
\snippet qml/mousearea/mousearea-snippet.qml enable handlers
Additionally, to disable the whole mouse area, set the MouseArea
\c enabled property to \c false.
 
\section1 MouseEvent Object
 
Signals and their callbacks receive a \l MouseEvent object as a parameter.
The \c mouse object contains information about the mouse event. For example,
the mouse button that started the event is queried through the
\l {MouseEvent::button}{mouse.button} property.
 
The \c MouseEvent object can also ignore a mouse event using its \c accepted
property.
 
\section2 Accepting Further Signals
Many of the signals are sent multiple times to reflect various mouse events
such as double clicking. To facilitate the classification of mouse clicks, the
MouseEvent object has an \c accepted property to disable the event propagation.
 
To learn more about QML's event system, please read the
\l{qtqml-syntax-signals.html}{signals and handlers, and event system} document.
 
*/