From 93855f56bf750e22f2c10763c6306748e87e691d Mon Sep 17 00:00:00 2001
From: Shawn Rutledge <shawn.rutledge@qt.io>
Date: Wed, 16 Aug 2017 10:36:10 +0200
Subject: improve documentation of DragHandler
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Change-Id: Ifde67ba567b447da948b79d32676458fd0628ec5
Reviewed-by: Jan Arve Sæther <jan-arve.saether@qt.io>
---
 src/quick/handlers/qquickdraghandler.cpp | 40 ++++++++++++++++++++++++++++++--
 1 file changed, 38 insertions(+), 2 deletions(-)

(limited to 'src/quick/handlers')

diff --git a/src/quick/handlers/qquickdraghandler.cpp b/src/quick/handlers/qquickdraghandler.cpp
index 5e7b6a4962..12f1a29bca 100644
--- a/src/quick/handlers/qquickdraghandler.cpp
+++ b/src/quick/handlers/qquickdraghandler.cpp
@@ -46,11 +46,29 @@ QT_BEGIN_NAMESPACE
 /*!
     \qmltype DragHandler
     \instantiates QQuickDragHandler
-    \inqmlmodule QtQuick
+    \inherits SinglePointHandler
+    \inqmlmodule Qt.labs.handlers
     \ingroup qtquick-handlers
     \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
+    manipulates its \l target.
+
+    \snippet pointerHandlers/dragHandler.qml 0
+
+    It has properties to restrict the range of dragging.
+
+    If it is declared within one Item but is assigned a different \l target,
+    then it handles events within the bounds of the \l parent Item but
+    manipulates the \c target Item instead:
+
+    \snippet pointerHandlers/dragHandlerDifferentTarget.qml 0
+
+    A third way to use it is to set \l target to \c null and react to property
+    changes in some other way:
+
+    \snippet pointerHandlers/dragHandlerNullTarget.qml 0
 
     At this time, drag-and-drop is not yet supported.
 
@@ -172,7 +190,25 @@ void QQuickDragHandler::setTranslation(const QVector2D &trans)
     emit translationChanged();
 }
 
-
+/*!
+    \qmlpropertygroup QtQuick::DragHandler::xAxis
+    \qmlpropertygroup QtQuick::DragHandler::yAxis
+    \qmlproperty real QtQuick::DragHandler::DragAxis::minimum
+    \qmlproperty real QtQuick::DragHandler::DragAxis::maximum
+    \qmlproperty real QtQuick::DragHandler::DragAxis::enabled
+
+    \c xAxis and yAxis control the constraints for horizontal and vertical
+    dragging, respectively.
+
+    \value minimum
+        The minimum acceptable value of \l {Item::x}{x} or \l {Item::y}{y}
+        to be applied to the \l target
+    \value maximum
+        The maximum acceptable value of \l {Item::x}{x} or \l {Item::y}{y}
+        to be applied to the \l target
+    \value enabled
+        Whether dragging in this direction is allowed at all
+*/
 QQuickDragAxis::QQuickDragAxis()
   : m_minimum(-DBL_MAX)
   , m_maximum(DBL_MAX)
-- 
cgit v1.2.3