Scrollable pages and list views

#Kirigami.ScrollablePage

A Kirigami.ScrollablePage is a page that holds scrollable content, such as a ListView. Scrolling and scroll bars are managed automatically.

Kirigami.ScrollablePage {
    id: root
    // The rectangle will automatically be scrollable
    Rectangle {
        width: root.width
        implicitHeight: 99999
    }
}

The page works out how far its content can scroll from the implicitHeight of its children, so give them an implicit height: a child that only sets height doesn't make the page scrollable.

In almost every other way, a scrollable page is the same as a normal page.

Warning: Don't put a ScrollView inside a Kirigami.ScrollablePage: the children of a Kirigami.ScrollablePage are already inside a ScrollView.

#ListView in a ScrollablePage

When the direct children of a Kirigami.ScrollablePage extend vertically beyond the size of the page itself, a scroll bar appears at the right edge of the page and the page becomes scrollable.

Often you have more than one child in your Kirigami.ScrollablePage, and positioning items can be tricky, especially together with a ListView.

• Non-visual components don't change how the page looks when they are inside the ListView, so we can move them into the scope of the list view. The same goes for elements anchored to the center of the page, such as placeholder messages for empty list views.
• For other items, it may make sense to move them to the header or footer of the Kirigami.ScrollablePage. This is often the case for search bars.

#PlaceholderMessage

You can add a Kirigami.PlaceholderMessage with some instructions for when the list view is empty. Its helpfulAction adds a button the user can click.

Kirigami.ScrollablePage {
    ListView {
        id: listView
        Kirigami.PlaceholderMessage {
            anchors.centerIn: parent
            width: parent.width - (Kirigami.Units.largeSpacing * 4)
            visible: listView.count === 0
            text: i18n("No data found")
            helpfulAction: Kirigami.Action {
                text: i18n("Load data")
                // More code...
            }
        }
        model: // Model code...
    }
}

#Search in the ListView

A search field is often added to a Kirigami.ScrollablePage to filter the ListView. You can do this by replacing the default titleDelegate with a Kirigami.SearchField.

Kirigami.ScrollablePage {
    titleDelegate: Kirigami.SearchField {
        Layout.topMargin: Kirigami.Units.smallSpacing
        Layout.bottomMargin: Kirigami.Units.smallSpacing
        Layout.fillHeight: true
        Layout.fillWidth: true
        onTextChanged: mySortFilterModel.filterString = text
        KeyNavigation.tab: listView
    }

    ListView {
        id: listView
        // Rest of listview code...
    }
}

Hint: With KSortFilterProxyModel from KItemModels (import org.kde.kitemmodels) you can add filtering directly in QML, without any C++ code. Set its sourceModel and filterRoleName, use it as the list view's model, and the search field above filters it through filterString.

#Pull to refresh

ScrollablePage also provides a "pull to refresh" action. Turn it on with supportsRefreshing:

Kirigami.ScrollablePage {
    id: view
    supportsRefreshing: true
    onRefreshingChanged: {
        if (refreshing) {
            myModel.refresh();
        }
    }
    ListView {
        // NOTE: MyModel doesn't come from the components,
        // it's purely an example on how it can be used together with
        // some application logic that can update the list model
        // and signals when it's done.
        model: MyModel {
            id: myModel
            onRefreshDone: view.refreshing = false;
        }
        delegate: Controls.ItemDelegate {}
    }
}

Pulling the list down far enough and holding it briefly sets refreshing to true. A busy indicator stays above the list until your code sets refreshing back to false, as onRefreshDone does here.