Merge lp:~zsombi/ubuntu-ui-toolkit/asyncPageCreation into lp:ubuntu-ui-toolkit/staging

[Zsombor Egri]

Turn AdaptivePageLayout page creation to be asynchronous.

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:1622
http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-ci/2184/
Executed test runs:
    UNSTABLE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-amd64-ci/912
    SUCCESS: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-armhf-ci/914
        deb: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-armhf-ci/914/artifact/work/output/*zip*/output.zip
    UNSTABLE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-i386-ci/911

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-ci/2184/rebuild

review: Needs Fixing (continuous-integration)

[Cris Dywan (kalikiana)]

tests/unit_x11/tst_components/tst_multicolumnheader.qml and tests/unit_x11/tst_components/tst_pagestack.new_header.qml need adapting so they don't immediately check the header.

The fake incubator looks pretty straightforward. Can we link to the upstream docs¹, though? And point out that it's equivalent to using incubateObject or a Loader, which may even get people to use it in their own code.

¹ http://doc.qt.io/qt-5/qml-qtqml-component.html#incubateObject-method

review: Needs Fixing

[Zsombor Egri (zsombi)]

> tests/unit_x11/tst_components/tst_multicolumnheader.qml and
> tests/unit_x11/tst_components/tst_pagestack.new_header.qml need adapting so
> they don't immediately check the header.

Actually PageStack should behave like did before, loading pages synchronously. We should mark the PageStack deprecated, and instruct people to move away from it from 1.3 onwards. So the only test needed to be adjusted is the tst_multicolumnheader, but the incubation had to be fixed to work synchronously when not used from AdaptivePageLayout.

>
> The fake incubator looks pretty straightforward. Can we link to the upstream
> docs¹, though? And point out that it's equivalent to using incubateObject or a
> Loader, which may even get people to use it in their own code.
>
> ¹ http://doc.qt.io/qt-5/qml-qtqml-component.html#incubateObject-method

I did that, however would be nicer if we could link to the d.u.c link. But d.u.c is broken, seems not all Qt docs are taken from qt.io.

[lp:~zsombi/ubuntu-ui-toolkit/asyncPageCreation]

1623. By Zsombor Egri on 2015-08-30

adapt multicolumn test to async page loading

1624. By Zsombor Egri on 2015-08-31

fix async loading to be triggered only when PageWrapper synchronous is not set to avoid breaking PageStack behavior; toolkit gallery title not being set fixed; adapt multicolumnheader test to async loading

[Tim Peeters (tpeeters)]

I prefer not to touch 1.2, so that would mean we don't edit 1.2/PageWrapperUtils.js, but create a copy in 1.3/PageWrapperUtils.js that we edit.

[Cris Dywan (kalikiana)]

> I prefer not to touch 1.2, so that would mean we don't edit
> 1.2/PageWrapperUtils.js, but create a copy in 1.3/PageWrapperUtils.js that we
> edit.

It's internal.. but I agree for consistency it makes sense.

[lp:~zsombi/ubuntu-ui-toolkit/asyncPageCreation]

1625. By Zsombor Egri on 2015-08-31

copy PageWrapperUtils.js to 1.3 and have the changes there only.

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:1625
http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-ci/2191/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-amd64-ci/919/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-armhf-ci/921/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-i386-ci/918/console

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-ci/2191/rebuild

review: Needs Fixing (continuous-integration)

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:1625
http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-ci/2187/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-amd64-ci/915/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-armhf-ci/917/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-i386-ci/914/console

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-ci/2187/rebuild

review: Needs Fixing (continuous-integration)

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:1625
http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-ci/2186/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-amd64-ci/914/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-armhf-ci/916/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-i386-ci/913/console

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-ci/2186/rebuild

review: Needs Fixing (continuous-integration)

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:1625
http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-ci/2193/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-amd64-ci/921/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-armhf-ci/923/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-i386-ci/920/console

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-ci/2193/rebuild

review: Needs Fixing (continuous-integration)

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:1625
http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-ci/2192/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-amd64-ci/920/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-armhf-ci/922/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-i386-ci/919/console

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-ci/2192/rebuild

