Kirigami2

ScrollablePage.qml
1 /*
2  * SPDX-FileCopyrightText: 2015 Marco Martin <[email protected]>
3  *
4  * SPDX-License-Identifier: LGPL-2.0-or-later
5  */
6 
7 import QtQuick 2.15
8 import QtQuick.Templates 2.15 as T
9 import QtQuick.Layouts 1.15
10 
11 import org.kde.kirigami 2.19
12 import org.kde.kirigami.templates 2.2 as KT
13 import "private"
14 
15 /**
16  * ScrollablePage is a Page that holds scrollable content, such as ListViews.
17  * Scrolling and scrolling indicators will be automatically managed.
18  *
19  * @code
20  * ScrollablePage {
21  * id: root
22  * //The rectangle will automatically be scrollable
23  * Rectangle {
24  * width: root.width
25  * height: 99999
26  * }
27  * }
28  * @endcode
29  *
30  * @warning Do not put a ScrollView inside of a ScrollablePage; children of a ScrollablePage are already inside a ScrollView.
31  *
32  * Another behavior added by this class is a "scroll down to refresh" behavior
33  * It also can give the contents of the flickable to have more top margins in order
34  * to make possible to scroll down the list to reach it with the thumb while using the
35  * phone with a single hand.
36  *
37  * Implementations should handle the refresh themselves as follows
38  *
39  * @code
40  * Kirigami.ScrollablePage {
41  * id: view
42  * supportsRefreshing: true
43  * onRefreshingChanged: {
44  * if (refreshing) {
45  * myModel.refresh();
46  * }
47  * }
48  * ListView {
49  * // NOTE: MyModel doesn't come from the components,
50  * // it's purely an example on how it can be used together
51  * // some application logic that can update the list model
52  * // and signals when it's done.
53  * model: MyModel {
54  * onRefreshDone: view.refreshing = false;
55  * }
56  * delegate: BasicListItem {}
57  * }
58  * }
59  * [...]
60  * @endcode
61  *
62  */
63 Page {
64  id: root
65 
66  /**
67  * \property bool ScrollablePage::refreshing
68  * If true the list is asking for refresh and will show a loading spinner.
69  * it will automatically be set to true when the user pulls down enough the list.
70  * This signals the application logic to start its refresh procedure.
71  * The application itself will have to set back this property to false when done.
72  */
73  property alias refreshing: scrollView.refreshing
74 
75  /**
76  * \property bool ScrollablePage::supportsRefreshing
77  * If true the list supports the "pull down to refresh" behavior.
78  * By default it is false.
79  */
80  property alias supportsRefreshing: scrollView.supportsRefreshing
81 
82  /**
83  * \property QtQuick.Flickable ScrollablePage::flickable
84  * The main Flickable item of this page.
85  */
86  property alias flickable: scrollView.flickableItem
87 
88  /**
89  * \property Qt.ScrollBarPolicy ScrollablePage::verticalScrollBarPolicy
90  * The vertical scrollbar policy.
91  */
92  property alias verticalScrollBarPolicy: scrollView.verticalScrollBarPolicy
93 
94  /**
95  * \property Qt.ScrollBarPolicy ScrollablePage::horizontalScrollBarPolicy
96  * The horizontal scrollbar policy.
97  */
98  property alias horizontalScrollBarPolicy: scrollView.horizontalScrollBarPolicy
99 
100  /**
101  * The main content Item of this page.
102  * In the case of a ListView or GridView, both contentItem and flickable
103  * will be a pointer to the ListView (or GridView).
104  * @note This can't be contentItem as Page's contentItem is final.
105  */
106  default property QtObject mainItem
107 
108  /**
109  * If true, and if flickable is an item view, like a ListView or
110  * a GridView, it will be possible to navigate the list current item
111  * to next and previous items with keyboard up/down arrow buttons.
112  * Also, any key event will be forwarded to the current list item.
113  * default is true.
114  */
115  property bool keyboardNavigationEnabled: true
116 
117  contentHeight: root.flickable.contentHeight
118  implicitHeight: ((header && header.visible) ? header.implicitHeight : 0) + ((footer && footer.visible) ? footer.implicitHeight : 0) + contentHeight + topPadding + bottomPadding
119  implicitWidth: root.flickable.contentItem ? root.flickable.contentItem.implicitWidth : contentItem.implicitWidth + leftPadding + rightPadding
120 
121  Theme.inherit: false
122  Theme.colorSet: flickable && flickable.hasOwnProperty("model") ? Theme.View : Theme.Window
123 
124  clip: true
125  contentItem: RefreshableScrollView {
126  id: scrollView
127  //NOTE: here to not expose it to public api
128  property QtObject oldMainItem
129  page: root
130  clip: true
131  topPadding: contentItem === flickableItem ? 0 : root.topPadding
132  leftPadding: root.leftPadding
133  rightPadding: root.rightPadding
134  bottomPadding: contentItem === flickableItem ? 0 : root.bottomPadding
135  anchors {
136  top: (root.header && root.header.visible)
137  ? root.header.bottom
138  //FIXME: for now assuming globalToolBarItem is in a Loader, which needs to be got rid of
139  : (globalToolBarItem && globalToolBarItem.parent && globalToolBarItem.visible
140  ? globalToolBarItem.parent.bottom
141  : parent.top)
142  bottom: (root.footer && root.footer.visible) ? root.footer.top : parent.bottom
143  left: parent.left
144  right: parent.right
145  }
146  }
147 
148  anchors.topMargin: 0
149 
150  Keys.forwardTo: root.keyboardNavigationEnabled && root.flickable
151  ? (("currentItem" in root.flickable) && root.flickable.currentItem ?
152  [ root.flickable.currentItem, root.flickable ] : [ root.flickable ])
153  : []
154 
155  //HACK to get the mainItem as the last one, all the other eventual items as an overlay
156  //no idea if is the way the user expects
157  onMainItemChanged: {
158  if (mainItem instanceof Item) {
159  scrollView.contentItem = mainItem
160  mainItem.focus = true
161  } else if (mainItem instanceof T.Drawer) {
162  //don't try to reparent drawers
163  return;
164  } else if (mainItem instanceof KT.OverlaySheet) {
165  //reparent sheets
166  if (mainItem.parent === root || mainItem.parent === null) {
167  mainItem.parent = root;
168  }
169  root.data.push(mainItem);
170  return;
171  }
172 
173  if (scrollView.oldMainItem && scrollView.oldMainItem instanceof Item
174  && (typeof applicationWindow === 'undefined'|| scrollView.oldMainItem.parent !== applicationWindow().overlay)) {
175  scrollView.oldMainItem.parent = overlay
176  }
177  scrollView.oldMainItem = mainItem
178  }
179 }
Flickable flickable
If the central element of the page is a Flickable (ListView and Gridview as well) you can set it ther...
Definition: Page.qml:32
QTextStream & left(QTextStream &s)
QTextStream & right(QTextStream &s)
Page is a container for all the app pages: everything pushed to the ApplicationWindow's pageStack sho...
Definition: Page.qml:20
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Fri May 20 2022 04:05:12 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.