/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** 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 Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\page qtquick-input-mouseevents.html
\ingroup QML Features
\title Mouse Events
\brief handling mouse events in Qt Quick

\tableofcontents

\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 which allow developers to define 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 provides
\l{qtqml-syntax-signals.html}{signals and handlers} to detect 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 have signal handlers that are invoked when the signals are emitted.
\snippet qml/mousearea/mousearea-snippet.qml mouse 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 handlers receive a \l MouseEvent object as a parameter. The
\c mouse object contain 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.

*/