Merge lp:~faenil/ubuntu-ui-toolkit/scrollbar_defaultTopBottomMargins into lp:ubuntu-ui-toolkit/staging

[Andrea Bernabei]

Change Scrollbar default top and bottom anchor margins. Tests included.

With this MR Scrollbar will default to using Flickable.topMargin and Flickable.bottomMargin (which are CONTENT margins, not anchor ones) as top/bottom ANCHORS margins.

This is to workaround the fact that Header and BottomEdgeHint modify Flickable.topMargin/bottomMargin in order to make space for themselves.

The solution was brainstormed with timp, zsombi, kalikiana.
If the developer wants to have custom Flickable top/bottomMargin (content margins), he will have to also modify Scrollbar margins.
This usecase will be addressed by a future MR, as the solution is still being brainstormed.

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

FAILED: Continuous integration, rev:1904
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-armhf-stable/568/
Executed test runs:
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2055/console

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-armhf-stable/568/rebuild

review: Needs Fixing (continuous-integration)

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

FAILED: Continuous integration, rev:1904
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-stable/556/
Executed test runs:
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2057/console

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-stable/556/rebuild

review: Needs Fixing (continuous-integration)

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

FAILED: Continuous integration, rev:1904
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-devel/336/
Executed test runs:
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2058/console

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-devel/336/rebuild

review: Needs Fixing (continuous-integration)

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

FAILED: Continuous integration, rev:1904
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-i386-gles-stable/310/
Executed test runs:
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2062/console

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-i386-gles-stable/310/rebuild

review: Needs Fixing (continuous-integration)

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

FAILED: Continuous integration, rev:1904
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci/197/
Executed test runs:
    FAILURE: https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-stable/556/console
    FAILURE: https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-armhf-stable/568/console
    FAILURE: https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-devel/336/console
    FAILURE: https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-i386-gles-stable/310/console
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2063/console
    SUCCESS: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2057
    SUCCESS: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2055
    SUCCESS: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2058
    SUCCESS: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2062

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci/197/rebuild

review: Needs Fixing (continuous-integration)

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

FAILED: Continuous integration, rev:1905
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-armhf-stable/569/
Executed test runs:
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2064/console

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-armhf-stable/569/rebuild

review: Needs Fixing (continuous-integration)

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

FAILED: Continuous integration, rev:1905
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-stable/557/
Executed test runs:
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2065/console

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-stable/557/rebuild

review: Needs Fixing (continuous-integration)

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

FAILED: Continuous integration, rev:1905
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-devel/337/
Executed test runs:
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2066/console

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-devel/337/rebuild

review: Needs Fixing (continuous-integration)

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

FAILED: Continuous integration, rev:1905
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-i386-gles-stable/311/
Executed test runs:
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2067/console

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-i386-gles-stable/311/rebuild

review: Needs Fixing (continuous-integration)

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

FAILED: Continuous integration, rev:1905
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci/198/
Executed test runs:
    FAILURE: https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-stable/557/console
    FAILURE: https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-armhf-stable/569/console
    FAILURE: https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-devel/337/console
    FAILURE: https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-i386-gles-stable/311/console
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2068/console
    SUCCESS: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2065
    SUCCESS: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2064
    SUCCESS: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2066
    SUCCESS: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2067

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci/198/rebuild

review: Needs Fixing (continuous-integration)

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

PASSED: Continuous integration, rev:1906
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-stable/558/
Executed test runs:
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2069/console

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-stable/558/rebuild

review: Approve (continuous-integration)

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

PASSED: Continuous integration, rev:1906
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-devel/338/
Executed test runs:
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2070/console

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-devel/338/rebuild

review: Approve (continuous-integration)

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

PASSED: Continuous integration, rev:1906
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-i386-gles-stable/312/
Executed test runs:
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2071/console

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-i386-gles-stable/312/rebuild

review: Approve (continuous-integration)

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

PASSED: Continuous integration, rev:1906
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-armhf-stable/570/
Executed test runs:
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2072/console

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-armhf-stable/570/rebuild

