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 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 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 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 as Kirigami
99 *
100 ** Used as a "Here's what you do next" button
101 * Kirigami.Page {
102 * id: root
103 *
104 * Kirigami.PlaceholderMessage {
105 * anchors.centerIn: parent
106 * width: parent.width - (Kirigami.Units.largeSpacing * 4)
107 *
108 * visible: root.loading
109 *
110 * helpfulAction: Kirigami.Action {
111 * icon.name: "list-add"
112 * text: "Add item..."
113 * onTriggered: {
114 * [...]
115 * }
116 * }
117 * }
118 * }
119 * @endcode
120 * @inherit QtQuick.Layouts.ColumnLayout
121 * @since 2.12
122 */
123ColumnLayout {
124 id: root
125
126 enum Type {
127 Actionable,
128 Informational
129 }
130
131//BEGIN properties
132 /**
133 * @brief This property holds the PlaceholderMessage type.
134 *
135 * The type of the message. This can be:
136 * * ``Kirigami.PlaceholderMessage.Type.Actionable``: Makes it more attention-getting. Useful when the user is expected to interact with the message.
137 * * ``Kirigami.PlaceholderMessage.Type.Informational``: Makes it less prominent. Useful when the message in only informational.
138 *
139 * default: `if a helpfulAction is provided this will be of type Actionable otherwise of type Informational.`
140 *
141 * @since 5.94
142 */
143 property int type: actionButton.action?.enabled
144 ? PlaceholderMessage.Type.Actionable
145 : PlaceholderMessage.Type.Informational
146
147 /**
148 * @brief This property holds the text to show in the placeholder label.
149 *
150 * Optional; if not defined, the message will have no large text label
151 * text. If both text: and explanation: are omitted, the message will have
152 * no text and only an icon, action button, and/or other custom content.
153 *
154 * @since 5.70
155 */
156 property string text
157
158 /**
159 * @brief This property holds the smaller explanatory text to show below the larger title-style text
160 *
161 * Useful for providing a user-friendly explanation on how to proceed.
162 *
163 * Optional; if not defined, the message will have no supplementary
164 * explanatory text.
165 *
166 * @since 5.80
167 */
168 property string explanation
169
170 /**
171 * @brief This property provides an icon to display above the top text label.
172 * @note It accepts ``icon.name`` and ``icon.source`` to set the icon source.
173 * It is suggested to use ``icon.name``.
174 *
175 * Optional; if undefined, the message will have no icon.
176 * Falls back to `undefined` if the specified icon is not valid or cannot
177 * be loaded.
178 *
179 * @see org::kde::kirigami::private::ActionIconGroup
180 * @since 5.70
181 */
182 property P.ActionIconGroup icon: P.ActionIconGroup {}
184 /**
185 * @brief This property holds an action that helps the user proceed.
186 *
187 * Typically used to guide the user to the next step for adding
188 * content or items to an empty view.
190 * Optional; if undefined, no button will appear below the text label.
191 *
192 * @property QtQuick.Controls.Action helpfulAction
193 * @since 5.70
194 */
195 property alias helpfulAction: actionButton.action
196
197 /**
198 * This property holds the link embedded in the explanatory message text that
199 * the user is hovering over.
200 */
201 readonly property alias hoveredLink: label.hoveredLink
202
203 /**
204 * This signal is emitted when a link is hovered in the explanatory message
205 * text.
206 * @param The hovered link.
207 */
208 signal linkHovered(string link)
209
210 /**
211 * This signal is emitted when a link is clicked or tapped in the explanatory
212 * message text.
213 * @param The clicked or tapped link.
214 */
215 signal linkActivated(string link)
216//END properties
217
218 spacing: Kirigami.Units.largeSpacing
219
220 Component.onCompleted: _announce();
221 onVisibleChanged: {
222 _announce();
223 }
224 function _announce()
225 {
226 if (visible && Accessible.announce) {
227 // Accessible.announce was added in Qt 6.8.0
228 if (root.text.length > 0)
229 Accessible.announce(root.text);
230 if (root.explanation.length > 0)
231 Accessible.announce(root.explanation);
232 }
233 }
234
235 Kirigami.Icon {
236 visible: source !== undefined
237 opacity: 0.5
238
239 Layout.alignment: Qt.AlignHCenter
240 Layout.preferredWidth: Math.round(Kirigami.Units.iconSizes.huge * 1.5)
241 Layout.preferredHeight: Math.round(Kirigami.Units.iconSizes.huge * 1.5)
242
243 source: {
244 if (root.icon.source.length > 0) {
245 return root.icon.source
246 } else if (root.icon.name.length > 0) {
247 return root.icon.name
248 }
249 return undefined
250 }
251 }
252
253 Kirigami.Heading {
254 text: root.text
255 visible: text.length > 0
256
257 type: Kirigami.Heading.Primary
258 opacity: root.type === PlaceholderMessage.Type.Actionable ? 1 : 0.65
259
260
261 Layout.fillWidth: true
262 horizontalAlignment: Qt.AlignHCenter
263 verticalAlignment: Qt.AlignVCenter
264
265 wrapMode: Text.WordWrap
266 }
267
268 Kirigami.SelectableLabel {
269 id: label
270
271 text: root.explanation
272 visible: root.explanation.length > 0
273 opacity: root.type === PlaceholderMessage.Type.Actionable ? 1 : 0.65
274
275 horizontalAlignment: Qt.AlignHCenter
276 wrapMode: Text.WordWrap
277
278 Layout.fillWidth: true
279
280 onLinkHovered: link => root.linkHovered(link)
281 onLinkActivated: link => root.linkActivated(link)
282 }
283
284 QQC2.Button {
285 id: actionButton
286
287 Layout.alignment: Qt.AlignHCenter
288 Layout.topMargin: Kirigami.Units.gridUnit
289
290 visible: action?.enabled ?? false
291 }
292}
A placeholder message indicating that a view is empty.
Type type(const QSqlDatabase &db)
KIOCORE_EXPORT CopyJob * link(const QList< QUrl > &src, const QUrl &destDir, JobFlags flags=DefaultFlags)
QString label(StandardShortcut id)
qsizetype length() const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 19 2024 11:52:23 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.