diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/examples/imagegestures.qdoc | 116 | ||||
| -rw-r--r-- | doc/src/frameworks-technologies/gestures.qdoc | 18 |
2 files changed, 125 insertions, 9 deletions
diff --git a/doc/src/examples/imagegestures.qdoc b/doc/src/examples/imagegestures.qdoc new file mode 100644 index 0000000..33c1ace --- /dev/null +++ b/doc/src/examples/imagegestures.qdoc @@ -0,0 +1,116 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example gestures/imagegestures + \title Image Gestures Example + + This example shows how to enable gestures for a widget and use gesture input + to perform actions. + + \image imagegestures-example.png Screenshot of the Image Gestures example. + + We use two classes to create the user interface for the application: \c MainWidget + and \c ImageWidget. The \c MainWidget class is simply used as a container for the + \c ImageWidget class, which we will configure to accept gesture input. Since we + are interested in the way gestures are used, we will concentrate on the + implementation of the \c ImageWidget class. + + \section1 ImageWidget Class Definition + + The \c ImageWidget class is a simple QWidget subclass that reimplements the general + QWidget::event() handler function in addition to several more specific event handlers: + + \snippet examples/gestures/imagegestures/imagewidget.h class definition begin + \dots + \snippet examples/gestures/imagegestures/imagewidget.h class definition end + + We also implement a private helper function, \c gestureEvent(), to help manage + gesture events delivered to the widget, and three functions to perform actions + based on gestures: \c panTriggered(), \c pinchTriggered() and \c swipeTriggered(). + + \section1 ImageWidget Class Implementation + + In the widget's constructor, we begin by setting up various parameters that will + be used to control the way images are displayed. + + \snippet examples/gestures/imagegestures/imagewidget.cpp constructor + + We enable three of the standard gestures for the widget by calling QWidget::grabGesture() + with the types of gesture we need. These will be recognized by the application's + default gesture recognizer, and events will be delivered to our widget. + + Since QWidget does not define a specific event handler for gestures, the widget + needs to reimplement the general QWidget::event() to receive gesture events. + + \snippet examples/gestures/imagegestures/imagewidget.cpp event handler + + We implement the event handler to delegate gesture events to a private function + specifically written for the task, and pass all other events to QWidget's + implementation. + + The \c gestureHandler() function examines the gestures supplied by the + newly-delivered QGestureEvent. Since only one gesture of a given type can be + used on a widget at any particular time, we can check for each gesture type + using the QGestureEvent::gesture() function: + + \snippet examples/gestures/imagegestures/imagewidget.cpp gesture event handler + + If a QGesture object is supplied for a certain type of gesture, we call a special + purpose function to deal with it, casting the gesture object to the appropriate + QGesture subclass. + + To illustrate how a standard gesture can be interpreted by an application, we + show the implementation of the \c swipeTriggered() function, which handles the + gesture associated with a brushing or swiping motion on the user's display or + input device: + + \snippet examples/gestures/imagegestures/imagewidget.cpp swipe function + + The QSwipeGesture class provides specialized functions and defines a enum + to make it more convenient for developers to discover which direction, if + any, the user swiped the display. Here, we simply navigate to the previous + image in the collection if the user swiped upwards or to the left; otherwise + we navigate to the next image in the collection. + + The other gestures are also handled by special purpose functions, but use + the values of properties held by the QGesture object passed to them. +*/ diff --git a/doc/src/frameworks-technologies/gestures.qdoc b/doc/src/frameworks-technologies/gestures.qdoc index a619fe8..2fa8dab 100644 --- a/doc/src/frameworks-technologies/gestures.qdoc +++ b/doc/src/frameworks-technologies/gestures.qdoc @@ -122,7 +122,7 @@ \section2 Filtering Input Events - The \l{QGestureRecognizer::}{filterEvent()} function must be reimplemented. + The \l{QGestureRecognizer::}{recognize()} 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. @@ -132,15 +132,15 @@ persistent information about the state of the recognition process in the QGesture object supplied. - Your \l{QGestureRecognizer::}{filterEvent()} function must return a value of - Qt::GestureState that indicates the state of recognition for a given gesture and + Your \l{QGestureRecognizer::}{recognize()} function must return a value of + QGestureRecognizer::Result 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. \section2 Custom Gestures If you choose to represent a gesture by a custom QGesture subclass, you will need to - reimplement the \l{QGestureRecognizer::}{createGesture()} function to construct + reimplement the \l{QGestureRecognizer::}{create()} function to construct instances of your gesture class instead of standard QGesture instances. Alternatively, you may want to use standard QGesture instances, but add additional dynamic properties to them to express specific details of the gesture you want to handle. @@ -152,7 +152,7 @@ \l{QGestureRecognizer::}{reset()} function to perform these special tasks. Note that QGesture objects are only created once for each combination of target object - and gesture type, and they are reused every time the user attempts to perform the + 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 \l{QGestureRecognizer::}{reset()} function to clean up after each previous attempt at recognizing a gesture. @@ -162,12 +162,12 @@ To use a gesture recognizer, construct an instance of your QGestureRecognizer subclass, and register it with the application with - QApplication::registerGestureRecognizer(). A recognizer for a given type of - gesture can be removed with QApplication::unregisterGestureRecognizer(). + QGestureRecognizer::registerRecognizer(). A recognizer for a given type of + gesture can be removed with QGestureRecognizer::unregisterRecognizer(). \section1 Further Reading - The \l{Image Gestures Example} shows how to enable gestures for a widget in - a simple image viewer application. + The \l{gestures/imagegestures}{Image Gestures Example} shows how to enable + gestures for a widget in a simple image viewer application. */ |