~oif-team/ubuntu/natty/qt4-x11/xi2.1

<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="functions.html"><font color="#004faf">All Functions</font></a> · <a href="overviews.html"><font color="#004faf">Overviews</font></a></td><td class="searchBar" align="right" valign="center"><form action="http://www.google.com/cse" id="cse-search-box"><div><input type="hidden" name="cx" value="000136343326384750312:dhbxnqlakyu" /><input type="hidden" name="ie" value="UTF-8" /><input type="text" name="q" size="31" /><input type="submit" name="sa" value="Search" /></div></form></td>

</tr></table><p>

</p>

<h1 class="title">Gestures Programming<br /><span class="subtitle"></span>

</h1>

<p>Qt includes a framework for gesture programming that gives 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>

<ul><li><a href="#overview">Overview</a></li>

<li><a href="#using-standard-gestures-with-widgets">Using Standard Gestures with Widgets</a></li>

<li><a href="#using-standard-gestures-with-graphics-items">Using Standard Gestures with Graphics Items</a></li>

<li><a href="#creating-your-own-gesture-recognizer">Creating Your Own Gesture Recognizer</a></li>

<li><a href="#the-imageviewer-example">The ImageViewer Example</a></li>

</ul>

<h3>Overview</h3>

<p><a href="qgesture.html">QGesture</a> is the central class in Qt's gesture framework, providing the API used by classes that represent specific gestures, such as QPanGesture, QPinchGesture, and QSwipeGesture. These standard classes are ready to use, and each exposes functions and properties that give gesture-specific information about the user's input. This is described in the <a href="#using-standard-gestures-with-widgets">Using Standard Gestures With Widgets</a> section.</p>

<p><a href="qgesture.html">QGesture</a> is also designed to be subclassed and extended so that support for new gestures can be implemented by developers. Adding support for a new gesture involves implementing code to recognize the gesture from incoming events. This is described in the <a href="#creating-your-own-gesture-recognizer">Creating Your Own Gesture Recognizer</a> section.</p>

<h3>Using Standard Gestures with Widgets</h3>

<p>Gesture objects are applied directly to widgets and other controls that accept user input — these are the <i>target objects</i>. When a gesture object is constructed, the target object is typically passed to the constructor, though it can also be passed as the argument to the setGestureTarget() function.</p>

<p>In the above code, the gesture is set up in the constructor of the target object itself, so the argument to the QSwipeGesture constructor is <i>this</i>.</p>

<p>When the user performs a gesture, various signals may be emitted by the gesture object. To monitor the user's actions, you need to connect signals from the gesture object to slots in your code.</p>

<p>Here, the triggered() signal is used to inform the application that a gesture was used. More precise monitoring of a gesture can be implemented by connecting its started(), canceled() and finished() signals to slots.</p>

<p>Responding to a signal is simply a matter of obtaining the gesture that sent it and examining the information it contains.</p>

<p>Here, we examine the direction in which the user swiped the widget and modify its contents accordingly.</p>

<h3>Using Standard Gestures with Graphics Items</h3>

<p>The approach used for applying gestures to widgets can also be used with graphics items. However, instead of passing a target object to the gesture object's constructor, you set a target graphics item with the setGraphicsItem() function.</p>

<h3>Creating Your Own Gesture Recognizer</h3>

<p><a href="qgesture.html">QGesture</a> is a base class for a user defined gesture recognizer class. In order to implement the recognizer you will need to subclass the <a href="qgesture.html">QGesture</a> class and implement the pure virtual function filterEvent() to filter out events that are not relevant to your gesture.</p>

<p>Once you have implemented the filterEvent() function to make your own recognizer you can process events. A sequence of events may, according to your own rules, represent a gesture. The events can be singly passed to the recognizer via the filterEvent() function or as a stream of events by specifying a parent source of events. The events can be from any source and could result in any action as defined by the user. The source and action need not be graphical, though that would be the most likely scenario. To find how to connect a source of events to automatically feed into the recognizer see the <a href="qgesture.html">QGesture</a> documentation.</p>

<p>Recognizers based on <a href="qgesture.html">QGesture</a> can emit any of the following signals to indicate their progress in recognizing user input:</p>

<ul>

<li>triggered() is emitted when a gesture is recognized.</li>

<li>started() indicates that the gesture object has started to recognize user input.</li>

<li>finished() is emitted when the gesture object has recognized the user input as a gesture, and finished handling it.</li>

<li>canceled() indicates that the gesture was canceled, either by the user or by the application.</li>

</ul>

<p>These signals are emitted when the state changes with the call to updateState(), more than one signal may be emitted when a change of state occurs. There are four GestureStates</p>

<thead><tr valign="top" class="qt-style"><th>New State</th><th>Description</th><th><a href="qgesture.html">QGesture</a> Actions on Entering this State</th></tr></thead>

