Nova Flow OS
KDE Developer Platform
KDE Developer Platform
  • KDE Developer Platform
    • Getting started
      • Building KDE software
        • KDE software
        • Where to find the development team
        • Learning more
        • Choose what to work on
        • Source code cross-referencing
        • Installing build dependencies
        • Set up a development environment
        • Building KDE software with kdesrc-build
        • Basic troubleshooting
        • Tips and tricks
        • IDE Configuration
          • Setting up an IDE for KDE development
          • Visual Studio Code
          • Qt Creator
          • Kate
          • KDevelop
          • CLion
          • Sublime Text
        • Building KDE software manually
        • Building KDE software with distrobox and podman
      • Kirigami
        • KDE is ours
        • Setting up and getting started
        • Explaining pages
        • Layouts, ListViews, and Cards
        • Adding actions
        • Adding a dialog
        • Using separate files
        • Next steps
        • Colors and themes in Kirigami
        • Typography
        • Actions based components
        • Page rows and page stacks
        • Scrollable pages and list views
        • Cards
        • Drawers
        • Chips
        • Dialog types
        • Controls and interactive elements
        • Form layouts
        • Inline messages
        • Action toolbars
        • Progress bars and indicators
        • List views
        • Understanding CMakeLists
        • Figuring out main.cpp
        • Connect logic to your QML user interface
        • Connect models to your QML user interface
        • About page
        • Introduction to Kirigami Addons
        • FormCard About pages
        • Form delegates in your settings pages
      • KXmlGui
        • Getting started with KXmlGui
        • Hello World!
        • Creating the main window
        • Using actions
        • Saving and loading
        • Command line interface
      • Python with Kirigami
        • Apps with QML and Python
        • Your first Python + Kirigami application
        • Creating a Python package
        • Creating a Flatpak
      • Common programming mistakes
      • Adding a new KDE project
    • Features
      • Icons
      • Configuration
        • The KConfig Framework
        • Introduction to KConfig
        • Using KConfig XT
        • KDE Frameworks 6 porting guide
        • Settings module (KCM) development
        • KConfigDialog
      • D-Bus
        • What is D-Bus practically useful for?
        • Introduction to D-Bus
        • Accessing D-Bus interfaces
        • Intermediate D-Bus
        • Creating D-Bus interfaces
        • Using custom types with D-Bus
        • D-Bus autostart services
      • Create your own mouse cursor theme
      • Session management
      • Archives
      • Desktop file
      • KAuth
        • Privilege Escalation
        • Using actions in your applications
      • KIdleTime
      • Akonadi: personal information management
        • Debugging Akonadi Resources
        • Using Akonadi in applications
      • Concurrent programming
      • Solid
      • Sonnet
    • Plasma themes and plugins
      • Getting started
      • Plasma Widget tutorial
        • How to create a plasmoid
        • Setup
        • Porting Plasmoids to KF6
        • Testing
        • QML
        • Plasma's QML API
        • Widget Properties
        • Configuration
        • Translations / i18n
        • Examples
        • C++ API
      • KWin Effects
      • Plasma Desktop scripting
        • Javascript Interaction With Plasma Shells
        • Templates
        • Examples
        • API documentation
        • Configuration keys
      • Plasma Style tutorial
        • Creating a Plasma Style quickstart
        • Understanding Plasma Styles
        • SVG elements and Inkscape
        • Background SVG format
        • System and accent colors
        • Theme elements reference
        • Porting themes to Plasma 5
        • Porting themes to Plasma 6
      • Aurorae window decorations
      • KWin scripting tutorial
        • Quick start
        • KWin scripting API
      • Wallpapers
      • Plasma comic
        • Tutorial
        • Testing and debugging
        • Examples
      • Create a custom Window Switcher
      • KRunner C++ Plugin
        • Basic Anatomy of a Runner
        • KRunner metadata format
    • Applications
      • Creating sensor faces
      • Dolphin
        • Creating Dolphin service menus
      • Kate
        • Kate plugin tutorial
      • KMines
        • Making a KMines theme
      • Writing tests
        • Appium automation testing
    • Packaging
      • Android
        • KDE on Android
        • Building applications for Android
        • Packaging and publishing applications for Android
        • Publishing on Google Play
          • Introduction
          • Packaging your app
          • Adding your app to Google Play
          • Publishing your app
          • Releasing new versions of old apps
        • Porting applications to Android
          • Basic porting
          • Making applications run well on Android
          • Metadata
      • Windows
        • Packaging and publishing applications for Windows
        • Publish your app in the Microsoft Store
          • Packaging your app for the Microsoft Store
          • Submitting your app to the Microsoft Store
      • Plasma Mobile
        • KDE on mobile devices
        • Porting a new device to Plasma Mobile
        • KDE Telephony stack
          • General Overview
          • Kernel layer
          • System daemons
            • General overview
            • Developing Telephony functionality
            • ModemManager Telephony functions
          • Session daemons
          • QML declarative plugin layer
          • KDE application layer
        • Execute applications
      • Distributing KDE software as Flatpak
        • Your first Flatpak
        • Extending your package
        • Nightly Flatpaks and Flathub
        • Testing your Flatpak
    • System administration
      • Shell scripting with KDE dialogs
      • Kiosk: Simple configuration management for large deployment
        • Abstract
        • Introduction to Kiosk
        • Kiosk keys
    • Contribute to the documentation
    • About
      • Readme
      • License
        • Creative Commons Attribution-ShareAlike 4.0 International
        • GNU General Public License 3.0 or later