review: Needs Fixing (continuous-integration)

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:1625
http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-ci/2189/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-amd64-ci/917/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-armhf-ci/919/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-i386-ci/916/console

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-ci/2189/rebuild

review: Needs Fixing (continuous-integration)

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:1625
http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-ci/2188/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-amd64-ci/916/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-armhf-ci/918/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-i386-ci/915/console

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-ci/2188/rebuild

review: Needs Fixing (continuous-integration)

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:1625
http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-ci/2190/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-amd64-ci/918/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-armhf-ci/920/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-i386-ci/917/console

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-ci/2190/rebuild

review: Needs Fixing (continuous-integration)

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:1625
http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-ci/2194/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-amd64-ci/922/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-armhf-ci/924/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-i386-ci/921/console

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-ci/2194/rebuild

review: Needs Fixing (continuous-integration)

[lp:~zsombi/ubuntu-ui-toolkit/asyncPageCreation]

1626. By Zsombor Egri on 2015-09-01

documentation fix

1627. By Zsombor Egri on 2015-09-01

staging merge

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:1627
http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-ci/2198/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-amd64-ci/926
    SUCCESS: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-armhf-ci/928
        deb: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-armhf-ci/928/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-vivid-i386-ci/925

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/ubuntu-sdk-team-ubuntu-ui-toolkit-staging-ci/2198/rebuild

review: Approve (continuous-integration)

[Cris Dywan (kalikiana)]

Let's get it landed!

review: Approve

=== modified file 'documentation/ubuntu-ui-toolkit-common.qdocconf'
--- documentation/ubuntu-ui-toolkit-common.qdocconf	2015-07-24 18:00:54 +0000
+++ documentation/ubuntu-ui-toolkit-common.qdocconf	2015-09-01 12:00:47 +0000
@@ -26,7 +26,7 @@
 sources.fileextensions = "*.qml *.qdoc *.cpp *.js"
 headers.fileextensions = "*.h"
 # exclude qml files that have the component documented in a separate qdoc file
-excludefiles = $BLD/../src/Ubuntu/Components/MainView.qml
+excludefiles += $BLD/../src/Ubuntu/Components/1.3/PageWrapperUtils.js
 outputdir = $BLD/html
 outputformats = HTML
 version = 1.2

=== modified file 'examples/ubuntu-ui-toolkit-gallery/ubuntu-ui-toolkit-gallery.qml'
--- examples/ubuntu-ui-toolkit-gallery/ubuntu-ui-toolkit-gallery.qml	2015-08-14 10:11:58 +0000
+++ examples/ubuntu-ui-toolkit-gallery/ubuntu-ui-toolkit-gallery.qml	2015-09-01 12:00:47 +0000
@@ -96,9 +96,8 @@
                         selected: index === widgetList.currentIndex
                         onClicked: {
                             var source = Qt.resolvedUrl(model.source);
-                            var newPage = layout.addPageToNextColumn(mainPage, source);
+                            layout.addPageToNextColumn(mainPage, source, {title: model.label});
 
-                            newPage.title = model.label;
                             widgetList.currentIndex = index;
                         }
                     }

=== modified file 'src/Ubuntu/Components/1.3/AdaptivePageLayout.qml'
--- src/Ubuntu/Components/1.3/AdaptivePageLayout.qml	2015-08-27 20:27:45 +0000
+++ src/Ubuntu/Components/1.3/AdaptivePageLayout.qml	2015-09-01 12:00:47 +0000
@@ -83,6 +83,12 @@
     }
   \endqml
 
+  \note Observe the use of the \c Page::pageStack property in the example above.
+  The same property is used to share the AdaptivePageLayout instance the Page is
+  used in, therefore the same page can be used in a PageStack or in an AdaptivePageLayout.
+  However implementations must make sure the desired PageStack or AdaptivePageLayout
+  function exists in the instance before using it.
+
   AdaptivePageLayout supports adaptive column handling. When the number of columns changes at
   runtime the pages are automatically rearranged.
 
