# AdaptivePageLayout QML Type

View with multiple columns of Pages. More...

Import Statement: | import Lomiri.Components 1.3
Since: | Qt Lomiri.Components

- List of all members, including inherited members

## Properties

- asynchronous : bool
- columns : int
- layouts : PageColumnsLayout
- primaryPage : Page
- primaryPageSource : var

## Methods

- object addPageToCurrentColumn(Item sourcePage, var[, var properties] page)
- object addPageToCurrentColumn(Item sourcePage, var[, var properties] page)
- Item addPageToNextColumn(Item sourcePage, var[, var properties] page)
- Item addPageToNextColumn(Item sourcePage, var[, var properties] page)
- void removePages(Item page)
- void removePages(Item page)

## Detailed Description

The component provides a flexible way of viewing a stack of pages in one or more columns. Unlike in PageStack, there can be more than one Page active at a time, depending on the number of the columns in the view.

AdaptivePageLayout stores pages added in a tree. Pages are added relative to a given page, either as sibling (addPageToCurrentColumn) or as child (addPageToNextColumn). This means that removing a non-leaf page from the Page tree will remove all its children from the page tree.

The columns are populated from left to right. The column a page is added to is detected based on the source page that is given to the functions adding the page. The pages can be added either to the same column the source page resides or to the column next to the source page. Giving a null value to the source page will add the page to the leftmost column of the view.

The primary page, the very first page must be specified either through the primaryPage or primaryPageSource properties. primaryPage can only hold a Page instance, primaryPageSource can either be a Component or a url to a document defining a Page. primaryPageSource has precedence over primaryPage, and when set it will report the loaded Page through primaryPage property, and will replace any value set into that property.

    import QtQuick 2.4
    import Lomiri.Components

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

        AdaptivePageLayout {
            anchors.fill: parent
            primaryPage: page1
            Page {
                id: page1
                header: PageHeader {
                    id: header
                    title: "Main Page"
                }
                Column {
                    anchors.top: header.bottom
                    Button {
                        text: "Add Page2 above " + page1.title
                        onClicked: page1.pageStack.addPageToCurrentColumn(page1, page2)
                    }
                    Button {
                        text: "Add Page3 next to " + page1.title
                        onClicked: page1.pageStack.addPageToNextColumn(page1, page3)
                    }
                }
            }
            Page {
                id: page2
                header: PageHeader {
                    title: "Page #2"
                }
            }
            Page {
                id: page3
                header: PageHeader {
                    title: "Page #3"
                }
            }
        }
    }

