summaryrefslogtreecommitdiff
path: root/src/quick/doc/snippets/pointerHandlers
Commit message (Collapse)AuthorAgeFilesLines
* Use correct names for QEventPoint::State, PointerDevice::GrabTransitionShawn Rutledge2023-04-141-0/+46
| | | | | | | | | | | | | | | | | | | | | | | | | Qt::TouchPointState is not the actual type here, and we should not encourage e.g. making a comparison between eventPoint.state and Qt.TouchPointMoved in an onGrabChanged handler. The equivalence is an internal detail; and eventPoint can come from any pointing device, not only from a touchscreen. QEventPoint is a Q_GADGET; we keep the registration to expose it as a value type (eventPoint). But such types cannot be created in QML, and we also need to give it an uppercase name to scope the enum values that it declares: that's a new foreign namespace called EventPoint. So it's possible to compare an eventPoint instance's state property against EventPoint.Pressed, and so on. Also show complete QML syntax in the \value tables where PointerDevice::GrabTransition is emitted to QML, namely PointerDevice::grabChanged and PointerHandler::grabChanged. Amends b43a873264d012dc0a0e574ea53335a40af8aa38 Task-number: QTBUG-102160 Change-Id: If1a97f21d8e005e3692298b8512f7f8b56a92c97 Reviewed-by: Ulf Hermann <ulf.hermann@qt.io>
* doc: Customize and update docs for PointHandlerShawn Rutledge2023-03-145-2/+150
| | | | | | | | | | | | | | | | Many of the inherited docs were inappropriate or insufficiently specific to PointHandler. Now we have more snippets with more ideas for how it can be used. As a drive-by, fix a typo in the docs for PointerDeviceHandler::acceptedPointerTypes and add a link to the new PointerDevice page added in e283c05af745210d4a1f6c0aa9c33bf4da23a1e0 Pick-to: 6.2 6.4 6.5 6.5.0 Fixes: QTBUG-74020 Fixes: QTBUG-106878 Change-Id: I028e1577ac5d4ef0b927c94259d6ab25b6028885 Reviewed-by: Doris Verria <doris.verria@qt.io>
* doc: Add snippets and animations illustrating TapHandler.GesturePolicyShawn Rutledge2023-03-024-0/+225
| | | | | | | | | | | | | | | | | | | | | | People are constantly confused by GesturePolicy and its default value, so we really need a "glanceable" reference in the docs to show the differences between use cases. Also clarify the pitfalls with the default DragThreshold value. We switch from the \value tag to a 2-column \table because the \image would otherwise break the table, and also because it saves space and acts as a meaningful reminder to have the animation right under the enum value that is being documented. Pick-to: 6.5 6.4 6.2 Task-number: QTBUG-70397 Task-number: QTBUG-73262 Task-number: QTBUG-100534 Task-number: QTBUG-107239 Task-number: QTBUG-111310 Change-Id: I1ff45f58a8a8edf55f4a8696d881aa9e0bedcfe3 Reviewed-by: Oliver Eftevaag <oliver.eftevaag@qt.io>
* Standardize Drag/PinchHandler active/persistent scale, rotation, translationShawn Rutledge2022-12-103-9/+35
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | PinchHandler.scale is persistent between gestures, whereas rotation and translation were active-gesture properties; that wasn't consistent. We fixed up DragHandler in just this way in 6.2. The translationChanged() signal now comes with a vector delta, which is often useful when writing an onTranslationChanged JS handler. Likewise, scaleChanged() and rotationChanged() come with qreal deltas. The scaleChanged() delta is multiplicative rather than additive, because an additive delta would not be useful in cases when some target item's scale can be adjusted by alternative means: you need to multiply it in your onScaleChanged function. Now that PinchHandler has 4 axes as grouped properties, some properties in the handlers themselves begin to look redundant; but at least the translation properties are useful to group x and y together. So in this patch we continue to follow the pattern that was set in 60d11e1f69470d588666b76092cd40ae5644a855. PinchHandler.scale is equivalent to persistentScale, whereas rotation is equivalent to activeRotation; so we have a reason to deprecate those properties, as in ea63ee523377bd11b957a9e74185792edd9b32e8. The persistent values have setters, to provide another way for applications to compensate when the values are adjusted by other means, as an alternative to incremental changes via a script such as rotationAxis.onValueDelta, onRotationChanged etc. [ChangeLog][QtQuick][Event Handlers] PinchHandler.activeTranslation now holds the amount of movement since the pinch gesture began. PinchHandler.persistentTranslation holds the accumulated sum of movement that has occurred during subsequent pinch gestures, and can be set to arbitrary values between gestures. Likewise, activeScale, persistentScale, activeRotation and persistentRotation follow the same pattern. The scaleChanged, rotationChanged, and translationChanged signals include delta arguments, which are useful for incrementally adjusting a non-default item property when the target is null. Fixes: QTBUG-76739 Task-number: QTBUG-94168 Change-Id: I6aaa1aa3356b85e6d27abc64bfa67781ecb4f062 Reviewed-by: Richard Moe Gustavsen <richard.gustavsen@qt.io>
* Add PinchHandler.scaleAxis, rotationAxis; hold values in axesShawn Rutledge2022-12-102-0/+61
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Pointer Handlers that manipulate target item properties should now use QQuickDragAxis consistently to: - enforce minimum and maximum values - hold the persistent and active values - make those available via properties - emit a new activeValueChanged(delta) signal when the value changes, so that it's possible to incrementally update a target item property in JS (onValueDelta: target.property += delta) In the pinchHandler.qml example, you can use the PinchHandler to adjust 4 properties of one Rectangle independently (it requires coordination). m_boundedActiveValue controls whether m_activeValue will be kept between minimum and maximum. For rotation, tst_QQuickPinchHandler::scaleNativeGesture() expects it to be, although that seems questionable now, and may be addressed later. [ChangeLog][QtQuick][Event Handlers] PinchHandler now has scaleAxis and rotationAxis grouped properties, alongside the existing xAxis and yAxis; and all of these now have activeValue and persistentValue properties. The activeValueChanged signal includes a delta value, giving the incremental change since the previous activeValue. The persistentValue is settable, in case some target item property can be adjusted in multiple ways: the handler's stored value can then be synced up with the item property value after each external change. These features are also added to DragHandler's xAxis and yAxis properties. Task-number: QTBUG-68108 Task-number: QTBUG-76380 Task-number: QTBUG-76379 Task-number: QTBUG-94168 Change-Id: I78a5b43e9ba580448ef05054b6c4bc71b1834dd6 Reviewed-by: Richard Moe Gustavsen <richard.gustavsen@qt.io>
* Use SPDX license identifiersLucie Gérard2022-06-1115-735/+30
| | | | | | | | | | | | Replace the current license disclaimer in files by a SPDX-License-Identifier. Files that have to be modified by hand are modified. License files are organized under LICENSES directory. Pick-to: 6.4 Task-number: QTBUG-67283 Change-Id: I63563bbeb6f60f89d2c99660400dca7fab78a294 Reviewed-by: Shawn Rutledge <shawn.rutledge@qt.io>
* doc: Fix inherited property docs in HoverHandlerShawn Rutledge2022-04-284-0/+214
| | | | | | | | | | | | Some base class snippets use TapHandler, but it's better to show snippets specifically with HoverHandler. These snippets are also runnable and thus testable. Fixes: QTBUG-95395 Task-number: QTBUG-101932 Pick-to: 6.3 6.2 5.15 Change-Id: Ibcdc30ff8a785a3651177c79522332cf09c3013c Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* Add button argument to the TapHandler.[single|double|]tapped signalsShawn Rutledge2021-09-081-4/+4
| | | | | | | | | | | | | | | | | | | | | | | | It would be better to emit the whole pointer event (by pointer because it's non-copyable, or make it copyable and emit by value), but we can't. So we just add the button being tapped; more information is available from the eventpoint argument and TapHandler's point property. To avoid name clashes with anything that's already called "button" in anyone's QML (which is quite likely, actually), the new signal argument is unnamed, so that users will be required to write a function signature that gives it a name rather than relying on context injection. [ChangeLog][QtQuick][Event Handlers] TapHandler's tapped(), singleTapped() and doubleTapped() signals now have two arguments: the QEventPoint instance, and the button being tapped. If you need it, you should write an explicit function for the signal handler: onTapped: function(point, button) { ... } or onDoubleTapped: (point, button)=> ... Fixes: QTBUG-91350 Task-number: QTBUG-64847 Pick-to: 6.2 6.2.0 Change-Id: I6d25300cbfceb56f27452eac4b29b66bd1b2a41a Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
* doc: Add a TapHandler button snippetShawn Rutledge2021-08-051-0/+80
| | | | | | | | | It was ironic that it's the most obvious use case of TapHandler but we didn't have some easy copy-and-paste code for making your own button. Pick-to: 6.1 6.2 Change-Id: I680b6f828f0df82e2ab8b434a2e76aabb21fc2b9 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* doc: Improve the Input Handlers index pageShawn Rutledge2021-08-051-0/+73
| | | | | | | | | | | | | - Document the exclusive/passive grab concepts better - Mention gesturePolicy's impact on grab behavior in the TapHandler docs too - More links - Add a couple of snippets illustrating simple use cases with handlers - Don't bother mentioning Qt.labs.handlers anymore Task-number: QTBUG-68110 Pick-to: 5.15 6.1 6.2 Change-Id: I5e6f538c2bc8cafef679f535a5248b218b4a8068 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* Use functions as signal handlers when accessing parametersUlf Hermann2021-02-122-5/+6
| | | | | | | | | Injected signal handlers are bad practice because they aren't declared. Pick-to: 6.1 Task-number: QTBUG-89943 Change-Id: I3a691f68342a199bd63034637aa7ed438e3a037b Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
* Merge remote-tracking branch 'origin/5.13' into devQt Forward Merge Bot2019-05-161-0/+64
|\ | | | | | | Change-Id: I192cb06f3b92869699cb3e072f2c6c1e8dbb1ef4
| * Merge remote-tracking branch 'origin/5.12' into 5.13Qt Forward Merge Bot2019-05-161-0/+64
| |\ | | | | | | | | | Change-Id: Ia93dc734ce25b3134b0f905f473a0c30777ceaf1
| | * Document TapHandler.tapped and [single|double]Tapped eventPoint argumentShawn Rutledge2019-05-091-0/+64
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Amends b8fd580cb3453b3850c36765c4b2537538d2f4f8 to add documentation. The eventPoint is important to get ephemeral state from the pointing device: which button was released (thus triggering the tap), which device it was, and where the release occurred. Users may expect to use the point property, but QQuickHandlerPoint::reset(QQuickEventPoint *) resets every property of the point at the same time, so the architecture currently does not allow for mixed state, i.e. having correct button state but still holding leftover position information. It may be surprising for users, but the changes to the point property are an atomic transaction that occurs before the signal. Task-number: QTBUG-61749 Task-number: QTBUG-64847 Change-Id: I33e0e232084beba8e10d8b02fa3bf85f36293358 Reviewed-by: Jan Arve Sæther <jan-arve.saether@qt.io>
* | | Add WheelHandlerShawn Rutledge2019-04-272-0/+151
|/ / | | | | | | | | | | | | | | | | | | | | | | | | It can be used to change any qreal property of its target Item in response to wheel rotation, or it can be used in other ways that involve bindings but without a target item. [ChangeLog][QtQuick][Event Handlers] Added WheelHandler, which handles mouse wheel rotation by modifying arbitrary Item properties. Fixes: QTBUG-68119 Change-Id: I247e2325ee993cc1b91a47fbd6c4ba0ffde7ad49 Reviewed-by: Jan Arve Sæther <jan-arve.saether@qt.io>
* | Doc: Fix a code snippet in DragHandler QML typeTopi Reinio2019-02-251-1/+1
|/ | | | | | | Task-number: QTBUG-73900 Change-Id: I00875525450a91d6841e5e7a2af77b41e400ea46 Reviewed-by: Shawn Rutledge <shawn.rutledge@qt.io> Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
* Doc: Show that DragHandler is now a multi-point handlerShawn Rutledge2018-09-112-7/+7
| | | | | | | | | Inheritance changed, and that means it has a centroid property. Amends ca7cdd71ee33f0d77eb6bf1367d2532e26155cb2 Task-number: QTBUG-68106 Change-Id: Ie68eb1376868b143dd56564a3abc896dd7e745c6 Reviewed-by: Jan Arve Sæther <jan-arve.saether@qt.io>
* Get rid of Qt.labs.handlers import, merge into QtQuick 2.12Shawn Rutledge2018-07-177-14/+7
| | | | | | | ... and clean up imports in examples, snippets and tests accordingly. Change-Id: I5bbe63afd2614cdc2c1ec7d179c9acd6bc03b167 Reviewed-by: Jan Arve Sæther <jan-arve.saether@qt.io>
* PointHandler: fix and improve the docsShawn Rutledge2017-11-231-0/+79
| | | | | | | | | | The qml module tag did not make it clear that it's in Qt.labs.handlers, not officially part of QtQuick yet. Some features needed better explanations. A snippet is helpful. Change-Id: Ie6a57510390bb376f20f5c1d98d8fc4c148af71b Reviewed-by: Jan Arve Sæther <jan-arve.saether@qt.io>
* Fix outdated BSD license headerKai Koehne2017-11-156-12/+72
| | | | | Change-Id: Ib1fe267c23ea9fce9bcc0a91ed61081260338460 Reviewed-by: Liang Qi <liang.qi@qt.io>
* improve documentation of DragHandlerShawn Rutledge2017-09-293-0/+172
| | | | | Change-Id: Ifde67ba567b447da948b79d32676458fd0628ec5 Reviewed-by: Jan Arve Sæther <jan-arve.saether@qt.io>
* improve documentation of PinchHandlerShawn Rutledge2017-09-143-0/+169
Change-Id: If7acf359731a046637248d9b415b9e865365a068 Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io> Reviewed-by: Shawn Rutledge <shawn.rutledge@qt.io>