@@ -196,12 +202,72 @@
     property list<PageColumnsLayout> layouts
 
     /*!
-      \qmlmethod Item addPageToCurrentColumn(Item sourcePage, var page[, var properties])
+      \qmlmethod object addPageToCurrentColumn(Item sourcePage, var page[, var properties])
       Adds a \c page to the column the \c sourcePage resides in and removes all pages
       from the higher columns. \c page can be a Component or a file.
-      \c properties is a JSON object containing properties
-      to be set when page is created. \c sourcePage must be active. Returns the
-      instance of the page created.
+      \c properties is a JSON object containing properties to be set when page
+      is created. \c sourcePage must be active.
+
+      The function creates the new page asynchronously if the new \c page to be
+      added is a Component or a QML document. In this case the function returns
+      an incubator which can be used to track the page creation.For more about
+      incubation in QML and creating components asynchronously, see
+      \l {http://doc.qt.io/qt-5/qml-qtqml-component.html#incubateObject-method}
+      {Component.incubateObject()}.
+      The following example removes an element from the list model whenever the
+      page opened in the second column is closed. Note, the example must be run
+      on desktop or on a device with at least 90 grid units screen width.
+      \qml
+      import QtQuick 2.4
+      import Ubuntu.Components 1.3
+
+      MainView {
+          width: units.gu(90)
+          height: units.gu(70)
+
+          Component {
+              id: page2Component
+              Page {
+                  title: "Second Page"
+                  Button {
+                      text: "Close me"
+                      onClicked: pageStack.removePages(pageStack.primaryPage);
+                  }
+              }
+          }
+
+          AdaptivePageLayout {
+              id: pageLayout
+              anchors.fill: parent
+              primaryPage: Page {
+                  title: "Primary Page"
+                  ListView {
+                      id: listView
+                      anchors.fill: parent
+                      model: 10
+                      delegate: ListItem {
+                          Label { text: modelData }
+                          onClicked: {
+                              var incubator = pageLayout.addPageToNextColumn(pageLayout.primaryPage, page2Component);
+                              if (incubator && incubator.status == Component.Loading) {
+                                  incubator.onStatusChanged = function(status) {
+                                      if (status == Component.Ready) {
+                                          // connect page's destruction to decrement model
+                                          incubator.object.Component.destruction.connect(function() {
+                                              listView.model--;
+                                          });
+                                      }
+                                  }
+                              }
+                          }
+                      }
+                  }
+              }
+          }
+      }
+      \endqml
+
+      \sa {http://doc.qt.io/qt-5/qml-qtqml-component.html#incubateObject-method}{Component.incubateObject}
       */
     function addPageToCurrentColumn(sourcePage, page, properties) {
         var nextColumn = d.columnForPage(sourcePage) + 1;
@@ -221,6 +287,7 @@
       holds \c sourcePage) and all following columns, and then add \c page to the next column.
       If \c sourcePage is located in the
       rightmost column, the new page will be pushed to the same column as \c sourcePage.
