@@ -18,27 +18,50 @@ import QtQuick 2.0
1818import Ubuntu.Components 0.1
1919import "carousel.js" as CarouselJS
2020
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+ */
2124Item {
2225 id: carousel
2326
24− clip: true // FIXME ?
27+ /// The component to be used as delegate. This component has to be derived from BaseCarouselDelegate
2528 property Component itemComponent
26− property var model
27− property alias minimumTileWidth: flickable.minimumTileWidth
28− property alias pathItemCount: flickable.pathItemCount
29− property alias tileAspectRatio: flickable.tileAspectRatio
30− property int cacheBuffer: 0
29+ /// Model for the Carousel, which has to be a model usable by a ListView
30+ property alias model: listView.model
31+ /// A minimal width of a tile can be set here. Per default a best fit will be calculated
32+ property alias minimumTileWidth: listView.minimumTileWidth
33+ /// Sets the number of tiles that are visible
34+ property alias pathItemCount: listView.pathItemCount
35+ /// Aspect ratio of the tiles width/height
36+ property alias tileAspectRatio: listView.tileAspectRatio
37+ /// Used to cache some delegates for performance reasons. See the ListView documentation for details
38+ property alias cacheBuffer: listView.cacheBuffer
39+ /// Width of the "draw buffer" in pixel. The drawBuffer is an additional area at start/end where
40+ /// items drawn, even if it is not in the visible area.
41+ /// cacheBuffer controls only the to retain delegates outside the visible area (and is used on top of the drawBuffer)
42+ /// see https://bugreports.qt-project.org/browse/QTBUG-29173
43+ property int drawBuffer: width / pathItemCount // an "ok" value - but values used from the listView cause loops
44+ /// The selected item can be shown in a different size controlled by selectedItemScaleFactor
3145 property real selectedItemScaleFactor: 1.1
3246
47+ /// Emitted when the user clicked on an item
48+ /// @param index is the index of the clicked item
49+ /// @param delegateItem is the clicked component/delegate itself
50+ /// @param itemY is y of the clicked delegate
3351 signal clicked(int index, var delegateItem, real itemY)
3452
35− implicitHeight: flickable.tileHeight * selectedItemScaleFactor
53+ implicitHeight: listView.tileHeight * selectedItemScaleFactor
3654
37− /* TODO: evaluate if the component could be more efficient with a ListView,
38− using this technique https://bugreports.qt-project.org/browse/QTBUG-29173 */
55+ /* Basic idea behind the carousel effect is to move the items of the delegates (compacting /stuffing them).
56+ One drawback is, that more delegates have to be drawn than usually. As some items are moved from the
57+ invisible to the visible area. Setting the cacheBuffer does not fix this.
58+ See https://bugreports.qt-project.org/browse/QTBUG-29173
59+ Therefore the ListView has negative left and right anchors margins, and in addition a header
60+ and footer item to compensate that.
3961
40− Flickable {
41− id: flickable
62+ The scaling of the items is controlled by the variable continuousIndex, described below. */
63+ ListView {
64+ id: listView
4265
4366 property real minimumTileWidth: 0
4467 property real newContentX: -1
@@ -58,20 +81,27 @@ Item {
5881 - 'gapToEndPhase' gap in pixels between middle and end phase
5982 - 'kGapEnd' constant used to calculate 'continuousIndex' in end phase
6083 - 'kMiddleIndex' constant used to calculate 'continuousIndex' in middle phase
61− - 'kXBeginningEnd' constant used to calculate 'continuousIndex' in beginning and end phase. */
84+ - 'kXBeginningEnd' constant used to calculate 'continuousIndex' in beginning and end phase
85+ - 'realContentWidth' the width of all the delegates only (without header/footer)
86+ - 'realContentX' the 'contentX' of the listview ignoring the 'drawBuffer'
87+ - 'realWidth' the 'width' of the listview, as it is used as component. */
6288
63− readonly property real gapToMiddlePhase: Math.min(width / 2 - tileWidth / 2, (contentWidth - width) / 2)
64− readonly property real gapToEndPhase: contentWidth - width - gapToMiddlePhase
89+ readonly property real gapToMiddlePhase: Math.min(realWidth / 2 - tileWidth / 2, (realContentWidth - realWidth) / 2)
90+ readonly property real gapToEndPhase: realContentWidth - realWidth - gapToMiddlePhase
6591 readonly property real kGapEnd: kMiddleIndex * (1 - gapToEndPhase / gapToMiddlePhase)
66− readonly property real kMiddleIndex: (width / 2) / tileWidth - 0.5
92+ readonly property real kMiddleIndex: (realWidth / 2) / tileWidth - 0.5
6793 readonly property real kXBeginningEnd: 1 / tileWidth + kMiddleIndex / gapToMiddlePhase
68− readonly property real realPathItemCount: Math.min(width / tileWidth, pathItemCount)
69− readonly property real referenceGapToMiddlePhase: width / 2 - tileWidth / 2
94+ readonly property real maximumItemTranslation: (listView.tileWidth * 3) / listView.scaleFactor
95+ readonly property real realContentWidth: contentWidth - 2 * carousel.drawBuffer
96+ readonly property real realContentX: contentX + carousel.drawBuffer
97+ readonly property real realPathItemCount: Math.min(realWidth / tileWidth, pathItemCount)
98+ readonly property real realWidth: carousel.width
99+ readonly property real referenceGapToMiddlePhase: realWidth / 2 - tileWidth / 2
70100 readonly property real referencePathItemCount: referenceWidth / referenceTileWidth
71101 readonly property real referenceWidth: 848
72102 readonly property real referenceTileWidth: 175
73103 readonly property real scaleFactor: tileWidth / referenceTileWidth
74− readonly property real tileWidth: Math.max(width / pathItemCount, minimumTileWidth)
104+ readonly property real tileWidth: Math.max(realWidth / pathItemCount, minimumTileWidth)
75105 readonly property real tileHeight: tileWidth / tileAspectRatio
76106 readonly property real translationXViewFactor: 0.2 * (referenceGapToMiddlePhase / gapToMiddlePhase)
77107 readonly property real verticalMargin: (parent.height - tileHeight) / 2
@@ -81,20 +111,36 @@ Item {
81111 fill: parent
82112 topMargin: verticalMargin
83113 bottomMargin: verticalMargin
114+ // extending the "drawing area"
115+ leftMargin: -carousel.drawBuffer
116+ rightMargin: -carousel.drawBuffer
84117 }
85− contentWidth: view.width
86− contentHeight: height
118+
119+ /* The header and footer help to "extend" the area, the listview draws items.
120+ This together with anchors.leftMargin and anchors.rightMargin. */
121+ header: Item {
122+ width: carousel.drawBuffer
123+ height: listView.tileHeight
124+ }
125+ footer: Item {
126+ width: carousel.drawBuffer
127+ height: listView.tileHeight
128+ }
129+
87130 boundsBehavior: Flickable.StopAtBounds
88− flickDeceleration: Math.max(1500 * Math.pow(width / referenceWidth, 1.5), 1500) // 1500 is platform default
89− maximumFlickVelocity: Math.max(2500 * Math.pow(width / referenceWidth, 1.5), 2500) // 2500 is platform default
131+ cacheBuffer: carousel.cacheBuffer
132+ flickDeceleration: Math.max(1500 * Math.pow(realWidth / referenceWidth, 1.5), 1500) // 1500 is platform default
133+ maximumFlickVelocity: Math.max(2500 * Math.pow(realWidth / referenceWidth, 1.5), 2500) // 2500 is platform default
134+ orientation: ListView.Horizontal
90135
91136 function itemClicked(index, delegateItem) {
92137 var x = CarouselJS.getXFromContinuousIndex(index,
93− width,
94− contentWidth,
138+ realWidth,
139+ realContentWidth,
95140 tileWidth,
96141 gapToMiddlePhase,
97− gapToEndPhase)
142+ gapToEndPhase,
143+ carousel.drawBuffer)
98144
99145 if (Math.abs(x - contentX) < 1) {
100146 /* We're clicking the selected item and
@@ -117,22 +163,22 @@ Item {
117163 newContentX = -1
118164 }
119165 onMovementEnded: {
120− if (contentX > 0 && contentX < contentWidth - width)
166+ if (realContentX > 0 && realContentX < realContentWidth - realWidth)
121167 stepAnimation.start()
122168 }
123169
124170 SmoothedAnimation {
125171 id: stepAnimation
126172
127− target: flickable
173+ target: listView
128174 property: "contentX"
129− from: flickable.contentX
130− to: CarouselJS.getXFromContinuousIndex(view.selectedIndex,
131− flickable.width,
132− flickable.contentWidth,
133− flickable.tileWidth,
134− flickable.gapToMiddlePhase,
135− flickable.gapToEndPhase)
175+ to: CarouselJS.getXFromContinuousIndex(listView.selectedIndex,
176+ listView.realWidth,
177+ listView.realContentWidth,
178+ listView.tileWidth,
179+ listView.gapToMiddlePhase,
180+ listView.gapToEndPhase,
181+ carousel.drawBuffer)
136182 duration: 450
137183 velocity: 200
138184 easing.type: Easing.InOutQuad
@@ -142,112 +188,96 @@ Item {
142188 id: newContentXAnimation
143189
144190 NumberAnimation {
145− target: flickable
191+ target: listView
146192 property: "contentX"
147− from: flickable.contentX
148− to: flickable.newContentX
193+ from: listView.contentX
194+ to: listView.newContentX
149195 duration: 300
150196 easing.type: Easing.InOutQuad
151197 }
152198 ScriptAction {
153− script: flickable.newContentX = -1
199+ script: listView.newContentX = -1
154200 }
155201 }
156202
157− Row {
158− id: view
159−
160− readonly property int selectedIndex: Math.round(continuousIndex)
161− readonly property real continuousIndex: CarouselJS.getContinuousIndex(flickable.contentX,
162− flickable.tileWidth,
163− flickable.gapToMiddlePhase,
164− flickable.gapToEndPhase,
165− flickable.kGapEnd,
166− flickable.kMiddleIndex,
167− flickable.kXBeginningEnd)
168−
169− height: parent.height
170− anchors.verticalCenter: parent.verticalCenter
203+ readonly property int selectedIndex: Math.round(continuousIndex)
204+ readonly property real continuousIndex: CarouselJS.getContinuousIndex(listView.realContentX,
205+ listView.tileWidth,
206+ listView.gapToMiddlePhase,
207+ listView.gapToEndPhase,
208+ listView.kGapEnd,
209+ listView.kMiddleIndex,
210+ listView.kXBeginningEnd)
211+
212+ property real viewTranslation: CarouselJS.getViewTranslation(listView.realContentX,
213+ listView.tileWidth,
214+ listView.gapToMiddlePhase,
215+ listView.gapToEndPhase,
216+ listView.translationXViewFactor)
217+
218+ delegate: Loader {
219+ property bool explicitlyScaled: explicitScaleFactor == carousel.selectedItemScaleFactor
220+ property real explicitScaleFactor: explicitScale ? carousel.selectedItemScaleFactor : 1.0
221+ readonly property bool explicitScale: (!listView.moving ||
222+ listView.realContentX <= 0 ||
223+ listView.realContentX >= listView.realContentWidth - listView.realWidth) &&
224+ listView.newContentX < 0 &&
225+ index === listView.selectedIndex
226+ readonly property real cachedTiles: listView.realPathItemCount + carousel.drawBuffer / listView.tileWidth
227+ readonly property real distance: listView.continuousIndex - index
228+ readonly property real itemTranslationScale: CarouselJS.getItemScale(0.5,
229+ (index + 0.5), // good approximation of scale while changing selected item
230+ listView.count,
231+ listView.visibleTilesScaleFactor)
232+ readonly property real itemScale: CarouselJS.getItemScale(distance,
233+ listView.continuousIndex,
234+ listView.count,
235+ listView.visibleTilesScaleFactor)
236+ readonly property real translationX: CarouselJS.getItemTranslation(index,
237+ listView.selectedIndex,
238+ distance,
239+ itemScale,
240+ itemTranslationScale,
241+ listView.maximumItemTranslation)
242+
243+ width: listView.tileWidth
244+ height: listView.tileHeight
245+ scale: itemScale * explicitScaleFactor
246+ sourceComponent: itemComponent
247+ z: cachedTiles - Math.abs(index - listView.selectedIndex)
171248
172249 transform: Translate {
173− x: CarouselJS.getViewTranslation(flickable.contentX,
174− flickable.tileWidth,
175− flickable.gapToMiddlePhase,
176− flickable.gapToEndPhase,
177− flickable.translationXViewFactor)
250+ x: listView.viewTranslation + translationX * listView.scaleFactor
178251 }
179252
180− Repeater {
181− id: repeater
182−
183− model: carousel.model
184−
185− Loader {
186− property bool explicitlyScaled: explicitScaleFactor == carousel.selectedItemScaleFactor
187− property real explicitScaleFactor: explicitScale ? carousel.selectedItemScaleFactor : 1.0
188− readonly property bool explicitScale: (!flickable.moving ||
189− flickable.contentX <= 0 ||
190− flickable.contentX >= flickable.contentWidth - flickable.width) &&
191− flickable.newContentX < 0 &&
192− index === view.selectedIndex
193− readonly property real cachedTiles: flickable.realPathItemCount + carousel.cacheBuffer / flickable.tileWidth
194− readonly property real distance: view.continuousIndex - index
195− readonly property real itemTranslationScale: CarouselJS.getItemScale(0.5,
196− (index + 0.5), // good approximation of scale while changing selected item
197− repeater.count,
198− flickable.visibleTilesScaleFactor)
199− readonly property real itemScale: CarouselJS.getItemScale(distance,
200− view.continuousIndex,
201− repeater.count,
202− flickable.visibleTilesScaleFactor)
203− readonly property real translationFactor: (flickable.tileWidth * 3) / flickable.scaleFactor
204− readonly property real translationX: index === view.selectedIndex ? 0 :
205− CarouselJS.getItemTranslation(distance,
206− itemScale,
207− itemTranslationScale,
208− translationFactor)
209−
210− width: flickable.tileWidth
211− height: flickable.tileHeight
212− scale: itemScale * explicitScaleFactor
213− opacity: scale > 0.02 ? 1 : 0
214− sourceComponent: z > 0 ? itemComponent : undefined
215− z: cachedTiles - Math.abs(index - view.selectedIndex)
216−
217− transform: Translate {
218− x: translationX * flickable.scaleFactor
253+ Behavior on explicitScaleFactor {
254+ SequentialAnimation {
255+ ScriptAction {
256+ script: if (!explicitScale)
257+ explicitlyScaled = false
219258 }
220−
221− Behavior on explicitScaleFactor {
222− SequentialAnimation {
223− ScriptAction {
224− script: if (!explicitScale)
225− explicitlyScaled = false
226− }
227− NumberAnimation {
228− duration: explicitScaleFactor === 1.0 ? 250 : 150
229− easing.type: Easing.InOutQuad
230− }
231− ScriptAction {
232− script: if (explicitScale)
233− explicitlyScaled = true
234− }
235− }
259+ NumberAnimation {
260+ duration: explicitScaleFactor === 1.0 ? 250 : 150
261+ easing.type: Easing.InOutQuad
236262 }
237−
238− onLoaded: {
239− item.explicitlyScaled = Qt.binding(function() { return explicitlyScaled; })
240− item.model = Qt.binding(function() { return model; })
263+ ScriptAction {
264+ script: if (explicitScale)
265+ explicitlyScaled = true
241266 }
267+ }
268+ }
242269
243− MouseArea {
244− id: mouseArea
270+ onLoaded: {
271+ item.explicitlyScaled = Qt.binding(function() { return explicitlyScaled; })
272+ item.model = Qt.binding(function() { return model; })
273+ }
245274
246− anchors.fill: parent
275+ MouseArea {
276+ id: mouseArea
247277
248− onClicked: flickable.itemClicked(index, item)
249− }
250− }
278+ anchors.fill: parent
279+
280+ onClicked: listView.itemClicked(index, item)
251281 }
252282 }
253283 }