1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the documentation of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:FDL$
10 ** GNU Free Documentation License
11 ** Alternatively, this file may be used under the terms of the GNU Free
12 ** Documentation License version 1.3 as published by the Free Software
13 ** Foundation and appearing in the file included in the packaging of
17 ** Alternatively, this file may be used in accordance with the terms
18 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
29 \page mouseevents.html
30 \inqmlmodule QtQuick 2
31 \title QML Mouse Events
33 \previouspage {Anchor-based Layout in QML}{Layouts using Anchors}
34 \nextpage {QML Text Handling and Validators}{Text Handling and Validators}
35 \contentspage QML Features
39 \section1 Mouse Elements
42 \o \l{MouseArea} Element
43 \o \l{MouseEvent} Object
46 \section1 Mouse Event Handling
48 QML uses \l{QML Signal and Handler Event System}{signals and handlers} to
49 deliver mouse interactions. Specifically, the \l MouseArea and \l MouseEvent
50 elements provide QML components with signal handlers to accept mouse events
51 within a defined area.
53 \section1 Defining a Mouse Area
55 The \l MouseArea element receives events within a defined area. One quick way
56 to define this area is to anchor the \c MouseArea to its parent's area using the
57 \c anchors.fill property. If the parent is a \l Rectangle (or any \l Item
58 component), then the MouseArea will fill the area defined by the parent's
59 dimensions. Alternatively, an area smaller or larger than the parent is
61 \snippet doc/src/snippets/declarative/mousearea/mousearea-snippet.qml anchor fill
63 \section1 Receiving Events
65 The MouseArea element provides
66 \l{QML Signal and Handler Event System}{signals and handlers} to detect different
67 mouse events. The \l MouseArea element documentation describes these
68 gestures in greater detail:
82 These signals have signal handlers that are invoked when the signals are emitted.
83 \snippet doc/src/snippets/declarative/mousearea/mousearea-snippet.qml mouse handlers
85 \section1 Enabling Gestures
86 Some mouse gestures and button clicks need to be enabled before they send or
87 receive events. Certain \l MouseArea and \l MouseEvent properties enable these
90 To listen to (or explicitly ignore) a certain mouse button, set the appropriate
91 mouse button to the \l {MouseArea::acceptedButtons}{acceptedButtons} property.
93 Naturally, the mouse events, such as button presses and mouse positions, are
94 sent during a mouse click. For example, the \c containsMouse property will only
95 retrieve its correct value during a mouse press. The
96 \l {MouseArea::hoverEnabled}{hoverEnabled} will enable mouse events and
97 positioning even when there are no mouse button presses. Setting the
98 \c hoverEnabled property to \c true, in turn will enable the \c entered,
99 \c exited, and \c positionChanged signal and their respective signal handlers.
101 \snippet doc/src/snippets/declarative/mousearea/mousearea-snippet.qml enable handlers
102 Additionally, to disable the whole mouse area, set the \c MouseArea
103 element's \c enabled property to \c false.
105 \section1 MouseEvent Object
107 Signals and their handlers receive a \l MouseEvent object as a parameter. The
108 \c mouse object contain information about the mouse event. For example, the
109 mouse button that started the event is queried through the
110 \l {MouseEvent::button}{mouse.button} property.
112 The \c MouseEvent object can also ignore a mouse event using its \c accepted
115 \section2 Accepting Further Signals
116 Many of the signals are sent multiple times to reflect various mouse events
117 such as double clicking. To facilitate the classification of mouse clicks, the
118 MouseEvent object has an \c accepted property to disable the event propagation.
120 To learn more about QML's event system, please read the \l {QML Signal and Handler Event System} document.