<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qevent.cpp -->
<title>QTouchEvent Class | Qt GUI 5.12.6</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.12</td><td ><a href="qtgui-index.html">Qt GUI</a></td><td ><a href="qtgui-module.html">C++ Classes</a></td><td >QTouchEvent</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="qtgui-index.html">Qt 5.12.6 Reference Documentation</a></td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#public-types">Public Types</a></li>
<li class="level1"><a href="#public-functions">Public Functions</a></li>
<li class="level1"><a href="#protected-variables">Protected Variables</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
<li class="level2"><a href="#enabling-touch-events">Enabling Touch Events</a></li>
<li class="level2"><a href="#event-handling">Event Handling</a></li>
<li class="level2"><a href="#event-delivery-and-propagation">Event Delivery and Propagation</a></li>
<li class="level2"><a href="#touch-point-grouping">Touch Point Grouping</a></li>
<li class="level2"><a href="#mouse-events-and-touch-event-synthesizing">Mouse Events and Touch Event Synthesizing</a></li>
<li class="level2"><a href="#caveats">Caveats</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">QTouchEvent Class</h1>
<!-- $$$QTouchEvent-brief -->
<p>The <a href="qtouchevent.html">QTouchEvent</a> class contains parameters that describe a touch event. <a href="#details">More...</a></p>
<!-- @@@QTouchEvent -->
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> Header:</td><td class="memItemRight bottomAlign"> <span class="preprocessor">#include <QTouchEvent></span>
</td></tr><tr><td class="memItemLeft rightAlign topAlign"> qmake:</td><td class="memItemRight bottomAlign"> QT += gui</td></tr><tr><td class="memItemLeft rightAlign topAlign"> Since:</td><td class="memItemRight bottomAlign"> Qt 4.6</td></tr><tr><td class="memItemLeft rightAlign topAlign"> Inherits:</td><td class="memItemRight bottomAlign"> <a href="qinputevent.html">QInputEvent</a></td></tr></table></div><ul>
<li><a href="qtouchevent-members.html">List of all members, including inherited members</a></li>
<li><a href="qtouchevent-obsolete.html">Obsolete members</a></li>
</ul>
<a name="public-types"></a>
<h2 id="public-types">Public Types</h2>
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> class </td><td class="memItemRight bottomAlign"><b><a href="qtouchevent-touchpoint.html">TouchPoint</a></b></td></tr>
</table></div>
<a name="public-functions"></a>
<h2 id="public-functions">Public Functions</h2>
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="qtouchevent.html#QTouchEvent">QTouchEvent</a></b>(QEvent::Type <i>eventType</i>, QTouchDevice *<i>device</i> = nullptr, Qt::KeyboardModifiers <i>modifiers</i> = Qt::NoModifier, Qt::TouchPointStates <i>touchPointStates</i> = ..., const QList<QTouchEvent::TouchPoint> &<i>touchPoints</i> = ...)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> virtual </td><td class="memItemRight bottomAlign"><b><a href="qtouchevent.html#dtor.QTouchEvent">~QTouchEvent</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QTouchDevice *</td><td class="memItemRight bottomAlign"><b><a href="qtouchevent.html#device">device</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QObject *</td><td class="memItemRight bottomAlign"><b><a href="qtouchevent.html#target">target</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> Qt::TouchPointStates </td><td class="memItemRight bottomAlign"><b><a href="qtouchevent.html#touchPointStates">touchPointStates</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> const QList<QTouchEvent::TouchPoint> &</td><td class="memItemRight bottomAlign"><b><a href="qtouchevent.html#touchPoints">touchPoints</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QWindow *</td><td class="memItemRight bottomAlign"><b><a href="qtouchevent.html#window">window</a></b>() const</td></tr>
</table></div>
<ul>
<li class="fn">2 public functions inherited from <a href="qinputevent.html#public-functions">QInputEvent</a></li>
<li class="fn">6 public functions inherited from <a href="../qtcore/qevent.html#public-functions">QEvent</a></li>
</ul>
<a name="protected-variables"></a>
<h2 id="protected-variables">Protected Variables</h2>
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> QTouchDevice *</td><td class="memItemRight bottomAlign"><b><a href="qtouchevent.html#underscore.device-var">_device</a></b></td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QObject *</td><td class="memItemRight bottomAlign"><b><a href="qtouchevent.html#underscore.target-var">_target</a></b></td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> Qt::TouchPointStates </td><td class="memItemRight bottomAlign"><b><a href="qtouchevent.html#underscore.touchPointStates-var">_touchPointStates</a></b></td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QList<QTouchEvent::TouchPoint> </td><td class="memItemRight bottomAlign"><b><a href="qtouchevent.html#underscore.touchPoints-var">_touchPoints</a></b></td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QWindow *</td><td class="memItemRight bottomAlign"><b><a href="qtouchevent.html#underscore.window-var">_window</a></b></td></tr>
</table></div>
<h3>Additional Inherited Members</h3>
<ul>
<li class="fn">1 property inherited from <a href="../qtcore/qevent.html#properties">QEvent</a></li>
<li class="fn">1 static public member inherited from <a href="../qtcore/qevent.html#static-public-members">QEvent</a></li>
</ul>
<a name="details"></a>
<!-- $$$QTouchEvent-description -->
<div class="descr">
<h2 id="details">Detailed Description</h2>
<p>The <a href="qtouchevent.html">QTouchEvent</a> class contains parameters that describe a touch event.</p>
<a name="enabling-touch-events"></a>
<h3 id="enabling-touch-events">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="../qtcore/qt.html#WidgetAttribute-enum">Qt::WA_AcceptTouchEvents</a> attribute set and graphics items need to have the <a href="../qtwidgets/qgraphicsitem.html#setAcceptTouchEvents">acceptTouchEvents</a> attribute set to true.</p>
<p>When using <a href="../qtwidgets/qabstractscrollarea.html">QAbstractScrollArea</a> based widgets, you should enable the <a href="../qtcore/qt.html#WidgetAttribute-enum">Qt::WA_AcceptTouchEvents</a> attribute on the scroll area's <a href="../qtwidgets/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 name="event-handling"></a>
<h3 id="event-handling">Event Handling</h3>
<p>All touch events are of type <a href="../qtcore/qevent.html#Type-enum">QEvent::TouchBegin</a>, <a href="../qtcore/qevent.html#Type-enum">QEvent::TouchUpdate</a>, <a href="../qtcore/qevent.html#Type-enum">QEvent::TouchEnd</a> or <a href="../qtcore/qevent.html#Type-enum">QEvent::TouchCancel</a>. Reimplement <a href="../qtwidgets/qwidget.html#event">QWidget::event</a>() or <a href="../qtwidgets/qabstractscrollarea.html#viewportEvent">QAbstractScrollArea::viewportEvent</a>() for widgets and <a href="../qtwidgets/qgraphicsitem.html#sceneEvent">QGraphicsItem::sceneEvent</a>() for items in a graphics view to receive touch events.</p>
<p>Unlike widgets, QWindows receive touch events always, there is no need to opt in. When working directly with a <a href="qwindow.html">QWindow</a>, it is enough to reimplement <a href="qwindow.html#touchEvent">QWindow::touchEvent</a>().</p>
<p>The <a href="../qtcore/qevent.html#Type-enum">QEvent::TouchUpdate</a> and <a href="../qtcore/qevent.html#Type-enum">QEvent::TouchEnd</a> events are sent to the widget or item that accepted the <a href="../qtcore/qevent.html#Type-enum">QEvent::TouchBegin</a> event. If the <a href="../qtcore/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="../qtcore/qevent.html#Type-enum">QEvent::TouchBegin</a>.</p>
<p>Some systems may send an event of type <a href="../qtcore/qevent.html#Type-enum">QEvent::TouchCancel</a>. Upon receiving this event applications are requested to ignore the entire active touch sequence. For example in a composited system the compositor may decide to treat certain gestures as system-wide gestures. Whenever such a decision is made (the gesture is recognized), the clients will be notified with a <a href="../qtcore/qevent.html#Type-enum">QEvent::TouchCancel</a> event so they can update their state accordingly.</p>
<p>The <a href="qtouchevent.html#touchPoints">touchPoints</a>() function returns a list of all touch points contained in the event. Note that this list may be empty, for example in case of a <a href="../qtcore/qevent.html#Type-enum">QEvent::TouchCancel</a> event. Information about each touch point can be retrieved using the <a href="qtouchevent-touchpoint.html">QTouchEvent::TouchPoint</a> class. The <a href="../qtcore/qt.html#TouchPointState-enum">Qt::TouchPointState</a> enum describes the different states that a touch point may have.</p>
<p><b>Note: </b>The list of <a href="qtouchevent.html#touchPoints">touchPoints</a>() will never be partial: A touch event will always contain a touch point for each existing physical touch contacts targetting the window or widget to which the event is sent. For instance, assuming that all touches target the same window or widget, an event with a condition of <a href="qtouchevent.html#touchPoints">touchPoints</a>().count()==2 is guaranteed to imply that the number of fingers touching the touchscreen or touchpad is exactly two.</p><a name="event-delivery-and-propagation"></a>
<h3 id="event-delivery-and-propagation">Event Delivery and Propagation</h3>
<p>By default, <a href="qguiapplication.html">QGuiApplication</a> translates the first touch point in a <a href="qtouchevent.html">QTouchEvent</a> into a <a href="qmouseevent.html">QMouseEvent</a>. This makes it possible to enable touch events on existing widgets that do not normally handle <a href="qtouchevent.html">QTouchEvent</a>. See below for information on some special considerations needed when doing this.</p>
<p><a href="../qtcore/qevent.html#Type-enum">QEvent::TouchBegin</a> is the first touch event sent to a widget. The <a href="../qtcore/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="../qtcore/qevent.html#ignore">ignore</a>() if the touch event is not handled by your widget. The <a href="../qtcore/qevent.html#Type-enum">QEvent::TouchBegin</a> event is propagated up the parent widget chain until a widget accepts it with <a href="../qtcore/qevent.html#accept">accept</a>(), or an event filter consumes it. For QGraphicsItems, the <a href="../qtcore/qevent.html#Type-enum">QEvent::TouchBegin</a> event is propagated to items under the mouse (similar to mouse event propagation for QGraphicsItems).</p>
<a name="touch-point-grouping"></a>
<h3 id="touch-point-grouping">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="../qtcore/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="../qtwidgets/qgroupbox.html">QGroupBox</a> and both widgets ignored the <a href="../qtcore/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 <a href="qtouchevent.html">QTouchEvent</a> 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 name="mouse-events-and-touch-event-synthesizing"></a>
<h3 id="mouse-events-and-touch-event-synthesizing">Mouse Events and Touch Event Synthesizing</h3>
<p><a href="qtouchevent.html">QTouchEvent</a> delivery is independent from that of <a href="qmouseevent.html">QMouseEvent</a>. The application flags <a href="../qtcore/qt.html#ApplicationAttribute-enum">Qt::AA_SynthesizeTouchForUnhandledMouseEvents</a> and <a href="../qtcore/qt.html#ApplicationAttribute-enum">Qt::AA_SynthesizeMouseForUnhandledTouchEvents</a> can be used to enable or disable automatic synthesizing of touch events to mouse events and mouse events to touch events.</p>
<a name="caveats"></a>
<h3 id="caveats">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="../qtwidgets/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="../qtwidgets/qslider.html">QSlider</a> with one finger and pressing a <a href="../qtwidgets/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="../qtwidgets/qdialog.html#exec">QDialog::exec</a>() or <a href="../qtwidgets/qmenu.html#exec">QMenu::exec</a>()) in a <a href="qtouchevent.html">QTouchEvent</a> 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="../qtwidgets/qwidget.html#grabMouse">mouse grab</a> or an <a href="../qtwidgets/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>
</div>
<p><b>See also </b><a href="qtouchevent-touchpoint.html">QTouchEvent::TouchPoint</a>, <a href="../qtcore/qt.html#TouchPointState-enum">Qt::TouchPointState</a>, <a href="../qtcore/qt.html#WidgetAttribute-enum">Qt::WA_AcceptTouchEvents</a>, and <a href="../qtwidgets/qgraphicsitem.html#acceptTouchEvents">QGraphicsItem::acceptTouchEvents</a>().</p>
<!-- @@@QTouchEvent -->
<div class="func">
<h2>Member Function Documentation</h2>
<!-- $$$QTouchEvent[overload1]$$$QTouchEventQEvent::TypeQTouchDevice*Qt::KeyboardModifiersQt::TouchPointStatesconstQList<QTouchEvent::TouchPoint>& -->
<h3 class="fn" id="QTouchEvent"><a name="QTouchEvent"></a>QTouchEvent::<span class="name">QTouchEvent</span>(<span class="type"><a href="../qtcore/qevent.html#Type-enum">QEvent::Type</a></span> <i>eventType</i>, <span class="type"><a href="qtouchdevice.html">QTouchDevice</a></span> *<i>device</i> = nullptr, <span class="type"><a href="../qtcore/qt.html#KeyboardModifier-enum">Qt::KeyboardModifiers</a></span> <i>modifiers</i> = Qt::NoModifier, <span class="type"><a href="../qtcore/qt.html#TouchPointState-enum">Qt::TouchPointStates</a></span> <i>touchPointStates</i> = ..., const <span class="type">QList</span><<span class="type"><a href="qtouchevent-touchpoint.html">QTouchEvent::TouchPoint</a></span>> &<i>touchPoints</i> = ...)</h3>
<p>Constructs a <a href="qtouchevent.html">QTouchEvent</a> with the given <i>eventType</i>, <i>device</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>
<!-- @@@QTouchEvent -->
<!-- $$$~QTouchEvent[overload1]$$$~QTouchEvent -->
<h3 class="fn" id="dtor.QTouchEvent"><a name="dtor.QTouchEvent"></a><code>[virtual] </code>QTouchEvent::<span class="name">~QTouchEvent</span>()</h3>
<p>Destroys the <a href="qtouchevent.html">QTouchEvent</a>.</p>
<!-- @@@~QTouchEvent -->
<!-- $$$device[overload1]$$$device -->
<h3 class="fn" id="device"><a name="device"></a><span class="type"><a href="qtouchdevice.html">QTouchDevice</a></span> *QTouchEvent::<span class="name">device</span>() const</h3>
<p>Returns the touch device from which this touch event originates.</p>
<!-- @@@device -->
<!-- $$$target[overload1]$$$target -->
<h3 class="fn" id="target"><a name="target"></a><span class="type"><a href="../qtcore/qobject.html">QObject</a></span> *QTouchEvent::<span class="name">target</span>() const</h3>
<p>Returns the target object within the window on which the event occurred. This is typically a <a href="../qtwidgets/qwidget.html">QWidget</a> or a QQuickItem. May be 0 when no specific target is available.</p>
<!-- @@@target -->
<!-- $$$touchPointStates[overload1]$$$touchPointStates -->
<h3 class="fn" id="touchPointStates"><a name="touchPointStates"></a><span class="type"><a href="../qtcore/qt.html#TouchPointState-enum">Qt::TouchPointStates</a></span> QTouchEvent::<span class="name">touchPointStates</span>() const</h3>
<p>Returns a bitwise OR of all the touch point states for this event.</p>
<!-- @@@touchPointStates -->
<!-- $$$touchPoints[overload1]$$$touchPoints -->
<h3 class="fn" id="touchPoints"><a name="touchPoints"></a>const <span class="type">QList</span><<span class="type"><a href="qtouchevent-touchpoint.html">QTouchEvent::TouchPoint</a></span>> &QTouchEvent::<span class="name">touchPoints</span>() const</h3>
<p>Returns the list of touch points contained in the touch event.</p>
<!-- @@@touchPoints -->
<!-- $$$window[overload1]$$$window -->
<h3 class="fn" id="window"><a name="window"></a><span class="type"><a href="qwindow.html">QWindow</a></span> *QTouchEvent::<span class="name">window</span>() const</h3>
<p>Returns the window on which the event occurred. Useful for doing global-local mapping on data like rawScreenPositions() which, for performance reasons, only stores the global positions in the touch event.</p>
<!-- @@@window -->
</div>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2019 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br/> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br/> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
d5e62c01ae8d1e579463c6a871dd44bf
>
files
>
1918
