Contents

ScrollablePage QML Type

ScrollablePage is a Page that holds scrollable content, such as a ListView. More...

Import Statement: import org.kde.kirigami
Inherits:

Page

Inherited By:

AboutPage

Properties

Methods

Detailed Description

Scrolling and scrolling indicators will be automatically managed.

Example usage:

ScrollablePage {
    id: root
    // The page will automatically be scrollable
    Rectangle {
        width: root.width
        height: 99999
    }
}

Warning: Do not put a ScrollView inside of a ScrollablePage; children of a ScrollablePage are already inside a ScrollView.

Another behavior added by this class is a "scroll down to refresh" behavior It also can give the contents of the flickable to have more top margins in order to make possible to scroll down the list to reach it with the thumb while using the phone with a single hand.

Implementations should handle the refresh themselves as follows.

Example usage:

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
        // some application logic that can update the list model
        // and signals when it's done.
        model: MyModel {
            onRefreshDone: view.refreshing = false;
        }
        delegate: ItemDelegate {}
    }
}
[...]

Property Documentation

horizontalScrollBarInteractive : bool

Set if the horizontal scrollbar should be interactable.


horizontalScrollBarPolicy : int

This property sets the horizontal scrollbar policy.

Possible values:

ConstantDescription
QQC2.ScrollBar.AsNeededThe scroll bar is only shown when the content is too large to fit.
QQC2.ScrollBar.AlwaysOffThe scroll bar is never shown.
QQC2.ScrollBar.AlwaysOnThe scroll bar is always shown.

The default value is ScrollBar.AlwaysOff

See also Qt::ScrollBarPolicy.


keyboardNavigationEnabled : bool

This property sets whether it is possible to navigate the items in a view that support it.

If true, and if flickable is an item view (e.g. ListView, GridView), it will be possible to navigate the view current items with keyboard up/down arrow buttons. Also, any key event will be forwarded to the current list item.

default: true


refreshing : bool

This property tells whether the list is asking for a refresh.

This property will automatically be set to true when the user pulls the list down enough, which in return, shows a loading spinner. When this is set to true, it signals the application logic to start its refresh procedure.

default: false

Note: The application itself will have to set back this property to false when done.


supportsRefreshing : bool

This property sets whether scrollable page supports "pull down to refresh" behaviour.

default: false


verticalScrollBarInteractive : bool

Set if the vertical scrollbar should be interactable.


verticalScrollBarPolicy : int

This property sets the vertical scrollbar policy.

Possible values:

ConstantDescription
QQC2.ScrollBar.AsNeededThe scroll bar is only shown when the content is too large to fit.
QQC2.ScrollBar.AlwaysOffThe scroll bar is never shown.
QQC2.ScrollBar.AlwaysOnThe scroll bar is always shown.

See also Qt.ScrollBarPolicy.


Method Documentation

ensureVisible(item, xOffset, yOffset)

This method checks whether a particular child item is in view, and scrolls the page to center the item if it is not.

If the page is a View, the view should handle this by itself, but if the page is a manually handled layout, this needs to be done manually. Otherwise, if the user passes focus to an item with e.g. keyboard navigation, this may be outside the visible area.

When called, this method will place the visible area such that the item at the center if any part of it is currently outside. If the item is larger than the viewable area in either direction, the area will be scrolled such that the top left corner is visible.

Kirigami.ScrollablePage {
    id: page
    ColumnLayout {
        Repeater {
            model: 100
            delegate: QQC2.Button {
                text: modelData
                onFocusChanged: if (focus) page.ensureVisible(this)
            }
        }
    }
}

item The item that should be in the visible area of the flickable. Item coordinates need to be in the flickable's coordinate system.

xOffset (optional) Offsets to align the item's and the flickable's coordinate system

yOffset (optional) Offsets to align the item's and the flickable's coordinate system