Skip to main content
Skip to content
Edit this page See source code Create documentation issue Formatting guidelines Style guidelines

API documentation

API documentation for Plasma scripting API

In addition to the normal Javascript API and the Qt-specific extensions (such as signal/slot support) provided by QtJSEngine, the following API is provided for use by scripts.

All of the API below, unless otherwise noted with a version noticed, appear as below in the KDE Software Compilation v4.4.0 and later. API that is not noted as being part of a given class or object is part of the global namespace.

Version Numbers

Starting with KDE SC 4.5, the version number of both the scripting API and the application is available to the script via the following read-only properties:

  • string applicationVersion: the version of the application, e.g. 5.20.3
  • number scriptingVersion: the version of the scripting API; e.g. for Plasma 5.20 it is 20.

Activities

Activities are similar to virtual desktops, except that in Plasma, activities can have different desktop wallpapers and desktop widgets. All activities share the same panels. Individual activities can have many other settings like energy profiles. Read this for more info on Plasma Activities.

For plasma scripting purposes, we only need worry about how each activity has a different Desktop containment for each screen. Each Desktop instance can have a custom wallpaper and widgets.

Consider the following example. We have two activities. The first activity named Default has a desktop widget, while the 2nd activity named Gaming only has a solid black color fill. The Default activity has a weather desktop widget, while the Gaming activity does not.

  • plasmashell

    • All Activities

      • Panel(id=0) for Screen(id=0)
        • Widget(id=0)
        • Widget(id=1)
        • ...

    • Activity(name="Default", id="80cddcc9-cf02-4e23-af0b-dc569f24a2b4")

      • Desktop(id=0, wallpaperPlugin="org.kde.image") for Screen(id=0)
        • Widget(id=2) for the weather desktop widget
        • [Wallpaper][org.kde.image][General] Image=wallpaper.png
      • Desktop(id=1, ...) for the 2nd monitor Screen(id=1)

    • Activity(name="Gaming", id="3683ebee-8869-4d60-9db1-8e92cfebc0cf")

      • Desktop(id=2, wallpaperPlugin="org.kde.color") for Screen(id=0)
        • [Wallpaper][org.kde.color][General] Color=#000000
      • Desktop(id=3, ...) for the 2nd monitor Screen(id=1)

New Activities can be created using the createActivity(name, pluginId="") function, like this:

let activityId = createActivity("Activity Name")
let activityDesktops = desktopsForActivity(activityId)
let desktop = activityDesktops[0]
desktop.wallpaperPlugin = "org.kde.image"
desktop.currentConfigGroup = Array("Wallpaper", "org.kde.image", "General")
desktop.writeConfig("Image", "file:///usr/share/wallpapers/Next/contents/images/1920x1080.png")

Note, createActivity() returns a string id. There is no Activity type in Plasma Scripting.

The pluginId string passed into the createActivity() function should select the desktop "layout", however due to a bug it always creates an activity with a folder view layout. Should the bug be fixed, you can pass a pluginId of:

  • The Id of plasmoid with X-Plasma-ContainmentType=Desktop.
  • org.kde.desktopcontainment for a desktop without icons
  • org.kde.plasma.folder for a desktop with icons

Read-only properties:

  • array<number> activityIds: returns a list of integer ids of all existing Plasma activities
  • array<string> knownActivityTypes: a list of types of activities that can be created. This is useful to check if an Activity type is available on the system before trying to construct one.

Functions:

  • array<string> activities(): Returns an array of all activity ids of the activities that currently exist
  • string activityName(string activityId): Get the name of an activity by its id.
  • void setActivityName(string activityId): Set the name of an activity by its id.
  • string currentActivity(): Get the id of the current activity.
  • void setCurrentActivity(string activityId): Set the current activity using its id.
  • string createActivity(string name[, string plugin]): Returns the new activity id with the supplied name argument. The plugin argument is ignored due to a bug so you can call this function with just createActivity("Name").

Desktops

Every screen will have a Desktop instance. Desktops are containments which can have widgets and a wallpaper plugin.

The actual data type for a Desktop is WorkspaceScripting::Containment which Panels inherit. This documentation pretends it's a different type to make it saner to read.

let desktop = desktops()[0]
desktop.wallpaperPlugin = "org.kde.image"
desktop.currentConfigGroup = Array("Wallpaper", "org.kde.image", "General")
desktop.writeConfig("Image", "file:///usr/share/wallpapers/Next/contents/images/1920x1080.png")

Desktops also inherit all the Containment properties.

Global functions:

  • array<Desktop> desktopsForActivity(string id): return all the desktops associated to a specific activity id (one per physical screen).
  • array<Desktop> desktops(): returns an array of all desktops that currently exist.
  • Desktop desktopById(int id): return an object representing the activity with the given id
  • Desktop desktopForScreen(number screen[, number desktop]): returns an object representing the activity currently associated with the given screen and, optionally, the given desktop.

