org::kde::kirigami::PlaceholderMessage

Search for usage in LXR

org::kde::kirigami::PlaceholderMessage Class Reference
Inheritance diagram for org::kde::kirigami::PlaceholderMessage:

Public Types

enum  Type { Actionable, Informational }
 

Properties

ActionIconGroup
 
string explanation
 
alias helpfulAction
 
string text
 
int type
 

Detailed Description

A placeholder message indicating that a view is empty.

The message comprises a label with text, an optional explanation below the main text, an optional icon above all the text, and an optional button below all 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 QtQuick.Layouts.ColumnLayout, so additional components items can simply be added as child items and they will be positioned sanely.

Example usage: Used as a "this view is empty" message

import org.kde.kirigami 2.12 as Kirigami
ListView {
id: listView
model: [...]
delegate: [...]
Kirigami.PlaceholderMessage {
anchors.centerIn: parent
width: parent.width - (Kirigami.Units.largeSpacing * 4)
visible: listView.count === 0
text: "There are no items in this list"
}
}

Used as a "here's how to proceed" message:

import org.kde.kirigami 2.12 as Kirigami
ListView {
id: listView
model: [...]
delegate: [...]
Kirigami.PlaceholderMessage {
anchors.centerIn: parent
width: parent.width - (Kirigami.Units.largeSpacing * 4)
visible: listView.count === 0
text: "Add an item to proceed"
helpfulAction: Kirigami.Action {
icon.name: "list-add"
text: "Add item..."
onTriggered: {
[...]
}
}
}
[...]
}

Used as a "there was a problem here" message:

import org.kde.kirigami 2.12 as Kirigami
Kirigami.Page {
id: root
readonly property bool networkConnected: [...]
Kirigami.PlaceholderMessage {
anchors.centerIn: parent
width: parent.width - (Kirigami.Units.largeSpacing * 4)
visible: root.networkConnected
icon.name: "network-disconnect"
text: "Unable to load content
explanation: "Please try again later"
}
}

Used as a loading indicator:

import org.kde.kirigami 2.12 as Kirigami
Kirigami.Page {
id: root
readonly property bool loading: [...]
readonly property int completionStatus: [...]
Kirigami.PlaceholderMessage {
anchors.centerIn: parent
width: parent.width - (Kirigami.Units.largeSpacing * 4)
visible: root.loading
icon.name: "my-awesome-app-icon"
text: "Loading this awesome app"
ProgressBar {
Layout.preferredWidth: Kirigami.Units.gridUnit * 20
value: root.completionStatus
from: 0
to: 100
}
}
}

Used as a "Here's what you do next" button:

import org.kde.kirigami 2.12 as Kirigami
Kirigami.Page {
id: root
Kirigami.PlaceholderMessage {
anchors.centerIn: parent
width: parent.width - (Kirigami.Units.largeSpacing * 4)
visible: root.loading
helpfulAction: Kirigami.Action {
icon.name: "list-add"
text: "Add item..."
onTriggered: {
[...]
}
}
}
}
See also
KDE Human Interface Guidelines on Placeholder Messages
Since
org.kde.kirigami 2.12

Definition at line 147 of file PlaceholderMessage.qml.

Property Documentation

◆ ActionIconGroup

P org::kde::kirigami::PlaceholderMessage::ActionIconGroup
read

This property provides an icon to display above the top text label.

Optional; if undefined, the message will have no icon. Falls back to undefined if the specified icon is not valid or cannot be loaded.

Since
KDE Frameworks 5.70

Definition at line 196 of file PlaceholderMessage.qml.

◆ explanation

string org::kde::kirigami::PlaceholderMessage::explanation
read

This property holds the smaller explanatory text to show below the larger title-style text.

Useful for providing a user-friendly explanation on how to proceed.

Optional; if not defined, the message will have no supplementary explanatory text.

Since
KDE Frameworks 5.80

Definition at line 186 of file PlaceholderMessage.qml.

◆ helpfulAction

QtQuick Controls Action org::kde::kirigami::PlaceholderMessage::helpfulAction
read

This property holds 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; if undefined, no button will appear below the text label.

Since
KDE Frameworks 5.70

Definition at line 208 of file PlaceholderMessage.qml.

◆ text

string org::kde::kirigami::PlaceholderMessage::text
read

This property holds the text to show in the placeholder label.

Optional; if not defined, the message will have no large text label text. If both text: and explanation: are omitted, the message will have no text and only an icon, action button, and/or other custom content.

Since
KDE Frameworks 5.70

Definition at line 175 of file PlaceholderMessage.qml.

◆ type

int org::kde::kirigami::PlaceholderMessage::type
read

This property holds the PlaceholderMessage type.

The following values are allowed:

  • Kirigami.PlaceholderMessage.Type.Actionable: makes it more attention grabbing. Useful when the user is expected to interact with the message.
  • Kirigami.PlaceholderMessage.Type.Informational: makes it less prominent. Useful when the message is only informational.

default: if a ::helpfulAction is provided this will be of type Actionable otherwise of type Informational.

Since
KDE Frameworks 5.94

Definition at line 165 of file PlaceholderMessage.qml.


The documentation for this class was generated from the following file:
string text
This property holds the text to show in the placeholder label.
alias helpfulAction
This property holds an action that helps the user proceed.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Dec 8 2023 04:00:29 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.