@@ -18,26 +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
27+ /// The component to be used as delegate. This component has to be derived from BaseCarouselDelegate
2428 property Component itemComponent
25− property var model
26− property alias minimumTileWidth: flickable.minimumTileWidth
27− property alias pathItemCount: flickable.pathItemCount
28− property alias tileAspectRatio: flickable.tileAspectRatio
29− 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
3045 property real selectedItemScaleFactor: 1.1
3146
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
3251 signal clicked(int index, var delegateItem, real itemY)
3352
34− implicitHeight: flickable.tileHeight * selectedItemScaleFactor
53+ implicitHeight: listView.tileHeight * selectedItemScaleFactor
3554
36− /* TODO: evaluate if the component could be more efficient with a ListView,
37− 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.
3861
39− Flickable {
40− id: flickable
62+ The scaling of the items is controlled by the variable continuousIndex, described below. */
63+ ListView {
64+ id: listView
4165
4266 property real minimumTileWidth: 0
4367 property real newContentX: -1
@@ -57,20 +81,27 @@ Item {
5781 - 'gapToEndPhase' gap in pixels between middle and end phase
5882 - 'kGapEnd' constant used to calculate 'continuousIndex' in end phase
5983 - 'kMiddleIndex' constant used to calculate 'continuousIndex' in middle phase
60− - '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. */
6188
62− readonly property real gapToMiddlePhase: Math.min(width / 2 - tileWidth / 2, (contentWidth - width) / 2)
63− 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
6491 readonly property real kGapEnd: kMiddleIndex * (1 - gapToEndPhase / gapToMiddlePhase)
65− readonly property real kMiddleIndex: (width / 2) / tileWidth - 0.5
92+ readonly property real kMiddleIndex: (realWidth / 2) / tileWidth - 0.5
6693 readonly property real kXBeginningEnd: 1 / tileWidth + kMiddleIndex / gapToMiddlePhase
67− readonly property real realPathItemCount: Math.min(width / tileWidth, pathItemCount)
68− 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
69100 readonly property real referencePathItemCount: referenceWidth / referenceTileWidth
70101 readonly property real referenceWidth: 848
71102 readonly property real referenceTileWidth: 175
72103 readonly property real scaleFactor: tileWidth / referenceTileWidth
73− readonly property real tileWidth: Math.max(width / pathItemCount, minimumTileWidth)
104+ readonly property real tileWidth: Math.max(realWidth / pathItemCount, minimumTileWidth)
74105 readonly property real tileHeight: tileWidth / tileAspectRatio
75106 readonly property real translationXViewFactor: 0.2 * (referenceGapToMiddlePhase / gapToMiddlePhase)
76107 readonly property real verticalMargin: (parent.height - tileHeight) / 2
@@ -80,20 +111,36 @@ Item {
80111 fill: parent
81112 topMargin: verticalMargin
82113 bottomMargin: verticalMargin
114+ // extending the "drawing area"
115+ leftMargin: -carousel.drawBuffer
116+ rightMargin: -carousel.drawBuffer
83117 }
84− contentWidth: view.width
85− 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+
86130 boundsBehavior: Flickable.StopAtBounds
87− flickDeceleration: Math.max(1500 * Math.pow(width / referenceWidth, 1.5), 1500) // 1500 is platform default
88− 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
89135
90136 function itemClicked(index, delegateItem) {
91137 var x = CarouselJS.getXFromContinuousIndex(index,
92− width,
93− contentWidth,
138+ realWidth,
139+ realContentWidth,
94140 tileWidth,
95141 gapToMiddlePhase,
96− gapToEndPhase)
142+ gapToEndPhase,
143+ carousel.drawBuffer)
97144
98145 if (Math.abs(x - contentX) < 1) {
99146 /* We're clicking the selected item and
@@ -116,22 +163,22 @@ Item {
116163 newContentX = -1
117164 }
118165 onMovementEnded: {
119− if (contentX > 0 && contentX < contentWidth - width)
166+ if (realContentX > 0 && realContentX < realContentWidth - realWidth)
120167 stepAnimation.start()
121168 }
122169
123170 SmoothedAnimation {
124171 id: stepAnimation
125172
126− target: flickable
173+ target: listView
127174 property: "contentX"
128− from: flickable.contentX
129− to: CarouselJS.getXFromContinuousIndex(view.selectedIndex,
130− flickable.width,
131− flickable.contentWidth,
132− flickable.tileWidth,
133− flickable.gapToMiddlePhase,
134− 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)
135182 duration: 450
136183 velocity: 200
137184 easing.type: Easing.InOutQuad
@@ -141,112 +188,96 @@ Item {
141188 id: newContentXAnimation
142189
143190 NumberAnimation {
144− target: flickable
191+ target: listView
145192 property: "contentX"
146− from: flickable.contentX
147− to: flickable.newContentX
193+ from: listView.contentX
194+ to: listView.newContentX
148195 duration: 300
149196 easing.type: Easing.InOutQuad
150197 }
151198 ScriptAction {
152− script: flickable.newContentX = -1
199+ script: listView.newContentX = -1
153200 }
154201 }
155202
156− Row {
157− id: view
158−
159− readonly property int selectedIndex: Math.round(continuousIndex)
160− readonly property real continuousIndex: CarouselJS.getContinuousIndex(flickable.contentX,
161− flickable.tileWidth,
162− flickable.gapToMiddlePhase,
163− flickable.gapToEndPhase,
164− flickable.kGapEnd,
165− flickable.kMiddleIndex,
166− flickable.kXBeginningEnd)
167−
168− height: parent.height
169− 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)
170248
171249 transform: Translate {
172− x: CarouselJS.getViewTranslation(flickable.contentX,
173− flickable.tileWidth,
174− flickable.gapToMiddlePhase,
175− flickable.gapToEndPhase,
176− flickable.translationXViewFactor)
250+ x: listView.viewTranslation + translationX * listView.scaleFactor
177251 }
178252
179− Repeater {
180− id: repeater
181−
182− model: carousel.model
183−
184− Loader {
185− property bool explicitlyScaled: explicitScaleFactor == carousel.selectedItemScaleFactor
186− property real explicitScaleFactor: explicitScale ? carousel.selectedItemScaleFactor : 1.0
187− readonly property bool explicitScale: (!flickable.moving ||
188− flickable.contentX <= 0 ||
189− flickable.contentX >= flickable.contentWidth - flickable.width) &&
190− flickable.newContentX < 0 &&
191− index === view.selectedIndex
192− readonly property real cachedTiles: flickable.realPathItemCount + carousel.cacheBuffer / flickable.tileWidth
193− readonly property real distance: view.continuousIndex - index
194− readonly property real itemTranslationScale: CarouselJS.getItemScale(0.5,
195− (index + 0.5), // good approximation of scale while changing selected item
196− repeater.count,
197− flickable.visibleTilesScaleFactor)
198− readonly property real itemScale: CarouselJS.getItemScale(distance,
199− view.continuousIndex,
200− repeater.count,
201− flickable.visibleTilesScaleFactor)
202− readonly property real translationFactor: (flickable.tileWidth * 3) / flickable.scaleFactor
203− readonly property real translationX: index === view.selectedIndex ? 0 :
204− CarouselJS.getItemTranslation(distance,
205− itemScale,
206− itemTranslationScale,
207− translationFactor)
208−
209− width: flickable.tileWidth
210− height: flickable.tileHeight
211− scale: itemScale * explicitScaleFactor
212− opacity: scale > 0.02 ? 1 : 0
213− sourceComponent: z > 0 ? itemComponent : undefined
214− z: cachedTiles - Math.abs(index - view.selectedIndex)
215−
216− transform: Translate {
217− x: translationX * flickable.scaleFactor
253+ Behavior on explicitScaleFactor {
254+ SequentialAnimation {
255+ ScriptAction {
256+ script: if (!explicitScale)
257+ explicitlyScaled = false
218258 }
219−
220− Behavior on explicitScaleFactor {
221− SequentialAnimation {
222− ScriptAction {
223− script: if (!explicitScale)
224− explicitlyScaled = false
225− }
226− NumberAnimation {
227− duration: explicitScaleFactor === 1.0 ? 250 : 150
228− easing.type: Easing.InOutQuad
229− }
230− ScriptAction {
231− script: if (explicitScale)
232− explicitlyScaled = true
233− }
234− }
259+ NumberAnimation {
260+ duration: explicitScaleFactor === 1.0 ? 250 : 150
261+ easing.type: Easing.InOutQuad
235262 }
236−
237− onLoaded: {
238− item.explicitlyScaled = Qt.binding(function() { return explicitlyScaled; })
239− item.model = Qt.binding(function() { return model; })
263+ ScriptAction {
264+ script: if (explicitScale)
265+ explicitlyScaled = true
240266 }
267+ }
268+ }
241269
242− MouseArea {
243− id: mouseArea
270+ onLoaded: {
271+ item.explicitlyScaled = Qt.binding(function() { return explicitlyScaled; })
272+ item.model = Qt.binding(function() { return model; })
273+ }
244274
245− anchors.fill: parent
275+ MouseArea {
276+ id: mouseArea
246277
247− onClicked: flickable.itemClicked(index, item)
248− }
249− }
278+ anchors.fill: parent
279+
280+ onClicked: listView.itemClicked(index, item)
250281 }
251282 }
252283 }