git.iko.soy/unity8
on bc0a410 help sign in
unity8/Components/Carousel.qml
342 lines 18 kB history raw
1/*
2 * Copyright (C) 2013 Canonical, Ltd.
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; version 3.
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
12 *
13 * You should have received a copy of the GNU General Public License
14 * along with this program. If not, see <http://www.gnu.org/licenses/>.
15 */
17import QtQuick 2.0
18import Ubuntu.Components 0.1
19import "carousel.js" as CarouselJS
21/*! The Carousel component presents the items of a model in a carousel view. It's similar to a
22 cover flow. But it stops at it's boundaries (therefore no PathView is used).
23 */
24Item {
25 id: carousel
27 clip: true // Don't leak horizontally to other dashes
29 /// The component to be used as delegate. This component has to be derived from BaseCarouselDelegate
30 property Component itemComponent
31 /// Model for the Carousel, which has to be a model usable by a ListView
32 property alias model: listView.model
33 /// A minimal width of a tile can be set here. Per default a best fit will be calculated
34 property alias minimumTileWidth: listView.minimumTileWidth
35 /// Sets the number of tiles that are visible
36 property alias pathItemCount: listView.pathItemCount
37 /// Aspect ratio of the tiles width/height
38 property alias tileAspectRatio: listView.tileAspectRatio
39 /// Used to cache some delegates for performance reasons. See the ListView documentation for details
40 property alias cacheBuffer: listView.cacheBuffer
41 /// Width of the "draw buffer" in pixel. The drawBuffer is an additional area at start/end where
42 /// items drawn, even if it is not in the visible area.
43 /// cacheBuffer controls only the to retain delegates outside the visible area (and is used on top of the drawBuffer)
44 /// see https://bugreports.qt-project.org/browse/QTBUG-29173
45 property int drawBuffer: width / pathItemCount // an "ok" value - but values used from the listView cause loops
46 /// The selected item can be shown in a different size controlled by selectedItemScaleFactor
47 property real selectedItemScaleFactor: 1.1
48 /// The index of the item that should be highlighted
49 property alias highlightIndex: listView.highlightIndex
50 /// exposes the delegate of the currentItem
51 readonly property alias currentItem: listView.currentItem
52 /// exposes the distance to the next row (only one row in carousel, so it's the topMargins)
53 readonly property alias verticalSpacing: listView.verticalMargin
55 /// Emitted when the user clicked on an item
56 /// @param index is the index of the clicked item
57 /// @param model is the model of all the items in the carousel
58 /// @param itemY is y of the clicked delegate
59 signal clicked(int index, var model, real itemY)
61 /// Emitted when the user pressed and held on an item
62 /// @param index is the index of the held item
63 /// @param model is the model of all the items in the carousel
64 /// @param itemY is y of the held delegate
65 signal pressAndHold(int index, var model, real itemY)
67 implicitHeight: listView.tileHeight * selectedItemScaleFactor
69 /* Basic idea behind the carousel effect is to move the items of the delegates (compacting /stuffing them).
70 One drawback is, that more delegates have to be drawn than usually. As some items are moved from the
71 invisible to the visible area. Setting the cacheBuffer does not fix this.
72 See https://bugreports.qt-project.org/browse/QTBUG-29173
73 Therefore the ListView has negative left and right anchors margins, and in addition a header
74 and footer item to compensate that.
76 The scaling of the items is controlled by the variable continuousIndex, described below. */
77 ListView {
78 id: listView
80 property real minimumTileWidth: 0
81 property real newContentX: disabledNewContentX
82 property real pathItemCount: referenceWidth / referenceTileWidth
83 property real tileAspectRatio: 1
84 property int highlightIndex: -1
86 /* The positioning and scaling of the items in the carousel is based on the variable
87 'continuousIndex', a continuous real variable between [0, 'carousel.model.count'],
88 roughly representing the index of the item that is prioritised over the others.
89 'continuousIndex' is not linear, but is weighted depending on if it is close
90 to the beginning of the content (beginning phase), in the middle (middle phase)
91 or at the end (end phase).
92 Each tile is scaled and transformed in proportion to the difference between
93 its own index and continuousIndex.
94 To efficiently calculate continuousIndex, we have these values:
95 - 'gapToMiddlePhase' gap in pixels between beginning and middle phase
96 - 'gapToEndPhase' gap in pixels between middle and end phase
97 - 'kGapEnd' constant used to calculate 'continuousIndex' in end phase
98 - 'kMiddleIndex' constant used to calculate 'continuousIndex' in middle phase
99 - 'kXBeginningEnd' constant used to calculate 'continuousIndex' in beginning and end phase
100 - 'realContentWidth' the width of all the delegates only (without header/footer)
101 - 'realContentX' the 'contentX' of the listview ignoring the 'drawBuffer'
102 - 'realWidth' the 'width' of the listview, as it is used as component. */
104 readonly property real gapToMiddlePhase: Math.min(realWidth / 2 - tileWidth / 2, (realContentWidth - realWidth) / 2)
105 readonly property real gapToEndPhase: realContentWidth - realWidth - gapToMiddlePhase
106 readonly property real kGapEnd: kMiddleIndex * (1 - gapToEndPhase / gapToMiddlePhase)
107 readonly property real kMiddleIndex: (realWidth / 2) / tileWidth - 0.5
108 readonly property real kXBeginningEnd: 1 / tileWidth + kMiddleIndex / gapToMiddlePhase
109 readonly property real maximumItemTranslation: (listView.tileWidth * 3) / listView.scaleFactor
110 readonly property real disabledNewContentX: -carousel.drawBuffer - 1
111 readonly property real realContentWidth: contentWidth - 2 * carousel.drawBuffer
112 readonly property real realContentX: contentX + carousel.drawBuffer
113 readonly property real realPathItemCount: Math.min(realWidth / tileWidth, pathItemCount)
114 readonly property real realWidth: carousel.width
115 readonly property real referenceGapToMiddlePhase: realWidth / 2 - tileWidth / 2
116 readonly property real referencePathItemCount: referenceWidth / referenceTileWidth
117 readonly property real referenceWidth: 848
118 readonly property real referenceTileWidth: 175
119 readonly property real scaleFactor: tileWidth / referenceTileWidth
120 readonly property real tileWidth: Math.max(realWidth / pathItemCount, minimumTileWidth)
121 readonly property real tileHeight: tileWidth / tileAspectRatio
122 readonly property real translationXViewFactor: 0.2 * (referenceGapToMiddlePhase / gapToMiddlePhase)
123 readonly property real verticalMargin: (parent.height - tileHeight) / 2
124 readonly property real visibleTilesScaleFactor: realPathItemCount / referencePathItemCount
126 anchors {
127 fill: parent
128 topMargin: verticalMargin
129 bottomMargin: verticalMargin
130 // extending the "drawing area"
131 leftMargin: -carousel.drawBuffer
132 rightMargin: -carousel.drawBuffer
133 }
135 /* The header and footer help to "extend" the area, the listview draws items.
136 This together with anchors.leftMargin and anchors.rightMargin. */
137 header: Item {
138 width: carousel.drawBuffer
139 height: listView.tileHeight
140 }
141 footer: Item {
142 width: carousel.drawBuffer
143 height: listView.tileHeight
144 }
146 boundsBehavior: Flickable.StopAtBounds
147 cacheBuffer: carousel.cacheBuffer
148 flickDeceleration: Math.max(1500 * Math.pow(realWidth / referenceWidth, 1.5), 1500) // 1500 is platform default
149 maximumFlickVelocity: Math.max(2500 * Math.pow(realWidth / referenceWidth, 1.5), 2500) // 2500 is platform default
150 orientation: ListView.Horizontal
152 function itemClicked(index, delegateItem) {
153 listView.currentIndex = index
154 var x = CarouselJS.getXFromContinuousIndex(index,
155 realWidth,
156 realContentWidth,
157 tileWidth,
158 gapToMiddlePhase,
159 gapToEndPhase,
160 carousel.drawBuffer)
162 if (Math.abs(x - contentX) < 1 && delegateItem !== undefined) {
163 /* We're clicking the selected item and
164 we're in the neighbourhood of radius 1 pixel from it.
165 Let's emit the clicked signal. */
166 carousel.clicked(index, listView.model, delegateItem.y)
167 return
168 }
170 stepAnimation.stop()
171 newContentXAnimation.stop()
173 newContentX = x
174 newContentXAnimation.start()
175 }
177 function itemPressAndHold(index, delegateItem) {
178 var x = CarouselJS.getXFromContinuousIndex(index,
179 realWidth,
180 realContentWidth,
181 tileWidth,
182 gapToMiddlePhase,
183 gapToEndPhase,
184 carousel.drawBuffer);
186 if (Math.abs(x - contentX) < 1 && delegateItem !== undefined) {
187 /* We're pressAndHold the selected item and
188 we're in the neighbourhood of radius 1 pixel from it.
189 Let's emit the pressAndHold signal. */
190 carousel.pressAndHold(index, listView.model, delegateItem.y);
191 return;
192 }
194 stepAnimation.stop();
195 newContentXAnimation.stop();
197 newContentX = x;
198 newContentXAnimation.start();
199 }
201 onHighlightIndexChanged: {
202 if (highlightIndex != -1) {
203 itemClicked(highlightIndex)
204 }
205 }
207 onMovementStarted: {
208 stepAnimation.stop()
209 newContentXAnimation.stop()
210 newContentX = disabledNewContentX
211 }
212 onMovementEnded: {
213 if (realContentX > 0 && realContentX < realContentWidth - realWidth)
214 stepAnimation.start()
215 }
217 SmoothedAnimation {
218 id: stepAnimation
220 target: listView
221 property: "contentX"
222 to: CarouselJS.getXFromContinuousIndex(listView.selectedIndex,
223 listView.realWidth,
224 listView.realContentWidth,
225 listView.tileWidth,
226 listView.gapToMiddlePhase,
227 listView.gapToEndPhase,
228 carousel.drawBuffer)
229 duration: 450
230 velocity: 200
231 easing.type: Easing.InOutQuad
232 }
234 SequentialAnimation {
235 id: newContentXAnimation
237 NumberAnimation {
238 target: listView
239 property: "contentX"
240 from: listView.contentX
241 to: listView.newContentX
242 duration: 300
243 easing.type: Easing.InOutQuad
244 }
245 ScriptAction {
246 script: listView.newContentX = listView.disabledNewContentX
247 }
248 }
250 readonly property int selectedIndex: Math.round(continuousIndex)
251 readonly property real continuousIndex: CarouselJS.getContinuousIndex(listView.realContentX,
252 listView.tileWidth,
253 listView.gapToMiddlePhase,
254 listView.gapToEndPhase,
255 listView.kGapEnd,
256 listView.kMiddleIndex,
257 listView.kXBeginningEnd)
259 property real viewTranslation: CarouselJS.getViewTranslation(listView.realContentX,
260 listView.tileWidth,
261 listView.gapToMiddlePhase,
262 listView.gapToEndPhase,
263 listView.translationXViewFactor)
265 delegate: Loader {
266 property bool explicitlyScaled: explicitScaleFactor == carousel.selectedItemScaleFactor
267 property real explicitScaleFactor: explicitScale ? carousel.selectedItemScaleFactor : 1.0
268 readonly property bool explicitScale: (!listView.moving ||
269 listView.realContentX <= 0 ||
270 listView.realContentX >= listView.realContentWidth - listView.realWidth) &&
271 listView.newContentX === listView.disabledNewContentX &&
272 index === listView.selectedIndex
273 readonly property real cachedTiles: listView.realPathItemCount + carousel.drawBuffer / listView.tileWidth
274 readonly property real distance: listView.continuousIndex - index
275 readonly property real itemTranslationScale: CarouselJS.getItemScale(0.5,
276 (index + 0.5), // good approximation of scale while changing selected item
277 listView.count,
278 listView.visibleTilesScaleFactor)
279 readonly property real itemScale: CarouselJS.getItemScale(distance,
280 listView.continuousIndex,
281 listView.count,
282 listView.visibleTilesScaleFactor)
283 readonly property real translationX: CarouselJS.getItemTranslation(index,
284 listView.selectedIndex,
285 distance,
286 itemScale,
287 itemTranslationScale,
288 listView.maximumItemTranslation)
290 readonly property real xTransform: listView.viewTranslation + translationX * listView.scaleFactor
291 readonly property real center: x - listView.contentX + xTransform - drawBuffer + (width/2)
293 width: listView.tileWidth
294 height: listView.tileHeight
295 scale: itemScale * explicitScaleFactor
296 sourceComponent: itemComponent
297 z: cachedTiles - Math.abs(index - listView.selectedIndex)
298 opacity: highlightIndex == -1 ? 1 : (highlightIndex == index ? 0.6 : 0.2)
300 transform: Translate {
301 x: xTransform
302 }
304 Behavior on explicitScaleFactor {
305 SequentialAnimation {
306 ScriptAction {
307 script: if (!explicitScale)
308 explicitlyScaled = false
309 }
310 NumberAnimation {
311 duration: explicitScaleFactor === 1.0 ? 250 : 150
312 easing.type: Easing.InOutQuad
313 }
314 ScriptAction {
315 script: if (explicitScale)
316 explicitlyScaled = true
317 }
318 }
319 }
321 onLoaded: {
322 item.explicitlyScaled = Qt.binding(function() { return explicitlyScaled; })
323 item.model = Qt.binding(function() { return model; })
324 }
326 MouseArea {
327 id: mouseArea
329 anchors.fill: parent
331 onClicked: {
332 listView.itemClicked(index, item)
333 }
335 onPressAndHold: {
336 listView.itemPressAndHold(index, item)
337 }
339 }
340 }
341 }