<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html><head><title>QTouchEvent Class Reference</title><style>h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
td.postheader { font-family: sans-serif }
tr.address { font-family: sans-serif }
body { background: #ffffff; color: black; }
</style></head><body><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr /><td align="left" valign="top" width="32"><img align="left" border="0" height="32" src="images/rb-logo.png" width="32" /></td><td width="1">  </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a> · <a href="classes.html"><font color="#004faf">All Classes</font></a> · <a href="modules.html"><font color="#004faf">Modules</font></a></td></table><h1 align="center">QTouchEvent Class Reference<br /><sup><sup>[<a href="qtgui.html">QtGui</a> module]</sup></sup></h1><p>The QTouchEvent class contains parameters that describe a touch
event. <a href="#details">More...</a></p>
<p>Inherits <a href="qinputevent.html">QInputEvent</a>.</p><h3>Types</h3><ul><li><div class="fn" />enum <b><a href="qtouchevent.html#DeviceType-enum">DeviceType</a></b> { TouchScreen, TouchPad }</li><li><div class="fn" />class <b><a href="qtouchevent-touchpoint.html">TouchPoint</a></b></li></ul><h3>Methods</h3><ul><li><div class="fn" /><b><a href="qtouchevent.html#QTouchEvent">__init__</a></b> (<i>self</i>, QEvent.Type <i>eventType</i>, DeviceType <i>deviceType</i> = QTouchEvent.TouchScreen, Qt.KeyboardModifiers <i>modifiers</i> = Qt.NoModifier, Qt.TouchPointStates <i>touchPointStates</i> = 0, list-of-QTouchEvent.TouchPoint <i>touchPoints</i> = QList<QTouchEvent.TouchPoint>())</li><li><div class="fn" /><b><a href="qtouchevent.html#QTouchEvent-2">__init__</a></b> (<i>self</i>, QTouchEvent)</li><li><div class="fn" />DeviceType <b><a href="qtouchevent.html#deviceType">deviceType</a></b> (<i>self</i>)</li><li><div class="fn" />list-of-QTouchEvent.TouchPoint <b><a href="qtouchevent.html#touchPoints">touchPoints</a></b> (<i>self</i>)</li><li><div class="fn" />Qt.TouchPointStates <b><a href="qtouchevent.html#touchPointStates">touchPointStates</a></b> (<i>self</i>)</li><li><div class="fn" />QWidget <b><a href="qtouchevent.html#widget">widget</a></b> (<i>self</i>)</li></ul><a name="details" /><hr /><h2>Detailed Description</h2><p>The QTouchEvent class contains parameters that describe a touch
event.</p>
<a id="enabling-touch-events" name="enabling-touch-events" />
<h3>Enabling Touch Events</h3>
<p>Touch events occur when pressing, releasing, or moving one or
more touch points on a touch device (such as a touch-screen or
track-pad). To receive touch events, widgets have to have the
<a href="qt.html#WidgetAttribute-enum">Qt.WA_AcceptTouchEvents</a>
attribute set and graphics items need to have the <a href="qgraphicsitem.html#setAcceptTouchEvents">acceptTouchEvents</a>
attribute set to true.</p>
<p>When using <a href="qabstractscrollarea.html">QAbstractScrollArea</a> based widgets,
you should enable the <a href="qt.html#WidgetAttribute-enum">Qt.WA_AcceptTouchEvents</a>
attribute on the scroll area's <a href="qabstractscrollarea.html#viewport">viewport</a>.</p>
<p>Similarly to <a href="qmouseevent.html">QMouseEvent</a>, Qt
automatically grabs each touch point on the first press inside a
widget, and the widget will receive all updates for the touch point
until it is released. Note that it is possible for a widget to
receive events for numerous touch points, and that multiple widgets
may be receiving touch events at the same time.</p>
<a id="event-handling" name="event-handling" />
<h3>Event Handling</h3>
<p>All touch events are of type <a href="qevent.html#Type-enum">QEvent.TouchBegin</a>, <a href="qevent.html#Type-enum">QEvent.TouchUpdate</a>, or <a href="qevent.html#Type-enum">QEvent.TouchEnd</a>. Reimplement <a href="qwidget.html#event">QWidget.event</a>() or <a href="qabstractscrollarea.html#viewportEvent">QAbstractScrollArea.viewportEvent</a>()
for widgets and <a href="qgraphicsitem.html#sceneEvent">QGraphicsItem.sceneEvent</a>() for
items in a graphics view to receive touch events.</p>
<p>The <a href="qevent.html#Type-enum">QEvent.TouchUpdate</a> and
<a href="qevent.html#Type-enum">QEvent.TouchEnd</a> events are
sent to the widget or item that accepted the <a href="qevent.html#Type-enum">QEvent.TouchBegin</a> event. If the
<a href="qevent.html#Type-enum">QEvent.TouchBegin</a> event is not
accepted and not filtered by an event filter, then no further touch
events are sent until the next <a href="qevent.html#Type-enum">QEvent.TouchBegin</a>.</p>
<p>The <a href="qtouchevent.html#touchPoints">touchPoints</a>()
function returns a list of all touch points contained in the event.
Information about each touch point can be retrieved using the
<a href="qtouchevent-touchpoint.html">QTouchEvent.TouchPoint</a>
class. The <a href="qt.html#TouchPointState-enum">Qt.TouchPointState</a> enum
describes the different states that a touch point may have.</p>
<a id="event-delivery-and-propagation" name="event-delivery-and-propagation" />
<h3>Event Delivery and Propagation</h3>
<p>By default, <a href="qwidget.html#event">QWidget.event</a>()
translates the first non-primary touch point in a QTouchEvent into
a <a href="qmouseevent.html">QMouseEvent</a>. This makes it
possible to enable touch events on existing widgets that do not
normally handle QTouchEvent. See below for information on some
special considerations needed when doing this.</p>
<p><a href="qevent.html#Type-enum">QEvent.TouchBegin</a> is the
first touch event sent to a widget. The <a href="qevent.html#Type-enum">QEvent.TouchBegin</a> event contains a
special accept flag that indicates whether the receiver wants the
event. By default, the event is accepted. You should call <a href="qevent.html#ignore">ignore</a>() if the touch event is not handled
by your widget. The <a href="qevent.html#Type-enum">QEvent.TouchBegin</a> event is propagated
up the parent widget chain until a widget accepts it with <a href="qevent.html#accept">accept</a>(), or an event filter consumes it.
For QGraphicsItems, the <a href="qevent.html#Type-enum">QEvent.TouchBegin</a> event is propagated
to items under the mouse (similar to mouse event propagation for
QGraphicsItems).</p>
<a id="touch-point-grouping" name="touch-point-grouping" />
<h3>Touch Point Grouping</h3>
<p>As mentioned above, it is possible that several widgets can be
receiving QTouchEvents at the same time. However, Qt makes sure to
never send duplicate <a href="qevent.html#Type-enum">QEvent.TouchBegin</a> events to the same
widget, which could theoretically happen during propagation if, for
example, the user touched 2 separate widgets in a <a href="qgroupbox.html">QGroupBox</a> and both widgets ignored the
<a href="qevent.html#Type-enum">QEvent.TouchBegin</a> event.</p>
<p>To avoid this, Qt will group new touch points together using the
following rules:</p>
<ul>
<li>When the first touch point is detected, the destination widget
is determined firstly by the location on screen and secondly by the
propagation rules.</li>
<li>When additional touch points are detected, Qt first looks to
see if there are any active touch points on any ancestor or
descendent of the widget under the new touch point. If there are,
the new touch point is grouped with the first, and the new touch
point will be sent in a single QTouchEvent to the widget that
handled the first touch point. (The widget under the new touch
point will not receive an event).</li>
</ul>
<p>This makes it possible for sibling widgets to handle touch
events independently while making sure that the sequence of
QTouchEvents is always correct.</p>
<a id="mouse-events-and-the-primary-touch-point" name="mouse-events-and-the-primary-touch-point" />
<h3>Mouse Events and the Primary Touch Point</h3>
<p>QTouchEvent delivery is independent from that of <a href="qmouseevent.html">QMouseEvent</a>. On some windowing systems,
mouse events are also sent for the <a href="qtouchevent-touchpoint.html#isPrimary">primary touch point</a>.
This means it is possible for your widget to receive both
QTouchEvent and <a href="qmouseevent.html">QMouseEvent</a> for the
same user interaction point. You can use the <a href="qtouchevent-touchpoint.html#isPrimary">QTouchEvent.TouchPoint.isPrimary</a>()
function to identify the primary touch point.</p>
<p>Note that on some systems, it is possible to receive touch
events without a primary touch point. All this means is that there
will be no mouse event generated for the touch points in the
QTouchEvent.</p>
<a id="caveats" name="caveats" />
<h3>Caveats</h3>
<ul>
<li>As mentioned above, enabling touch events means multiple
widgets can be receiving touch events simultaneously. Combined with
the default <a href="qwidget.html#event">QWidget.event</a>()
handling for QTouchEvents, this gives you great flexibility in
designing touch user interfaces. Be aware of the implications. For
example, it is possible that the user is moving a <a href="qslider.html">QSlider</a> with one finger and pressing a <a href="qpushbutton.html">QPushButton</a> with another. The signals
emitted by these widgets will be interleaved.</li>
<li>Recursion into the event loop using one of the exec() methods
(e.g., <a href="qdialog.html#exec">QDialog.exec</a>() or <a href="qmenu.html#exec">QMenu.exec</a>()) in a QTouchEvent event handler
is not supported. Since there are multiple event recipients,
recursion may cause problems, including but not limited to lost
events and unexpected infinite recursion.</li>
<li>QTouchEvents are not affected by a <a href="qwidget.html#grabMouse">mouse grab</a> or an <a href="qapplication.html#activePopupWidget">active pop-up widget</a>. The
behavior of QTouchEvents is undefined when opening a pop-up or
grabbing the mouse while there are more than one active touch
points.</li>
</ul>
<hr /><h2>Type Documentation</h2><h3 class="fn"><a name="DeviceType-enum" />QTouchEvent.DeviceType</h3><p>This enum represents the type of device that generated a
<a href="qtouchevent.html">QTouchEvent</a>.</p>
<table class="valuelist">
<tr class="odd" valign="top">
<th class="tblConst">Constant</th>
<th class="tblval">Value</th>
<th class="tbldscr">Description</th>
</tr>
<tr>
<td class="topAlign"><tt>QTouchEvent.TouchScreen</tt></td>
<td class="topAlign"><tt>0</tt></td>
<td class="topAlign">In this type of device, the touch surface and
display are integrated. This means the surface and display
typically have the same size, such that there is a direct
relationship between the touch points' physical positions and the
coordinate reported by <a href="qtouchevent-touchpoint.html">QTouchEvent.TouchPoint</a>. As a
result, Qt allows the user to interact directly with multiple
QWidgets and QGraphicsItems at the same time.</td>
</tr>
<tr>
<td class="topAlign"><tt>QTouchEvent.TouchPad</tt></td>
<td class="topAlign"><tt>1</tt></td>
<td class="topAlign">In this type of device, the touch surface is
separate from the display. There is not a direct relationship
between the physical touch location and the on-screen coordinates.
Instead, they are calculated relative to the current mouse
position, and the user must use the touch-pad to move this
reference point. Unlike touch-screens, Qt allows users to only
interact with a single <a href="qwidget.html">QWidget</a> or
<a href="qgraphicsitem.html">QGraphicsItem</a> at a time.</td>
</tr>
</table>
<hr /><h2>Method Documentation</h2><h3 class="fn"><a name="QTouchEvent" />QTouchEvent.__init__ (<i>self</i>, <a href="qevent.html#Type-enum">QEvent.Type</a> <i>eventType</i>, <a href="qtouchevent.html#DeviceType-enum">DeviceType</a> <i>deviceType</i> = QTouchEvent.TouchScreen, <a href="qt-keyboardmodifiers.html">Qt.KeyboardModifiers</a> <i>modifiers</i> = Qt.NoModifier, <a href="qt-touchpointstates.html">Qt.TouchPointStates</a> <i>touchPointStates</i> = 0, list-of-QTouchEvent.TouchPoint <i>touchPoints</i> = QList<QTouchEvent.TouchPoint>())</h3><p>Constructs a <a href="qtouchevent.html">QTouchEvent</a> with the
given <i>eventType</i>, <i>deviceType</i>, and <i>touchPoints</i>.
The <i>touchPointStates</i> and <i>modifiers</i> are the current
touch point states and keyboard modifiers at the time of the
event.</p>
<h3 class="fn"><a name="QTouchEvent-2" />QTouchEvent.__init__ (<i>self</i>, <a href="qtouchevent.html">QTouchEvent</a>)</h3><h3 class="fn"><a name="deviceType" /><a href="qtouchevent.html#DeviceType-enum">DeviceType</a> QTouchEvent.deviceType (<i>self</i>)</h3><p>Returns the touch device Type, which is of type <a href="qtouchevent.html#DeviceType-enum">DeviceType</a>.</p>
<h3 class="fn"><a name="touchPoints" />list-of-QTouchEvent.TouchPoint QTouchEvent.touchPoints (<i>self</i>)</h3><p>Returns the list of touch points contained in the touch
event.</p>
<h3 class="fn"><a name="touchPointStates" /><a href="qt-touchpointstates.html">Qt.TouchPointStates</a> QTouchEvent.touchPointStates (<i>self</i>)</h3><p>Returns a bitwise OR of all the touch point states for this
event.</p>
<h3 class="fn"><a name="widget" /><a href="qwidget.html">QWidget</a> QTouchEvent.widget (<i>self</i>)</h3><p>Returns the widget on which the event occurred.</p>
<address><hr /><div align="center"><table border="0" cellspacing="0" width="100%"><tr class="address"><td align="left" width="25%">PyQt 4.10.3 for X11</td><td align="center" width="50%">Copyright © <a href="http://www.riverbankcomputing.com">Riverbank Computing Ltd</a> and <a href="http://www.qtsoftware.com">Nokia</a> 2012</td><td align="right" width="25%">Qt 4.8.5</td></tr></table></div></address></body></html>
