Adaptive page layouts made easy

Adaptive page layouts made easy

Convergent applications

We want to make it easy for app developers to write an app that can run on different form factors without changes in the code. This implies that an app should support screens of various sizes, and the layout of the app should be optimal for each screen size. For example, a messaging app running on a desktop PC in a big window could show a list of conversations in a narrow column on the left, and the selected conversation in a wider column on the right side. The same application on a phone would show only the list of conversations, or the selected conversation with a back-button to return to the list. It would also be useful if the app automatically switches between the 1-column and 2-column layouts when the user resizes the window, or attaches a large screen to the phone.

To accomplish this, we introduced the AdaptivePageLayout component in Ubuntu.Components 1.3. This version of  Ubuntu.Components is still under development (expect an official release announcement soon), but if you are running the latest version of the Ubuntu UI Toolkit, you can already try it out by updating your import Ubuntu.Components to version 1.3. Note that you should not mix import versions, so when you update one of your components to 1.3, they should all be updated.

AdaptivePageLayout

AdaptivePageLayout is an Item with the following properties and functions:

  • property Page primaryPage
  • function addPageToCurrentColumn(sourcePage, newPage)
  • function addPageToNextColumn(sourcePage, newPage)
  • function removePages(page)

To understand how it works, imagine that internally, the AdaptivePageLayout keeps track of an infinite number of virtual columns that may be displayed on your screen. Not all virtual columns are visible on the screen. By default, depending on the width of your AdaptivePageLayout, either one or two columns are visible. When a Page is added to a virtual column that is not visible, it will instead be shown in the right-most visible column.

The Page defined as primaryPage will initially be visible in the first (left-most) column and all the other columns are empty (see figure 1).

Figure 1: Showing only primaryPage in layouts of 100 and 50 grid-units.
Showing only primaryPage at 100 grid units. Showing primaryPage at 50 grid units.

To show another Page in the first column, call addPageToCurrentColumn() with as parameters the current page (primaryPage), and the new page. The new page will then show up in the same column with a back button in the header to close the new page and return to the previous page (see figure 2). So far, AdaptivePageLayout is no different than a PageStack.

Figure 2: Page with back button in the first column.
Page with back button in the first column at 100 grid units. Page with back button in first column at 50 grid units.

The differences with PageStack become evident when you want to keep the first page visible in the first column, while adding a new page to the next column. To do this, call addPageToNextColumn() with the same parameters as addPageToCurrentColumn() above. The new page will now show up in the following column on the screen (see figure  3).

Figure 3: Adding a page to the next column.
Added a page to the next column at 100 grid units. Added a page to the next column at 50 grid units.

However, if you resize the window so that it fits only one column, the left column will be hidden, and the page that was in the right column will now have a back button. Resizing back to get the two-column layout will again give you the first page on the left, and the new page on the right. Call removePages(page) to remove page and all pages that were added after page was added. There is one exception: primaryPage is never removed, so removePages(primaryPage) will remove all pages except primaryPage and return your AdaptivePageLayout to its initial state.

AdaptivePageLayout automatically chooses between a one and two-column layout depending on the width of the window. It also automatically shows a back button in the correct column when one is needed and synchronizes the header size between the different columns (see figure 4).

Figure 4: Adding sections to any column increases the height of the header in every column.
Added a page with sections to the right column at 100 grid units. Added a page with sections at 50 grid units.

Future extensions

The version of AdaptivePageLayout that is now in the UI toolkit is only the first version. What works now will keep working, but we will extend the API to support the following:

  • Layouts with more than two columns
  • Use different conditions for switching between layouts
  • User-resizable columns
  • Automatic and manual hiding of the header in single-column layouts
  • Custom proxy objects to support Autopilot tests for applications

Below you can read the full source code that was used to create the screenshots above. The screenhots do not cover all the possible orders in which the pages left and right can be added, so I encourage you to run the code for yourself and discover its full behavior. We are looking forward to see your first applications using the new AdaptivePageLayout component soon :). Of course if there are any questions you can leave a comment below or ping members of the SDK team (I am t1mp) in #ubuntu-app-devel on Freenode IRC.

 

import QtQuick 2.4
import Ubuntu.Components 1.3

MainView {
    width: units.gu(100)
    height: units.gu(70)

    AdaptivePageLayout {
        id: layout
        anchors.fill: parent
        primaryPage: rootPage

        Page {
            id: rootPage
            title: i18n.tr("Root page")

            Column {
                anchors {
                    top: parent.top
                    left: parent.left
                    margins: units.gu(1)
                }
                spacing: units.gu(1)

                Button {
                    text: "Add page left"
                    onClicked: layout.addPageToCurrentColumn(rootPage, leftPage)
                }
                Button {
                    text: "Add page right"
                    onClicked: layout.addPageToNextColumn(rootPage, rightPage)
                }
                Button {
                    text: "Add sections page right"
                    onClicked: layout.addPageToNextColumn(rootPage, sectionsPage)
                }
            }
        }

        Page {
            id: leftPage
            title: i18n.tr("First column")

            Rectangle {
                anchors {
                    fill: parent
                    margins: units.gu(2)
                }
                color: UbuntuColors.orange

                Button {
                    anchors.centerIn: parent
                    text: "right"
                    onTriggered: layout.addPageToNextColumn(leftPage, rightPage)
                }
            }
        }

        Page {
            id: rightPage
            title: i18n.tr("Second column")

            Rectangle {
                anchors {
                    fill: parent
                    margins: units.gu(2)
                }
                color: UbuntuColors.green

                Button {
                    anchors.centerIn: parent
                    text: "Another page!"
                    onTriggered: layout.addPageToCurrentColumn(rightPage, sectionsPage)
                }
            }
        }

        Page {
            id: sectionsPage
            title: i18n.tr("Page with sections")
            head.sections.model: [i18n.tr("one"), i18n.tr("two"), i18n.tr("three")]

            Rectangle {
                anchors {
                    fill: parent
                    margins: units.gu(2)
                }
                color: UbuntuColors.blue
            }
        }
    }
}

 

Comments

No comments yet.

Add your comment