18
18
import Ubuntu.Components 1.3 as Toolkit
22
22
\inqmlmodule Ubuntu.Components 1.1
24
\brief The ScrollBar component provides scrolling functionality for
24
\brief The Scrollbar component provides scrolling functionality for
25
25
scrollable views (i.e. Flickable, ListView).
27
The ScrollBar can be set to any flickable and has built-in anchoring setup
28
to the attached flickable's front, rear, top or bottom. the scrollbar can
27
\b NOTE: the Scrollbar component was revamped for OTA9 and used for the implementation
28
of \l ScrollView. Apps targeting system version OTA9 (or newer) should use ScrollView instead
29
of Scrollbar, as it features convergent-ready features, such as (but not limited to)
30
keyboard input handling.
32
The Scrollbar can be set to any flickable and has built-in anchoring setup
33
to the attached flickable's front, rear, top or bottom. The scrollbar can
29
34
also be aligned using anchors, however the built-in align functionality
30
35
makes sure to have the proper alignemt applied based on theme and layout
31
36
direction (RTL or LTR).
66
\section1 Vertical Scrollbar and Flickable behaviour
68
Since Flickable's topMargin and bottomMargin are modified by Ubuntu components
69
such as \l BottomEdgeHint and \l Header in their positioning logic, the Scrollbar component
70
uses the value of those properties to its top and bottom anchors margins, by default. This is
71
to prevent any overlap with BottomEdgeHint or Header (see \l {Vertical Scrollbar and Header behaviour}
72
for more info about that). In case you need to specify custom Flickable
73
content margins (note: we're talking about content margins, not anchors ones), you will also have to
74
override the top and bottom anchors margins of the Scrollbar accordingly.
76
\section1 Vertical Scrollbar and Header behaviour
78
The thumb of the Scrollbar should not move or resize unexpectedly. It would be confusing,
79
for instance, if it moved under the user's finger (or pointer) while he's dragging it.
81
Because the size and position of the thumb in a scrollbar is related to the size of the
82
trough (or track) it slides in, it is important that the trough does not resize or move while the
83
user is interacting with the component.
85
In the context of a \l Page with a \l Header that slides in and out dynamically when the user
86
flicks the surface (see \l {Header::flickable}), a vertical Scrollbar that is linked
87
to the same flickable surface as the Header behaves as described below:
90
\li - when the Header is exposed, the Scrollbar component sits right below it, \
91
thus avoiding overlaps;
93
\li - when the Header hides due to the user either flicking the surface or dragging \
94
the thumb, the trough of the Scrollbar does not resize or move, thus avoiding \
95
unexpected changes in thumb's position or size. As a side effect, the space \
96
above the Scrollbar, previously occupied by Header, stays empty until the Header \
101
This behaviour is intended and makes for a less confusing User Experience.
62
104
Toolkit.StyledItem {
135
177
right: internals.rightAnchor(__viewport ? __viewport : flickableItem)
136
178
rightMargin: internals.rightAnchorMargin()
137
179
top: internals.topAnchor(__viewport ? __viewport : flickableItem)
138
topMargin: internals.topAnchorMargin()
180
topMargin: (flickableItem ? flickableItem.topMargin : 0) + internals.topAnchorMargin()
139
181
bottom: internals.bottomAnchor(__viewport ? __viewport : flickableItem)
140
bottomMargin: internals.bottomAnchorMargin()
182
bottomMargin: (flickableItem ? flickableItem.bottomMargin : 0) + internals.bottomAnchorMargin()
183
225
&& __buddyScrollbar.align === Qt.AlignLeading
184
226
&& __buddyScrollbar.__styleInstance.isScrollable)
185
227
return __buddyScrollbar.__styleInstance.troughThicknessSteppersStyle
186
//return buddyScrollbar.__styleInstance.indicatorThickness
187
228
// *ELSE FALLTHROUGH*
209
250
&& __buddyScrollbar.align === Qt.AlignTrailing
210
251
&& __buddyScrollbar.__styleInstance.isScrollable)
211
252
return __buddyScrollbar.__styleInstance.troughThicknessSteppersStyle
212
//return buddyScrollbar.__styleInstance.indicatorThickness
213
253
// *ELSE FALLTHROUGH*
234
274
&& __buddyScrollbar.align === Qt.AlignTop
235
275
&& __buddyScrollbar.__styleInstance.isScrollable)
236
276
return __buddyScrollbar.__styleInstance.troughThicknessSteppersStyle
237
//return buddyScrollbar.__styleInstance.indicatorThickness
238
277
// *ELSE FALLTHROUGH*
260
299
&& __buddyScrollbar.align === Qt.AlignBottom
261
300
&& __buddyScrollbar.__styleInstance.isScrollable)
262
301
return __buddyScrollbar.__styleInstance.troughThicknessSteppersStyle
263
//return buddyScrollbar.__styleInstance.indicatorThickness
264
302
// *ELSE FALLTHROUGH*