Update copyright headers
[qt:qt.git] / doc / src / declarative / mouseevents.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29 \page mouseevents.html
30 \title QML Mouse Events
31 \ingroup QML Features
32 \previouspage {Anchor-based Layout in QML}{Layouts using Anchors}
33 \nextpage {QML Text Handling and Validators}{Text Handling and Validators}
34 \contentspage QML Features
35
36 \tableofcontents
37
38 \section1 Mouse Elements
39
40 \list
41 \o \l{MouseArea} Element
42 \o \l{MouseEvent} Object
43 \endlist
44
45 \section1 Mouse Event Handling
46
47 QML uses \l{QML Signal and Handler Event System}{signals and handlers} to
48 deliver mouse interactions. Specifically, the \l MouseArea and \l MouseEvent
49 elements provide QML components with signal handlers to accept mouse events
50 within a defined area.
51
52 \section1 Defining a Mouse Area
53
54 The \l MouseArea element receives events within a defined area. One quick way
55 to define this area is to anchor the \c MouseArea to its parent's area using the
56 \c anchors.fill property. If the parent is a \l Rectangle (or any \l Item
57 component), then the MouseArea will fill the area defined by the parent's
58 dimensions. Alternatively, an area smaller or larger than the parent is
59 definable.
60 \snippet doc/src/snippets/declarative/mousearea/mousearea-snippet.qml anchor fill
61
62 \section1 Receiving Events
63
64 The MouseArea element provides
65 \l{QML Signal and Handler Event System}{signals and handlers} to detect different
66 mouse events. The \l MouseArea element documentation describes these
67 gestures in greater detail:
68
69 \list
70 \o canceled
71 \o clicked
72 \o doubleClicked
73 \o entered
74 \o exited
75 \o positionChanged
76 \o pressAndHold
77 \o pressed
78 \o released
79 \endlist
80
81 These signals have signal handlers that are invoked when the signals are emitted.
82 \snippet doc/src/snippets/declarative/mousearea/mousearea-snippet.qml mouse handlers
83
84 \section1 Enabling Gestures
85 Some mouse gestures and button clicks need to be enabled before they send or
86 receive events. Certain \l MouseArea and \l MouseEvent properties enable these
87 gestures.
88
89 To listen to (or explicitly ignore) a certain mouse button, set the appropriate
90 mouse button to the \l {MouseArea::acceptedButtons}{acceptedButtons} property.
91
92 Naturally, the mouse events, such as button presses and mouse positions, are
93 sent during a mouse click. For example, the \c containsMouse property will only
94 retrieve its correct value during a mouse press. The
95 \l {MouseArea::hoverEnabled}{hoverEnabled} will enable mouse events and
96 positioning even when there are no mouse button presses. Setting the
97 \c hoverEnabled property to \c true, in turn will enable the \c entered,
98 \c exited, and \c positionChanged signal and their respective signal handlers.
99
100 \snippet doc/src/snippets/declarative/mousearea/mousearea-snippet.qml enable handlers
101 Additionally, to disable the whole mouse area, set the \c MouseArea
102 element's \c enabled property to \c false.
103
104 \section1 MouseEvent Object
105
106 Signals and their handlers receive a \l MouseEvent object as a parameter. The
107 \c mouse object contain information about the mouse event. For example, the
108 mouse button that started the event is queried through the
109 \l {MouseEvent::button}{mouse.button} property.
110
111 The \c MouseEvent object can also ignore a mouse event using its \c accepted
112 property.
113
114 \section2 Accepting Further Signals
115 Many of the signals are sent multiple times to reflect various mouse events
116 such as double clicking. To facilitate the classification of mouse clicks, the
117 MouseEvent object has an \c accepted property to disable the event propagation.
118
119 To learn more about QML's event system, please read the \l {QML Signal and Handler Event System} document.
120 */