From 8092c5617092195d7df02775f423f5e420eb764f Mon Sep 17 00:00:00 2001 From: Shawn Rutledge Date: Tue, 19 Jun 2018 18:05:14 +0200 Subject: Rename Pointer Handlers to Input Handlers (as a concept) This is a documentation change to alleviate some confusion that we've seen during the Tech Preview period. It doesn't make sense to actually rename the base class though, because it is intended to handle QQuickPointerEvents, not QEvents. The reason for that is that refactoring the QEvent hierarchy has to wait until Qt 6. So maybe in Qt 6 we can remove QQuickPointerEvent and have a QQuickInputHandler base class which handles QInputEvents; but for now, this conceptual renaming seems about as far as we can go. Task-number: QTBUG-66651 Change-Id: I84a41dc282c480d08f4d4a0d9a857e37e074aa7a Reviewed-by: Frederik Gladhorn --- src/quick/handlers/qquickdraghandler.cpp | 2 +- src/quick/handlers/qquickmultipointhandler.cpp | 4 ++-- src/quick/handlers/qquickpinchhandler.cpp | 2 +- src/quick/handlers/qquickpointerhandler.cpp | 16 ++++++++-------- src/quick/handlers/qquickpointhandler.cpp | 2 +- src/quick/handlers/qquicktaphandler.cpp | 4 ++-- 6 files changed, 15 insertions(+), 15 deletions(-) (limited to 'src/quick/handlers') diff --git a/src/quick/handlers/qquickdraghandler.cpp b/src/quick/handlers/qquickdraghandler.cpp index b588faa507..8bb8612fb3 100644 --- a/src/quick/handlers/qquickdraghandler.cpp +++ b/src/quick/handlers/qquickdraghandler.cpp @@ -52,7 +52,7 @@ QT_BEGIN_NAMESPACE \brief Handler for dragging. DragHandler is a handler that is used to interactively move an Item. - Like other Pointer Handlers, by default it is fully functional, and + Like other Input Handlers, by default it is fully functional, and manipulates its \l {PointerHandler::target} {target}. \snippet pointerHandlers/dragHandler.qml 0 diff --git a/src/quick/handlers/qquickmultipointhandler.cpp b/src/quick/handlers/qquickmultipointhandler.cpp index 2236a7d18e..9a3732ff84 100644 --- a/src/quick/handlers/qquickmultipointhandler.cpp +++ b/src/quick/handlers/qquickmultipointhandler.cpp @@ -133,7 +133,7 @@ QVector QQuickMultiPointHandler::eligiblePoints(QQuickPointe If a smaller number of touchpoints are in contact with the \l {PointerHandler::parent}{parent}, they will be ignored. - Any ignored points are eligible to activate other Pointer Handlers that + Any ignored points are eligible to activate other Input Handlers that have different constraints, on the same Item or on other Items. The default value is 2. @@ -159,7 +159,7 @@ void QQuickMultiPointHandler::setMinimumPointCount(int c) chosen in the order that they are pressed, and the remaining points will be ignored. - Any ignored points are eligible to activate other Pointer Handlers that + Any ignored points are eligible to activate other Input Handlers that have different constraints, on the same Item or on other Items. The default value is the same as \l minimumPointCount. diff --git a/src/quick/handlers/qquickpinchhandler.cpp b/src/quick/handlers/qquickpinchhandler.cpp index 38e3d00e9e..c251ae6d36 100644 --- a/src/quick/handlers/qquickpinchhandler.cpp +++ b/src/quick/handlers/qquickpinchhandler.cpp @@ -61,7 +61,7 @@ Q_LOGGING_CATEGORY(lcPinchHandler, "qt.quick.handler.pinch") \brief Handler for pinch gestures. PinchHandler is a handler that interprets a multi-finger gesture to - interactively rotate, zoom, and drag an Item. Like other Pointer Handlers, + interactively rotate, zoom, and drag an Item. Like other Input Handlers, by default it is fully functional, and manipulates its \l target, which is the Item within which it is declared. diff --git a/src/quick/handlers/qquickpointerhandler.cpp b/src/quick/handlers/qquickpointerhandler.cpp index b2fead32fd..8e10003c6a 100644 --- a/src/quick/handlers/qquickpointerhandler.cpp +++ b/src/quick/handlers/qquickpointerhandler.cpp @@ -57,8 +57,8 @@ Q_LOGGING_CATEGORY(lcPointerHandlerActive, "qt.quick.handler.active") \ingroup qtquick-handlers \brief Abstract handler for pointer events. - PointerHandler is the base class handler (not registered as a QML type) for - pointer events without regard to source (touch, mouse or graphics tablet). + PointerHandler is the base class Input Handler (not registered as a QML type) for + events from any kind of pointing device (touch, mouse or graphics tablet). */ QQuickPointerHandler::QQuickPointerHandler(QObject *parent) @@ -115,12 +115,12 @@ void QQuickPointerHandler::setMargin(qreal pointDistanceThreshold) /*! Notification that the grab has changed in some way which is relevant to this handler. - The \a grabber (subject) will be the PointerHandler whose state is changing, + The \a grabber (subject) will be the Input Handler whose state is changing, or null if the state change regards an Item. The \a stateChange (verb) tells what happened. The \a point (object) is the point that was grabbed or ungrabbed. EventPoint has the sole responsibility to call this function. - The PointerHandler must react in whatever way is appropriate, and must + The Input Handler must react in whatever way is appropriate, and must emit the relevant signals (for the benefit of QML code). A subclass is allowed to override this virtual function, but must always call its parent class's implementation in addition to (usually after) @@ -164,10 +164,10 @@ void QQuickPointerHandler::onGrabChanged(QQuickPointerHandler *grabber, QQuickEv /*! Acquire or give up a passive grab of the given \a point, according to the \a grab state. - Unlike the exclusive grab, multiple PointerHandlers can have passive grabs + Unlike the exclusive grab, multiple Input Handlers can have passive grabs simultaneously. This means that each of them will receive further events - when the \a point moves, and when it is finally released. Typically a - PointerHandler should acquire a passive grab as soon as a point is pressed, + when the \a point moves, and when it is finally released. Typically an + Input Handler should acquire a passive grab as soon as a point is pressed, if the handler's constraints do not clearly rule out any interest in that point. For example, DragHandler needs a passive grab in order to watch the movement of a point to see whether it will be dragged past the drag @@ -464,7 +464,7 @@ bool QQuickPointerHandler::wantsEventPoint(QQuickEventPoint *point) \readonly \qmlproperty bool QtQuick::PointerHandler::active - This holds true whenever this PointerHandler has taken sole responsibility + This holds true whenever this Input Handler has taken sole responsibility for handing one or more EventPoints, by successfully taking an exclusive grab of those points. This means that it is keeping its properties up-to-date according to the movements of those Event Points and actively diff --git a/src/quick/handlers/qquickpointhandler.cpp b/src/quick/handlers/qquickpointhandler.cpp index 7e2d40452c..7cf37969cc 100644 --- a/src/quick/handlers/qquickpointhandler.cpp +++ b/src/quick/handlers/qquickpointhandler.cpp @@ -97,7 +97,7 @@ QT_BEGIN_NAMESPACE \snippet pointerHandlers/pointHandler.qml 0 - Like all pointer handlers, a PointHandler has a \l target property, which + 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 \c target item in any way. You need to use bindings to make it react to the \l point. diff --git a/src/quick/handlers/qquicktaphandler.cpp b/src/quick/handlers/qquicktaphandler.cpp index b12894e23f..255059b9bd 100644 --- a/src/quick/handlers/qquicktaphandler.cpp +++ b/src/quick/handlers/qquicktaphandler.cpp @@ -65,7 +65,7 @@ int QQuickTapHandler::m_touchMultiTapDistanceSquared(-1); value is DragThreshold, which requires the press and release to be close together in both space and time. In this case, DragHandler is able to function using only a passive grab, and therefore does not interfere with - event delivery to any other Items or Pointer Handlers. So the default + event delivery to any other Items or Input Handlers. So the default gesturePolicy is useful when you want to modify behavior of an existing control or Item by adding a TapHandler with bindings and/or JavaScript callbacks. @@ -237,7 +237,7 @@ void QQuickTapHandler::timerEvent(QTimerEvent *event) threshold (QStyleHints::startDragDistance), the tap gesture is canceled, even if the button or finger is still pressed. This policy can be useful whenever TapHandler needs to cooperate with other - pointer handlers (for example \l DragHandler) or event-handling Items + input handlers (for example \l DragHandler) or event-handling Items (for example QtQuick Controls), because in this case TapHandler will not take the exclusive grab, but merely a passive grab. -- cgit v1.2.3