1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the QtQml module of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** GNU Lesser General Public License Usage
10 ** This file may be used under the terms of the GNU Lesser General Public
11 ** License version 2.1 as published by the Free Software Foundation and
12 ** appearing in the file LICENSE.LGPL included in the packaging of this
13 ** file. Please review the following information to ensure the GNU Lesser
14 ** General Public License version 2.1 requirements will be met:
15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
17 ** In addition, as a special exception, Nokia gives you certain additional
18 ** rights. These rights are described in the Nokia Qt LGPL Exception
19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
21 ** GNU General Public License Usage
22 ** Alternatively, this file may be used under the terms of the GNU General
23 ** Public License version 3.0 as published by the Free Software Foundation
24 ** and appearing in the file LICENSE.GPL included in the packaging of this
25 ** file. Please review the following information to ensure the GNU General
26 ** Public License version 3.0 requirements will be met:
27 ** http://www.gnu.org/copyleft/gpl.html.
30 ** Alternatively, this file may be used in accordance with the terms and
31 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
42 #include "qquickevents_p_p.h"
48 \instantiates QQuickKeyEvent
49 \inqmlmodule QtQuick 2
50 \ingroup qtquick-input-events
52 \brief Provides information about a key event
54 For example, the following changes the Item's state property when the Enter
59 Keys.onPressed: { if (event.key == Qt.Key_Enter) state = 'ShowDetails'; }
65 \qmlproperty int QtQuick2::KeyEvent::key
67 This property holds the code of the key that was pressed or released.
69 See \l {Qt::Key}{Qt.Key} for the list of keyboard codes. These codes are
70 independent of the underlying window system. Note that this
71 function does not distinguish between capital and non-capital
72 letters, use the text() function (returning the Unicode text the
73 key generated) for this purpose.
75 A value of either 0 or \l {Qt::Key_unknown}{Qt.Key_Unknown} means that the event is not
76 the result of a known key; for example, it may be the result of
77 a compose sequence, a keyboard macro, or due to key event
82 \qmlproperty string QtQuick2::KeyEvent::text
84 This property holds the Unicode text that the key generated.
85 The text returned can be an empty string in cases where modifier keys,
86 such as Shift, Control, Alt, and Meta, are being pressed or released.
87 In such cases \c key will contain a valid value
91 \qmlproperty bool QtQuick2::KeyEvent::isAutoRepeat
93 This property holds whether this event comes from an auto-repeating key.
97 \qmlproperty quint32 QtQuick2::KeyEvent::nativeScanCode
99 This property contains the native scan code of the key that was pressed. It is
100 passed through from QKeyEvent unchanged.
102 \sa QKeyEvent::nativeScanCode()
106 \qmlproperty int QtQuick2::KeyEvent::count
108 This property holds the number of keys involved in this event. If \l KeyEvent::text
109 is not empty, this is simply the length of the string.
113 \qmlproperty bool QtQuick2::KeyEvent::accepted
115 Setting \a accepted to true prevents the key event from being
116 propagated to the item's parent.
118 Generally, if the item acts on the key event then it should be accepted
119 so that ancestor items do not also respond to the same event.
123 \qmlproperty int QtQuick2::KeyEvent::modifiers
125 This property holds the keyboard modifier flags that existed immediately
126 before the event occurred.
128 It contains a bitwise combination of:
130 \li Qt.NoModifier - No modifier key is pressed.
131 \li Qt.ShiftModifier - A Shift key on the keyboard is pressed.
132 \li Qt.ControlModifier - A Ctrl key on the keyboard is pressed.
133 \li Qt.AltModifier - An Alt key on the keyboard is pressed.
134 \li Qt.MetaModifier - A Meta key on the keyboard is pressed.
135 \li Qt.KeypadModifier - A keypad button is pressed.
138 For example, to react to a Shift key + Enter key combination:
143 if ((event.key == Qt.Key_Enter) && (event.modifiers & Qt.ShiftModifier))
153 \instantiates QQuickMouseEvent
154 \inqmlmodule QtQuick 2
155 \ingroup qtquick-input-events
157 \brief Provides information about a mouse event
159 The position of the mouse can be found via the \l x and \l y properties.
160 The button that caused the event is available via the \l button property.
167 \class QQuickMouseEvent
171 \qmlproperty int QtQuick2::MouseEvent::x
172 \qmlproperty int QtQuick2::MouseEvent::y
174 These properties hold the coordinates of the position supplied by the mouse event.
179 \qmlproperty bool QtQuick2::MouseEvent::accepted
181 Setting \a accepted to true prevents the mouse event from being
182 propagated to items below this item.
184 Generally, if the item acts on the mouse event then it should be accepted
185 so that items lower in the stacking order do not also respond to the same event.
189 \qmlproperty enumeration QtQuick2::MouseEvent::button
191 This property holds the button that caused the event. It can be one of:
200 \qmlproperty bool QtQuick2::MouseEvent::wasHeld
202 This property is true if the mouse button has been held pressed longer the
207 \qmlproperty int QtQuick2::MouseEvent::buttons
209 This property holds the mouse buttons pressed when the event was generated.
210 For mouse move events, this is all buttons that are pressed down. For mouse
211 press and double click events this includes the button that caused the event.
212 For mouse release events this excludes the button that caused the event.
214 It contains a bitwise combination of:
223 \qmlproperty int QtQuick2::MouseEvent::modifiers
225 This property holds the keyboard modifier flags that existed immediately
226 before the event occurred.
228 It contains a bitwise combination of:
230 \li Qt.NoModifier - No modifier key is pressed.
231 \li Qt.ShiftModifier - A Shift key on the keyboard is pressed.
232 \li Qt.ControlModifier - A Ctrl key on the keyboard is pressed.
233 \li Qt.AltModifier - An Alt key on the keyboard is pressed.
234 \li Qt.MetaModifier - A Meta key on the keyboard is pressed.
235 \li Qt.KeypadModifier - A keypad button is pressed.
238 For example, to react to a Shift key + Left mouse button click:
242 if ((mouse.button == Qt.LeftButton) && (mouse.modifiers & Qt.ShiftModifier))
252 \instantiates QQuickWheelEvent
253 \inqmlmodule QtQuick 2
254 \ingroup qtquick-input-events
255 \brief Provides information about a mouse wheel event
257 The position of the mouse can be found via the \l x and \l y properties.
264 \class QQuickWheelEvent
268 \qmlproperty int QtQuick2::WheelEvent::x
269 \qmlproperty int QtQuick2::WheelEvent::y
271 These properties hold the coordinates of the position supplied by the wheel event.
275 \qmlproperty bool QtQuick2::WheelEvent::accepted
277 Setting \a accepted to true prevents the wheel event from being
278 propagated to items below this item.
280 Generally, if the item acts on the wheel event then it should be accepted
281 so that items lower in the stacking order do not also respond to the same event.
285 \qmlproperty int QtQuick2::WheelEvent::buttons
287 This property holds the mouse buttons pressed when the wheel event was generated.
289 It contains a bitwise combination of:
298 \qmlproperty point QtQuick2::WheelEvent::angleDelta
300 This property holds the distance that the wheel is rotated in wheel degrees.
301 The x and y cordinate of this property holds the delta in horizontal and
302 vertical orientation.
304 A positive value indicates that the wheel was rotated up/right;
305 a negative value indicates that the wheel was rotated down/left.
307 Most mouse types work in steps of 15 degrees, in which case the delta value is a
308 multiple of 120; i.e., 120 units * 1/8 = 15 degrees.
312 \qmlproperty point QtQuick2::WheelEvent::pixelDelta
314 This property holds the delta in screen pixels and is available in plataforms that
315 have high-resolution trackpads, such as Mac OS X.
316 The x and y cordinate of this property holds the delta in horizontal and
317 vertical orientation. The value should be used directly to scroll content on screen.
319 For platforms without high-resolution trackpad support, pixelDelta will always be (0,0),
320 and angleDelta should be used instead.
324 \qmlproperty int QtQuick2::WheelEvent::modifiers
326 This property holds the keyboard modifier flags that existed immediately
327 before the event occurred.
329 It contains a bitwise combination of:
331 \li Qt.NoModifier - No modifier key is pressed.
332 \li Qt.ShiftModifier - A Shift key on the keyboard is pressed.
333 \li Qt.ControlModifier - A Ctrl key on the keyboard is pressed.
334 \li Qt.AltModifier - An Alt key on the keyboard is pressed.
335 \li Qt.MetaModifier - A Meta key on the keyboard is pressed.
336 \li Qt.KeypadModifier - A keypad button is pressed.
339 For example, to react to a Control key pressed during the wheel event:
343 if (wheel.modifiers & Qt.ControlModifier) {
344 if (wheel.angleDelta.y > 0)