+      The return value is the same as in \l addPageToCurrentColumn case.
       */
     function addPageToNextColumn(sourcePage, page, properties) {
         var nextColumn = d.columnForPage(sourcePage) + 1;
@@ -304,7 +371,7 @@
 
         function createWrapper(page, properties) {
             var wrapperComponent = Qt.createComponent("PageWrapper.qml");
-            var wrapperObject = wrapperComponent.createObject(hiddenPages);
+            var wrapperObject = wrapperComponent.createObject(hiddenPages, {synchronous: false});
             wrapperObject.pageStack = layout;
             wrapperObject.properties = properties;
             // set reference last because it will trigger creation of the object
@@ -320,7 +387,14 @@
             // replace page holder's child
             var holder = body.children[targetColumn];
             holder.detachCurrentPage();
-            holder.attachPage(pageWrapper)
+            if ((pageWrapper.incubator && pageWrapper.incubator.status == Component.Ready) || pageWrapper.object) {
+                holder.attachPage(pageWrapper);
+            } else {
+                // asynchronous, connect to page load completion and attach when page is available
+                pageWrapper.pageLoaded.connect(function () {
+                    holder.attachPage(pageWrapper);
+                });
+            }
         }
 
         function getWrapper(page) {
@@ -378,7 +452,7 @@
             newWrapper.parentPage = sourcePage;
             newWrapper.column = column;
             d.addWrappedPage(newWrapper);
-            return newWrapper.object;
+            return newWrapper.incubator;
         }
 
         // update the page for the specified column

=== modified file 'src/Ubuntu/Components/1.3/PageWrapper.qml'
--- src/Ubuntu/Components/1.3/PageWrapper.qml	2015-06-15 07:45:34 +0000
+++ src/Ubuntu/Components/1.3/PageWrapper.qml	2015-09-01 12:00:47 +0000
@@ -15,7 +15,7 @@
  */
 
 import QtQuick 2.4
-import "../1.2/PageWrapperUtils.js" as Utils
+import "PageWrapperUtils.js" as Utils
 
 /*!
     \internal
@@ -66,6 +66,22 @@
     property Item pageHolder
 
     /*!
+      Instructs to load the page synchronously or not. Used by AdaptivePageLayout.
+      True by default to keep PageStack integrity.
+      */
+    property bool synchronous: true
+
+    /*!
+      Incubator for the asynchronous page creation
+      */
+    property var incubator: null
+
+    /*!
+      Signal emitted when incubator completes page loading.
+      */
+    signal pageLoaded()
+
+    /*!
       Returns true if the current PageWrapper is a child of the given page
       */
     function childOf(page) {
@@ -114,7 +130,14 @@
         if (pageWrapper.object) pageWrapper.object = null;
         Utils.initPage(pageWrapper);
         if (pageWrapper.active && reference) {
-            Utils.activate(pageWrapper);
+            if ((pageWrapper.incubator && pageWrapper.incubator.status == Component.Ready) || pageWrapper.object) {
+                Utils.activate(pageWrapper);
+            } else {
+                // asynchronous, connect page activation
+                pageLoaded.connect(function () {
+                    Utils.activate(pageWrapper);
+                });
+            }
         }
     }
 

=== added file 'src/Ubuntu/Components/1.3/PageWrapperUtils.js'
--- src/Ubuntu/Components/1.3/PageWrapperUtils.js	1970-01-01 00:00:00 +0000
+++ src/Ubuntu/Components/1.3/PageWrapperUtils.js	2015-09-01 12:00:47 +0000
@@ -0,0 +1,167 @@
+/*
+ * Copyright 2015 Canonical Ltd.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation; version 3.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+//.pragma library // FIXME: cannot refer to Component.Error if I use this.
+// FIXME: ideally we would make this a stateless library, but that breaks applications
+//  that rely on accessing context variables in pages that were pushed on a PageStack
+//  by url (PageStack.push("FileName.qml")) because of a Qt bug:
+//  https://bugreports.qt-project.org/browse/QTBUG-31347
+
+/*!
+  \internal
+  Incubator wrapper object. Used when page is loaded asynchronously.
+  */
+
+function Incubator(pageWrapper, pageComponent) {
+    // private variable for QmlIncubatorObject
+    var incubator = null;
+
+    // public API
+    this.status = Component.Ready;
+    this.object = null;
+    this.onStatusChanged = null;
+    this.forceCompletion = function () {
+        if (incubator) {
+            incubator.forceCompletion();
+        }
+    }
+
+    // internal function to catch status changes
+    function incubatorStatusChanged(status) {
+        // update wrapper incubator fields
+        pageWrapper.incubator.status = status;
+        pageWrapper.incubator.object = pageWrapper.object = incubator.object;
+
+        // emit pageWrapper's pageLoaded signal to complete page activation and loading
+        if (status === Component.Ready) {
+            pageWrapper.pageLoaded();
+        }
+
+        // forward state change to the user
+        if (pageWrapper.incubator.onStatusChanged) {
+            // call onStatusChanged
+            pageWrapper.incubator.onStatusChanged(status);
+        }
+
+        // cleanup of ready or error
+        if (status !== Component.Loading) {
+            pageWrapper.incubator = null;
+            incubator = null;
+        }
+    }
+
+    if (pageWrapper.properties) {
+        incubator = pageComponent.incubateObject(pageWrapper, pageWrapper.properties);
+    } else {
+        incubator = pageComponent.incubateObject(pageWrapper);
+    }
+
+    this.status = incubator.status;
+    if (incubator.status != Component.Ready) {
+        incubator.onStatusChanged = incubatorStatusChanged;
+    } else {
+        incubatorStatusChanged(incubator.status);
+    }
+}
+
+/*******************************************************
+ *
+ */
+/*!
+  \internal
+  Initialize pageWrapper.object.
+ */
+function initPage(pageWrapper) {
+    var pageComponent;
+
+    if (pageWrapper.reference.createObject) {
+        // page reference is a component
+        pageComponent = pageWrapper.reference;
+    } else if (typeof pageWrapper.reference == "string") {
+        // page reference is a string (url)
+        pageComponent = Qt.createComponent(pageWrapper.reference);
+    }
+
+    // PageWrapper can override the synchronous loading
+    var synchronous = pageWrapper.hasOwnProperty("synchronous") ? pageWrapper.synchronous : true;
+
+    if (pageComponent) {
+        if (pageComponent.status === Component.Error) {
+            throw new Error("Error while loading page: " + pageComponent.errorString());
+        } else {
+            // create the object
+            pageWrapper.incubator = new Incubator(pageWrapper, pageComponent);
+            if (synchronous) {
+                pageWrapper.incubator.forceCompletion();
+            }
+            pageWrapper.canDestroy = true;
+        }
+    } else {
+        // page reference is an object
+        pageWrapper.object = pageWrapper.reference;
+        pageWrapper.object.parent = pageWrapper;
+        pageWrapper.canDestroy = false;
+
+        // copy the properties to the page object
+        for (var prop in pageWrapper.properties) {
+            if (pageWrapper.properties.hasOwnProperty(prop)) {
+                pageWrapper.object[prop] = pageWrapper.properties[prop];
+            }
+        }
+    }
+
+    return pageWrapper.object;
+}
+
+/*!
+  \internal
+  Create the page object if needed, and make the page object visible.
+ */
+function activate(pageWrapper) {
+    if (!pageWrapper.object) {
+        initPage(pageWrapper);
+    }
+
+    // Having the same page pushed multiple times on a stack changes
+    // the parent of the page object. Change it back here.
+    pageWrapper.object.parent = pageWrapper;
+
+    // Some page objects are invisible initially. Make visible.
+
+    pageWrapper.object.visible = true;
+    pageWrapper.active = true;
+}
+
+/*!
+  \internal
+  Hide page object.
+ */
+function deactivate(pageWrapper) {
+    pageWrapper.active = false;
+}
+
+/*!
+  \internal
+  Destroy the page object if pageWrapper.canDestroy is true.
+  Do nothing if pageWrapper.canDestroy is false.
+ */
+function destroyObject(pageWrapper) {
+    if (pageWrapper.canDestroy) {
+        pageWrapper.object.destroy();
+        pageWrapper.object = null;
+        pageWrapper.canDestroy = false;
+    }
+}

=== modified file 'src/Ubuntu/Components/ComponentModule.pro'
--- src/Ubuntu/Components/ComponentModule.pro	2015-08-24 16:02:50 +0000
+++ src/Ubuntu/Components/ComponentModule.pro	2015-09-01 12:00:47 +0000
@@ -110,6 +110,7 @@
              1.3/PageTreeNode.qml \
              1.3/pageUtils.js \
              1.3/PageWrapper.qml \
+             1.3/PageWrapperUtils.js \
              1.3/Panel.qml \
              1.3/ProgressBar.qml \
              1.3/PullToRefresh.qml \

=== modified file 'tests/unit_x11/tst_components/tst_adaptivepagelayout.qml'
--- tests/unit_x11/tst_components/tst_adaptivepagelayout.qml	2015-08-11 08:30:57 +0000
+++ tests/unit_x11/tst_components/tst_adaptivepagelayout.qml	2015-09-01 12:00:47 +0000
@@ -69,9 +69,25 @@
         id: defaults
     }
 