Powered by GitBook
On this page
  • Plasmoid property group
  • metadata.json
  1. KDE Developer Platform
  2. Plasma themes and plugins
  3. Plasma Widget tutorial

Widget Properties

A rundown of the QML Properties in a widget

PreviousPlasma's QML APINextConfiguration

Last updated 8 months ago

Plasmoid property group

As discussed in , when you import org.kde.plasma.plasmoid 2.0, the main Item in your widget will have the Plasmoid (with a capital) property group similar to when you import QtQuick.Layouts 1.0. This Plasmoid has properties from which inherits a few properties from .

plasmoid context property

You can reference a property from the Plasmoid.___ property group by the root Item { id: widget } of the widget with widget.Plasmoid.___. An easier method is to use the global context property plasmoid (lowercase) which is when the property group is imported.

contents/ui/main.qml

import QtQuick 2.0
import org.kde.plasma.components 3.0 as PlasmaComponents3
import org.kde.plasma.plasmoid 2.0
Item {
    id: widget
    Plasmoid.icon: 'starred-symbolic'
    Plasmoid.fullRepresentation: PlasmaComponents3.Label {
        text: plasmoid.icon
        // OR
        // text: widget.Plasmoid.icon
    }
}

Plasmoid properties

Property
Type
Notes

Plasmoid.activationTogglesExpanded

bool

Plasmoid.apiVersion

int

Plasmoid.associatedApplication

string

Plasmoid.associatedApplicationUrls

QList<QUrl>

Plasmoid.availableScreenRect

Plasmoid.availableScreenRegion

QVariantList

Plasmoid.backgroundHints

Plasmoid.busy

bool

Draw the [BusyIndicator]({{< ref "plasma-qml-api#busyindicator" >}}) overtop the widget.

Plasmoid.compactRepresentation

Plasmoid.compactRepresentationItem

The instance of the compactRepresentation Component. May be null on load if not visible.

Plasmoid.configuration

Plasmoid.configurationRequired

bool

Wither to show a Configure button on top of the compact/full representation. It may look better to create your own button that calls plasmoid.action("configure").trigger().

Plasmoid.configurationRequiredReason

string

Not currently implemented to do anything.

Plasmoid.constraintHints

Plasmoid.containmentDisplayHints

Plasmoid.contextualActions

QList<QObject*>

Plasmoid.currentActivity

string

Plasmoid.editMode

bool

Only available to Containments like the "panel" widget. Used to toggle the global widget editing mode.

Plasmoid.effectiveBackgroundHints

Plasmoid.expanded

bool

Plasmoid.formFactor

Plasmoid.fullRepresentation

Plasmoid.fullRepresentationItem

The instance of the fullRepresentation Component. Since widget popup's a lazy loaded, it is null until the popup is opened.

Plasmoid.globalShortcut

Plasmoid.hideOnWindowDeactivate

bool

Set to false to "pin" the widget's full representation dialog open when out of focus.

Plasmoid.icon

string

Plasmoid.id

uint

This is an integer representing the widget instance. See Plasmoid.metaData.pluginId for the widget namespace.

Plasmoid.immutability

Detect if Kiosk mode has locked the widgets, or the user Lock Widget mode from Plasma 5.18 and below.

