Kirigami2

PlaceholderMessage.qml
1 /*
2  * SPDX-FileCopyrightText: 2020 by Nate Graham <[email protected]>
3  *
4  * SPDX-License-Identifier: LGPL-2.0-or-later
5  */
6 
7 import QtQuick 2.0
8 import QtQuick.Layouts 1.12
9 import QtQuick.Controls 2.12 as QQC2
10 
11 import org.kde.kirigami 2.12 as Kirigami
12 
13 import "private"
14 
15 /**
16  * A placeholder message indicating that a list view is empty. The message
17  * comprises a label with lightened text, an optional icon above the text, and
18  * an optional button below the text which can be used to easily show the user
19  * what to do next to add content to the view.
20  *
21  * The top-level component is a ColumnLayout, so additional components items can
22  * simply be added as child items and they will be positioned sanely.
23  *
24  * Example usage:
25  *
26  * @code{.qml}
27  ** used as a "this view is empty" message
28  * import org.kde.kirigami 2.12 as Kirigami
29  *
30  * ListView {
31  * id: listView
32  * model: [...]
33  * delegate: [...]
34  *
35  * Kirigami.PlaceholderMessage {
36  * anchors.centerIn: parent
37  * width: parent.width - (Kirigami.Units.largeSpacing * 4)
38  *
39  * visible: listView.count == 0
40  *
41  * text: "There are no items in this list"
42  * }
43  * }
44  * @endcode
45  * @code{.qml}
46  ** Used as a "here's how to proceed" message
47  * import org.kde.kirigami 2.12 as Kirigami
48  *
49  * ListView {
50  * id: listView
51  * model: [...]
52  * delegate: [...]
53  *
54  * Kirigami.PlaceholderMessage {
55  * anchors.centerIn: parent
56  * width: parent.width - (Kirigami.Units.largeSpacing * 4)
57  *
58  * visible: listView.count == 0
59  *
60  * text: "Add an item to proceed"
61  *
62  * helpfulAction: Kirigami.Action {
63  * icon.name: "list-add"
64  * text: "Add item..."
65  * onTriggered: {
66  * [...]
67  * }
68  * }
69  * }
70  * [...]
71  * }
72  * @endcode
73  * @code{.qml}
74  ** Used as a "there was a problem here" message
75  * import org.kde.kirigami 2.12 as Kirigami
76  *
77  * Kirigami.Page {
78  * id: root
79  * readonly property bool networkConnected: [...]
80  *
81  * Kirigami.PlaceholderMessage {
82  * anchors.centerIn: parent
83  * width: parent.width - (Kirigami.Units.largeSpacing * 4)
84  *
85  * visible: root.networkConnected
86  *
87  * icon.name: "network-disconnect"
88  * text: "Unable to load content
89  * explanation: "Please try again later"
90  * }
91  * }
92  * @endcode
93  * @code{.qml}
94  * import org.kde.kirigami 2.12 as Kirigami
95  *
96  ** Used as a loading indicator
97  * Kirigami.Page {
98  * id: root
99  * readonly property bool loading: [...]
100  * readonly property int completionStatus: [...]
101  *
102  * Kirigami.PlaceholderMessage {
103  * anchors.centerIn: parent
104  * width: parent.width - (Kirigami.Units.largeSpacing * 4)
105  *
106  * visible: root.loading
107  *
108  * icon.name: "my-awesome-app-icon"
109  * text: "Loading this awesome app"
110  *
111  * ProgressBar {
112  * Layout.preferredWidth: Kirigami.Units.gridUnit * 20
113  * value: root.completionStatus
114  * from: 0
115  * to: 100
116  * }
117  * }
118  * }
119  * @endcode
120  * @code{.qml}
121  * import org.kde.kirigami 2.12 as Kirigami
122  *
123  ** Used as a "Here's what you do next" button
124  * Kirigami.Page {
125  * id: root
126  *
127  * Kirigami.PlaceholderMessage {
128  * anchors.centerIn: parent
129  * width: parent.width - (Kirigami.Units.largeSpacing * 4)
130  *
131  * visible: root.loading
132  *
133  * helpfulAction: Kirigami.Action {
134  * icon.name: "list-add"
135  * text: "Add item..."
136  * onTriggered: {
137  * [...]
138  * }
139  * }
140  * }
141  * }
142  * @endcode
143  * @inherit QtQuick.Layouts.ColumnLayout
144  * @since 2.12
145  */
146 ColumnLayout {
147  id: root
148 
149  /**
150  * text: string
151  * The text to show as a placeholder label
152  *
153  * Optional; if not defined, the message will have no large text label
154  * text. If both text: and explanation: are omitted, the message will have
155  * no text and only an icon, action button, and/or other custom content.
156  *
157  * @since 5.70
158  */
159  property string text
160 
161  /**
162  * explanation: string
163  * Smaller explanatory text to show below the larger title-style text
164  *
165  * Useful for providing a user-friendly explanation for how to proceed.
166  *
167  * Optional; if not defined, the message will have no supplementary
168  * explanatory text.
169  *
170  * @since 5.80
171  */
172  property string explanation
173 
174  /**
175  * icon: QVariant
176  * The icon to show above the text label. Accepts "icon.name" and
177  * "icon.source"
178  *
179  * Optional; if undefined, the message will have no icon.
180  * Falls back to `undefined` if the specified icon is not valid or cannot
181  * be loaded.
182  *
183  * @since 5.70
184  * @see Icon::source
185  */
186  property ActionIconGroup icon: ActionIconGroup {}
187 
188  /**
189  * helpfulAction: QtQuickControls2 Action
190  * An action that helps the user proceed. Typically used to guide the user
191  * to the next step for adding content or items to an empty view.
192  *
193  * Optional; if undefined, no button will appear below the text label.
194  *
195  * @since 5.70
196  */
197  property alias helpfulAction: actionButton.action
198 
199  spacing: Kirigami.Units.largeSpacing
200 
201  Kirigami.Icon {
202 
203  Layout.alignment: Qt.AlignHCenter
204  Layout.preferredWidth: Kirigami.Units.iconSizes.huge
205  Layout.preferredHeight: Kirigami.Units.iconSizes.huge
206 
207  source: {
208  if (root.icon.source && root.icon.source.length > 0) {
209  return root.icon.source
210  } else if (root.icon.name && root.icon.name.length > 0) {
211  return root.icon.name
212  }
213  return undefined
214  }
215 
216  visible: source != undefined
217  opacity: 0.5
218  }
219 
220  Kirigami.Heading {
221  text: root.text
222  visible: root.text !== ""
223 
224  level: 2
225  opacity: 0.5
226 
227  Layout.fillWidth: true
228  horizontalAlignment: Qt.AlignHCenter
229 
230  wrapMode: Text.WordWrap
231  }
232 
233  QQC2.Label {
234  text: root.explanation
235  visible: root.explanation !== ""
236 
237  opacity: 0.5
238 
239  horizontalAlignment: Qt.AlignHCenter
240  wrapMode: Text.WordWrap
241 
242  Layout.fillWidth: true
243  }
244 
245  QQC2.Button {
246  id: actionButton
247 
248  Layout.alignment: Qt.AlignHCenter
249 
250  visible: action && action.enabled
251  }
252 }
Definition: icon.h:18
int largeSpacing
units.largeSpacing is the amount of spacing that should be used inside bigger UI elements, for example between an icon and the corresponding text.
Definition: units.h:111
IconSizes iconSizes
units.iconSizes provides access to platform-dependent icon sizing
Definition: units.h:95
A set of values to define semantically sizes and durations.
Definition: units.h:68
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sun Oct 24 2021 22:39:11 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.