Kirigami2

PlaceholderMessage.qml
1/*
2 * SPDX-FileCopyrightText: 2020 by Nate Graham <nate@kde.org>
3 *
4 * SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6
7import QtQuick
8import QtQuick.Layouts
9import QtQuick.Controls as QQC2
10import org.kde.kirigami as Kirigami
11import "private" as P
12
13/**
14 * @brief A placeholder message indicating that a view is empty.
15 *
16 * The message comprises a label with text, an optional explanation below the main text,
17 * an optional icon above all the text, and an optional button below all the text which
18 * can be used to easily show the user what to do next to add content to the view.
19 *
20 * The explanatory text is selectable and can contain clickable links. In this latter
21 * case, client code must implement an ``onLinkactivated:`` signal handler or the links
22 * will not work.
23 *
24 * The top-level component is a ColumnLayout, so additional components items can
25 * simply be added as child items and they will be positioned sanely.
26 *
27 * Example usage:
28 * @code{.qml}
29 ** used as a "this view is empty" message
30 * import org.kde.kirigami 2.12 as Kirigami
31 *
32 * ListView {
33 * id: listView
34 * model: [...]
35 * delegate: [...]
36 *
37 * Kirigami.PlaceholderMessage {
38 * anchors.centerIn: parent
39 * width: parent.width - (Kirigami.Units.largeSpacing * 4)
40 *
41 * visible: listView.count === 0
42 *
43 * text: "There are no items in this list"
44 * }
45 * }
46 * @endcode
47 * @code{.qml}
48 ** Used as a "here's how to proceed" message
49 * import org.kde.kirigami 2.12 as Kirigami
50 *
51 * ListView {
52 * id: listView
53 * model: [...]
54 * delegate: [...]
55 *
56 * Kirigami.PlaceholderMessage {
57 * anchors.centerIn: parent
58 * width: parent.width - (Kirigami.Units.largeSpacing * 4)
59 *
60 * visible: listView.count === 0
61 *
62 * text: "Add an item to proceed"
63 *
64 * helpfulAction: Kirigami.Action {
65 * icon.name: "list-add"
66 * text: "Add item..."
67 * onTriggered: {
68 * [...]
69 * }
70 * }
71 * }
72 * [...]
73 * }
74 * @endcode
75 * @code{.qml}
76 ** Used as a "there was a problem here" message
77 * import org.kde.kirigami 2.12 as Kirigami
78 *
79 * Kirigami.Page {
80 * id: root
81 * readonly property bool networkConnected: [...]
82 *
83 * Kirigami.PlaceholderMessage {
84 * anchors.centerIn: parent
85 * width: parent.width - (Kirigami.Units.largeSpacing * 4)
86 *
87 * visible: root.networkConnected
88 *
89 * icon.name: "network-disconnect"
90 * text: "Unable to load content"
91 * explanation: "Please try again later."
92 * " Visit <a href="https://foo.com/com>this link</a> for more details."
93 * onLinkActivated: link => Qt.openUrlExternally(link)
94 * }
95 * }
96 * @endcode
97 * @code{.qml}
98 * import org.kde.kirigami 2.12 as Kirigami
99 *
100 ** Used as a loading indicator
101 * Kirigami.Page {
102 * id: root
103 * readonly property bool loading: [...]
104 * readonly property int completionStatus: [...]
105 *
106 * Kirigami.PlaceholderMessage {
107 * anchors.centerIn: parent
108 * width: parent.width - (Kirigami.Units.largeSpacing * 4)
109 *
110 * visible: root.loading
111 *
112 * icon.name: "my-awesome-app-icon"
113 * text: "Loading this awesome app"
114 *
115 * 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 org.kde.kirigami 2.12 as Kirigami
126 *
127 ** Used as a "Here's what you do next" button
128 * Kirigami.Page {
129 * id: root
130 *
131 * Kirigami.PlaceholderMessage {
132 * anchors.centerIn: parent
133 * width: parent.width - (Kirigami.Units.largeSpacing * 4)
134 *
135 * visible: root.loading
136 *
137 * helpfulAction: Kirigami.Action {
138 * icon.name: "list-add"
139 * text: "Add item..."
140 * onTriggered: {
141 * [...]
142 * }
143 * }
144 * }
145 * }
146 * @endcode
147 * @inherit QtQuick.Layouts.ColumnLayout
148 * @since 2.12
149 */
150ColumnLayout {
151 id: root
152
153 enum Type {
154 Actionable,
155 Informational
156 }
157
158//BEGIN properties
159 /**
160 * @brief This property holds the PlaceholderMessage type.
161 *
162 * The type of the message. This can be:
163 * * ``Kirigami.PlaceholderMessage.Type.Actionable``: Makes it more attention-getting. Useful when the user is expected to interact with the message.
164 * * ``Kirigami.PlaceholderMessage.Type.Informational``: Makes it less prominent. Useful when the message in only informational.
165 *
166 * default: `if a helpfulAction is provided this will be of type Actionable otherwise of type Informational.`
167 *
168 * @since 5.94
169 */
170 property int type: actionButton.action?.enabled
171 ? PlaceholderMessage.Type.Actionable
172 : PlaceholderMessage.Type.Informational
173
174 /**
175 * @brief This property holds the text to show in the placeholder label.
176 *
177 * Optional; if not defined, the message will have no large text label
178 * text. If both text: and explanation: are omitted, the message will have
179 * no text and only an icon, action button, and/or other custom content.
180 *
181 * @since 5.70
182 */
183 property string text
184
185 /**
186 * @brief This property holds the smaller explanatory text to show below the larger title-style text
187 *
188 * Useful for providing a user-friendly explanation on how to proceed.
189 *
190 * Optional; if not defined, the message will have no supplementary
191 * explanatory text.
192 *
193 * @since 5.80
194 */
195 property string explanation
196
197 /**
198 * @brief This property provides an icon to display above the top text label.
199 * @note It accepts ``icon.name`` and ``icon.source`` to set the icon source.
200 * It is suggested to use ``icon.name``.
201 *
202 * Optional; if undefined, the message will have no icon.
203 * Falls back to `undefined` if the specified icon is not valid or cannot
204 * be loaded.
205 *
206 * @see org::kde::kirigami::private::ActionIconGroup
207 * @since 5.70
208 */
209 property P.ActionIconGroup icon: P.ActionIconGroup {}
210
211 /**
212 * @brief This property holds an action that helps the user proceed.
213 *
214 * Typically used to guide the user to the next step for adding
215 * content or items to an empty view.
216 *
217 * Optional; if undefined, no button will appear below the text label.
218 *
219 * @property QtQuick.Controls.Action helpfulAction
220 * @since 5.70
221 */
222 property alias helpfulAction: actionButton.action
223
224 /**
225 * This property holds the link embedded in the explanatory message text that
226 * the user is hovering over.
227 */
228 readonly property alias hoveredLink: label.hoveredLink
229
230 /**
231 * This signal is emitted when a link is hovered in the explanatory message
232 * text.
233 * @param The hovered link.
234 */
235 signal linkHovered(string link)
236
237 /**
238 * This signal is emitted when a link is clicked or tapped in the explanatory
239 * message text.
240 * @param The clicked or tapped link.
241 */
242 signal linkActivated(string link)
243//END properties
244
245 spacing: Kirigami.Units.largeSpacing
246
247 Kirigami.Icon {
248 visible: source !== undefined
249 opacity: 0.5
250
251 Layout.alignment: Qt.AlignHCenter
252 Layout.preferredWidth: Math.round(Kirigami.Units.iconSizes.huge * 1.5)
253 Layout.preferredHeight: Math.round(Kirigami.Units.iconSizes.huge * 1.5)
254
255 source: {
256 if (root.icon.source.length > 0) {
257 return root.icon.source
258 } else if (root.icon.name.length > 0) {
259 return root.icon.name
260 }
261 return undefined
262 }
263 }
264
265 Kirigami.Heading {
266 text: root.text
267 visible: text.length > 0
268
269 type: Kirigami.Heading.Primary
270 opacity: root.type === PlaceholderMessage.Type.Actionable ? 1 : 0.65
271
272
273 Layout.fillWidth: true
274 horizontalAlignment: Qt.AlignHCenter
275 verticalAlignment: Qt.AlignVCenter
276
277 wrapMode: Text.WordWrap
278 }
279
280 Kirigami.SelectableLabel {
281 id: label
282
283 text: root.explanation
284 visible: root.explanation.length > 0
285 opacity: root.type === PlaceholderMessage.Type.Actionable ? 1 : 0.65
286
287 horizontalAlignment: Qt.AlignHCenter
288 wrapMode: Text.WordWrap
289
290 Layout.fillWidth: true
291
292 onLinkHovered: link => root.linkHovered(link)
293 onLinkActivated: link => root.linkActivated(link)
294 }
295
296 QQC2.Button {
297 id: actionButton
298
299 Layout.alignment: Qt.AlignHCenter
300 Layout.topMargin: Kirigami.Units.gridUnit
301
302 visible: action?.enabled ?? false
303 }
304}
Type type(const QSqlDatabase &db)
KIOCORE_EXPORT CopyJob * link(const QList< QUrl > &src, const QUrl &destDir, JobFlags flags=DefaultFlags)
QString label(StandardShortcut id)
int length() const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sun Feb 25 2024 18:45:17 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.