org::kde::kirigami::PlaceholderMessage

org
kde
kirigami
PlaceholderMessage

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

Public Types
enum	Type { Actionable, Informational }

Properties
P	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 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"
    }
}

import org.kde.kirigami 2.12 as Kirigami
 
 Used as a loading indicator
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
        }
    }
}

import org.kde.kirigami 2.12 as Kirigami
 
 Used as a "Here's what you do next" button
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: {
                [...]
            }
        }
    }
}

Since: 2.12

Definition at line 142 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.

Note: It accepts icon.name and icon.source to set the icon source. It is suggested to use icon.name.

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

See also: org::kde::kirigami::private::ActionIconGroup

Since: 5.70

Definition at line 194 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: 5.80

Definition at line 181 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: 5.70

Definition at line 206 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: 5.70

Definition at line 170 of file PlaceholderMessage.qml.

◆ type

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

read

This property holds the PlaceholderMessage type.

The type of the message. This can be:

Kirigami.PlaceholderMessage.Type.Actionable: Makes it more attention-getting. Useful when the user is expected to interact with the message.
Kirigami.PlaceholderMessage.Type.Informational: Makes it less prominent. Useful when the message in only informational.

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