path: root/kde-frameworks/plasma/files/plasma-5.71.0-introduce-PlaceholderMessage.patch

From e1475e090747088288b05279633d19f12ae257aa Mon Sep 17 00:00:00 2001
From: Nate Graham <nate@kde.org>
Date: Fri, 19 Jun 2020 22:45:19 +0000
Subject: [PATCH] Introduce PlaceholderMessage

This is a clone of the Kirigami component that we can use in Plasma
applets until we arrive at a solution for styling QQC2 items using the
Plasma style (https://phabricator.kde.org/T13256).

See dependent patches:
- plasma-workspace: https://invent.kde.org/plasma/plasma-workspace/-/merge_requests/73
- bluedevil: https://invent.kde.org/plasma/bluedevil/-/merge_requests/1
- print-manager: https://invent.kde.org/utilities/print-manager/-/merge_requests/1
- plasma-vault: https://invent.kde.org/plasma/plasma-vault/-/merge_requests/3

Merge request: https://invent.kde.org/frameworks/plasma-framework/-/merge_requests/13
---
 .../qml/PlaceholderMessage.qml                | 237 ++++++++++++++++++
 .../plasmaextracomponents/qml/qmldir          |   1 +
 2 files changed, 238 insertions(+)
 create mode 100644 src/declarativeimports/plasmaextracomponents/qml/PlaceholderMessage.qml

diff --git a/src/declarativeimports/plasmaextracomponents/qml/PlaceholderMessage.qml b/src/declarativeimports/plasmaextracomponents/qml/PlaceholderMessage.qml
new file mode 100644
index 000000000..958399a8f
--- /dev/null
+++ b/src/declarativeimports/plasmaextracomponents/qml/PlaceholderMessage.qml
@@ -0,0 +1,237 @@
+/*
+ *   Copyright 2020 Nate Graham <nate@kde.org>
+ *
+ *   This program is free software; you can redistribute it and/or modify
+ *   it under the terms of the GNU Library General Public License as
+ *   published by the Free Software Foundation; either version 2, or
+ *   (at your option) any later version.
+ *
+ *   This program is distributed in the hope that it will be useful,
+ *   but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *   GNU Library General Public License for more details
+ *
+ *   You should have received a copy of the GNU Library General Public
+ *   License along with this program; if not, write to the
+ *   Free Software Foundation, Inc.,
+ *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+
+import QtQuick 2.0
+import QtQuick.Layouts 1.12
+import QtQuick.Controls 2.12 as QQC2
+
+import org.kde.plasma.core 2.0 as PlasmaCore
+import org.kde.plasma.components 3.0 as PlasmaComponents3
+import org.kde.plasma.extras 2.0 as PlasmaExtras
+
+/**
+ * A placeholder message indicating that a list view is empty. The message
+ * comprises a label with lightened text, an optional icon above the text, and
+ * an optional button below the text which can be used to easily show the user
+ * what to do next to add content to the view.
+ *
+ * The top-level component is a ColumnLayout, so additional components items can
+ * simply be added as child items and they will be positioned sanely.
+ *
+ * Example usage:
+ *
+ * @code{.qml}
+ ** Shows how to use PlaceholderMessage to implement a "this view is empty" message
+ * import QtQuick 2.12
+ * import org.kde.plasma.extras 2.0 as PlasmaExtras
+ *
+ * ListView {
+ *     id: listView
+ *     model: [...]
+ *     delegate: [...]
+ *
+ *     PlasmaExtras.PlaceholderMessage {
+ *         anchors.centerIn: parent
+ *         width: parent.width - (units.largeSpacing * 4)
+ *
+ *         visible: listView.count == 0
+ *
+ *         text: "There are no items in this list"
+ *     }
+ * }
+ * @endcode
+ * @code{.qml}
+ ** Shows how to use PlaceholderMessage to implement a "here's how to proceed" message
+ * import QtQuick 2.12
+ * import QtQuick.Controls 2.12 as QQC2
+ * import org.kde.plasma.extras 2.0 as PlasmaExtras
+ *
+ * ListView {
+ *     id: listView
+ *     model: [...]
+ *     delegate: [...]
+ *
+ *     PlasmaExtras.PlaceholderMessage {
+ *         anchors.centerIn: parent
+ *         width: parent.width - (units.largeSpacing * 4)
+ *
+ *         visible: listView.count == 0
+ *
+ *         text: "Add an item to proceed"
+ *
+ *         helpfulAction: QQC2.Action {
+ *             icon.name: "list-add"
+ *             text: "Add item..."
+ *             onTriggered: {
+ *                 [...]
+ *             }
+ *         }
+ *     }
+ *     [...]
+ * }
+ * @endcode
+ * @code{.qml}
+ ** Shows how to use PlaceholderMessage to implement a "there was a problem here" message
+ * import org.kde.plasma.components 3.0 as PlasmaComponents3
+ * import org.kde.plasma.extras 2.0 as PlasmaExtras
+ *
+ * PlasmaComponents3.Page {
+ *     id: root
+ *     readonly property bool networkConnected: [...]
+ *
+ *     PlasmaExtras.PlaceholderMessage {
+ *         anchors.centerIn: parent
+ *         width: parent.width - (units.largeSpacing * 4)
+ *
+ *         visible: root.networkConnected
+ *
+ *         icon.name: "network-disconnect"
+ *         text: "Network disconnected; unable to load content"
+ *     }
+ * }
+ * @endcode
+ * @code{.qml}
+ * import org.kde.plasma.components 3.0 as PlasmaComponents3
+ * import org.kde.plasma.extras 2.0 as PlasmaExtras
+ *
+ ** Shows how to use PlaceholderMessage to implement a loading indicator
+ * PlasmaComponents3.Page {
+ *     id: root
+ *     readonly property bool loading: [...]
+ *     readonly property int completionStatus: [...]
+ *
+ *     PlasmaExtras.PlaceholderMessage {
+ *         anchors.centerIn: parent
+ *         width: parent.width - (units.largeSpacing * 4)
+ *
+ *         visible: root.loading
+ *
+ *         icon.name: "my-awesome-app-icon"
+ *         text: "Loading this awesome app"
+ *
+ *         PlasmaComponents3.ProgressBar {
+ *             Layout.preferredWidth: units.gridUnit * 20
+ *             value: root.completionStatus
+ *             from: 0
+ *             to: 100
+ *         }
+ *     }
+ * }
+ * @endcode
+ * @code{.qml}
+ * import QtQuick.Controls 2.12 as QQC2
+ * import org.kde.plasma.components 3.0 as PlasmaComponents3
+ * import org.kde.plasma.extras 2.0 as PlasmaExtras
+ *
+ ** Shows how to use PlaceholderMessage to implement a "Here's what you do next" button
+ * PlasmaComponents3.Page {
+ *     id: root
+ *
+ *     PlasmaExtras.PlaceholderMessage {
+ *         anchors.centerIn: parent
+ *         width: parent.width - (units.largeSpacing * 4)
+ *
+ *         visible: root.loading
+ *
+ *         helpfulAction: QQC2.Action {
+ *             icon.name: "list-add"
+ *             text: "Add item..."
+ *             onTriggered: {
+ *                 [...]
+ *             }
+ *         }
+ *     }
+ * }
+ * @endcode
+ * @since 5.72
+ */
+ColumnLayout {
+    id: root
+
+    /**
+     * text: string
+     * The text to show as a placeholder label
+     *
+     * Optional. Not setting any text is useful when you only want to display
+     * an icon, action button, and/or other custom content
+     *
+     * @since 5.72
+     */
+    property alias text: label.text
+
+    /**
+     * iconName: string
+     * The icon to show above the text label.
+     *
+     * Optional
+     * Falls back to `undefined` if the specified icon is not valid or cannot
+     * be loaded.
+     *
+     * @since 5.72
+     * @see Icon::source
+     */
+    property string iconName: string
+
+    /**
+     * helpfulAction: QtQuickControls2 Action
+     * An action that helps the user proceed. Typically used to guide the user
+     * to the next step for adding content or items to an empty view.
+     *
+     * Optional
+     *
+     * @since 5.72
+     */
+    property alias helpfulAction: actionButton.action
+
+    spacing: units.largeSpacing
+
+    PlasmaCore.IconItem {
+        visible: source != undefined
+        opacity: 0.5
+
+        Layout.alignment: Qt.AlignHCenter
+        Layout.preferredWidth: units.iconSizes.huge
+        Layout.preferredHeight: units.iconSizes.huge
+
+        source: root.iconName || null
+    }
+
+    PlasmaExtras.Heading {
+        id: label
+
+        visible: text.length > 0
+        opacity: 0.5
+
+        Layout.fillWidth: true
+        Layout.alignment: Qt.AlignHCenter
+        horizontalAlignment: Qt.AlignHCenter
+
+        level: 2
+
+        wrapMode: Text.WordWrap
+    }
+
+    PlasmaComponents3.Button {
+        id: actionButton
+
+        Layout.alignment: Qt.AlignHCenter
+
+        visible: action && action.enabled
+    }
+}
diff --git a/src/declarativeimports/plasmaextracomponents/qml/qmldir b/src/declarativeimports/plasmaextracomponents/qml/qmldir
index 4ba4ed7b7..6eb4af8a9 100644
--- a/src/declarativeimports/plasmaextracomponents/qml/qmldir
+++ b/src/declarativeimports/plasmaextracomponents/qml/qmldir
@@ -7,6 +7,7 @@ ExpandableListItem 2.0 ExpandableListItem.qml
 Heading 2.0 Heading.qml
 Paragraph 2.0 Paragraph.qml
 PageRow 2.0 PageRow.qml
+PlaceholderMessage 2.0 PlaceholderMessage.qml
 ScrollArea 2.0 ScrollArea.qml
 Title 2.0 Title.qml
 DescriptiveLabel 2.0 DescriptiveLabel.qml
-- 
2.27.0