QGestureRecognizer¶
Note
This class was introduced in Qt 4.6
Synopsis¶
Static functions¶
- def registerRecognizer (recognizer)
- def unregisterRecognizer (type)
Detailed Description¶
The PySide.QtGui.QGestureRecognizer class provides the infrastructure for gesture recognition.
Gesture recognizers are responsible for creating and managing PySide.QtGui.QGesture objects and monitoring input events sent to PySide.QtGui.QWidget and PySide.QtGui.QGraphicsObject subclasses. PySide.QtGui.QGestureRecognizer is the base class for implementing custom gestures.
Developers that only need to provide gesture recognition for standard gestures do not need to use this class directly. Instances will be created behind the scenes by the framework.
For an overview of gesture handling in Qt and information on using gestures in your applications, see the Gestures Programming document.
Recognizing Gestures¶
The process of recognizing gestures involves filtering input events sent to specific objects, and modifying the associated PySide.QtGui.QGesture objects to include relevant information about the user’s input.
Gestures are created when the framework calls PySide.QtGui.QGestureRecognizer.create() to handle user input for a particular instance of a PySide.QtGui.QWidget or PySide.QtGui.QGraphicsObject subclass. A PySide.QtGui.QGesture object is created for each widget or item that is configured to use gestures.
Once a PySide.QtGui.QGesture has been created for a target object, the gesture recognizer will receive events for it in its PySide.QtGui.QGestureRecognizer.recognize() handler function.
When a gesture is canceled, the PySide.QtGui.QGestureRecognizer.reset() function is called, giving the recognizer the chance to update the appropriate properties in the corresponding PySide.QtGui.QGesture object.
Supporting New Gestures¶
To add support for new gestures, you need to derive from PySide.QtGui.QGestureRecognizer to create a custom recognizer class, construct an instance of this class, and register it with the application by calling QGestureRecognizer.registerRecognizer() . You can also subclass PySide.QtGui.QGesture to create a custom gesture class, or rely on dynamic properties to express specific details of the gesture you want to handle.
Your custom PySide.QtGui.QGestureRecognizer subclass needs to reimplement the PySide.QtGui.QGestureRecognizer.recognize() function to handle and filter the incoming input events for PySide.QtGui.QWidget and PySide.QtGui.QGraphicsObject subclasses. Although the logic for gesture recognition is implemented in this function, you can store persistent information about the state of the recognition process in the PySide.QtGui.QGesture object supplied. The PySide.QtGui.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.
If you choose to represent a gesture by a custom PySide.QtGui.QGesture subclass, you will need to reimplement the PySide.QtGui.QGestureRecognizer.create() function to construct instances of your gesture class. Similarly, you may need to reimplement the PySide.QtGui.QGestureRecognizer.reset() function if your custom gesture objects need to be specially handled when a gesture is canceled.
See also
- class PySide.QtGui.QGestureRecognizer¶
Constructs a new gesture recognizer object.
- PySide.QtGui.QGestureRecognizer.ResultFlag¶
This enum describes the result of the current event filtering step in a gesture recognizer state machine.
The result consists of a state value (one of Ignore, MayBeGesture , TriggerGesture , FinishGesture , CancelGesture ) and an optional hint ( ConsumeEventHint ).
Constant Description QGestureRecognizer.Ignore The event does not change the state of the recognizer. QGestureRecognizer.MayBeGesture The event changed the internal state of the recognizer, but it isn’t clear yet if it is a gesture or not. The recognizer needs to filter more events to decide. Gesture recognizers in the MayBeGesture state may be reset automatically if they take too long to recognize gestures. QGestureRecognizer.TriggerGesture The gesture has been triggered and the appropriate PySide.QtGui.QGesture object will be delivered to the target as a part of a PySide.QtGui.QGestureEvent . QGestureRecognizer.FinishGesture The gesture has been finished successfully and the appropriate PySide.QtGui.QGesture object will be delivered to the target as a part of a PySide.QtGui.QGestureEvent . QGestureRecognizer.CancelGesture The event made it clear that it is not a gesture. If the gesture recognizer was in GestureTriggered state before, then the gesture is canceled and the appropriate PySide.QtGui.QGesture object will be delivered to the target as a part of a PySide.QtGui.QGestureEvent . QGestureRecognizer.ConsumeEventHint This hint specifies that the gesture framework should consume the filtered event and not deliver it to the receiver. See also
- PySide.QtGui.QGestureRecognizer.create(target)¶
Parameters: target – PySide.QtCore.QObject Return type: PySide.QtGui.QGesture This function is called by Qt to create a new PySide.QtGui.QGesture object for the given target ( PySide.QtGui.QWidget or PySide.QtGui.QGraphicsObject ).
Reimplement this function to create a custom PySide.QtGui.QGesture -derived gesture object if necessary.
The application takes ownership of the created gesture object.
- PySide.QtGui.QGestureRecognizer.recognize(state, watched, event)¶
Parameters: - state – PySide.QtGui.QGesture
- watched – PySide.QtCore.QObject
- event – PySide.QtCore.QEvent
Return type: PySide.QtGui.QGestureRecognizer.Result
Handles the given event for the watched object, updating the state of the gesture object as required, and returns a suitable result for the current recognition step.
This function is called by the framework to allow the recognizer to filter input events dispatched to PySide.QtGui.QWidget or PySide.QtGui.QGraphicsObject instances that it is monitoring.
The result reflects how much of the gesture has been recognized. The state of the gesture object is set depending on the result.
See also
QGestureRecognizer.Result
- static PySide.QtGui.QGestureRecognizer.registerRecognizer(recognizer)¶
Parameters: recognizer – PySide.QtGui.QGestureRecognizer Return type: PySide.QtCore.Qt.GestureType Registers the given recognizer in the gesture framework and returns a gesture ID for it.
The application takes ownership of the recognizer and returns the gesture type ID associated with it. For gesture recognizers which handle custom PySide.QtGui.QGesture objects (i.e., those which return Qt.CustomGesture in a QGesture.gestureType() function) the return value is a generated gesture ID with the Qt.CustomGesture flag set.
- PySide.QtGui.QGestureRecognizer.reset(state)¶
Parameters: state – PySide.QtGui.QGesture This function is called by the framework to reset a given gesture .
Reimplement this function to implement additional requirements for custom PySide.QtGui.QGesture objects. This may be necessary if you implement a custom PySide.QtGui.QGesture whose properties need special handling when the gesture is reset.
- static PySide.QtGui.QGestureRecognizer.unregisterRecognizer(type)¶
Parameters: type – PySide.QtCore.Qt.GestureType
