docs and example: clarify the usage of Flickable contentX/contentY

It's such a common mistake to observe that they normally go to zero at
the top-left corner, but fail to realize that they won't always do that.

Task-number: QTBUG-64219
Task-number: QTBUG-22894
Task-number: QTBUG-27884
Change-Id: I6bc81d4761debdaff8fb3366bf1e944241207157
Reviewed-by: J-P Nurmi <jpnurmi@qt.io>

1 files changed, 15 insertions, 1 deletions

diff --git a/src/quick/items/qquickflickable.cpp b/src/quick/items/qquickflickable.cpp
index e0f8b6de00..3662827973 100644
--- a/src/quick/items/qquickflickable.cpp
+++ b/src/quick/items/qquickflickable.cpp
@@ -734,7 +734,19 @@ QQuickFlickable::~QQuickFlickable()
 
     These properties hold the surface coordinate currently at the top-left
     corner of the Flickable. For example, if you flick an image up 100 pixels,
-    \c contentY will be 100.
+    \c contentY will increase by 100.
+
+    \note If you flick back to the origin (the top-left corner), after the
+    rebound animation, \c contentX will settle to the same value as \c originX,
+    and \c contentY to \c originY. These are usually (0,0), however ListView
+    and GridView may have an arbitrary origin due to delegate size variation,
+    or item insertion/removal outside the visible region. So if you want to
+    implement something like a vertical scrollbar, one way is to use
+    \c {y: (contentY - originY) * (height / contentHeight)}
+    for the position; another way is to use the normalized values in
+    \l {QtQuick::Flickable::visibleArea}{visibleArea}.
+
+    \sa originX, originY
 */
 qreal QQuickFlickable::contentX() const
 {
@@ -2153,6 +2165,8 @@ void QQuickFlickable::setRightMargin(qreal m)
     This is usually (0,0), however ListView and GridView may have an arbitrary
     origin due to delegate size variation, or item insertion/removal outside
     the visible region.
+
+    \sa contentX, contentY
 */
 
 qreal QQuickFlickable::originY() const