Read-only properties:

  • Inherits Containment.formFactor
  • Inherits Containment.screen
  • Inherits Containment.widgetIds
  • Inherits Applet.id: the numerical instance id of this containment
  • Inherits Applet.type: the X-KDE-PluginInfo-Name of the containment
  • Inherits Applet.version
  • Inherits Applet.configKeys
  • Inherits Applet.configGroups
  • Inherits Applet.globalConfigKeys
  • Inherits Applet.globalConfigGroups

Read-write properties:

  • string wallpaperPlugin: the wallpaper plugin to use with the Desktop.
    kpackagetool5 --global --type=Plasma/Wallpaper --list
kpackagetool5 --type=Plasma/Wallpaper --list
    Listing service types: Plasma/Wallpaper in /usr/share/plasma/wallpapers/
org.kde.color
org.kde.haenau
org.kde.hunyango
org.kde.image
org.kde.potd
org.kde.slideshow
Listing service types: Plasma/Wallpaper in ~/.local/share/plasma/wallpapers/
...
  • string wallpaperMode: the wallpaper plugin mode to use with the Desktop. Does nothing in Plasma 5.
  • Inherits Containment.locked
  • Inherits Applet.currentConfigGroup
  • Inherits Applet.currentGlobalConfigGroup

Functions:

  • Inherits Containment.addWidget(...)
  • Inherits Containment.widgetById(...)
  • Inherits Containment.widgets(...)
  • Inherits Applet.remove()
  • Inherits Applet.showConfigurationInteface()
  • Inherits Applet.readConfig(...)
  • Inherits Applet.writeConfig(...)
  • Inherits Applet.readGlobalConfig(...)
  • Inherits Applet.writeGlobalConfig(...)
  • Inherits Applet.reloadConfig()

Panels

Panels can be created, enumerated, modified and destroyed. A panel object combines both a containment as well as the container itself, allowing for full control of things such as where it appears on the screen and the hiding features associated with them.

New Panels can be created using the Panel constructor, like this:

let panel = new Panel

Panels also inherit all the Containment properties.

Global properties:

  • array<int> panelIds: returns a list of integer ids of all existing Plasma panels
  • array<string> knownPanelTypes: a list of types of panels that can be created. This is useful to check if a Panel type is available on the system before trying to construct one.

Global functions:

  • Panel panelById(int id): returns an object representing the Panel that matches the given id
  • array<Panel> panels(): returns an array of all panels that currently exist

Read-only properties:

  • Inherits Containment.formFactor
  • Inherits Containment.screen
  • Inherits Containment.widgetIds
  • Inherits Applet.id: the numerical instance id of this containment
  • Inherits Applet.type: the X-KDE-PluginInfo-Name of the containment
  • Inherits Applet.version
  • Inherits Applet.configKeys
  • Inherits Applet.configGroups
  • Inherits Applet.globalConfigKeys
  • Inherits Applet.globalConfigGroups

Read-write properties:

_ string lengthMode: (since 6.0) fill, fit, or custom length modes. fill means FillAvailable, and fit means FitContent.

  • number length: the number of pixels along the screen edge used
  • number minimumLength: (scriptingVersion >= 7) the minimum number of pixels along the screen edge used (auto-resize panels)
  • number maximumLength: (scriptingVersion >= 7) the maximum number of pixels along the screen edge used (auto-resize panels)
  • number height: the height (or for vertical panels, the width) of the panel
  • string hiding: the hiding mode of the panel, one of none (for no hiding), autohide, dodgewindows or windowsgobelow
  • string alignment: right, left or center alignment of the panel (for vertical panels, right corresponds to top and left to bottom)
  • number offset: how much the panel is moved from the left/right/center anchor point
  • string location: returns the location of the Panel; valid values include top, bottom, left, right and floating.
  • Inherits Containment.locked
  • Inherits Applet.currentConfigGroup
  • Inherits Applet.currentGlobalConfigGroup

Functions:

  • Inherits Containment.addWidget(...)
  • Inherits Containment.widgetById(...)
  • Inherits Containment.widgets(...)
  • Inherits Applet.remove(): deletes this containment and all widgets inside of it
  • Inherits Applet.showConfigurationInteface()
  • Inherits Applet.readConfig(...)
  • Inherits Applet.writeConfig(...)
  • Inherits Applet.readGlobalConfig(...)
  • Inherits Applet.writeGlobalConfig(...)
  • Inherits Applet.reloadConfig()

Containments (Desktops and Panels)

Desktop and Panel objects are both Containments.

Containments also inherit all the Applet properties.

Read-only properties: