<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- gestures.qdoc -->
<title>Gestures in Widgets and Graphics View | Qt Widgets 5.9</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.9</td><td ><a href="qtwidgets-index.html">Qt Widgets</a></td><td >Gestures in Widgets and Graphics View</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.4 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<link rel="start" href="index.html" />
<p class="naviNextPrevious headerNavi">
</p><p/>
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#overview">Overview</a></li>
<li class="level1"><a href="#using-standard-gestures-with-widgets">Using Standard Gestures with Widgets</a></li>
<li class="level1"><a href="#handling-events">Handling Events</a></li>
<li class="level2"><a href="#standard-procedure-for-event-handling">Standard Procedure for Event Handling</a></li>
<li class="level2"><a href="#example-event-handling">Example Event Handling</a></li>
<li class="level1"><a href="#creating-your-own-gesture-recognizer">Creating Your Own Gesture Recognizer</a></li>
<li class="level2"><a href="#filtering-input-events">Filtering Input Events</a></li>
<li class="level2"><a href="#custom-gestures">Custom Gestures</a></li>
<li class="level2"><a href="#resetting-gestures">Resetting Gestures</a></li>
<li class="level1"><a href="#using-a-new-gesture-recognizer">Using a New Gesture Recognizer</a></li>
<li class="level1"><a href="#further-reading">Further Reading</a></li>
<li class="level2"><a href="#gestures-in-qt-quick">Gestures in Qt Quick</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Gestures in Widgets and Graphics View</h1>
<span class="subtitle"></span>
<!-- $$$gestures-overview.html-description -->
<div class="descr"> <a name="details"></a>
<p>Qt includes a framework for gesture programming that has the ability to form gestures from a series of events, independently of the input methods used. A gesture could be a particular movement of a mouse, a touch screen action, or a series of events from some other source. The nature of the input, the interpretation of the gesture and the action taken are the choice of the developer.</p>
<a name="overview"></a>
<h2 id="overview">Overview</h2>
<p><a href="qgesture.html">QGesture</a> is the central class in Qt's gesture framework, providing a container for information about gestures performed by the user. <a href="qgesture.html">QGesture</a> exposes properties that give general information that is common to all gestures, and these can be extended to provide additional gesture-specific information. Common panning, pinching and swiping gestures are represented by specialized classes: <a href="qpangesture.html">QPanGesture</a>, <a href="qpinchgesture.html">QPinchGesture</a> and <a href="qswipegesture.html">QSwipeGesture</a>.</p>
<p>Developers can also implement new gestures by subclassing and extending the <a href="qgesturerecognizer.html">QGestureRecognizer</a> class. Adding support for a new gesture involves implementing code to recognize the gesture from input events. This is described in the <a href="gestures-overview.html#creating-your-own-gesture-recognizer">Creating Your Own Gesture Recognizer</a> section.</p>
<a name="using-standard-gestures-with-widgets"></a>
<h2 id="using-standard-gestures-with-widgets">Using Standard Gestures with Widgets</h2>
<p>Gestures can be enabled for instances of <a href="qwidget.html">QWidget</a> and <a href="qgraphicsobject.html">QGraphicsObject</a> subclasses. An object that accepts gesture input is referred to throughout the documentation as a <i>target object</i>.</p>
<p>To enable a gesture for a target object, call its <a href="qwidget.html#grabGesture">QWidget::grabGesture</a>() or <a href="qgraphicsobject.html#grabGesture">QGraphicsObject::grabGesture</a>() function with an argument describing the required gesture type. The standard types are defined by the <a href="../qtcore/qt.html#GestureType-enum">Qt::GestureType</a> enum and include many commonly used gestures.</p>
<pre class="cpp">
foreach (<span class="type"><a href="../qtcore/qt.html">Qt</a></span><span class="operator">::</span>GestureType gesture<span class="operator">,</span> gestures)
grabGesture(gesture);
</pre>
<p>In the above code, the gestures are set up in the constructor of the target object itself.</p>
<a name="handling-events"></a>
<h2 id="handling-events">Handling Events</h2>
<p>When the user performs a gesture, <a href="qgestureevent.html">QGestureEvent</a> events will be delivered to the target object, and these can be handled by reimplementing the <a href="qwidget.html#event">QWidget::event</a>() handler function for widgets or <a href="qgraphicsitem.html#sceneEvent">QGraphicsItem::sceneEvent</a>() for graphics objects.</p>
<p>As one target object can subscribe to more than one gesture type, the <a href="qgestureevent.html">QGestureEvent</a> can contain more than one <a href="qgesture.html">QGesture</a>, indicating several possible gestures are active at the same time. It is then up to the widget to determine how to handle those multiple gestures and choose if some should be canceled in favor of others.</p>
<p>Each <a href="qgesture.html">QGesture</a> contained within a <a href="qgestureevent.html">QGestureEvent</a> object can be accepted() or ignored() individually, or all together. Additionally, you can query the individual <a href="qgesture.html">QGesture</a> data objects (the state) using several getters.</p>
<a name="standard-procedure-for-event-handling"></a>
<h3 >Standard Procedure for Event Handling</h3>
<p>A <a href="qgesture.html">QGesture</a> is by default accepted when it arrives at your widget. However, it is good practice to always explicitly accept or reject a gesture. The general rule is that, if you accept a gesture, you are using it. If you are ignoring it you are not interested in it. Ignoring a gesture may mean it gets offered to another target object, or it will get canceled.</p>
<p>Each <a href="qgesture.html">QGesture</a> has several states it goes through; there is a well defined way to change the state, typically the user input is the cause of state changes (by starting and stopping interaction, for instance) but the widget can also cause state changes.</p>
<p>The first time a particular <a href="qgesture.html">QGesture</a> is delivered to a widget or graphics item, it will be in the <a href="../qtcore/qt.html#GestureState-enum">Qt::GestureStarted</a> state. The way you handle the gesture at this point influences whether you can interact with it later.</p>
<ul>
<li>Accepting the gesture means the widget acts on the gesture and there will follow gestures with the Qt::GestureUpdatedstate.</li>
<li>Ignoring the gesture will mean the gesture will never be offered to you again. It will be offered to a parent widget or item as well.</li>
<li>Calling setGestureCancelPolicy() on the gesture when it is in its starting state, and is also accepted can cause other gestures to be canceled.</li>
</ul>
<p>Using <a href="qgesture.html#GestureCancelPolicy-enum">QGesture::CancelAllInContext</a> to cancel a gesture will cause all gestures, in any state, to be canceled unless they are explicitly accepted. This means that active gestures on children will get canceled. It also means that gestures delivered in the same <a href="qgestureevent.html">QGestureEvent</a> will get canceled if the widget ignores them. This can be a useful way to filter out all gestures except the one you are interested in.</p>
<a name="example-event-handling"></a>
<h3 >Example Event Handling</h3>
<p>For convenience, the <a href="qtwidgets-gestures-imagegestures-example.html">Image Gestures Example</a> reimplements the general <a href="qwidget.html#event">event()</a> handler function and delegates gesture events to a specialized gestureEvent() function:</p>
<pre class="cpp">
bool ImageWidget<span class="operator">::</span>event(<span class="type"><a href="../qtcore/qevent.html">QEvent</a></span> <span class="operator">*</span>event)
{
<span class="keyword">if</span> (event<span class="operator">-</span><span class="operator">></span>type() <span class="operator">=</span><span class="operator">=</span> <span class="type"><a href="../qtcore/qevent.html">QEvent</a></span><span class="operator">::</span>Gesture)
<span class="keyword">return</span> gestureEvent(<span class="keyword">static_cast</span><span class="operator"><</span><span class="type"><a href="qgestureevent.html">QGestureEvent</a></span><span class="operator">*</span><span class="operator">></span>(event));
<span class="keyword">return</span> <span class="type"><a href="qwidget.html">QWidget</a></span><span class="operator">::</span>event(event);
}
</pre>
<p>The gesture events delivered to the target object can be examined individually and dealt with appropriately:</p>
<pre class="cpp">
bool ImageWidget<span class="operator">::</span>gestureEvent(<span class="type"><a href="qgestureevent.html">QGestureEvent</a></span> <span class="operator">*</span>event)
{
qCDebug(lcExample) <span class="operator"><</span><span class="operator"><</span> <span class="string">"gestureEvent():"</span> <span class="operator"><</span><span class="operator"><</span> event;
<span class="keyword">if</span> (<span class="type"><a href="qgesture.html">QGesture</a></span> <span class="operator">*</span>swipe <span class="operator">=</span> event<span class="operator">-</span><span class="operator">></span>gesture(<span class="type"><a href="../qtcore/qt.html">Qt</a></span><span class="operator">::</span>SwipeGesture))
swipeTriggered(<span class="keyword">static_cast</span><span class="operator"><</span><span class="type"><a href="qswipegesture.html">QSwipeGesture</a></span> <span class="operator">*</span><span class="operator">></span>(swipe));
<span class="keyword">else</span> <span class="keyword">if</span> (<span class="type"><a href="qgesture.html">QGesture</a></span> <span class="operator">*</span>pan <span class="operator">=</span> event<span class="operator">-</span><span class="operator">></span>gesture(<span class="type"><a href="../qtcore/qt.html">Qt</a></span><span class="operator">::</span>PanGesture))
panTriggered(<span class="keyword">static_cast</span><span class="operator"><</span><span class="type"><a href="qpangesture.html">QPanGesture</a></span> <span class="operator">*</span><span class="operator">></span>(pan));
<span class="keyword">if</span> (<span class="type"><a href="qgesture.html">QGesture</a></span> <span class="operator">*</span>pinch <span class="operator">=</span> event<span class="operator">-</span><span class="operator">></span>gesture(<span class="type"><a href="../qtcore/qt.html">Qt</a></span><span class="operator">::</span>PinchGesture))
pinchTriggered(<span class="keyword">static_cast</span><span class="operator"><</span><span class="type"><a href="qpinchgesture.html">QPinchGesture</a></span> <span class="operator">*</span><span class="operator">></span>(pinch));
<span class="keyword">return</span> <span class="keyword">true</span>;
}
</pre>
<p>Responding to a gesture is simply a matter of obtaining the <a href="qgesture.html">QGesture</a> object delivered in the <a href="qgestureevent.html">QGestureEvent</a> sent to the target object and examining the information it contains.</p>
<pre class="cpp">
<span class="type">void</span> ImageWidget<span class="operator">::</span>swipeTriggered(<span class="type"><a href="qswipegesture.html">QSwipeGesture</a></span> <span class="operator">*</span>gesture)
{
<span class="keyword">if</span> (gesture<span class="operator">-</span><span class="operator">></span>state() <span class="operator">=</span><span class="operator">=</span> <span class="type"><a href="../qtcore/qt.html">Qt</a></span><span class="operator">::</span>GestureFinished) {
<span class="keyword">if</span> (gesture<span class="operator">-</span><span class="operator">></span>horizontalDirection() <span class="operator">=</span><span class="operator">=</span> <span class="type"><a href="qswipegesture.html">QSwipeGesture</a></span><span class="operator">::</span>Left
<span class="operator">|</span><span class="operator">|</span> gesture<span class="operator">-</span><span class="operator">></span>verticalDirection() <span class="operator">=</span><span class="operator">=</span> <span class="type"><a href="qswipegesture.html">QSwipeGesture</a></span><span class="operator">::</span>Up) {
qCDebug(lcExample) <span class="operator"><</span><span class="operator"><</span> <span class="string">"swipeTriggered(): swipe to previous"</span>;
goPrevImage();
} <span class="keyword">else</span> {
qCDebug(lcExample) <span class="operator"><</span><span class="operator"><</span> <span class="string">"swipeTriggered(): swipe to next"</span>;
goNextImage();
}
update();
}
}
</pre>
<p>Here, we examine the direction in which the user swiped the widget and modify its contents accordingly.</p>
<a name="creating-your-own-gesture-recognizer"></a>
<h2 id="creating-your-own-gesture-recognizer">Creating Your Own Gesture Recognizer</h2>
<p>Adding support for a new gesture involves creating and registering a new gesture recognizer. Depending on the recognition process for the gesture, it may also involve creating a new gesture object.</p>
<p>To create a new recognizer, you need to subclass <a href="qgesturerecognizer.html">QGestureRecognizer</a> to create a custom recognizer class. There is one virtual function that you must reimplement and two others that can be reimplemented as required.</p>
<a name="filtering-input-events"></a>
<h3 >Filtering Input Events</h3>
<p>The <a href="qgesturerecognizer.html#recognize">recognize()</a> function must be reimplemented. This function handles and filters the incoming input events for the target objects and determines whether or not they correspond to the gesture the recognizer is looking for.</p>
<p>Although the logic for gesture recognition is implemented in this function, possibly using a state machine based on the <a href="../qtcore/qt.html#GestureState-enum">Qt::GestureState</a> enums, you can store persistent information about the state of the recognition process in the <a href="qgesture.html">QGesture</a> object supplied.</p>
<p>Your <a href="qgesturerecognizer.html#recognize">recognize()</a> function must return a value of <a href="qgesturerecognizer.html#ResultFlag-enum">QGestureRecognizer::Result</a> that indicates the state of recognition for a given gesture and target object. This determines whether or not a gesture event will be delivered to a target object.</p>
<a name="custom-gestures"></a>
<h3 >Custom Gestures</h3>
<p>If you choose to represent a gesture by a custom <a href="qgesture.html">QGesture</a> subclass, you will need to reimplement the <a href="qgesturerecognizer.html#create">create()</a> function to construct instances of your gesture class instead of standard <a href="qgesture.html">QGesture</a> instances. Alternatively, you may want to use standard <a href="qgesture.html">QGesture</a> instances, but add additional dynamic properties to them to express specific details of the gesture you want to handle.</p>
<a name="resetting-gestures"></a>
<h3 >Resetting Gestures</h3>
<p>If you use custom gesture objects that need to be reset or otherwise specially handled when a gesture is canceled, you need to reimplement the <a href="qgesturerecognizer.html#reset">reset()</a> function to perform these special tasks.</p>
<p>Note that <a href="qgesture.html">QGesture</a> objects are only created once for each combination of target object and gesture type, and they might be reused every time the user attempts to perform the same gesture type on the target object. As a result, it can be useful to reimplement the <a href="qgesturerecognizer.html#reset">reset()</a> function to clean up after each previous attempt at recognizing a gesture.</p>
<a name="using-a-new-gesture-recognizer"></a>
<h2 id="using-a-new-gesture-recognizer">Using a New Gesture Recognizer</h2>
<p>To use a gesture recognizer, construct an instance of your <a href="qgesturerecognizer.html">QGestureRecognizer</a> subclass, and register it with the application with <a href="qgesturerecognizer.html#registerRecognizer">QGestureRecognizer::registerRecognizer</a>(). A recognizer for a given type of gesture can be removed with <a href="qgesturerecognizer.html#unregisterRecognizer">QGestureRecognizer::unregisterRecognizer</a>().</p>
<a name="further-reading"></a>
<h2 id="further-reading">Further Reading</h2>
<p>The <a href="qtwidgets-gestures-imagegestures-example.html">Image Gestures Example</a> shows how to enable gestures for a widget in a simple image viewer application.</p>
<a name="gestures-in-qt-quick"></a>
<h3 >Gestures in Qt Quick</h3>
<p>Qt Quick does not have a generic global gesture recognizer; rather, individual components can respond to touch events in their own ways. For example the PinchArea handles two-finger gestures, Flickable is for flicking content with a single finger, and MultiPointTouchArea can handle an arbitrary number of touch points and allow the application developer to write custom gesture recognition code.</p>
</div>
<!-- @@@gestures-overview.html -->
<p class="naviNextPrevious footerNavi">
</p>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 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
>
6
>
armv5tl
>
media
>
core-updates
>
by-pkgid
>
768f7d9f703884aa2562bf0a651086df
>
files
>
2431
