Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
Loading...
Searching...
No Matches
Signals | Public Member Functions | Protected Member Functions | Properties | List of all members
QQuickPointHandler Class Reference

#include <qquickpointhandler_p.h>

+ Inheritance diagram for QQuickPointHandler:
+ Collaboration diagram for QQuickPointHandler:

Signals

void translationChanged ()
 
- Signals inherited from QQuickSinglePointHandler
void pointChanged ()
 
- Signals inherited from QQuickPointerDeviceHandler
void acceptedDevicesChanged ()
 
void acceptedPointerTypesChanged ()
 
void acceptedButtonsChanged ()
 
void acceptedModifiersChanged ()
 
- Signals inherited from QQuickPointerHandler
void enabledChanged ()
 
void activeChanged ()
 
void targetChanged ()
 
void marginChanged ()
 
 Q_REVISION (2, 15) void dragThresholdChanged()
 
void grabChanged (QPointingDevice::GrabTransition transition, QEventPoint point)
 
void grabPermissionChanged ()
 
void canceled (QEventPoint point)
 
 Q_REVISION (6, 3) void parentChanged()
 
- Signals inherited from QObject
void destroyed (QObject *=nullptr)
 This signal is emitted immediately before the object obj is destroyed, after any instances of QPointer have been notified, and cannot be blocked.
 
void objectNameChanged (const QString &objectName, QPrivateSignal)
 This signal is emitted after the object's name has been changed.
 

Public Member Functions

 QQuickPointHandler (QQuickItem *parent=nullptr)
 \qmltype PointHandler \instantiates QQuickPointHandler \inherits SinglePointHandler \inqmlmodule QtQuick
 
QVector2D translation () const
 
- Public Member Functions inherited from QQuickSinglePointHandler
 QQuickSinglePointHandler (QQuickItem *parent=nullptr)
 \qmltype SinglePointHandler \qmlabstract \preliminary \instantiates QQuickSinglePointHandler \inherits PointerDeviceHandler \inqmlmodule QtQuick
 
QQuickHandlerPoint point () const
 
- Public Member Functions inherited from QQuickPointerDeviceHandler
 QQuickPointerDeviceHandler (QQuickItem *parent=nullptr)
 \qmltype PointerDeviceHandler \qmlabstract
 
QInputDevice::DeviceTypes acceptedDevices () const
 
QPointingDevice::PointerTypes acceptedPointerTypes () const
 
Qt::MouseButtons acceptedButtons () const
 \qmlproperty flags QtQuick::PointerDeviceHandler::acceptedButtons
 
Qt::KeyboardModifiers acceptedModifiers () const
 
- Public Member Functions inherited from QQuickPointerHandler
 QQuickPointerHandler (QQuickItem *parent=nullptr)
 \qmltype PointerHandler \qmlabstract
 
 ~QQuickPointerHandler ()
 
bool enabled () const
 \qmlproperty bool QtQuick::PointerHandler::enabled
 
void setEnabled (bool enabled)
 
bool active () const
 \readonly \qmlproperty bool QtQuick::PointerHandler::active
 
QQuickItem * target () const
 \qmlproperty Item QtQuick::PointerHandler::target
 
void setTarget (QQuickItem *target)
 
QQuickItem * parentItem () const
 \qmlproperty Item QtQuick::PointerHandler::parent
 
void setParentItem (QQuickItem *p)
 
void handlePointerEvent (QPointerEvent *event)
 
GrabPermissions grabPermissions () const
 \qmlproperty flags QtQuick::PointerHandler::grabPermissions
 
void setGrabPermissions (GrabPermissions grabPermissions)
 
qreal margin () const
 \qmlproperty real PointerHandler::margin
 
void setMargin (qreal pointDistanceThreshold)
 
int dragThreshold () const
 \qmlproperty int PointerHandler::dragThreshold
 
void setDragThreshold (int t)
 
void resetDragThreshold ()
 
- Public Member Functions inherited from QObject
Q_INVOKABLE QObject (QObject *parent=nullptr)
 Constructs an object with parent object parent.
 
virtual ~QObject ()
 Destroys the object, deleting all its child objects.
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 Filters events if this object has been installed as an event filter for the watched object.
 
QString objectName () const
 
Q_WEAK_OVERLOAD void setObjectName (const QString &name)
 Sets the object's name to name.
 