Plasmoid.immutable

bool

true if either UserImmutable or SystemImmutable.

Plasmoid.loading

bool

Always false when widget is running.

Plasmoid.location

Location of widget on the screen.

Plasmoid.metaData

Plasmoid.metaData.authors

QVariantList

Plasmoid.metaData.category

string

Plasmoid.metaData.copyrightText

string

Plasmoid.metaData.dependencies

QStringList

Plasmoid.metaData.description

string

Plasmoid.metaData.extraInformation

string

Plasmoid.metaData.fileName

string

Plasmoid.metaData.formFactors

QStringList

Plasmoid.metaData.iconName

string

Plasmoid.metaData.initialPreference

int

Plasmoid.metaData.isEnabledByDefault

bool

Plasmoid.metaData.isHidden

bool

Plasmoid.metaData.isValid

bool

Plasmoid.metaData.license

string

Plasmoid.metaData.licenseText

string

Plasmoid.metaData.metaDataFileName

string

Plasmoid.metaData.mimeTypes

QStringList

Plasmoid.metaData.name

string

The translated widget Name. Also see Plasmoid.title

Plasmoid.metaData.otherContributors

QVariantList

Plasmoid.metaData.pluginId

string

Plasmoid.metaData.rawData

QJsonObject

Plasmoid.metaData.serviceTypes

QStringList

Plasmoid.metaData.translators

QVariantList

Plasmoid.metaData.version

string

Reads Version in metadata.json or X-KDE-PluginInfo-Version in metadata.desktop.

Plasmoid.metaData.website

string

Plasmoid.nativeInterface

QObject

[Documentation]({{< ref "c-api.md#plasmoidnativeinterface" >}}). Provides access to C++ properties by extending Plasma::Applet like the SystemTray.

Plasmoid.pluginName

string

Plasmoid.preferredRepresentation

Plasmoid.rootItem

QObject

Reference the widget's root item. Cannot be used in the config dialog.

Plasmoid.screen

int

Plasmoid.screenGeometry

Plasmoid.self

AppletInterface

Plasmoid.status

Plasmoid.switchHeight

int

The minimum height required to switch to fullRepresentation.

Plasmoid.switchWidth

int

The minimum width required to switch to fullRepresentation.

Plasmoid.title

string

The translated widget name.

Plasmoid.toolTipItem

Plasmoid.toolTipMainText

string

The mainText in the default tooltip layout.

Plasmoid.toolTipSubText

string

The subText in the default tooltip layout.

Plasmoid.toolTipTextFormat

int

Plasmoid.userBackgroundHints

Plasmoid.userConfiguring

bool

Plasmoid.compactRepresentation

Plasmoid.fullRepresentation

Plasmoid.preferredRepresentation: Plasmoid.fullRepresentation
  • Set Layout.preferredWidth and Layout.preferredHeight in your full representation Item to change to dialog size.

contents/ui/main.qml

import QtQuick 2.0
import QtQuick.Layouts 1.0
import org.kde.plasma.core 2.0 as PlasmaCore
import org.kde.plasma.components 2.0 as PlasmaComponents
import org.kde.plasma.plasmoid 2.0

Item {
    // Always display the compact view.
    // Never show the full popup view even if there is space for it.
    Plasmoid.preferredRepresentation: Plasmoid.compactRepresentation

    Plasmoid.fullRepresentation: Item {
        Layout.minimumWidth: label.implicitWidth
        Layout.minimumHeight: label.implicitHeight
        Layout.preferredWidth: 640 * PlasmaCore.Units.devicePixelRatio
        Layout.preferredHeight: 480 * PlasmaCore.Units.devicePixelRatio
        
        PlasmaComponents.Label {
            id: label
            anchors.fill: parent
            text: "Hello World!"
            horizontalAlignment: Text.AlignHCenter
        }
    }
}

Plasmoid.icon

To set a dynamic or user configurable icon, you will need to assign an icon name to Plasmoid.icon.

Also checkout the configurable panel icon example

contents/ui/main.qml

import QtQuick 2.0
import org.kde.plasma.plasmoid 2.0

Item {
    id: widget
    property bool hasUnread: true
    Plasmoid.icon: hasUnread ? "mail-unread" : "mail-message"

    Timer {
        interval: 1000
        repeat: true
        running: true
        onTriggered: widget.hasUnread = !widget.hasUnread
    }
}

