src/quick/items/qquickevents.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: http://www.qt-project.org/
   6 **
   7 ** This file is part of the QtDeclarative module of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** GNU Lesser General Public License Usage
  11 ** This file may be used under the terms of the GNU Lesser General Public
  12 ** License version 2.1 as published by the Free Software Foundation and
  13 ** appearing in the file LICENSE.LGPL included in the packaging of this
  14 ** file. Please review the following information to ensure the GNU Lesser
  15 ** General Public License version 2.1 requirements will be met:
  16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  17 **
  18 ** In addition, as a special exception, Nokia gives you certain additional
  19 ** rights. These rights are described in the Nokia Qt LGPL Exception
  20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  21 **
  22 ** GNU General Public License Usage
  23 ** Alternatively, this file may be used under the terms of the GNU General
  24 ** Public License version 3.0 as published by the Free Software Foundation
  25 ** and appearing in the file LICENSE.GPL included in the packaging of this
  26 ** file. Please review the following information to ensure the GNU General
  27 ** Public License version 3.0 requirements will be met:
  28 ** http://www.gnu.org/copyleft/gpl.html.
  29 **
  30 ** Other Usage
  31 ** Alternatively, this file may be used in accordance with the terms and
  32 ** conditions contained in a signed written agreement between you and Nokia.
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qquickevents_p_p.h"
  43
  44 QT_BEGIN_NAMESPACE
  45
  46 /*!
  47     \qmlclass KeyEvent QQuickKeyEvent
  48     \inqmlmodule QtQuick 2
  49     \ingroup qml-event-elements
  50
  51     \brief The KeyEvent object provides information about a key event.
  52
  53     For example, the following changes the Item's state property when the Enter
  54     key is pressed:
  55     \qml
  56 Item {
  57     focus: true
  58     Keys.onPressed: { if (event.key == Qt.Key_Enter) state = 'ShowDetails'; }
  59 }
  60     \endqml
  61 */
  62
  63 /*!
  64     \qmlproperty int QtQuick2::KeyEvent::key
  65
  66     This property holds the code of the key that was pressed or released.
  67
  68     See \l {Qt::Key}{Qt.Key} for the list of keyboard codes. These codes are
  69     independent of the underlying window system. Note that this
  70     function does not distinguish between capital and non-capital
  71     letters, use the text() function (returning the Unicode text the
  72     key generated) for this purpose.
  73
  74     A value of either 0 or \l {Qt::Key_unknown}{Qt.Key_Unknown} means that the event is not
  75     the result of a known key; for example, it may be the result of
  76     a compose sequence, a keyboard macro, or due to key event
  77     compression.
  78 */
  79
  80 /*!
  81     \qmlproperty string QtQuick2::KeyEvent::text
  82
  83     This property holds the Unicode text that the key generated.
  84     The text returned can be an empty string in cases where modifier keys,
  85     such as Shift, Control, Alt, and Meta, are being pressed or released.
  86     In such cases \c key will contain a valid value
  87 */
  88
  89 /*!
  90     \qmlproperty bool QtQuick2::KeyEvent::isAutoRepeat
  91
  92     This property holds whether this event comes from an auto-repeating key.
  93 */
  94
  95 /*!
  96     \qmlproperty int QtQuick2::KeyEvent::count
  97
  98     This property holds the number of keys involved in this event. If \l KeyEvent::text
  99     is not empty, this is simply the length of the string.
 100 */
 101
 102 /*!
 103     \qmlproperty bool QtQuick2::KeyEvent::accepted
 104
 105     Setting \a accepted to true prevents the key event from being
 106     propagated to the item's parent.
 107
 108     Generally, if the item acts on the key event then it should be accepted
 109     so that ancestor items do not also respond to the same event.
 110 */
 111
 112 /*!
 113     \qmlproperty int QtQuick2::KeyEvent::modifiers
 114
 115     This property holds the keyboard modifier flags that existed immediately
 116     before the event occurred.
 117
 118     It contains a bitwise combination of:
 119     \list
 120     \o Qt.NoModifier - No modifier key is pressed.
 121     \o Qt.ShiftModifier - A Shift key on the keyboard is pressed.
 122     \o Qt.ControlModifier - A Ctrl key on the keyboard is pressed.
 123     \o Qt.AltModifier - An Alt key on the keyboard is pressed.
 124     \o Qt.MetaModifier - A Meta key on the keyboard is pressed.
 125     \o Qt.KeypadModifier - A keypad button is pressed.
 126     \endlist
 127
 128     For example, to react to a Shift key + Enter key combination:
 129     \qml
 130     Item {
 131         focus: true
 132         Keys.onPressed: {
 133             if ((event.key == Qt.Key_Enter) && (event.modifiers & Qt.ShiftModifier))
 134                 doSomething();
 135         }
 136     }
 137     \endqml
 138 */
 139
 140
 141 /*!
 142     \qmlclass MouseEvent QQuickMouseEvent
 143     \inqmlmodule QtQuick 2
 144     \ingroup qml-event-elements
 145
 146     \brief The MouseEvent object provides information about a mouse event.
 147
 148     The position of the mouse can be found via the \l x and \l y properties.
 149     The button that caused the event is available via the \l button property.
 150
 151     \sa MouseArea
 152 */
 153
 154 /*!
 155     \internal
 156     \class QQuickMouseEvent
 157 */
 158
 159 /*!
 160     \qmlproperty int QtQuick2::MouseEvent::x
 161     \qmlproperty int QtQuick2::MouseEvent::y
 162
 163     These properties hold the coordinates of the position supplied by the mouse event.
 164 */
 165
 166
 167 /*!
 168     \qmlproperty bool QtQuick2::MouseEvent::accepted
 169
 170     Setting \a accepted to true prevents the mouse event from being
 171     propagated to items below this item.
 172
 173     Generally, if the item acts on the mouse event then it should be accepted
 174     so that items lower in the stacking order do not also respond to the same event.
 175 */
 176
 177 /*!
 178     \qmlproperty enumeration QtQuick2::MouseEvent::button
 179
 180     This property holds the button that caused the event.  It can be one of:
 181     \list
 182     \o Qt.LeftButton
 183     \o Qt.RightButton
 184     \o Qt.MiddleButton
 185     \endlist
 186 */
 187
 188 /*!
 189     \qmlproperty bool QtQuick2::MouseEvent::wasHeld
 190
 191     This property is true if the mouse button has been held pressed longer the
 192     threshold (800ms).
 193 */
 194
 195 /*!
 196     \qmlproperty int QtQuick2::MouseEvent::buttons
 197
 198     This property holds the mouse buttons pressed when the event was generated.
 199     For mouse move events, this is all buttons that are pressed down. For mouse
 200     press and double click events this includes the button that caused the event.
 201     For mouse release events this excludes the button that caused the event.
 202
 203     It contains a bitwise combination of:
 204     \list
 205     \o Qt.LeftButton
 206     \o Qt.RightButton
 207     \o Qt.MiddleButton
 208     \endlist
 209 */
 210
 211 /*!
 212     \qmlproperty int QtQuick2::MouseEvent::modifiers
 213
 214     This property holds the keyboard modifier flags that existed immediately
 215     before the event occurred.
 216
 217     It contains a bitwise combination of:
 218     \list
 219     \o Qt.NoModifier - No modifier key is pressed.
 220     \o Qt.ShiftModifier - A Shift key on the keyboard is pressed.
 221     \o Qt.ControlModifier - A Ctrl key on the keyboard is pressed.
 222     \o Qt.AltModifier - An Alt key on the keyboard is pressed.
 223     \o Qt.MetaModifier - A Meta key on the keyboard is pressed.
 224     \o Qt.KeypadModifier - A keypad button is pressed.
 225     \endlist
 226
 227     For example, to react to a Shift key + Left mouse button click:
 228     \qml
 229     MouseArea {
 230         onClicked: {
 231             if ((mouse.button == Qt.LeftButton) && (mouse.modifiers & Qt.ShiftModifier))
 232                 doSomething();
 233         }
 234     }
 235     \endqml
 236 */
 237
 238
 239 QT_END_NAMESPACE