void setObjectName (QAnyStringView name)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
QBindable< QString > bindableObjectName ()
 
bool isWidgetType () const
 Returns true if the object is a widget; otherwise returns false.
 
bool isWindowType () const
 Returns true if the object is a window; otherwise returns false.
 
bool isQuickItemType () const
 Returns true if the object is a QQuickItem; otherwise returns false.
 
bool signalsBlocked () const noexcept
 Returns true if signals are blocked; otherwise returns false.
 
bool blockSignals (bool b) noexcept
 If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it).
 
QThread * thread () const
 Returns the thread in which the object lives.
 
bool moveToThread (QThread *thread QT6_DECL_NEW_OVERLOAD_TAIL)
 Changes the thread affinity for this object and its children and returns true on success.
 
int startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
 This is an overloaded function that will start a timer of type timerType and a timeout of interval milliseconds.
 
int startTimer (std::chrono::nanoseconds time, Qt::TimerType timerType=Qt::CoarseTimer)
 
void killTimer (int id)
 Kills the timer with timer identifier, id.
 
void killTimer (Qt::TimerId id)
 
template<typename T >
T findChild (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 Returns the child of this object that can be cast into type T and that is called name, or \nullptr if there is no such object.
 
template<typename T >
QList< T > findChildren (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects.
 
template<typename T >
T findChild (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
template<typename T >
QList< T > findChildren (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
const QObjectList & children () const
 Returns a list of child objects.
 
void setParent (QObject *parent)
 Makes the object a child of parent.
 
void installEventFilter (QObject *filterObj)
 Installs an event filter filterObj on this object.
 
void removeEventFilter (QObject *obj)
 Removes an event filter object obj from this object.
 
QMetaObject::Connection connect (const QObject *sender, const char *signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const
 
bool disconnect (const char *signal=nullptr, const QObject *receiver=nullptr, const char *member=nullptr) const
 
bool disconnect (const QObject *receiver, const char *member=nullptr) const
 
void dumpObjectTree () const
 Dumps a tree of children to the debug output.
 
void dumpObjectInfo () const
 Dumps information about signal connections, etc.
 
bool setProperty (const char *name, const QVariant &value)
 Sets the value of the object's name property to value.
 
bool setProperty (const char *name, QVariant &&value)
 
QVariant property (const char *name) const
 Returns the value of the object's name property.
 
QList< QByteArray > dynamicPropertyNames () const
 
QBindingStorage * bindingStorage ()
 
const QBindingStorage * bindingStorage () const
 
QObject * parent () const
 Returns a pointer to the parent object.
 
bool inherits (const char *classname) const
 Returns true if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns false.
 
- Public Member Functions inherited from QQmlParserStatus
 QQmlParserStatus ()
 
virtual ~QQmlParserStatus ()
 

Protected Member Functions

bool wantsEventPoint (const QPointerEvent *event, const QEventPoint &point) override
 Returns true if the given point (as part of event) could be relevant at all to this handler, as a preliminary check.
 
void handleEventPoint (QPointerEvent *event, QEventPoint &point) override
 
- Protected Member Functions inherited from QQuickSinglePointHandler
 QQuickSinglePointHandler (QQuickSinglePointHandlerPrivate &dd, QQuickItem *parent)
 
bool wantsPointerEvent (QPointerEvent *event) override
 It is the responsibility of this function to decide whether the event could be relevant at all to this handler, as a preliminary check.
 
void handlePointerEventImpl (QPointerEvent *event) override
 This function can be overridden to implement whatever behavior a specific subclass is intended to have: \list.
 
QEventPoint & currentPoint (QPointerEvent *ev)
 
void onGrabChanged (QQuickPointerHandler *grabber, QPointingDevice::GrabTransition transition, QPointerEvent *event, QEventPoint &point) override
 Notification that the grab has changed in some way which is relevant to this handler.
 
void setIgnoreAdditionalPoints (bool v=true)
 
void moveTarget (QPointF pos, QEventPoint &point)
 
void setPointId (int id)
 
- Protected Member Functions inherited from QQuickPointerDeviceHandler
 QQuickPointerDeviceHandler (QQuickPointerDeviceHandlerPrivate &dd, QQuickItem *parent=nullptr)
 
- Protected Member Functions inherited from QQuickPointerHandler
 QQuickPointerHandler (QQuickPointerHandlerPrivate &dd, QQuickItem *parent)
 
void classBegin () override
 Overridden only because QQmlParserStatus requires it.
 
void componentComplete () override
 Overridden from QQmlParserStatus to ensure that parentItem() sets its cursor if this handler's \l cursorShape property has been set.
 
bool event (QEvent *) override
 
QPointerEvent * currentEvent ()
 
void setActive (bool active)
 
virtual void onTargetChanged (QQuickItem *oldTarget)
 
virtual void onActiveChanged ()
 
virtual bool canGrab (QPointerEvent *event, const QEventPoint &point)
 Check whether it's OK to take an exclusive grab of the point.
 
virtual bool approveGrabTransition (QPointerEvent *event, const QEventPoint &point, QObject *proposedGrabber)
 Check this handler's rules to see if \l proposedGrabber will be allowed to take the exclusive grab.
 
void setPassiveGrab (QPointerEvent *event, const QEventPoint &point, bool grab=true)
 Acquire or give up a passive grab of the given point, according to the grab state.
 
bool setExclusiveGrab (QPointerEvent *ev, const QEventPoint &point, bool grab=true)
 Acquire or give up the exclusive grab of the given point, according to the grab state, and subject to the rules: canGrab(), and the rule not to relinquish another handler's grab.
 
void cancelAllGrabs (QPointerEvent *event, QEventPoint &point)
 Cancel any existing grab of the given point.
 
QPointF eventPos (const QEventPoint &point) const
 
bool parentContains (const QEventPoint &point) const
 Returns true if margin() > 0 and point is within the margin beyond QQuickItem::boundingRect(), or else returns QQuickItem::contains() QEventPoint::position() effectively (because parentContains(scenePosition) calls QQuickItem::mapFromScene()).
 
bool parentContains (const QPointF &scenePosition) const
 Returns true if scenePosition is within the margin() beyond QQuickItem::boundingRect() (if margin > 0), or parentItem() contains scenePosition according to QQuickItem::contains().
 
- Protected Member Functions inherited from QObject
QObject * sender () const
 Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns \nullptr.
 
int senderSignalIndex () const
 
int receivers (const char *signal) const
 Returns the number of receivers connected to the signal.
 
bool isSignalConnected (const QMetaMethod &signal) const
 
virtual void timerEvent (QTimerEvent *event)
 This event handler can be reimplemented in a subclass to receive timer events for the object.
 
virtual void childEvent (QChildEvent *event)
 This event handler can be reimplemented in a subclass to receive child events.
 
virtual void customEvent (QEvent *event)
 This event handler can be reimplemented in a subclass to receive custom events.
 
virtual void connectNotify (const QMetaMethod &signal)
 
virtual void disconnectNotify (const QMetaMethod &signal)
 
 QObject (QObjectPrivate &dd, QObject *parent=nullptr)
 

Properties

QVector2D translation
 
- Properties inherited from QQuickSinglePointHandler
QQuickHandlerPoint point
 
- Properties inherited from QQuickPointerDeviceHandler
QInputDevice::DeviceTypes acceptedDevices
 
QPointingDevice::PointerTypes acceptedPointerTypes
 
Qt::MouseButtons acceptedButtons
 
Qt::KeyboardModifiers acceptedModifiers
 
- Properties inherited from QQuickPointerHandler
bool enabled
 
bool active
 
QQuickItem * target
 
QQuickItem * parent
 
GrabPermissions grabPermissions
 
qreal margin
 
int dragThreshold
 
- Properties inherited from QObject
QString objectName
 the name of this object
 

Additional Inherited Members

- Public Types inherited from QQuickPointerHandler
enum  GrabPermission {
  TakeOverForbidden = 0x0 , CanTakeOverFromHandlersOfSameType = 0x01 , CanTakeOverFromHandlersOfDifferentType = 0x02 , CanTakeOverFromItems = 0x04 ,
  CanTakeOverFromAnything = 0x0F , ApprovesTakeOverByHandlersOfSameType = 0x10 , ApprovesTakeOverByHandlersOfDifferentType = 0x20 , ApprovesTakeOverByItems = 0x40 ,
  ApprovesCancellation = 0x80 , ApprovesTakeOverByAnything = 0xF0
}
 
- Public Slots inherited from QQuickPointerDeviceHandler
void setAcceptedDevices (QInputDevice::DeviceTypes acceptedDevices)
 \qmlproperty flags PointerDeviceHandler::acceptedDevices
 
void setAcceptedPointerTypes (QPointingDevice::PointerTypes acceptedPointerTypes)
 \qmlproperty flags PointerDeviceHandler::acceptedPointerTypes
 
void setAcceptedButtons (Qt::MouseButtons buttons)
 
void setAcceptedModifiers (Qt::KeyboardModifiers acceptedModifiers)
 \qmlproperty flags PointerDeviceHandler::acceptedModifiers
 
- Public Slots inherited from QObject
void deleteLater ()
 \threadsafe
 
- Static Public Member Functions inherited from QObject
static QMetaObject::Connection connect (const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
 \threadsafe
 
static QMetaObject::Connection connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)
 
template<typename Func1 , typename Func2 >
static QMetaObject::Connection connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const typename QtPrivate::ContextTypeForFunctor< Func2 >::ContextType *context, Func2 &&slot, Qt::ConnectionType type=Qt::AutoConnection)
 
template<typename Func1 , typename Func2 >
static QMetaObject::Connection connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, Func2 &&slot)
 
static bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *member)
 \threadsafe
 
static bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &member)
 
static bool disconnect (const QMetaObject::Connection &)
 Disconnect a connection.
 
template<typename Func1 , typename Func2 >
static bool disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const typename QtPrivate::FunctionPointer< Func2 >::Object *receiver, Func2 slot)
 