Plasmoid.configuration

This property provides access to the values user configurable values. You can easily access config values with plasmoid.configuration.varName. By default it populates with the keys and values in config/main.xml. You can easily write to plasmoid.configuration.varName = "value" to change the value for the user.

Read more about configuration and the config dialog in it's section of the tutorial.

The user's configuration is serialized to ~/.config/plasma-org.kde.plasma.desktop-appletsrc when the plasmashell process terminates and is only loaded at startup.

Since: KDE Frameworks 5.78, you can reference the default value of plasmoid.configuration.varName with plasmoid.configuration.varNameDefault.

contents/ui/main.qml

import QtQuick 2.0
import org.kde.plasma.components 3.0 as PlasmaComponents3
import org.kde.plasma.plasmoid 2.0

RowLayout {
    id: widget
    PlasmaComponents.Label {
        text: i18np("%1 Click", "%1 Clicks", plasmoid.configuration.numClicked)
    }
    PlasmaComponents3.Button {
        icon.name: "value-increase-symbolic"
        text: i18n("Add")
        onClicked: plasmoid.configuration.numClicked += 1
    }
}

Plasmoid.backgroundHints

  • PlasmaCore.Types.DefaultBackground (default) is equal to StandardBackground.

  • PlasmaCore.Types.TranslucentBackground An alternate version of the background is drawn, usually more translucent.

To use ConfigurableBackground, combine the flag with another value with the bitwise OR operator |.

PlasmaCore.Types.NoBackground | PlasmaCore.Types.ConfigurableBackground

Note: For ShadowBackground, make sure you use PlasmaCore.ColorScope.colorGroup in your IconItem to have the symbolic icons follow the text color.

PlasmaCore.IconItem {
    colorGroup: PlasmaCore.ColorScope.colorGroup
}

contents/ui/main.qml

import QtQuick 2.0
import org.kde.plasma.core 2.0 as PlasmaCore
import org.kde.plasma.plasmoid 2.0

Item {
    id: widget
    Plasmoid.backgroundHints: PlasmaCore.Types.NoBackground
}

contents/ui/main.qml

import QtQuick 2.0
import QtQuick.Layouts 1.0
import org.kde.plasma.core 2.0 as PlasmaCore
import org.kde.plasma.components 2.0 as PlasmaComponents3
import org.kde.plasma.plasmoid 2.0

Item {
    id: widget
    Plasmoid.icon: 'starred-symbolic'
    Plasmoid.backgroundHints: PlasmaCore.Types.StandardBackground | PlasmaCore.Types.ConfigurableBackground
    // Plasmoid.backgroundHints: PlasmaCore.Types.ShadowBackground | PlasmaCore.Types.ConfigurableBackground
    // Plasmoid.backgroundHints: PlasmaCore.Types.NoBackground | PlasmaCore.Types.ConfigurableBackground

    Plasmoid.preferredRepresentation: Plasmoid.fullRepresentation
    Plasmoid.fullRepresentation: RowLayout {
        PlasmaCore.IconItem {
            source: plasmoid.icon
            colorGroup: PlasmaCore.ColorScope.colorGroup
            Layout.fillHeight: true
            Layout.preferredWidth: height
        }
        PlasmaComponents3.Label {
            text: "Text"
            font.pointSize: 30
        }
    }
}

metadata.json

metadata.desktop is the older format while metadata.json is the newer replacement format. The .desktop file is simpler to script using kreadconfig5 which is the reason why this tutorial prefers it in certain places like translations.

Name, Description

metadata.json

{
    "KPlugin": {
        "Description": "Month display with your appointments and events",
        "Description[fr]": "Vue mensuelle avec vos rendez-vous et évènements",
        "Name": "Calendar",
        "Name[fr]": "Calendrier"
    }
}

metadata.desktop

[Desktop Entry]
Name=Calendar
Name[fr]=Calendrier
Comment=Month display with your appointments and events
Comment[fr]=Vue mensuelle avec vos rendez-vous et évènements

Icon

Icon is the icon name associated with the widget. You can search for icon names in the /usr/share/icon folder. You can also look for an icon name by right clicking your app launcher widget then editing the icon in its settings. It uses a searchable interface and lists them by category. Plasma's SDK also has the Cuttlefish app which you can install with sudo apt install plasma-sdk.

metadata.json

