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

KDE's Doxygen guidelines are available online.