template<typename Func1 >
static bool disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const QObject *receiver, void **zero)
 
- Protected Attributes inherited from QObject
QScopedPointer< QObjectData > d_ptr
 
- Related Symbols inherited from QObject
 Returns the given object cast to type T if the object is of type T (or of a subclass); otherwise returns \nullptr.
 
 
 
 \macro Q_CLASSINFO(Name, Value)
 

Detailed Description

Definition at line 22 of file qquickpointhandler_p.h.

Constructor & Destructor Documentation

◆ QQuickPointHandler()

QT_BEGIN_NAMESPACE QQuickPointHandler::QQuickPointHandler ( QQuickItem * parent = nullptr)
explicit

\qmltype PointHandler \instantiates QQuickPointHandler \inherits SinglePointHandler \inqmlmodule QtQuick

Handler for reacting to a single touchpoint.

PointHandler can be used to show feedback about a touchpoint or the mouse position, or to otherwise react to pointer events.

When a press event occurs, each instance of PointHandler chooses a single point which is not yet "taken" at that moment: if the press occurs within the bounds of the \l {PointerHandler::parent}, and no sibling PointHandler within the same \l {PointerHandler::parent} has yet acquired a passive grab on that point, and if the other constraints such as \l {PointerDeviceHandler::acceptedButtons}{acceptedButtons}, \l {PointerDeviceHandler::acceptedDevices}{acceptedDevices} etc. are satisfied, it's eligible, and the PointHandler then acquires a passive grab. In this way, the \l {PointerHandler::parent} acts like an exclusive group: there can be multiple instances of PointHandler, and the set of pressed touchpoints will be distributed among them. Each PointHandler which has chosen a point to track has its \l active property true. It then continues to track its chosen point until release: the properties of the \l point will be kept up-to-date. Any Item can bind to these properties, and thereby follow the point's movements.