Note: Observe the use of the `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.

By default the component splits the layout in two columns when the width of the layout exceeds 80 grid units. The first column is sized to 40 grid unit width and the second one to fill the rest of the remaining space. When the 80 grid unit breakpoint is reached, the component will switch from one column to two, and vice versa. These defaults can be overridden through the layouts property by defining the possible layouts, their column sizing and the breakpoints when the layouts should be activated. PageColumn configurations must appear in the same order (from left to right) as the columns appear in the layout. If none of the layouts condition is met, a one column layout will be used.

    import QtQuick 2.4
    import Lomiri.Components

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

        AdaptivePageLayout {
            anchors.fill: parent
            primaryPageSource: page1Component
            layouts: PageColumnsLayout {
                when: width > units.gu(80)
                // column #0
                PageColumn {
                    minimumWidth: units.gu(30)
                    maximumWidth: units.gu(60)
                    preferredWidth: units.gu(40)
                }
                // column #1
                PageColumn {
                    fillWidth: true
                }
            }

            Component {
                id: page1Component
                Page {
                    id: page1
                    header: PageHeader {
                        id: header
                        title: "Main page"
                    }
                    Column {
                        anchors.top: header.bottom
                        Button {
                            text: "Add Page2 above " + page1.title
                            onClicked: page1.pageStack.addPageToCurrentColumn(page1, page2)
                        }
                        Button {
                            text: "Add Page3 next to " + page1.title
                            onClicked: page1.pageStack.addPageToNextColumn(page1, page3)
                        }
                    }
                }
            }
            Page {
                id: page2
                header: PageHeader {
                    title: "Page #2"
                }
            }
            Page {
                id: page3
                header: PageHeader {
                    title: "Page #3"
                }
            }
        }
    }

A column is considered to be resizable if the PageColumn::minimumWidth and PageColumn::maximumWidth configuration differs. This implies that if a column is not meant to be resized, it should have PageColumn::minimumWidth and PageColumn::maximumWidth set to the same value. In the example above, the first column can be resized to a minimum of 30, and a maximum of 60 grid units, and the preferred width is set to 40 grid units. This width is set every time the layout is activated.

When a Page with the Page::header property set is added to an AdaptivePageLayout, the AdaptivePageLayout will synchronize the height of that header with the height of the headers in other columns, i.e., the height of each of the headers will be set to the maximum implicitHeight of all the headers.

See also PageStack, PageColumnsLayout, and PageColumn.

## Property Documentation

asynchronous : bool

The property drives the way the pages should be loaded, synchronously or asynchronously. Defaults to true.

[read-only] columns : int

The property holds the number of columns shown in the layout.

layouts : PageColumnsLayout

The property holds the different layout configurations overriding the default configurations. Defaults to an empty list.

See also PageColumnsLayout.

primaryPage : Page

The property holds the first Page which will be added to the view. If the view has more than one column, the page will be added to the leftmost column. The property can only hold a Page instance. When changed runtime (not by the AdaptivePageLayout component itself), the primaryPageSource property will be reset.

primaryPageSource : var

The property specifies the source of the primaryPage in case the primary page is created from a Component or loaded from an external document. It has precedence over primaryPage.

## Method Documentation

object addPageToCurrentColumn(Item sourcePage, var[, var properties] page)

Adds a `page` to the column the `sourcePage` resides in and removes all pages from the higher columns. `page` can be a Component or a file. `properties` is a JSON object containing properties to be set when page is created. `sourcePage` must be active.

The function creates the new page asynchronously if the new `page` to be added is a Component or a QML document and the asynchronous property is set to true. 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 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.

    import QtQuick 2.4
    import Lomiri.Components

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

        Component {
            id: page2Component
            Page {
                header: PageHeader {
                    id: header
                    title: "Second Page"
                }
                Button {
                    anchors.top: header.bottom
                    text: "Close me"
                    onClicked: pageStack.removePages(pageStack.primaryPage);
                }
            }
        }

        AdaptivePageLayout {
            id: pageLayout
            anchors.fill: parent
            primaryPage: Page {
                header: PageHeader {
                    title: "Primary Page"
                    flickable: listView
                }
                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--;
                                        });
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }

See also Component.incubateObject.

object addPageToCurrentColumn(Item sourcePage, var[, var properties] page)

Adds a `page` to the column the `sourcePage` resides in and removes all pages from the higher columns. `page` can be a Component or a file. `properties` is a JSON object containing properties to be set when page is created. `sourcePage` must be active.

The function creates the new page asynchronously if the new `page` to be added is a Component or a QML document and the asynchronous property is set to true. 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 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.

    import QtQuick 2.4
    import Lomiri.Components 1.3

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

        Component {
            id: page2Component
            Page {
                header: PageHeader {
                    id: header
                    title: "Second Page"
                }
                Button {
                    anchors.top: header.bottom
                    text: "Close me"
                    onClicked: pageStack.removePages(pageStack.primaryPage);
                }
            }
        }

        AdaptivePageLayout {
            id: pageLayout
            anchors.fill: parent
            primaryPage: Page {
                header: PageHeader {
                    title: "Primary Page"
                    flickable: listView
                }
                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--;
                                        });
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }

See also Component.incubateObject.

Item addPageToNextColumn(Item sourcePage, var[, var properties] page)

Remove all previous pages from the next column (relative to the column that holds `sourcePage`) and all following columns, and then add `page` to the next column. If `sourcePage` is located in the rightmost column, the new page will be pushed to the same column as `sourcePage`. The return value is the same as in addPageToCurrentColumn case.

Item addPageToNextColumn(Item sourcePage, var[, var properties] page)

Remove all previous pages from the next column (relative to the column that holds `sourcePage`) and all following columns, and then add `page` to the next column. If `sourcePage` is located in the rightmost column, the new page will be pushed to the same column as `sourcePage`. The return value is the same as in addPageToCurrentColumn case.

void removePages(Item page)

The function removes and deletes all pages up to and including `page` is reached. If the page is the same as the primaryPage, only its child pages will be removed.

void removePages(Item page)

The function removes and deletes all pages up to and including `page` is reached. If the page is the same as the primaryPage, only its child pages will be removed.