review: Approve (continuous-integration)

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

PASSED: Continuous integration, rev:1906
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci/199/
Executed test runs:
    SUCCESS: https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-stable/558
    SUCCESS: https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-armhf-stable/570
        deb: https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-armhf-stable/570/artifact/artifacts/*zip*/artifacts.zip
    SUCCESS: https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-devel/338
    SUCCESS: https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-i386-gles-stable/312
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2073/console
    SUCCESS: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2069
    SUCCESS: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2072
    SUCCESS: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2070
    SUCCESS: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2071

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci/199/rebuild

review: Approve (continuous-integration)

[Zsombor Egri (zsombi)]

Great fix, nice tests, that's my boy :)

review: Approve

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

PASSED: Continuous integration, rev:1907
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-devel/342/
Executed test runs:
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2083/console

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-devel/342/rebuild

review: Approve (continuous-integration)

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

PASSED: Continuous integration, rev:1907
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-stable/562/
Executed test runs:
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2084/console

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-stable/562/rebuild

review: Approve (continuous-integration)

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

PASSED: Continuous integration, rev:1907
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-stable/563/
Executed test runs:
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2085/console

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-stable/563/rebuild

review: Approve (continuous-integration)

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

FAILED: Continuous integration, rev:1907
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-i386-gles-stable/316/
Executed test runs:
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2086/console

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-i386-gles-stable/316/rebuild

review: Needs Fixing (continuous-integration)

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

PASSED: Continuous integration, rev:1907
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-devel/343/
Executed test runs:
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2087/console

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-devel/343/rebuild

review: Approve (continuous-integration)

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

PASSED: Continuous integration, rev:1907
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-i386-gles-stable/317/
Executed test runs:
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2088/console

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-i386-gles-stable/317/rebuild

review: Approve (continuous-integration)

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

PASSED: Continuous integration, rev:1907
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-i386-gles-stable/320/
Executed test runs:
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2097/console

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-i386-gles-stable/320/rebuild

review: Approve (continuous-integration)

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

PASSED: Continuous integration, rev:1907
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-armhf-stable/574/
Executed test runs:
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2108/console

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-armhf-stable/574/rebuild

review: Approve (continuous-integration)

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

FAILED: Continuous integration, rev:1907
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci/202/
Executed test runs:
    SUCCESS: https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-stable/562
    SUCCESS: https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-armhf-stable/574
        deb: https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-armhf-stable/574/artifact/artifacts/*zip*/artifacts.zip
    SUCCESS: https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-amd64-devel/342
    FAILURE: https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-i386-gles-stable/316/console
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2109/console
    SUCCESS: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2084
    SUCCESS: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2108
    SUCCESS: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2083
    SUCCESS: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2086

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci/202/rebuild

review: Needs Fixing (continuous-integration)

[ubuntu-sdk-build-bot (ubuntu-sdk-build-bot)]

PASSED: Continuous integration, rev:1907
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-armhf-stable/575/
Executed test runs:
    None: https://jenkins.ubuntu.com/ubuntu-sdk/job/generic-update-mp/2113/console

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/ubuntu-sdk/job/ubuntu-ui-toolkit-ci-armhf-stable/575/rebuild

review: Approve (continuous-integration)