{
    "KPlugin": {
        "Icon": "office-calendar",
    }
}

metadata.desktop

[Desktop Entry]
Icon=office-calendar

Id

The Id (or X-KDE-PluginInfo-Name in metadata.desktop) needs to be a unique name, since it's used for the folder name it's installed into. You could use com.github.zren.helloworld if you're on github, or use org.kde.plasma.helloworld if you are planning on contributing the widget to KDE. You should consider this the widget's namespace.

To view the currently installed namespaces use:

❯ kpackagetool5 --type Plasma/Applet --list
Listing service types: Plasma/Applet in ~/.local/share/plasma/plasmoids/
com.github.zren.helloworld

❯ kpackagetool5 --type Plasma/Applet --list --global
Listing service types: Plasma/Applet in /usr/share/plasma/plasmoids/
org.kde.desktopcontainment
org.kde.kdeconnect
org.kde.kscreen
org.kde.milou
org.kde.panel
org.kde.plasma.activitybar
org.kde.plasma.activitypager
org.kde.plasma.addons.katesessions
...
~/.local/share/plasma/plasmoids/com.github.zren.helloworld/
/usr/share/plasma/plasmoids/com.github.zren.helloworld/

metadata.json

{
    "KPlugin": {
        "Id": "com.github.zren.helloworld",
    }
}

metadata.desktop

[Desktop Entry]
X-KDE-PluginInfo-Name=com.github.zren.helloworld

Category

The Category (or X-KDE-PluginInfo-Category in metadata.desktop) is used to filter widgets in the widget list.

metadata.json

{
    "KPlugin": {
        "Category": "Date and Time",
    }
}

metadata.desktop

