/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\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.

*/