=== modified file 'examples/ubuntu-ui-toolkit-gallery/Template.qml'
--- examples/ubuntu-ui-toolkit-gallery/Template.qml	2016-01-13 16:14:08 +0000
+++ examples/ubuntu-ui-toolkit-gallery/Template.qml	2016-03-24 10:43:42 +0000
@@ -34,19 +34,16 @@
     }
 
     ScrollView {
-        //anchors.fill: parent
-        //anchors.topMargin: template.header.flickable ? 0 : template.header.height
         objectName: "TemplateScrollView"
         anchors {
             fill: parent
             topMargin: template.header.flickable ? 0 : template.header.height
         }
+
         Flickable {
             id: templateFlickable
             objectName: "TemplateFlickable"
             anchors.fill: parent
-            topMargin: units.gu(2)
-            bottomMargin: units.gu(2)
             contentHeight: column.height
             interactive: contentHeight > height
             Column {

=== modified file 'src/Ubuntu/Components/1.3/ScrollView.qml'
--- src/Ubuntu/Components/1.3/ScrollView.qml	2016-02-18 12:39:14 +0000
+++ src/Ubuntu/Components/1.3/ScrollView.qml	2016-03-24 10:43:42 +0000
@@ -30,6 +30,13 @@
     migrate to ScrollView, to ensure the UX is ready for convergent devices and is consistent with the
     rest of the platform.
 
+    ScrollView wraps \l {Scrollbar}(s) in a view, and provides additional features such as:
+    \list
+    \li - Keyboard navigation and focus handling, for a complete convergent experience.
+    \li - Automatic position handling of vertical and horizontal scrollbars, preventing them from
+          overlapping one another when both on screen.
+    \endlist
+
     Adding scrollbars and keyboard input handling to a QML item is as simple as wrapping that item in a
     ScrollView, as shown in the following example:
 

=== modified file 'src/Ubuntu/Components/1.3/Scrollbar.qml'
--- src/Ubuntu/Components/1.3/Scrollbar.qml	2016-02-25 12:59:27 +0000
+++ src/Ubuntu/Components/1.3/Scrollbar.qml	2016-03-24 10:43:42 +0000
@@ -18,14 +18,19 @@
 import Ubuntu.Components 1.3 as Toolkit
 
 /*!
-    \qmltype ScrollBar
+    \qmltype Scrollbar
     \inqmlmodule Ubuntu.Components 1.1
     \ingroup ubuntu
-    \brief The ScrollBar component provides scrolling functionality for
+    \brief The Scrollbar component provides scrolling functionality for
     scrollable views (i.e. Flickable, ListView).
 
-    The ScrollBar can be set to any flickable and has built-in anchoring setup
-    to the attached flickable's front, rear, top or bottom. the scrollbar can
+    \b NOTE: the Scrollbar component was revamped for OTA9 and used for the implementation
+    of \l ScrollView. Apps targeting system version OTA9 (or newer) should use ScrollView instead
+    of Scrollbar, as it features convergent-ready features, such as (but not limited to)
+    keyboard input handling.
+
+    The Scrollbar can be set to any flickable and has built-in anchoring setup
+    to the attached flickable's front, rear, top or bottom. The scrollbar can
     also be aligned using anchors, however the built-in align functionality
     makes sure to have the proper alignemt applied based on theme and layout
     direction (RTL or LTR).
@@ -57,6 +62,43 @@
         }
     }
     \endqml
+
+    \section1 Vertical Scrollbar and Flickable behaviour
+
+    Since Flickable's topMargin and bottomMargin are modified by Ubuntu components
+    such as \l BottomEdgeHint and \l Header in their positioning logic, the Scrollbar component
+    uses the value of those properties to its top and bottom anchors margins, by default. This is
+    to prevent any overlap with BottomEdgeHint or Header (see \l {Vertical Scrollbar and Header behaviour}
+    for more info about that). In case you need to specify custom Flickable
+    content margins (note: we're talking about content margins, not anchors ones), you will also have to
+    override the top and bottom anchors margins of the Scrollbar accordingly.
+
+    \section1 Vertical Scrollbar and Header behaviour
+
+    The thumb of the Scrollbar should not move or resize unexpectedly. It would be confusing,
+    for instance, if it moved under the user's finger (or pointer) while he's dragging it.
+
+    Because the size and position of the thumb in a scrollbar is related to the size of the
+    trough (or track) it slides in, it is important that the trough does not resize or move while the
+    user is interacting with the component.
+
+    In the context of a \l Page with a \l Header that slides in and out dynamically when the user
+    flicks the surface (see \l {Header::flickable}), a vertical Scrollbar that is linked
+    to the same flickable surface as the Header behaves as described below:
+
+    \list
+    \li - when the Header is exposed, the Scrollbar component sits right below it, \
+          thus avoiding overlaps;
+
+    \li - when the Header hides due to the user either flicking the surface or dragging \
+          the thumb, the trough of the Scrollbar does not resize or move, thus avoiding \
+          unexpected changes in thumb's position or size. As a side effect, the space \
+          above the Scrollbar, previously occupied by Header, stays empty until the Header \
+          is exposed again.
+
+    \endlist
+    \br
+    This behaviour is intended and makes for a less confusing User Experience.
   */
 
 Toolkit.StyledItem {
@@ -135,9 +177,9 @@
         right: internals.rightAnchor(__viewport ? __viewport : flickableItem)
         rightMargin: internals.rightAnchorMargin()
         top: internals.topAnchor(__viewport ? __viewport : flickableItem)
-        topMargin: internals.topAnchorMargin()
+        topMargin: (flickableItem ? flickableItem.topMargin : 0) + internals.topAnchorMargin()
         bottom: internals.bottomAnchor(__viewport ? __viewport : flickableItem)
-        bottomMargin: internals.bottomAnchorMargin()
+        bottomMargin: (flickableItem ? flickableItem.bottomMargin : 0) + internals.bottomAnchorMargin()
     }
 
     /*!
@@ -183,7 +225,6 @@
                         && __buddyScrollbar.align === Qt.AlignLeading
                         && __buddyScrollbar.__styleInstance.isScrollable)
                     return __buddyScrollbar.__styleInstance.troughThicknessSteppersStyle
-                    //return buddyScrollbar.__styleInstance.indicatorThickness
                 // *ELSE FALLTHROUGH*
             default:
                 return 0
@@ -209,7 +250,6 @@
                         && __buddyScrollbar.align === Qt.AlignTrailing
                         && __buddyScrollbar.__styleInstance.isScrollable)
                     return __buddyScrollbar.__styleInstance.troughThicknessSteppersStyle
-                    //return buddyScrollbar.__styleInstance.indicatorThickness
                 // *ELSE FALLTHROUGH*
             default:
                 return 0
@@ -234,7 +274,6 @@
                         && __buddyScrollbar.align === Qt.AlignTop
                         && __buddyScrollbar.__styleInstance.isScrollable)
                     return __buddyScrollbar.__styleInstance.troughThicknessSteppersStyle
-                    //return buddyScrollbar.__styleInstance.indicatorThickness
                 // *ELSE FALLTHROUGH*
 
             default:
@@ -260,7 +299,6 @@
                         && __buddyScrollbar.align === Qt.AlignBottom
                         && __buddyScrollbar.__styleInstance.isScrollable)
                     return __buddyScrollbar.__styleInstance.troughThicknessSteppersStyle
-                    //return buddyScrollbar.__styleInstance.indicatorThickness
                 // *ELSE FALLTHROUGH*
             default:
                 return 0

=== modified file 'tests/unit_x11/tst_components/tst_scrollbar.qml'
--- tests/unit_x11/tst_components/tst_scrollbar.qml	2016-02-25 17:22:48 +0000
+++ tests/unit_x11/tst_components/tst_scrollbar.qml	2016-03-24 10:43:42 +0000
@@ -867,7 +867,32 @@
             flickableSanityCheck.rightMargin = -units.gu(3)
             flickableSanityCheck.bottomMargin = -units.gu(4)
             performStyleSanityCheck(scrollbarSanityCheck)
-
+        }
+
+        //Test that Scrollbar defaults to Flickable.topMargin/bottomMargin (content margins)
+        //as its ANCHORS margins
+        function test_topBottomMargins(data) {
+            var freshTestItem = getFreshFlickable(data.alignment)
+            var flickable = freshTestItem.flickable
+            var scrollbar = freshTestItem.scrollbar
+
+            compare(scrollbar.__styleInstance.isScrollable, true, "The view is not scrollable.")
+            compare(scrollbar.__styleInstance.alwaysOnScrollbars, false, "This test assumes overlay scrollbars (if you need to change this, fix the expected margins).")
+            compare(scrollbar.anchors.topMargin, flickable.topMargin, "Wrong anchors.topMargin.")
+            compare(scrollbar.anchors.bottomMargin, flickable.bottomMargin, "Wrong anchors.bottomMargin.")
+
+            flickable.topMargin = units.gu(1)
+            compare(scrollbar.anchors.topMargin, units.gu(1), "Wrong anchors.topMargin.")
+            compare(scrollbar.anchors.bottomMargin, flickable.bottomMargin, "Wrong anchors.bottomMargin.")
+
+            flickable.bottomMargin = units.gu(3)
+            compare(scrollbar.anchors.topMargin, units.gu(1), "Wrong anchors.topMargin.")
+            compare(scrollbar.anchors.bottomMargin, units.gu(3), "Wrong anchors.bottomMargin.")
+
+            flickable.topMargin = 0
+            flickable.bottomMargin = units.gu(6)
+            compare(scrollbar.anchors.topMargin, 0, "Wrong anchors.topMargin.")
+            compare(scrollbar.anchors.bottomMargin, units.gu(6), "Wrong anchors.bottomMargin.")
         }
     }
 }

=== added file 'tests/unit_x11/tst_components/tst_scrollbar_header.qml'
--- tests/unit_x11/tst_components/tst_scrollbar_header.qml	1970-01-01 00:00:00 +0000
+++ tests/unit_x11/tst_components/tst_scrollbar_header.qml	2016-03-24 10:43:42 +0000
@@ -0,0 +1,311 @@
+/*
+ * Copyright 2016 Canonical Ltd.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation; version 3.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Author: Andrea Bernabei <[e-mail]>
+ */
+
+import QtQuick 2.4
+import QtTest 1.0
+import Ubuntu.Test 1.0
+import Ubuntu.Components 1.3
+import Ubuntu.Components.Styles 1.3
+import QtQml.Models 2.1
+
+Item {
+    id: main
+    width: units.gu(50)
+    height: units.gu(100)
+
+    Component {
+        id: flickableComp
+        Item {
+            id: item
+            width: units.gu(20)
+            height: units.gu(30)
+            property alias flickable: freshFlickable
+            property alias scrollbar: freshScrollbar
+            property alias content: content
+            property alias scrollbarAlignment: freshScrollbar.align
+
+            //Don't change this to a ListView, this usecase has to be simple,
+            //we don't want the difficulties added by ListView, i.e. delegates
+            //size estimation, dynamic contentWidth/Height, etc
+            Flickable {
+                id: freshFlickable
+                anchors.fill: parent
+                contentHeight: content.height
+                contentWidth: content.width
+                clip: true
+                Rectangle {
+                    id: content
+                    width: units.gu(40)
+                    //make this much taller than the flickable to avoid timing issues when
+                    //detecting if the flickable is flicking in the tests
+                    height: units.gu(200)
+                    color: "blue"
+                }
+            }
+            Scrollbar {
+                id: freshScrollbar
+                flickableItem: parent.flickable
+            }
+        }
+    }
+
+    SignalSpy {
+        id: signalSpy
+    }
+    SignalSpy {
+        id: anotherSignalSpy
+    }
+
+    Flickable {
+        anchors.fill: parent
+        Column {
+            id: column
+            Repeater {
+                model: layoutsModel
+            }
+        }
+    }
+
+    VisualItemModel {
+        id: layoutsModel
+        Item {
+            width: childrenRect.width
+            height: childrenRect.height
+            Flickable {
+                id: randomFlickable
+            }
+
+            //complex PageHeader example taken from the PageHeader tutorial
+            //https://developer.ubuntu.com/en/blog/2016/02/24/pageheader-tutorial/
+            MainView {
+                id: mainView_movingHeaderTest
+                width: units.gu(50)
+                height: units.gu(80)
+                clip: true
+
+                property alias page: pageItem
+                property alias standardHeader: standardHeaderItem
+                property alias editHeader: editHeaderItem
+
+                Page {
+                    id: pageItem
+                    header: standardHeaderItem
+
+                    onHeaderChanged: console.log("NEW HEADER")
+                    Flickable {
+                        id: flickable_movingHeaderTest
+                        anchors.fill: parent
+                        //just make sure the scrollbar is scrollable
+                        contentHeight: mainView_movingHeaderTest.height * 2
+                        contentWidth: mainView_movingHeaderTest.width * 2
+                        Label {
+                            text: "Use the icons in the header."
+                            visible: standardHeaderItem.visible
+                        }
+                    }
+                    Scrollbar {
+                        id: scrollbar_movingHeaderTest
+                        flickableItem: flickable_movingHeaderTest
+                    }
+
+                    PageHeader {
+                        id: standardHeaderItem
+                        visible: pageItem.header === standardHeaderItem
+                        title: "Default title"
+                        flickable: flickable_movingHeaderTest
+                        trailingActionBar.actions: [
+                            Action {
+                                iconName: "edit"
+                                text: "Edit"
+                                onTriggered: pageItem.header = editHeaderItem
+                            }
+                        ]
+                    }
+                    PageHeader {
+                        id: editHeaderItem
+                        visible: pageItem.header === editHeaderItem
+                        flickable: flickable_movingHeaderTest
+                        property Component delegate: Component {
+                            AbstractButton {
+                                id: button
+                                action: modelData
+                                width: label.width + units.gu(4)
+                                height: parent.height
+                                Rectangle {
+                                    color: UbuntuColors.slate
+                                    opacity: 0.1
+                                    anchors.fill: parent
+                                    visible: button.pressed
+                                }
+                                Label {
+                                    anchors.centerIn: parent
+                                    id: label
+                                    text: action.text
+                                    font.weight: text === "Confirm"
+                                                 ? Font.Normal
+                                                 : Font.Light
+                                }
+                            }
+                        }
+                        leadingActionBar {
+                            anchors.leftMargin: 0
+                            actions: Action {
+                                text: "Cancel"
+                                iconName: "close"
+                                onTriggered: pageItem.header = standardHeaderItem
+                            }
+                            delegate: editHeaderItem.delegate
+                        }
+                        trailingActionBar {
+                            anchors.rightMargin: 0
+                            actions: Action {
+                                text: "Confirm"
+                                iconName: "tick"
+                                onTriggered: pageItem.header = standardHeaderItem
+                            }
+                            delegate: editHeaderItem.delegate
+                        }
+                        extension: Toolbar {
+                            anchors {
+                                left: parent.left
+                                right: parent.right
+                                bottom: parent.bottom
+                            }
+                            trailingActionBar.actions: [
+                                Action { iconName: "bookmark-new" },
+                                Action { iconName: "add" },
+                                Action { iconName: "edit-select-all" },
+                                Action { iconName: "edit-copy" },
+                                Action { iconName: "select" }
+                            ]
+                            leadingActionBar.actions: Action {
+                                iconName: "delete"
+                                text: "delete"
+                                onTriggered: print("Delete action triggered")
+                            }
+                        }
+                    }
+
+                }
+            }
+
+        }
+    }
+
+    ScrollbarTestCase {
+        name: "Scrollbar"
+
+        function getMovingHeaderView() {
+            var wrapper = movingHeaderHandlingItem.createObject(column)
+            verify(wrapper !== null, "Error: dynamic item creation failed.")
+            currComponent = wrapper
+            return currComponent
+        }
+
+        function cleanup() {
+            if (currComponent) {
+                currComponent.destroy()
+                currComponent = null
+            }
+            gc()
+        }
+
+        function checkScrollbarPositionRelativeToPage(scrollbar, page, expectedY, msgPrefix) {
+            compare(scrollbar.mapToItem(page).y, expectedY, msgPrefix + ": Scrollbar does not start below the header.")
+        }
+
+        function test_handlingOfMovingHeader_data() {
+            return [
+                        { tag: "Standard header", header: standardHeaderItem },
+                        { tag: "Edit header (with extensions)", header: editHeaderItem },
+                        //Setting header to null means using the old header, and:
+                        //- We don't support this behaviour when using the old header
+                        //- There is no API to get the height of the old header, so we can't test it
+                        //{ tag: "Null header", header: null }
+                    ]
+        }
+        function test_handlingOfMovingHeader(data) {
+            var page = pageItem
+            var header = data.header
+
+            page.header = header
+            console.log(page.header, header.flickable)
+
+            //make sure the currently tested header is the one driving the flickable changes
+            //FIXME: this should not be needed after #1560458 is fixed
+            header.flickable = null
+            header.flickable = flickable_movingHeaderTest
+
+            compare(page.header, header, "Handling of moving header: wrong header.")
+            compare(scrollbar_movingHeaderTest.__styleInstance.isVertical, true, "Scrollbar is not vertical.")
+            compare(scrollbar_movingHeaderTest.__styleInstance.isScrollable, true, "Scrollbar is not scrollable.")
+
+            //don't do the rest of the checks on the null header, just check that it's aligning with the old header implementation
+            //(page.head.contents.height)
+            if (data.header === null) {
+                checkScrollbarPositionRelativeToPage(scrollbar_movingHeaderTest, page, page.head.contents.height, data.tag)
+                return
+            } else {
+                header.flickable = flickable_movingHeaderTest
+                compare(header.flickable, flickable_movingHeaderTest, "Wrong PageHeader flickable.")
+                checkScrollbarPositionRelativeToPage(scrollbar_movingHeaderTest, page, page.header.height, data.tag)
+            }
+
+            var tmpHeaderHeight = header.height
+            page.header.height += units.gu(1)
+            //make sure the header actually has a different height now
+            verify(scrollbar_movingHeaderTest.height !== tmpHeaderHeight, "Header height changed value.")
+            checkScrollbarPositionRelativeToPage(scrollbar_movingHeaderTest, page, page.header.height,
+                                                 data.tag + ", after changing height")
+
+            //now link the header to a null flickable and check that scrollbar is covered
+            //the header (yes, we're checking that it creates bad UX, because we're expecting the
+            //developer to set the anchors accordingly so that we don't need to add  inter-components
+            //dependencies. The test Page does not handle this on purpose, so the header
+            //should cover the scrollbar)
+            header.flickable = null
+            compare(header.flickable, null, "Wrong PageHeader flickable.")
+            expectFailContinue("Standard header", "Waiting on Header bug #1560458")
+            checkScrollbarPositionRelativeToPage(scrollbar_movingHeaderTest, page, 0, data.tag)
+
+            //reassign the correct flickable and check again
+            header.flickable = flickable_movingHeaderTest
+            compare(header.flickable, flickable_movingHeaderTest, "Wrong PageHeader flickable.")
+            checkScrollbarPositionRelativeToPage(scrollbar_movingHeaderTest, page, page.header.height, data.tag + ", scrollbar")
+
+            header.visible = false
+            compare(header.visible, false, "Header visibility did not change, should have been false.")
+            expectFailContinue("", "Waiting on Header bug #1560458")
+            checkScrollbarPositionRelativeToPage(scrollbar_movingHeaderTest, page, 0, data.tag + ", invisible header")
+
+            header.visible = true
+            compare(header.visible, true, "Header visibility did not change, should have been true.")
+            checkScrollbarPositionRelativeToPage(scrollbar_movingHeaderTest, page, page.header.height, data.tag + ", visible header")
+
+            //even if the header has opacity 0, we should still take it into account. This is a standard in
+            //QtQuick, you don't ignore a component just because opacity is 0, as that is also used for animations
+            header.opacity = 0.0
+            compare(header.opacity, 0.0, "Header opacity did not change, should have been 0.")
+            checkScrollbarPositionRelativeToPage(scrollbar_movingHeaderTest, page, page.header.height, data.tag + ", 0.0 header opacity")
+
+            header.opacity = 1.0
+            compare(header.opacity, 1.0, "Header opacity did not change, should have been 1.")
+            checkScrollbarPositionRelativeToPage(scrollbar_movingHeaderTest, page, page.header.height, data.tag + ", 1.0 header opacity")
+        }
+    }
+}