+    Component {
+        id: pageComponent
+        Page {
+            title: "DynamicPage"
+        }
+    }
+
     UbuntuTestCase {
+        id: testCase
         when: windowShown
 
+        signal pageLoaded()
+
+        SignalSpy {
+            id: loadedSpy
+            target: testCase
+            signalName: "pageLoaded"
+        }
+
         function resize_single_column() {
             layout.width = units.gu(40);
         }
@@ -82,6 +98,11 @@
         }
 
         function cleanup() {
+            page1.title = "Page1";
+            page2.title = "Page2";
+            page3.title = "Page3";
+            page4.title = "Page4";
+            loadedSpy.clear();
             resize_multiple_columns();
             layout.removePages(page1);
         }
@@ -185,5 +206,45 @@
             layout.removePages(page3);
             compare(page2.visible, true, "Adding page to current column pruned that column.");
         }
+
+        function test_add_page_to_current_data() {
+            return [
+                {tag: "Synchronously to current column", func: "addPageToCurrentColumn", page: page2, params: {}, sync: true},
+                {tag: "Synchronously to current column, with params", func: "addPageToCurrentColumn", page: page2, params: {title: "Altered title"}, sync: true},
+                {tag: "Synchronously to next column", func: "addPageToNextColumn", page: page2, params: {}, sync: true},
+                {tag: "Synchronously to next column, with params", func: "addPageToNextColumn", page: page2, params: {title: "Altered title"}, sync: true},
+                {tag: "Asynchronously to current column", func: "addPageToCurrentColumn", page: pageComponent, params: {}, sync: false},
+                {tag: "Asynchronously to current column, with params", func: "addPageToCurrentColumn", page: pageComponent, params: {title: "Altered title"}, sync: false},
+                {tag: "Asynchronously to next column", func: "addPageToNextColumn", page: pageComponent, params: {}, sync: false},
+                {tag: "Asynchronously to next column, with params", func: "addPageToNextColumn", page: pageComponent, params: {title: "Altered title"}, sync: false},
+            ]
+        }
+        function test_add_page_to_current(data) {
+            var incubator = layout[data.func](layout.primaryPage, data.page, data.params);
+            compare((incubator == null), data.sync);
+            if (incubator) {
+                compare(incubator.status, Component.Loading, "The incubator status is not Component.Loading, but " + incubator.status);
+                // for cleanup, we must wait till the page is added, so we can do proper cleanup
+                incubator.onStatusChanged = function (status) {
+                    // test params
+                    for (var param in data.params) {
+                        compare(incubator.object[param], data.params[param], "parameter '" + param + "' values do not match");
+                    }
+                    testCase.pageLoaded();
+                    layout.removePages(layout.primaryPage);
+                }
+                // make sure we wait enough to let additional tests to complete
+                loadedSpy.wait(1500);
+            }
+        }
+
+        function test_asynchronous_page_loading_incubator_forcecompletion() {
+            var incubator = layout.addPageToCurrentColumn(layout.primaryPage, pageComponent);
+            verify(incubator, "Page added synchronously!");
+            compare(incubator.status, Component.Loading, "Incubator in different state");
+            incubator.forceCompletion();
+            compare(incubator.status, Component.Ready, "Incubator not completed");
+            verify(incubator.object, "Page object not set");
+        }
     }
 }

=== modified file 'tests/unit_x11/tst_components/tst_multicolumnheader.qml'
--- tests/unit_x11/tst_components/tst_multicolumnheader.qml	2015-08-27 21:11:36 +0000
+++ tests/unit_x11/tst_components/tst_multicolumnheader.qml	2015-09-01 12:00:47 +0000
@@ -240,7 +240,12 @@
         }
 
         function test_header_title_for_external_page() {
-            layout.addPageToNextColumn(rootPage, Qt.resolvedUrl("MyExternalPage.qml"));
+            var incubator = layout.addPageToNextColumn(rootPage, Qt.resolvedUrl("MyExternalPage.qml"));
+            var pageLoaded = false;
+            incubator.onStatusChanged = function (status) {
+                pageLoaded = (incubator.object != null);
+            }
+            tryCompareFunction(function() {return pageLoaded}, true, 1000);
             var n = root.columns === 2 ? 1 : 0
             compare(get_header(n).config.title, "Page from QML file",
                     "Adding external Page does not update the header title.");