Libplasma

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

KDE's Doxygen guidelines are available online.