Warning, /frameworks/kirigami/src/controls/PlaceholderMessage.qml is written in an unsupported language. File is not indexed.
0001 /*
0002 * SPDX-FileCopyrightText: 2020 by Nate Graham <nate@kde.org>
0003 *
0004 * SPDX-License-Identifier: LGPL-2.0-or-later
0005 */
0006
0007 import QtQuick
0008 import QtQuick.Layouts
0009 import QtQuick.Controls as QQC2
0010 import org.kde.kirigami as Kirigami
0011 import "private" as P
0012
0013 /**
0014 * @brief A placeholder message indicating that a view is empty.
0015 *
0016 * The message comprises a label with text, an optional explanation below the main text,
0017 * an optional icon above all the text, and an optional button below all the text which
0018 * can be used to easily show the user what to do next to add content to the view.
0019 *
0020 * The explanatory text is selectable and can contain clickable links. In this latter
0021 * case, client code must implement an ``onLinkactivated:`` signal handler or the links
0022 * will not work.
0023 *
0024 * The top-level component is a ColumnLayout, so additional components items can
0025 * simply be added as child items and they will be positioned sanely.
0026 *
0027 * Example usage:
0028 * @code{.qml}
0029 ** used as a "this view is empty" message
0030 * import org.kde.kirigami 2.12 as Kirigami
0031 *
0032 * ListView {
0033 * id: listView
0034 * model: [...]
0035 * delegate: [...]
0036 *
0037 * Kirigami.PlaceholderMessage {
0038 * anchors.centerIn: parent
0039 * width: parent.width - (Kirigami.Units.largeSpacing * 4)
0040 *
0041 * visible: listView.count === 0
0042 *
0043 * text: "There are no items in this list"
0044 * }
0045 * }
0046 * @endcode
0047 * @code{.qml}
0048 ** Used as a "here's how to proceed" message
0049 * import org.kde.kirigami 2.12 as Kirigami
0050 *
0051 * ListView {
0052 * id: listView
0053 * model: [...]
0054 * delegate: [...]
0055 *
0056 * Kirigami.PlaceholderMessage {
0057 * anchors.centerIn: parent
0058 * width: parent.width - (Kirigami.Units.largeSpacing * 4)
0059 *
0060 * visible: listView.count === 0
0061 *
0062 * text: "Add an item to proceed"
0063 *
0064 * helpfulAction: Kirigami.Action {
0065 * icon.name: "list-add"
0066 * text: "Add item..."
0067 * onTriggered: {
0068 * [...]
0069 * }
0070 * }
0071 * }
0072 * [...]
0073 * }
0074 * @endcode
0075 * @code{.qml}
0076 ** Used as a "there was a problem here" message
0077 * import org.kde.kirigami 2.12 as Kirigami
0078 *
0079 * Kirigami.Page {
0080 * id: root
0081 * readonly property bool networkConnected: [...]
0082 *
0083 * Kirigami.PlaceholderMessage {
0084 * anchors.centerIn: parent
0085 * width: parent.width - (Kirigami.Units.largeSpacing * 4)
0086 *
0087 * visible: root.networkConnected
0088 *
0089 * icon.name: "network-disconnect"
0090 * text: "Unable to load content"
0091 * explanation: "Please try again later."
0092 * " Visit <a href="https://foo.com/com>this link</a> for more details."
0093 * onLinkActivated: link => Qt.openUrlExternally(link)
0094 * }
0095 * }
0096 * @endcode
0097 * @code{.qml}
0098 * import org.kde.kirigami 2.12 as Kirigami
0099 *
0100 ** Used as a loading indicator
0101 * Kirigami.Page {
0102 * id: root
0103 * readonly property bool loading: [...]
0104 * readonly property int completionStatus: [...]
0105 *
0106 * Kirigami.PlaceholderMessage {
0107 * anchors.centerIn: parent
0108 * width: parent.width - (Kirigami.Units.largeSpacing * 4)
0109 *
0110 * visible: root.loading
0111 *
0112 * icon.name: "my-awesome-app-icon"
0113 * text: "Loading this awesome app"
0114 *
0115 * ProgressBar {
0116 * Layout.preferredWidth: Kirigami.Units.gridUnit * 20
0117 * value: root.completionStatus
0118 * from: 0
0119 * to: 100
0120 * }
0121 * }
0122 * }
0123 * @endcode
0124 * @code{.qml}
0125 * import org.kde.kirigami 2.12 as Kirigami
0126 *
0127 ** Used as a "Here's what you do next" button
0128 * Kirigami.Page {
0129 * id: root
0130 *
0131 * Kirigami.PlaceholderMessage {
0132 * anchors.centerIn: parent
0133 * width: parent.width - (Kirigami.Units.largeSpacing * 4)
0134 *
0135 * visible: root.loading
0136 *
0137 * helpfulAction: Kirigami.Action {
0138 * icon.name: "list-add"
0139 * text: "Add item..."
0140 * onTriggered: {
0141 * [...]
0142 * }
0143 * }
0144 * }
0145 * }
0146 * @endcode
0147 * @inherit QtQuick.Layouts.ColumnLayout
0148 * @since 2.12
0149 */
0150 ColumnLayout {
0151 id: root
0152
0153 enum Type {
0154 Actionable,
0155 Informational
0156 }
0157
0158 //BEGIN properties
0159 /**
0160 * @brief This property holds the PlaceholderMessage type.
0161 *
0162 * The type of the message. This can be:
0163 * * ``Kirigami.PlaceholderMessage.Type.Actionable``: Makes it more attention-getting. Useful when the user is expected to interact with the message.
0164 * * ``Kirigami.PlaceholderMessage.Type.Informational``: Makes it less prominent. Useful when the message in only informational.
0165 *
0166 * default: `if a helpfulAction is provided this will be of type Actionable otherwise of type Informational.`
0167 *
0168 * @since 5.94
0169 */
0170 property int type: actionButton.action?.enabled
0171 ? PlaceholderMessage.Type.Actionable
0172 : PlaceholderMessage.Type.Informational
0173
0174 /**
0175 * @brief This property holds the text to show in the placeholder label.
0176 *
0177 * Optional; if not defined, the message will have no large text label
0178 * text. If both text: and explanation: are omitted, the message will have
0179 * no text and only an icon, action button, and/or other custom content.
0180 *
0181 * @since 5.70
0182 */
0183 property string text
0184
0185 /**
0186 * @brief This property holds the smaller explanatory text to show below the larger title-style text
0187 *
0188 * Useful for providing a user-friendly explanation on how to proceed.
0189 *
0190 * Optional; if not defined, the message will have no supplementary
0191 * explanatory text.
0192 *
0193 * @since 5.80
0194 */
0195 property string explanation
0196
0197 /**
0198 * @brief This property provides an icon to display above the top text label.
0199 * @note It accepts ``icon.name`` and ``icon.source`` to set the icon source.
0200 * It is suggested to use ``icon.name``.
0201 *
0202 * Optional; if undefined, the message will have no icon.
0203 * Falls back to `undefined` if the specified icon is not valid or cannot
0204 * be loaded.
0205 *
0206 * @see org::kde::kirigami::private::ActionIconGroup
0207 * @since 5.70
0208 */
0209 property P.ActionIconGroup icon: P.ActionIconGroup {}
0210
0211 /**
0212 * @brief This property holds an action that helps the user proceed.
0213 *
0214 * Typically used to guide the user to the next step for adding
0215 * content or items to an empty view.
0216 *
0217 * Optional; if undefined, no button will appear below the text label.
0218 *
0219 * @property QtQuick.Controls.Action helpfulAction
0220 * @since 5.70
0221 */
0222 property alias helpfulAction: actionButton.action
0223
0224 /**
0225 * This property holds the link embedded in the explanatory message text that
0226 * the user is hovering over.
0227 */
0228 readonly property alias hoveredLink: label.hoveredLink
0229
0230 /**
0231 * This signal is emitted when a link is hovered in the explanatory message
0232 * text.
0233 * @param The hovered link.
0234 */
0235 signal linkHovered(string link)
0236
0237 /**
0238 * This signal is emitted when a link is clicked or tapped in the explanatory
0239 * message text.
0240 * @param The clicked or tapped link.
0241 */
0242 signal linkActivated(string link)
0243 //END properties
0244
0245 spacing: Kirigami.Units.largeSpacing
0246
0247 Kirigami.Icon {
0248 visible: source !== undefined
0249 opacity: 0.5
0250
0251 Layout.alignment: Qt.AlignHCenter
0252 Layout.preferredWidth: Math.round(Kirigami.Units.iconSizes.huge * 1.5)
0253 Layout.preferredHeight: Math.round(Kirigami.Units.iconSizes.huge * 1.5)
0254
0255 source: {
0256 if (root.icon.source.length > 0) {
0257 return root.icon.source
0258 } else if (root.icon.name.length > 0) {
0259 return root.icon.name
0260 }
0261 return undefined
0262 }
0263 }
0264
0265 Kirigami.Heading {
0266 text: root.text
0267 visible: text.length > 0
0268
0269 type: Kirigami.Heading.Primary
0270 opacity: root.type === PlaceholderMessage.Type.Actionable ? 1 : 0.65
0271
0272
0273 Layout.fillWidth: true
0274 horizontalAlignment: Qt.AlignHCenter
0275 verticalAlignment: Qt.AlignVCenter
0276
0277 wrapMode: Text.WordWrap
0278 }
0279
0280 Kirigami.SelectableLabel {
0281 id: label
0282
0283 text: root.explanation
0284 visible: root.explanation.length > 0
0285 opacity: root.type === PlaceholderMessage.Type.Actionable ? 1 : 0.65
0286
0287 horizontalAlignment: Qt.AlignHCenter
0288 wrapMode: Text.WordWrap
0289
0290 Layout.fillWidth: true
0291
0292 onLinkHovered: link => root.linkHovered(link)
0293 onLinkActivated: link => root.linkActivated(link)
0294 }
0295
0296 QQC2.Button {
0297 id: actionButton
0298
0299 Layout.alignment: Qt.AlignHCenter
0300 Layout.topMargin: Kirigami.Units.gridUnit
0301
0302 visible: action?.enabled ?? false
0303 }
0304 }