By being only a passive grabber, it has the ability to keep independent oversight of all movements. The passive grab cannot be stolen or overridden even when other gestures are detected and exclusive grabs occur.

If your goal is orthogonal surveillance of eventpoints, an older alternative was QObject::installEventFilter(), but that has never been a built-in QtQuick feature: it requires some C++ code, such as a QQuickItem subclass. PointHandler is more efficient than that, because only pointer events will be delivered to it, during the course of normal event delivery in QQuickWindow; whereas an event filter needs to filter all QEvents of all types, and thus sets itself up as a potential event delivery bottleneck.

One possible use case is to add this handler to a transparent Item which is on top of the rest of the scene (by having a high \l{Item::z} {z} value), so that when a point is freshly pressed, it will be delivered to that Item and its handlers first, providing the opportunity to take the passive grab as early as possible. Such an item (like a pane of glass over the whole UI) can be a convenient parent for other Items which visualize the kind of reactive feedback which must always be on top; and likewise it can be the parent for popups, popovers, dialogs and so on. If it will be used in that way, it can be helpful for your main.cpp to use QQmlContext::setContextProperty() to make the "glass pane" accessible by ID to the entire UI, so that other Items and PointHandlers can be reparented to it.

import QtQuick
Window {
width: 480
height: 320
visible: true
Item {
id: glassPane
z: 10000
anchors.fill: parent
//![1]
PointHandler {
id: handler
acceptedDevices: PointerDevice.TouchScreen | PointerDevice.TouchPad
target: Rectangle {
parent: glassPane
color: "red"
visible: handler.active
x: handler.point.position.x - width / 2
y: handler.point.position.y - height / 2
width: 20; height: width; radius: width / 2
}
}
//![1]
}
}

