From e1475e090747088288b05279633d19f12ae257aa Mon Sep 17 00:00:00 2001 From: Nate Graham 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 + * + * 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