<tr valign="top" class="odd"><td><a href="qt.html#GestureState-enum">Qt::NoGesture</a></td><td>Initial value</td><td>emit canceled()</td></tr>

<tr valign="top" class="even"><td><a href="qt.html#GestureState-enum">Qt::GestureStarted</a></td><td>A continuous gesture has started</td><td>emit started() and emit triggered()</td></tr>

<tr valign="top" class="odd"><td><a href="qt.html#GestureState-enum">Qt::GestureUpdated</a></td><td>A gesture continues</td><td>emit triggered()</td></tr>

<tr valign="top" class="even"><td><a href="qt.html#GestureState-enum">Qt::GestureFinished</a></td><td>A gesture has finished.</td><td>emit finished()</td></tr>

</table></p>

<p><b>Note:</b> started() can be emitted if entering any state greater than NoGesture if NoGesture was the previous state. This means that your state machine does not need to explicitly use the <a href="qt.html#GestureState-enum">Qt::GestureStarted</a> state, you can simply proceed from NoGesture to <a href="qt.html#GestureState-enum">Qt::GestureUpdated</a> to emit a started() signal and a triggered() signal.</p>

<p>You may use some or all of these states when implementing the pure virtual function filterEvent(). filterEvent() will usually implement a state machine using the GestureState enums, but the details of which states are used is up to the developer.</p>

<p>You may also need to reimplement the virtual function reset() if internal data or objects need to be re-initialized. The function must conclude with a call to updateState() to change the current state to <a href="qt.html#GestureState-enum">Qt::NoGesture</a>.</p>

<h3>The ImageViewer Example</h3>

<p>To illustrate how to use <a href="qgesture.html">QGesture</a> we will look at the ImageViewer example. This example uses QPanGesture, a standard gesture, and an implementation of TapAndHoldGesture. Note that TapAndHoldGesture is platform-dependent.</p>

<pre> void TapAndHoldGesture::reset()

{

timer.stop();

iteration = 0;

position = startPosition = QPoint();

updateState(Qt::NoGesture);

}</pre>

<p>In ImageViewer we see that the ImageWidget class uses two gestures: QPanGesture and TapAndHoldGesture. The QPanGesture is a standard gesture which is part of Qt. TapAndHoldGesture is defined and implemented as part of the example. The ImageWidget listens for signals from the gestures, but is not interested in the started() signal.</p>

<pre> private slots:

void gestureTriggered();

void gestureFinished();

void gestureCancelled();</pre>

<p>TapAndHoldGesture uses <a href="qtouchevent.html">QTouchEvent</a> events and mouse events to detect start, update and end events that can be mapped onto the GestureState changes. The implementation in this case uses a timer as well. If the timeout event occurs a given number of times after the start of the gesture then the gesture is considered to have finished whether or not the appropriate touch or mouse event has occurred. Also if a large jump in the position of the event occurs, as calculated by the <a href="qpoint.html#manhattanLength">manhattanLength()</a> call, then the gesture is canceled by calling reset() which tidies up and uses updateState() to change state to NoGesture which will result in the canceled() signal being emitted by the recognizer.</p>

<p>ImageWidget handles the signals by connecting the slots to the signals, although <tt>canceled()</tt> is not connected here.</p>

<pre> panGesture = new QPanGesture(this);

connect(panGesture, SIGNAL(triggered()), this, SLOT(gestureTriggered()));

tapAndHoldGesture = new TapAndHoldGesture(this);

connect(tapAndHoldGesture, SIGNAL(triggered()), this, SLOT(gestureTriggered()));

connect(tapAndHoldGesture, SIGNAL(finished()), this, SLOT(gestureFinished()));</pre>

<p>These functions in turn will have to be aware of which gesture object was the source of the signal since we have more than one source per slot. This is easily done by using the <a href="qobject.html#sender">QObject::sender</a>() function as shown here</p>

<pre> void ImageWidget::gestureTriggered()

{

if (sender() == panGesture) {</pre>

<p>As triggered() signals are handled by gestureTriggered() there may be position updates invoking calls to, for example, goNextImage(), this will cause a change in the image handling logic of ImageWidget and a call to updateImage() to display the changed state.</p>

<p>Following the logic of how the <a href="qevent.html">QEvent</a> is processed we can summmarize it as follows:</p>

<ul>

<li>filterEvent() becomes the event filter of the parent ImageWidget object for a QPanGesture object and a TapAndHoldGesture object.</li>

<li>filterEvent() then calls updateState() to change states</li>

<li>updateState() emits the appropriate signal(s) for the state change.</li>

100

<li>The signals are caught by the defined slots in ImageWidget</li>

101

<li>The widget logic changes and an update() results in a paint event.</li>

102

</ul>

103

<p>

104

</p>

105

106

107

108

<td width="20%" align="center"><a href="trademarks.html">Trademarks</a></td>

109

110

111

</html>

Older »