Like all input handlers, a PointHandler has a \l target property, which may be used as a convenient place to put a point-tracking Item; but PointHandler will not automatically manipulate the target item in any way. You need to use bindings to make it react to the \l point.

Note
On macOS, PointHandler does not react to multiple fingers on the trackpad by default, although it does react to a pressed point (mouse position). That is because macOS can provide either native gesture recognition, or raw touchpoints, but not both. We prefer to use the native gesture event in PinchHandler, so we do not want to disable it by enabling touch. However MultiPointTouchArea does enable touch, thus disabling native gesture recognition within the entire window; so it's an alternative if you only want to react to all the touchpoints but do not require the smooth native-gesture experience.
See also
MultiPointTouchArea, HoverHandler, {Qt Quick Examples - Pointer Handlers}

Definition at line 84 of file qquickpointhandler.cpp.

References QQuickSinglePointHandler::setIgnoreAdditionalPoints().

+ Here is the call graph for this function:

Member Function Documentation

◆ handleEventPoint()

void QQuickPointHandler::handleEventPoint ( QPointerEvent * event,
QEventPoint & point )
overrideprotectedvirtual

Reimplemented from QQuickSinglePointHandler.

Definition at line 106 of file qquickpointhandler.cpp.

References QQuickPointerDeviceHandler::acceptedButtons, emit, QQuickSinglePointHandler::handleEventPoint(), QQuickDeliveryAgentPrivate::isTouchEvent(), Qt::NoButton, QQuickSinglePointHandler::point, QEventPoint::Pressed, QEventPoint::Released, QQuickPointerHandler::setActive(), QQuickPointerHandler::setPassiveGrab(), and translationChanged().

+ Here is the call graph for this function:

◆ translation()

QVector2D QQuickPointHandler::translation ( ) const

Definition at line 129 of file qquickpointhandler.cpp.

References QQuickSinglePointHandler::point, and position().

+ Here is the call graph for this function:

◆ translationChanged

void QQuickPointHandler::translationChanged ( )
signal

Referenced by handleEventPoint().

+ Here is the caller graph for this function:

◆ wantsEventPoint()

bool QQuickPointHandler::wantsEventPoint ( const QPointerEvent * event,
const QEventPoint & point )
overrideprotectedvirtual

Returns true if the given point (as part of event) could be relevant at all to this handler, as a preliminary check.

If you override this function, you should call the immediate parent class implementation (and return false if it returns false); that in turn calls its parent class implementation, and so on.

In particular, the bounds checking is done here: the base class QQuickPointerHandler::wantsEventPoint() calls parentContains(point) (which allows the flexibility promised by margin(), QQuickItem::contains() and QQuickItem::containmentMask()). Pointer Handlers can receive QEventPoints that are outside the parent item's bounds: this allows some flexibility for dealing with multi-point gestures in which one or more fingers have strayed outside the bounds, and yet the gesture is still unambiguously intended for the target() item.

You should not generally react to the event or point here, but it's ok to set state to remember what needs to be done in your overridden handlePointerEventImpl() or QQuickSinglePointHandler::handleEventPoint().

Reimplemented from QQuickPointerHandler.

Definition at line 90 of file qquickpointhandler.cpp.

References QQuickHandlerPoint::id, metaObject(), QQuickPointerHandler::parent, QQuickSinglePointHandler::point, QEventPoint::Pressed, and QQuickPointerHandler::wantsEventPoint().

+ Here is the call graph for this function:

Property Documentation

◆ translation

QVector2D QQuickPointHandler::translation
read

Definition at line 25 of file qquickpointhandler_p.h.

The documentation for this class was generated from the following files: