Merge lp:~ahayzen/music-app/remix-rewrite-column-flow into lp:music-app/remix

[Andrew Hayzen]

* Rewrite the ColumnFlow.qml to use incubation to create objects and set offscreen cards as invisible

* Rewrite the ColumnFlow.qml to use incubation to create objects and set offscreen cards as invisible

This is a *complete* rewrite of the ColumnFlow, please test all instances of the CardView.

[Ubuntu Phone Apps Jenkins Bot (ubuntu-phone-apps-jenkins-bot)]

PASSED: Continuous integration, rev:730
http://91.189.93.70:8080/job/music-app-remix-ci/240/
Executed test runs:
    SUCCESS: http://91.189.93.70:8080/job/generic-mediumtests-vivid/127
        deb: http://91.189.93.70:8080/job/generic-mediumtests-vivid/127/artifact/work/output/*zip*/output.zip
    SUCCESS: http://91.189.93.70:8080/job/music-app-remix-vivid-amd64-ci/15

Click here to trigger a rebuild:
http://91.189.93.70:8080/job/music-app-remix-ci/240/rebuild

review: Approve (continuous-integration)

[Ubuntu Phone Apps Jenkins Bot (ubuntu-phone-apps-jenkins-bot)]

PASSED: Continuous integration, rev:731
http://91.189.93.70:8080/job/music-app-remix-ci/241/
Executed test runs:
    SUCCESS: http://91.189.93.70:8080/job/generic-mediumtests-vivid/129
        deb: http://91.189.93.70:8080/job/generic-mediumtests-vivid/129/artifact/work/output/*zip*/output.zip
    SUCCESS: http://91.189.93.70:8080/job/music-app-remix-vivid-amd64-ci/16

Click here to trigger a rebuild:
http://91.189.93.70:8080/job/music-app-remix-ci/241/rebuild

review: Approve (continuous-integration)

[Ubuntu Phone Apps Jenkins Bot (ubuntu-phone-apps-jenkins-bot)]

PASSED: Continuous integration, rev:732
http://91.189.93.70:8080/job/music-app-remix-ci/243/
Executed test runs:
    SUCCESS: http://91.189.93.70:8080/job/generic-mediumtests-vivid/133
        deb: http://91.189.93.70:8080/job/generic-mediumtests-vivid/133/artifact/work/output/*zip*/output.zip
    SUCCESS: http://91.189.93.70:8080/job/music-app-remix-vivid-amd64-ci/18

Click here to trigger a rebuild:
http://91.189.93.70:8080/job/music-app-remix-ci/243/rebuild

review: Approve (continuous-integration)

[Ubuntu Phone Apps Jenkins Bot (ubuntu-phone-apps-jenkins-bot)]

PASSED: Continuous integration, rev:733
http://91.189.93.70:8080/job/music-app-remix-ci/244/
Executed test runs:
    SUCCESS: http://91.189.93.70:8080/job/generic-mediumtests-vivid/134
        deb: http://91.189.93.70:8080/job/generic-mediumtests-vivid/134/artifact/work/output/*zip*/output.zip
    SUCCESS: http://91.189.93.70:8080/job/music-app-remix-vivid-amd64-ci/19

Click here to trigger a rebuild:
http://91.189.93.70:8080/job/music-app-remix-ci/244/rebuild

review: Approve (continuous-integration)

[Victor Thompson (vthompson)]

2 inline comments so far.

Also, I've managed to get the Artist tab to do some bad things.

1. I've gotten this: http://i.imgur.com/qXAAxgb.png
2. Flicking downward in the Artists tab is initially "sticky". If you flick, it will stop quickly when it gets to the end of the currently loaded items.
3. I can cause the app to crash very easily in the Artists tab by over scrolling

review: Needs Fixing

[Andrew Hayzen (ahayzen)]

So we are going to investigate setting visible to false rather than destroying the old objects.

This should:
* Stop the thumbnails from reloading after they are destroyed
* Allow for easier implementation of adding/removing columns
* Still maintain the reduced time to initially load the thumbnails
* Simplify the code and reduce chances of corruption

[Andrew Hayzen (ahayzen)]

I've rewritten the component so that it incubates the objects as you scroll (meaning the thumbnails appear as fast as possible). Any cards that go out of the viewport are then set invisible to allow for increased performance. Resizing the window doesn't destroy the 'live' cards and instead reanchors them to their new positions so you get an animation.

Please rereview :)

[Victor Thompson (vthompson)]

Functionally I think this works really well. The code is looking good thus far--I have 2 minor inline comments.

Small typo, "Force any"

review: Needs Fixing

[Ubuntu Phone Apps Jenkins Bot (ubuntu-phone-apps-jenkins-bot)]

FAILED: Continuous integration, rev:737
http://91.189.93.70:8080/job/music-app-remix-ci/248/
Executed test runs:
    UNSTABLE: http://91.189.93.70:8080/job/generic-mediumtests-vivid/157
        deb: http://91.189.93.70:8080/job/generic-mediumtests-vivid/157/artifact/work/output/*zip*/output.zip
    SUCCESS: http://91.189.93.70:8080/job/music-app-remix-vivid-amd64-ci/23

Click here to trigger a rebuild:
http://91.189.93.70:8080/job/music-app-remix-ci/248/rebuild

review: Needs Fixing (continuous-integration)

[lp:~ahayzen/music-app/remix-rewrite-column-flow]

738. By Andrew Hayzen on 2014-11-11

* Fix for abstraction

[Ubuntu Phone Apps Jenkins Bot (ubuntu-phone-apps-jenkins-bot)]

PASSED: Continuous integration, rev:738
http://91.189.93.70:8080/job/music-app-remix-ci/250/
Executed test runs:
    SUCCESS: http://91.189.93.70:8080/job/generic-mediumtests-vivid/159
        deb: http://91.189.93.70:8080/job/generic-mediumtests-vivid/159/artifact/work/output/*zip*/output.zip
    SUCCESS: http://91.189.93.70:8080/job/music-app-remix-vivid-amd64-ci/25

Click here to trigger a rebuild:
http://91.189.93.70:8080/job/music-app-remix-ci/250/rebuild

review: Approve (continuous-integration)

[Victor Thompson (vthompson)]

LGTM! This makes the card views pretty snappy! :)

review: Approve

=== modified file 'MusicArtists.qml'
--- MusicArtists.qml	2014-11-01 23:25:42 +0000
+++ MusicArtists.qml	2014-11-11 20:14:18 +0000
@@ -23,7 +23,6 @@
 import Ubuntu.Components.ListItems 1.0 as ListItem
 import Ubuntu.MediaScanner 0.1
 import Ubuntu.Thumbnailer 0.1
-import QtMultimedia 5.0
 import QtQuick.LocalStorage 2.0
 import "meta-database.js" as Library
 import "playlists.js" as Playlists
@@ -37,6 +36,7 @@
 
     CardView {
         id: artistCardView
+        getter: function (i) { return {"artist": artistsModel.get(i, ArtistsModel.RoleArtist)}; }
         itemWidth: units.gu(12)
         model: ArtistsModel {
             id: artistsModel

=== modified file 'MusicPlaylists.qml'
--- MusicPlaylists.qml	2014-10-26 16:18:12 +0000
+++ MusicPlaylists.qml	2014-11-11 20:14:18 +0000
@@ -68,12 +68,12 @@
         objectName: "playlistsCardView"
         delegate: Card {
             id: playlistCard
-            coverSources: Playlists.getPlaylistCovers(name)
-            primaryText: name
-            secondaryText: i18n.tr("%1 song", "%1 songs", count).arg(count)
+            coverSources: Playlists.getPlaylistCovers(model.name)
+            primaryText: model.name
+            secondaryText: i18n.tr("%1 song", "%1 songs", model.count).arg(model.count)
 
             onClicked: {
-                albumTracksModel.filterPlaylistTracks(name)
+                albumTracksModel.filterPlaylistTracks(model.name)
 
                 var comp = Qt.createComponent("common/SongsPage.qml")
                 var songsPage = comp.createObject(mainPageStack,

=== modified file 'MusicStart.qml'
--- MusicStart.qml	2014-11-01 23:25:42 +0000
+++ MusicStart.qml	2014-11-11 20:14:18 +0000
@@ -79,7 +79,7 @@
             secondaryText: model.type === "playlist" ? i18n.tr("Playlist") : (recentAlbumSongs.status === SongsModel.Ready && recentAlbumSongs.get(0, SongsModel.RoleModelData).author != "" ? recentAlbumSongs.get(0, SongsModel.RoleModelData).author : i18n.tr("Unknown Artist"))
 
             onClicked: {
-                if (type === "playlist") {
+                if (model.type === "playlist") {
                     albumTracksModel.filterPlaylistTracks(model.data)
                 }
 

=== modified file 'common/AlbumsPage.qml'
--- common/AlbumsPage.qml	2014-11-01 23:25:42 +0000
+++ common/AlbumsPage.qml	2014-11-11 20:14:18 +0000
@@ -39,6 +39,13 @@
         anchors {
             fill: parent
         }
+        getter: function (i) {
+            return {
+                "art": artistsModel.get(i, AlbumsModel.RoleArt),
+                "artist": artistsModel.get(i, AlbumsModel.RoleArtist),
+                "title": artistsModel.get(i, AlbumsModel.RoleTitle),
+            };
+        }
         header: BlurredHeader {
             rightColumn: Column {
                 spacing: units.gu(2)

=== modified file 'common/BlurredHeader.qml'
--- common/BlurredHeader.qml	2014-10-22 15:40:36 +0000
+++ common/BlurredHeader.qml	2014-11-11 20:14:18 +0000
@@ -54,7 +54,6 @@
             left: coversImage.right
             leftMargin: units.gu(2)
         }
-        asynchronous: true
     }
 
     Loader {
@@ -66,6 +65,5 @@
             top: coversImage.bottom
             topMargin: units.gu(1)
         }
-        asynchronous: true
     }
 }

=== modified file 'common/Card.qml'
--- common/Card.qml	2014-10-21 20:11:35 +0000
+++ common/Card.qml	2014-11-11 20:14:18 +0000
@@ -23,6 +23,10 @@
     id: card
     height: cardColumn.childrenRect.height + 2 * bg.anchors.margins
 
+    /* Required by ColumnFlow */
+    property int index
+    property var model
+
     property alias coverSources: coverGrid.covers
     property alias primaryText: primaryLabel.text
     property alias secondaryText: secondaryLabel.text

=== modified file 'common/CardView.qml'
--- common/CardView.qml	2014-10-28 03:32:01 +0000
+++ common/CardView.qml	2014-11-11 20:14:18 +0000
@@ -20,21 +20,25 @@
 
 
 Flickable {
+    id: cardViewFlickable
     anchors {
         fill: parent
     }
 
     // dont use flow.contentHeight as it is inaccurate due to height of labels
     // changing as they load
-    contentHeight: headerLoader.childrenRect.height + flowContainer.height
+    contentHeight: headerLoader.childrenRect.height + flow.contentHeight + flowContainer.anchors.margins * 2
     contentWidth: width
 
     property alias count: flow.count
     property alias delegate: flow.delegate
+    property var getter
     property alias header: headerLoader.sourceComponent
     property var model: flow.model
     property real itemWidth: units.gu(15)
 
+    onGetterChanged: flow.getter = getter  // cannot use alias to set a function (must be var)
+
     onVisibleChanged: {
         if (visible) {  // only load model once CardView is visible
             flow.model = model
@@ -43,7 +47,6 @@
 
     Loader {
         id: headerLoader
-        asynchronous: true
         visible: sourceComponent !== undefined
         width: parent.width
     }
@@ -51,18 +54,21 @@
     Item {
         id: flowContainer
         anchors {
+            bottom: parent.bottom
+            left: parent.left
+            margins: units.gu(1)
+            right: parent.right
             top: headerLoader.bottom
         }
-        height: flow.childrenRect.height + flow.anchors.margins * 2
         width: parent.width
 
         ColumnFlow {
             id: flow
             anchors {
                 fill: parent
-                margins: units.gu(1)
             }
-            columns: parseInt(width / itemWidth)
+            columns: parseInt(cardViewFlickable.width / itemWidth)
+            flickable: cardViewFlickable
         }
     }
 

=== modified file 'common/ColumnFlow.qml'
--- common/ColumnFlow.qml	2014-10-13 16:56:55 +0000
+++ common/ColumnFlow.qml	2014-11-11 20:14:18 +0000
@@ -1,7 +1,6 @@
 /*
  * Copyright (C) 2014
  *      Andrew Hayzen <[e-mail]>
- *      Michael Spencer <[e-mail]>
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -14,147 +13,398 @@
  *
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- *
- * Upstream location:
- * https://github.com/iBeliever/ubuntu-ui-extras/blob/master/ColumnFlow.qml
  */
 
 import QtQuick 2.3
 
-
 Item {
     id: columnFlow
     property int columns: 1
-    property bool repeaterCompleted: false
-    property alias count: repeater.count
-    property alias model: repeater.model
-    property alias delegate: repeater.delegate
+    property Flickable flickable
+    property var model
+    property Component delegate
+
+    property var getter: function (i) { return model.get(i); }  // optional getter override (useful for music-app ms2 models)
+
+    property int buffer: units.gu(20)
+    property var columnHeights: []
+    property var columnHeightsMax: []
+    property int columnWidth: parent.width / columns
     property int contentHeight: 0
-
-    onColumnsChanged: reEvalColumns()
-    onModelChanged: reEvalColumns()
-    onWidthChanged: updateWidths()
-
-    function updateWidths() {
-        if (repeaterCompleted) {
-            var count = 0
-
-            //add the first <column> elements
-            for (var i = 0; count < columns && i < columnFlow.children.length; i++) {
-                //print(i, count)
-                if (!columnFlow.children[i] || String(columnFlow.children[i]).indexOf("QQuickRepeater") == 0)
-                        //|| !columnFlow.children[i].visible)  // CUSTOM - view is invisible at start
-                    continue
-
-                columnFlow.children[i].width = width / columns
-
-                count++
-            }
-        }
-    }
-
-    function reEvalColumns() {
-        if (columnFlow.repeaterCompleted === false)
-            return
-
-        if (columns === 0) {
-            contentHeight = 0
-            return
-        }
-
-        var i, j
-        var columnHeights = new Array(columns);
-        var lastItem = new Array(columns)
-        var lastI = -1
-        var count = 0
-
-        //add the first <column> elements
-        for (i = 0; count < columns && i < columnFlow.children.length; i++) {
-            // CUSTOM - ignore if has just been removed
-            if (i === repeater.removeHintIndex && columnFlow.children[i] === repeater.removeHintItem) {
-                continue
-            }
-
-            if (!columnFlow.children[i] || String(columnFlow.children[i]).indexOf("QQuickRepeater") == 0)
-                    //|| !columnFlow.children[i].visible)  // CUSTOM - view is invisible at start
-                continue
-
-            lastItem[count] = i
-
-            columnHeights[count] = columnFlow.children[i].height
-            columnFlow.children[i].anchors.top = columnFlow.top
-            columnFlow.children[i].anchors.left = (lastI === -1 ? columnFlow.left : columnFlow.children[lastI].right)
-            columnFlow.children[i].anchors.right = undefined
-            columnFlow.children[i].width = columnFlow.width / columns
-
-            lastI = i
-            count++
-        }
-
-        //add the other elements
-        for (i = i; i < columnFlow.children.length; i++) {
-            var highestHeight = Number.MAX_VALUE
-            var newColumn = 0
-
-            // CUSTOM - ignore if has just been removed
-            if (i === repeater.removeHintIndex && columnFlow.children[i] === repeater.removeHintItem) {
-                continue
-            }
-
-            if (!columnFlow.children[i] || String(columnFlow.children[i]).indexOf("QQuickRepeater") == 0)
-                    //|| !columnFlow.children[i].visible)  // CUSTOM - view is invisible at start
-                continue
-
-            // find the shortest column
-            for (j = 0; j < columns; j++) {
-                if (columnHeights[j] !== null && columnHeights[j] < highestHeight) {
-                    newColumn = j
-                    highestHeight = columnHeights[j]
-                }
-            }
-
-            // add the element to the shortest column
-            columnFlow.children[i].anchors.top = columnFlow.children[lastItem[newColumn]].bottom
-            columnFlow.children[i].anchors.left = columnFlow.children[lastItem[newColumn]].left
-            columnFlow.children[i].anchors.right = columnFlow.children[lastItem[newColumn]].right
-
-            lastItem[newColumn] = i
-            columnHeights[newColumn] += columnFlow.children[i].height
-        }
-
-        var cHeight = 0
-
-        for (i = 0; i < columnHeights.length; i++) {
-            if (columnHeights[i])
-                cHeight = Math.max(cHeight, columnHeights[i])
-        }
-
-        contentHeight = cHeight
-        updateWidths()
-    }
-
-    Repeater {
-        id: repeater
-        model: columnFlow.model
-        Component.onCompleted: {
-            columnFlow.repeaterCompleted = true
-            columnFlow.reEvalColumns()
-        }
-
-        // Provide a hint of the removed item
-        property int removeHintIndex: -1  // CUSTOM
-        property var removeHintItem  // CUSTOM
-
-        onItemAdded: columnFlow.reEvalColumns()  // CUSTOM - ms2 models are live
-        onItemRemoved: {
-            removeHintIndex = index
-            removeHintItem = item
-
-            columnFlow.reEvalColumns()  // CUSTOM - ms2 models are live
-
-            // Set back to null to allow freeing of memory
-            removeHintIndex = -1
-            removeHintItem = undefined
+    property int count: model === undefined ? 0 : model.count
+    property var incubating: ({})  // incubating objects
+    property var items: ({})
+    property var itemToColumn: ({})  // cache of the columns of indexes
+    property int lastIndex: 0  // the furtherest index loaded
+    property bool restoring: false  // is the view restoring?
+    property var restoreItems: ({})  // when rebuilding items are stored here temporarily
+
+    onColumnWidthChanged: {
+        if (restoring) {
+            return;
+        }
+        else if (columns != columnHeights.length && visible) {
+            // number of columns has changed so rebuild the columns
+            rebuildColumns()
+        } else {  // column width has changed update visible items properties linked to columnWidth
+            for (var column=0; column < columnHeights.length; column++) {
+                for (var i in columnHeights[column]) {
+                    if (columnHeights[column].hasOwnProperty(i) && items.hasOwnProperty(i)) {
+                        items[i].width = columnWidth;
+                        items[i].x = column * columnWidth;
+                    }
+                }
+            }
+
+            ensureItemsVisible()
+        }
+    }
+
+    onCountChanged: {
+        if (!visible) {  // store changes for when visible
+            if (count === 0 && lastIndex > -1) {
+                lastIndex = -1;
+            } else if (lastIndex > -1) {
+                lastIndex = -(lastIndex + 2);  // save the index to restore later
+            }
+        } else if (count === 0) {  // likely the model is been reset so reset the view
+            reset()
+        } else {  // likely new items in the model check if any can be shown
+            append()
+        }
+    }
+
+    onVisibleChanged: {
+        if (columns != columnHeights.length && visible) {  // number of columns has changed while invisible so reset
+            if (!restoring) {
+                rebuildColumns()
+            }
+        } else if (lastIndex < 0 && visible) {  // restore from count change
+            if (lastIndex === -1) {
+                reset()
+            } else {
+                lastIndex = (-lastIndex) - 2
+            }
+
+            append()
+        }
+    }
+
+    // Append a new row of items if possible
+    function append()
+    {
+        // Do not allow append to run if incubating
+        if (isIncubating() || restoring) {
+            return;
+        }
+
+        // get the columns in order
+        var columnsByHeight = getColumnsByHeight();
+        var workDone = false;
+
+        // check if a new item in each column is possible
+        for (var i=0; i < columnsByHeight.length; i++) {
+            var y = columnHeightsMax[columnsByHeight[i]];
+
+            // build new object in column if possible
+            if (count > 0 && lastIndex < count && inViewport(y, 0)) {
+                incubateObject(lastIndex++, columnsByHeight[i], getMaxInColumn(columnsByHeight[i]), append);
+                workDone = true
+            } else {
+                break;
+            }
+        }
+
+        if (!workDone) {  // last iteration over append so visible ensure items are correct
+            ensureItemsVisible();
+        }
+    }
+
+    // Cache the size of the columns for use later
+    function cacheColumnHeights()
+    {
+        columnHeightsMax = [];
+
+        for (var i=0; i < columnHeights.length; i++) {
+            var sum = 0;
+
+            for (var j in columnHeights[i]) {
+                sum += columnHeights[i][j];
+            }
+
+            columnHeightsMax.push(sum);
+        }
+
+        if (!restoring) {  // when not restoring otherwise user will be pushed to the top of the view
+            // set the height of columnFlow to max column (for flickable contentHeight)
+            contentHeight = Math.max.apply(null, columnHeightsMax);
+        }
+    }
+
+    // Recache the visible items heights (due to a change in their height)
+    function cacheVisibleItemsHeights()
+    {
+        for (var i in items) {
+            if (items.hasOwnProperty(i)) {
+                columnHeights[itemToColumn[i]][i] = items[i].height;
+            }
+        }
+
+        cacheColumnHeights();
+    }
+
+    // Ensures that the correct items are visible
+    function ensureItemsVisible()
+    {
+        for (var i in items) {
+            if (items.hasOwnProperty(i)) {
+                items[i].visible = inViewport(items[i].y, items[i].height)
+            }
+        }
+    }
+
+    // Return if there are incubating objects
+    function isIncubating()
+    {
+        for (var i in incubating) {
+            if (incubating.hasOwnProperty(i)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    // Run after incubation to store new column height and call any further append/restores
+    function finishIncubation(index, callback)
+    {
+        var obj = incubating[index].object;
+        delete incubating[index];
+
+        obj.heightChanged.connect(cacheVisibleItemsHeights)  // if the height changes recache
+
+        // Ensure properties linked to columnWidth are correct (as width may still be changing)
+        obj.x = itemToColumn[index] * columnWidth;
+        obj.width = columnWidth;
+
+        items[index] = obj;
+
+        columnHeights[itemToColumn[index]][index] = obj.height;  // ensure height is the latest
+
+        if (!isIncubating()) {
+            cacheColumnHeights();
+
+            // Check if there is any more work to be done (append or restore)
+            callback();
+        }
+    }
+
+    // Force any incubation to finish
+    function forceIncubationCompletion()
+    {
+        for (var i in incubating) {
+            if (incubating.hasOwnProperty(i)) {
+                incubating[i].forceCompletion()
+            }
+        }
+    }
+
+    // Get the column index in order of height
+    function getColumnsByHeight()
+    {
+        var columnsByHeight = [];
+
+        for (var i=0; i < columnHeightsMax.length; i++) {
+            var min = undefined;
+            var index = -1;
+
+            // Find the smallest column that has not been found yet
+            for (var j=0; j < columnHeightsMax.length; j++) {
+                if (columnsByHeight.indexOf(j) === -1 && (min === undefined || columnHeightsMax[j] < min)) {
+                    min = columnHeightsMax[j];
+                    index = j;
+                }
+            }
+
+            columnsByHeight.push(index);
+        }
+
+        return columnsByHeight;
+    }
+
+    // Get the highest index for a column
+    function getMaxInColumn(column)
+    {
+        var max;
+
+        for (var i in columnHeights[column]) {
+            if (columnHeights[column].hasOwnProperty(i)) {
+                i = parseInt(i);
+
+                if (items.hasOwnProperty(i)) {
+                    if (i > max || max === undefined) {
+                        max = i;
+                    }
+                }
+            }
+        }
+
+        return max;
+    }
+
+    // Incubate an object for creation
+    function incubateObject(index, column, anchorIndex, callback)
+    {
+        // Load parameters to send to the object on creation
+        var params = {
+            "anchors.top": anchorIndex === undefined ? parent.top : items[anchorIndex].bottom,
+            index: index,
+            model: getter(index),
+            width: columnWidth,
+            x: column * columnWidth
+        };
+
+        // Start incubating and cache the column
+        incubating[index] = delegate.incubateObject(parent, params);
+        itemToColumn[index] = column;
+
+        if (incubating[index].status != Component.Ready) {
+            incubating[index].onStatusChanged = function(status) {
+                if (status == Component.Ready) {
+                    finishIncubation(index, callback)
+                }
+            }
+        } else {
+            finishIncubation(index, callback)
+        }
+    }
+
+    // Detect if a loaded object is in the viewport with a buffer
+    function inViewport(y, height)
+    {
+        return flickable.contentY - buffer < y + height && y < flickable.contentY + flickable.height + buffer;
+    }
+
+    // Number of columns has changed rebuild with live items
+    function rebuildColumns()
+    {
+        restoring = true;
+        var i;
+
+        forceIncubationCompletion()
+
+        columnHeights = []
+        columnHeightsMax = []
+
+        for (i=0; i < columns; i++) {
+            columnHeights.push({});
+            columnHeightsMax.push(0);
+        }
+
+        lastIndex = 0;
+
+        restoreItems = items;
+        items = {};
+
+        restoreExisting()
+
+        restoring = false;
+
+        cacheColumnHeights();  // rebuilds contentHeight
+
+        // If the columns have changed while the view was locked rerun
+        if (columns != columnHeights.length && visible) {
+            rebuildColumns()
+        } else {
+            append()  // check if any new items can be added
+        }
+    }
+
+    // Restores existing items into potentially new positions
+    function restoreExisting()
+    {
+        var i;
+
+        // get the columns in order
+        var columnsByHeight = getColumnsByHeight();
+        var workDone = false;
+
+        // check if a new item in each column is possible
+        for (i=0; i < columnsByHeight.length; i++) {
+            var column = columnsByHeight[i];
+
+            // build new object in column if possible
+            if (count > 0 && lastIndex < count) {
+                if (restoreItems.hasOwnProperty(lastIndex)) {
+                    var item = restoreItems[lastIndex];
+                    var maxInColumn = getMaxInColumn(column);  // get lowest item in column
+
+                    itemToColumn[lastIndex] = column;
+                    columnHeights[column][lastIndex] = item.height;  // ensure height is the latest
+
+                    // Rebuild item properties
+                    item.anchors.bottom = undefined
+                    item.anchors.top = maxInColumn === undefined ? parent.top : items[maxInColumn].bottom;
+                    item.x = column * columnWidth;
+                    item.visible = inViewport(item.y, item.height);
+
+                    // Migrate item from restoreItems to items
+                    items[lastIndex] = item;
+                    delete restoreItems[lastIndex];
+
+                    // set after restore as height will likely change causing cacheVisibleItemsHeights to be run
+                    item.width = columnWidth;
+
+                    cacheColumnHeights();  // ensure column heights are up to date
+
+                    lastIndex++;
+                    workDone = true;
+                }
+            } else {
+                break;
+            }
+        }
+
+        if (workDone) {
+            restoreExisting()  // if work done then check if any more is needed
+        } else {
+            restoreItems = {};  // ensure restoreItems is empty
+        }
+    }
+
+    // Reset the column flow
+    function reset()
+    {
+        forceIncubationCompletion()
+
+        // Destroy any old items
+        for (var j in items) {
+            if (items.hasOwnProperty(j)) {
+                items[j].destroy()
+            }
+        }
+
+        // Reset and rebuild the variables
+        items = ({})
+        lastIndex = 0
+
+        columnHeights = []
+
+        for (var k=0; k < columns; k++) {
+            columnHeights.push({})
+        }
+
+        cacheColumnHeights()
+
+        contentHeight = 0
+    }
+
+    Connections {
+        target: flickable
+        onContentYChanged: {
+            append()  // Append any new items (scrolling down)
+
+            ensureItemsVisible()
         }
     }
 }