[Desktop Entry]
X-KDE-PluginInfo-Category=Date and Time
  • Accessibility: tools that help those with special needs or disabilities use their computer

  • Application Launchers: application starters and file openers.

  • Astronomy: anything to do with the night sky or other celestial bodies.

  • Date and Time: clocks, calendars, scheduling, etc

  • Development Tools: tools and utilities to aid software developers

  • Education: teaching and educational aides

  • Environment and Weather: add-ons that display information regarding the weather or other environmentally related data

  • Examples: samples that are not meant for production systems

  • File System: anything that operates on files or the file system as its primary purpose, such as file watchers or directory listings. Simply using a file as storage does not qualify the add-on for this category.

  • Fun and Games: for games and amusements

  • Graphics: for add-ons where displaying images, photos or graphical eye candy is the primary purpose

  • Language: add-ons whose primary purpose is language related, such as dictionaries and translators.

  • Mapping: geography and geographic data add-ons

  • Multimedia: music and video.

  • Online Services: add-ons that provide an interface to online services such as social networking or blogging sites. If there is another more appropriate category for the add-on given the topic (e.g. mapping if the applet's purpose is to show maps), even if the data is retrieved from the Internet prefer that other category over this one.

  • System Information: display and interaction with information about the computer such as network activity, hardware health, memory usage, etc

  • Utilities: Useful tools like calculators

  • Windows and Tasks: managers for application windows and/or tasks, such as taskbars

KPackageStructure

Note In desktop files, the ServiceTypes key was defined instead. This key is however deprecated and desktop files will no longer be supported in KF6. To convert a desktop file to json, you can run the desktoptojson -i metadata.json command. The ServiceTypes -> KPackageStructure change must be done manually

metadata.json

{
    "KPackageStructure": "Plasma/Applet"
}

metadata.desktop

[Desktop Entry]
X-KDE-ServiceTypes=Plasma/Applet

X-Plasma-API, X-Plasma-MainScript

X-Plasma-API tells plasma what script engine to use. declarativeappletscript is the standard QML loader.

X-Plasma-MainScript is the entry point of your qml code. The default value is ui/main.qml.

Note In Plasma 6, it is no longer possible to specify a custom mainscript. Instead, `ui/main.qml` is used as the entry point. The `X-Plasma-MainScript` entry may be omitted from the metadata in both Plasma 5 and 6. `X-Plasma-API` may also be removed in KF6, but is needed in KF5.

metadata.json

{
    "X-Plasma-API": "declarativeappletscript",
    "X-Plasma-MainScript": "ui/main.qml"
}

metadata.desktop

[Desktop Entry]
X-Plasma-API=declarativeappletscript
X-Plasma-MainScript=ui/main.qml

X-Plasma-Provides (Alternatives)

A Plasmoid can specify the type of functionality it offers, for example whether it's a clock, an application launcher, etc. This mechanism is used to list alternative plasmoids for a certain function. When you open the context menu of the Application Launcher (aka kickoff) in the Plasma desktop panel, you'll see that a number of different Plasmoids are offered here as alternatives, like the Application Menu (aka kicker) and Application Dashboard (aka kickerdash). All three of these widgets define:

metadata.json

{
    "X-Plasma-Provides": [
        "org.kde.plasma.launchermenu"
    ]
}

metadata.desktop

[Desktop Entry]
X-Plasma-Provides=org.kde.plasma.launchermenu

These "Provides" are in fact arbitrary, so you can choose your own here. The field accepts multiple values separated by a comma. Here are some possible values that are used throughout Plasma:

  • org.kde.plasma.launchermenu: App Launcher Menus

  • org.kde.plasma.multimediacontrols: Multimedia controls

  • org.kde.plasma.time: Clocks

  • org.kde.plasma.date: Calendars

  • org.kde.plasma.notifications: Notifications

  • org.kde.plasma.removabledevices: Removable devices, auto mounter, etc.

  • org.kde.plasma.multitasking: Task switchers

  • org.kde.plasma.virtualdesktops: Virtual desktop switcher

  • org.kde.plasma.activities: Switchers for Plasma activities

  • org.kde.plasma.trash: Trash / file deletion

You can search plasma's code for more examples:

X-Plasma-NotificationArea (System Tray)

metadata.json

{
    "KPlugin": {
        "EnabledByDefault": true
    },
    "X-Plasma-DBusActivationService": "org.mpris.MediaPlayer2.*",
    "X-Plasma-NotificationArea": "true",
    "X-Plasma-NotificationAreaCategory": "ApplicationStatus"
}

metadata.desktop

[Desktop Entry]
X-KDE-PluginInfo-EnabledByDefault=true
X-Plasma-NotificationArea=true
X-Plasma-NotificationAreaCategory=ApplicationStatus
X-Plasma-DBusActivationService=org.mpris.MediaPlayer2.*

By specifying X-Plasma-NotificationArea, this widget will be found by the systemtray widget.

EnabledByDefault will make sure it's enabled in the systemtray by default.

It's prudent for the widget to also set the X-Plasma-NotificationAreaCategory so that the icons are grouped together. Its allowed values are:

  • ApplicationStatus: indicates that this item represents an active application

  • Hardware: indicates that this item allows managing hardware (could be a battery monitor or the wifi applet)

  • SystemServices: indicates that this item shows information about system services, for example the status of file indexing, software updates, etc.

You can search plasma's code for more examples:

X-Plasma-DBusActivationService

X-Plasma-DBusActivationService will load and unload widgets in the systemtray automatically when a DBus service becomes available or is stopped. This is very convenient to load widgets automatically, so the user doesn't have to explicitly go to the notification area settings and enable or remove a widget.

metadata.json

{
    "X-Plasma-DBusActivationService": "org.mpris.MediaPlayer2.*"
}

metadata.desktop

[Desktop Entry]
X-Plasma-DBusActivationService=org.mpris.MediaPlayer2.*

Keyboard shortcut will toggle Plasmoid.expanded. , this is true by default.

Due not use. Always returns 0. .

. Turn off the desktop widget bg.

. The smaller "icon" view view of the widget shown in the panel.

. Provides access to all user configurable values as sub-properties.

. The actual background hints the applet has based on backgroundHints and userBackgroundHints.

. The full "popup" view of the widget.

Reads metadata.json (or metadata.desktop). See the for examples.

. The widget namespace. Id in metadata.json, or X-KDE-PluginInfo-Name in metadata.desktop.

. The widget namespace. Alias of Plasmoid.metaData.pluginId

Force a representation and ignore Plasmoid.switchHeight.

The of the subText. Defaults to PlainText.

. The user specified background hint.

The compact representation uses by default. To summarize, it:

Draws the plasmoid.icon using a

Defines a to toggle the expanded property which displays the full representation.

If there's enough room (more than ) then the widget's full representation can be drawn directly in the panel or on the desktop. If you want to force this behaviour you can set .

If there isn't enough room, then the widget will display Plasmoid.compactRepresentation instead, and the full representation will be visible when is true.

In a plasma widget, the full representation will be shown in a which you cannot access directly. You can manipulate the dialog with:

Set Plasmoid.hideOnWindowDeactivate to prevent the dialog from closing. You can use this to have a configurable "pin" .

The dialog's source code can be found in to see the exact behavior.

As mentioned in [the setup widget , by default the plasmoid icon is populated with the Icon value in metadata.json.

You can search for icon names in the /usr/share/icon folder. You can also look for an icon name by right clicking your app launcher widget then editing the icon in its settings. It uses a searchable interface and lists them by category. Plasma's SDK also has the Cuttlefish app () which you can install with sudo apt install plasma-sdk.

Since: KDE Frameworks 5.89, the datatype and will eventually change to KConfig's .

PlasmaCore.Types.StandardBackground The standard background from the theme is drawn.

PlasmaCore.Types.ShadowBackground The applet won't have a svg background but a drop shadow of its content done via a shader. The text color will also invert.

PlasmaCore.Types.NoBackground This property is used to hide a desktop widget background. An example would be .

PlasmaCore.Types.ConfigurableBackground Allows the user to toggle between StandardBackground and ShadowBackground. Note that this is a bit flag to be used with another enum value.

The common metadata.json properties are covered in the .

You can read the generated for the json schema. The full list of properties for the older metadata.desktop properties for widgets is defined in the .

These two are based on the standard properties. You can also translate these properties with Name[fr]. The translated Name is used in the "Add Widgets" list. The Description (previously known as Comment in the metadata.desktop) is only used for the default tooltip subtext when the widget is added to a panel.

This list was taken from:

KPackageStructure is a string to identify the associated . For a plasma widget, it should be Plasma/Applet.

org.kde.plasma.time,org.kde.plasma.date: Clocks with calendars ()

org.kde.plasma.powermanagement: Power management ()

The Media Controller widget serves as a good example since it uses most of the systemtray metadata features. the following:

An example of this is the Media Controller widget, which is auto-loaded as soon as an application starts offering the org.mpris.MediaPlayer2 DBus service in the session. As you can see , X-Plasma-DBusActivationService accepts wildcards which makes it a bit easier to match DBus names. This key can also be very useful to avoid having a widget loaded when it's unnecessary, so it can help to avoid visual clutter and wasted memory.

for more examples.

DefaultCompactRepresentation.qml
Kirigami.Icon
MouseArea
Plasmoid.switchHeight
Plasmoid.preferredRepresentation
plasmoid.expanded
PlasmaCore.Dialog
like the digital clock widget does
CompactApplet.qml
screenshot
KDeclarative::ConfigPropertyMap
was deprecated
KConfigPropertyMap
setup widget section
C++ API Documentation for metadata.json
Plasma/Applet service type
XDG desktop file
https://techbase.kde.org/Projects/Plasma/PIG
KPackage::PackageStructure
Eg: Digital Clock
Eg: Battery and Brightness
Search plasma-workspace for X-Plasma-Provides
Search plasma-desktop for X-Plasma-Provides
Search kdeplasma-addons for X-Plasma-Provides
Its metadata contains
Search plasma-workspace for X-Plasma-NotificationArea
Search plasma-desktop for X-Plasma-NotificationArea
Search kdeplasma-addons for X-Plasma-NotificationArea
in its metadata.json file
Search plasma-workspace for X-Plasma-DBusActivationService
metadata.json section
Since KDE Frameworks 5.76
Source code
rect
Plasma::Types::BackgroundHints
Component
Item
KDeclarative::ConfigPropertyMap
Plasma::Types::ConstraintHints
Plasma::Types::ContainmentDisplayHints
Plasma::Types::BackgroundHints
Plasma::Types::FormFactor
Component
Item
QKeySequence
Plasma::Types::ImmutabilityType
Plasma::Types::Location
KPluginMetaData
AboutPlugin.qml source code
Component
rect
Plasma::Types::ItemStatus
Item
TextFormat
Plasma::Types::BackgroundHints
Documentation
Documentation
Documentation
Documentation
Documentation
Example
Documentation
Documentation
Example
Documentation
property group
AppletInterface
PlasmaQuick::AppletQuickItem
dynamically defined at runtime
the Analog Clock widget
the main.qml setup widget section
desktoppackage/contents/applet/CompactApplet.qml · master · Plasma / Plasma Desktop · GitLabGitLab
Logo