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 2.0
0008 import QtQuick.Layouts 1.12
0009 import QtQuick.Controls 2.12 as QQC2
0010 import org.kde.kirigami 2.12 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 top-level component is a QtQuick.Layouts.ColumnLayout, so additional components items
0021 * can simply be added as child items and they will be positioned sanely.
0022 *
0023 * Example usage:
0024 ** Used as a "this view is empty" message
0025 * @code{.qml}
0026 * import org.kde.kirigami 2.12 as Kirigami
0027 *
0028 * ListView {
0029 * id: listView
0030 * model: [...]
0031 * delegate: [...]
0032 *
0033 * Kirigami.PlaceholderMessage {
0034 * anchors.centerIn: parent
0035 * width: parent.width - (Kirigami.Units.largeSpacing * 4)
0036 *
0037 * visible: listView.count === 0
0038 *
0039 * text: "There are no items in this list"
0040 * }
0041 * }
0042 * @endcode
0043 *
0044 ** Used as a "here's how to proceed" message:
0045 * @code{.qml}
0046 * import org.kde.kirigami 2.12 as Kirigami
0047 *
0048 * ListView {
0049 * id: listView
0050 * model: [...]
0051 * delegate: [...]
0052 *
0053 * Kirigami.PlaceholderMessage {
0054 * anchors.centerIn: parent
0055 * width: parent.width - (Kirigami.Units.largeSpacing * 4)
0056 *
0057 * visible: listView.count === 0
0058 *
0059 * text: "Add an item to proceed"
0060 *
0061 * helpfulAction: Kirigami.Action {
0062 * icon.name: "list-add"
0063 * text: "Add item..."
0064 * onTriggered: {
0065 * [...]
0066 * }
0067 * }
0068 * }
0069 * [...]
0070 * }
0071 * @endcode
0072 *
0073 ** Used as a "there was a problem here" message:
0074 * @code{.qml}
0075 * import org.kde.kirigami 2.12 as Kirigami
0076 *
0077 * Kirigami.Page {
0078 * id: root
0079 * readonly property bool networkConnected: [...]
0080 *
0081 * Kirigami.PlaceholderMessage {
0082 * anchors.centerIn: parent
0083 * width: parent.width - (Kirigami.Units.largeSpacing * 4)
0084 *
0085 * visible: root.networkConnected
0086 *
0087 * icon.name: "network-disconnect"
0088 * text: "Unable to load content
0089 * explanation: "Please try again later"
0090 * }
0091 * }
0092 * @endcode
0093 *
0094 ** Used as a loading indicator:
0095 * @code{.qml}
0096 * import org.kde.kirigami 2.12 as Kirigami
0097 *
0098 * Kirigami.Page {
0099 * id: root
0100 * readonly property bool loading: [...]
0101 * readonly property int completionStatus: [...]
0102 *
0103 * Kirigami.PlaceholderMessage {
0104 * anchors.centerIn: parent
0105 * width: parent.width - (Kirigami.Units.largeSpacing * 4)
0106 *
0107 * visible: root.loading
0108 *
0109 * icon.name: "my-awesome-app-icon"
0110 * text: "Loading this awesome app"
0111 *
0112 * ProgressBar {
0113 * Layout.preferredWidth: Kirigami.Units.gridUnit * 20
0114 * value: root.completionStatus
0115 * from: 0
0116 * to: 100
0117 * }
0118 * }
0119 * }
0120 * @endcode
0121 *
0122 ** Used as a "Here's what you do next" button:
0123 * @code{.qml}
0124 * import org.kde.kirigami 2.12 as Kirigami
0125 *
0126 * Kirigami.Page {
0127 * id: root
0128 *
0129 * Kirigami.PlaceholderMessage {
0130 * anchors.centerIn: parent
0131 * width: parent.width - (Kirigami.Units.largeSpacing * 4)
0132 *
0133 * visible: root.loading
0134 *
0135 * helpfulAction: Kirigami.Action {
0136 * icon.name: "list-add"
0137 * text: "Add item..."
0138 * onTriggered: {
0139 * [...]
0140 * }
0141 * }
0142 * }
0143 * }
0144 * @endcode
0145 * @see <a href="https://develop.kde.org/hig/patterns-content/placeholdermessage">KDE Human Interface Guidelines on Placeholder Messages</a>
0146 * @since org.kde.kirigami 2.12
0147 * @inherit QtQuick.Layouts.ColumnLayout
0148 */
0149 ColumnLayout {
0150 id: root
0151
0152 enum Type {
0153 Actionable,
0154 Informational
0155 }
0156
0157 //BEGIN properties
0158 /**
0159 * @brief This property holds the PlaceholderMessage type.
0160 *
0161 * The following values are allowed:
0162 * * ``Kirigami.PlaceholderMessage.Type.Actionable``: makes it more attention grabbing. Useful when the user is expected to interact with the message.
0163 * * ``Kirigami.PlaceholderMessage.Type.Informational``: makes it less prominent. Useful when the message is only informational.
0164 *
0165 * default: `if a ::helpfulAction is provided this will be of type Actionable otherwise of type Informational.`
0166 *
0167 * @since KDE Frameworks 5.94
0168 */
0169 property int type: actionButton.action && actionButton.action.enabled ? PlaceholderMessage.Type.Actionable : PlaceholderMessage.Type.Informational
0170
0171 /**
0172 * @brief This property holds the text to show in the placeholder label.
0173 *
0174 * Optional; if not defined, the message will have no large text label
0175 * text. If both text: and explanation: are omitted, the message will have
0176 * no text and only an icon, action button, and/or other custom content.
0177 *
0178 * @since KDE Frameworks 5.70
0179 */
0180 property string text
0181
0182 /**
0183 * @brief This property holds the smaller explanatory text to show below the larger title-style text
0184 *
0185 * Useful for providing a user-friendly explanation on how to proceed.
0186 *
0187 * Optional; if not defined, the message will have no supplementary
0188 * explanatory text.
0189 *
0190 * @since KDE Frameworks 5.80
0191 */
0192 property string explanation
0193
0194 /**
0195 * @brief This property provides an icon to display above the top text label.
0196 *
0197 * Optional; if undefined, the message will have no icon.
0198 * Falls back to `undefined` if the specified icon is not valid or cannot
0199 * be loaded.
0200 *
0201 * @since KDE Frameworks 5.70
0202 */
0203 property P.ActionIconGroup icon: P.ActionIconGroup {}
0204
0205 /**
0206 * @brief This property holds an action that helps the user proceed.
0207 *
0208 * Typically used to guide the user to the next step for adding
0209 * content or items to an empty view.
0210 *
0211 * Optional; if undefined, no button will appear below the text label.
0212 *
0213 * @property QtQuick.Controls.Action helpfulAction
0214 * @since KDE Frameworks 5.70
0215 */
0216 property alias helpfulAction: actionButton.action
0217 //END properties
0218
0219 spacing: Kirigami.Units.largeSpacing
0220
0221 Kirigami.Icon {
0222 visible: source !== undefined
0223 opacity: 0.5
0224
0225 Layout.alignment: Qt.AlignHCenter
0226 Layout.preferredWidth: Math.round(Kirigami.Units.iconSizes.huge * 1.5)
0227 Layout.preferredHeight: Math.round(Kirigami.Units.iconSizes.huge * 1.5)
0228
0229 source: {
0230 if (root.icon.source.length > 0) {
0231 return root.icon.source
0232 } else if (root.icon.name.length > 0) {
0233 return root.icon.name
0234 }
0235 return undefined
0236 }
0237 }
0238
0239 Kirigami.Heading {
0240 text: root.text
0241 visible: text.length > 0
0242
0243 type: Kirigami.Heading.Primary
0244 opacity: root.type === PlaceholderMessage.Type.Actionable ? 1 : 0.65
0245
0246
0247 Layout.fillWidth: true
0248 horizontalAlignment: Qt.AlignHCenter
0249 verticalAlignment: Qt.AlignVCenter
0250
0251 wrapMode: Text.WordWrap
0252 }
0253
0254 QQC2.Label {
0255 text: root.explanation
0256 visible: root.explanation !== ""
0257 opacity: root.type === PlaceholderMessage.Type.Actionable ? 1 : 0.65
0258
0259 horizontalAlignment: Qt.AlignHCenter
0260 wrapMode: Text.WordWrap
0261
0262 Layout.fillWidth: true
0263 }
0264
0265 QQC2.Button {
0266 id: actionButton
0267
0268 Layout.alignment: Qt.AlignHCenter
0269 Layout.topMargin: Kirigami.Units.gridUnit
0270
0271 visible: action && action.enabled
0272 }
0273 }