doc/src/qtquick1/mouseevents.qdoc

   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 documentation of the Qt Toolkit.
   8 **
   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
  14 ** this file.
  15 **
  16 ** Other Usage
  17 ** Alternatively, this file may be used in accordance with the terms
  18 ** and conditions contained in a signed written agreement between you
  19 ** and Nokia.
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page mouseevents.html
  30 \inqmlmodule QtQuick 1
  31 \title QML Mouse Events
  32 \ingroup QML Features
  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
  36
  37 \tableofcontents
  38
  39 \section1 Mouse Elements
  40
  41 \list
  42 \o \l{MouseArea} Element
  43 \o \l{MouseEvent} Object
  44 \endlist
  45
  46 \section1 Mouse Event Handling
  47
  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.
  52
  53 \section1 Defining a Mouse Area
  54
  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
  60 definable.
  61 \snippet doc/src/snippets/declarative/mousearea/mousearea-snippet.qml anchor fill
  62
  63 \section1 Receiving Events
  64
  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:
  69
  70 \list
  71 \o canceled
  72 \o clicked
  73 \o doubleClicked
  74 \o entered
  75 \o exited
  76 \o positionChanged
  77 \o pressAndHold
  78 \o pressed
  79 \o released
  80 \endlist
  81
  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
  84
  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
  88 gestures.
  89
  90 To listen to (or explicitly ignore) a certain mouse button, set the appropriate
  91 mouse button to the \l {MouseArea::acceptedButtons}{acceptedButtons} property.
  92
  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.
 100
 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.
 104
 105 \section1 MouseEvent Object
 106
 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.
 111
 112 The \c MouseEvent object can also ignore a mouse event using its \c accepted
 113 property.
 114
 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.
 119
 120 To learn more about QML's event system, please read the \l {QML Signal and Handler Event System} document.
 121 */