KDE System Administration/PlasmaDesktopScripting
ECMA Script Interaction With The Plasma Desktop Shell (plasma-desktop)
It is possible to control and interact with a plasma-desktop session using ECMA Script (aka JavaScript). This scripting mechanism exposes containments (Desktop Activities and Panels), widgets and various other aspects of plasma-desktop configuration using the widely known and used ECMA Script language. The QtScript engine is used for the runtime environment.
This document describes the API that is provided along with how to run such scripts in plasma-desktop.
Running Scripts
There are three ways that scripts can be executed in plasma-desktop:
- on first run: when plasma-desktop is started without any pre-existing configuration, any scripts in $APPDATA/plasma-desktop/init/ with a ".js" suffix are run. If there is more than one script, they are run sequentially in the alphabetical order of the file names.
Note
}
- on update: when plasma-desktop is started, it will check in
`kde4-config --path data`/plasma-desktop/updates/ with a ".js" suffix for scripts that have not yet been run. If there is more than one script which has not been run yet they will be executed serially in the alphabetical order of the file names.
A record of which update scripts have been run is kept in the application's config file in the [Updates] group. This means that if the plasma-desktop configuraiton file is removed, all the update scripts will be run again.
Note
}
- interactively: an interactive scripting dialog can be requested either via the KRunner window (Alt+F2, by default, or via the "Run Command" entry in various desktop menus) by entering "desktop console" as the search term. It can also be triggered directly via dbus with
qdbus org.kde.plasma-desktop /MainApplication showInteractiveConsole
- ECMA Script may be entered directly into this window for execution and output appears in the lower half of the window. Ctrl+E is a shortcut to run scripts, and scripts can be saved to and loaded from disk.
- Scripts from files can also be loaded using KRunner with "desktop console /path/to/file" or via dbus with
qdbus org.kde.plasma-desktop /MainApplication loadScriptInInteractiveConsole /path/to/file
API
In addition to the normal ECMA Script API and the Qt-specific extensions (such as signal/slot support) provided by QtScript, 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.
Note
Activities
Activities are the desktop layer in a plasma-desktop session and may contain widgts. In sightly more technical terms, they are desktop containments. Activities can be created, enumerated, modified and destroyed.
New Activities can be created using the Activity constructor, like this:
var activity = new Activity("folderview")
The string passed into the constructor maps to the X-KDE-PluginInfo-Name= entry in the plugin's .desktop file). See the documentation on the Containment object class below.
Read-only properties:
- Array[number] activityIds: returns a list of integer ids of all existing Plasma activities
Functions:
- Activity activityById(number id): return an object representing the activity with the given id
- Activity activityForScreen(number screen[, number dekstop]): returns an object representing the activity currently associated with the given screen and, optionally, the given desktop.
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 screen and the hiding features associated with them.
New Panels can be created using the Panel constructor, like this:
var panel = new Panel("dock")
The string passed into the constructor maps to the X-KDE-PluginInfo-Name= entry in the plugin's .desktop file).
Read-only properties:
- Array[number] panelIds: returns a list of integer ids of all existing Plasma panels
Functions:
- Panel panelById(int id): returns an object representing the Panel that matches the given id
Activities and Panels
Activity and Panel objects, ones created by the script, or as returned by activityById, activityForScreen, or panelById) provide the following read-only properties:
- number id: the integer id of this activity
- String formFactor: returns the form factor of the activity, e.g. "planar" for most desktop activities,"mediacenter" for media centers and either "horizontal" or "vertical" for panels.
- Array[number] widgetIds: a list of integer ids of all the widgets in this Activity
as well as the following read/write properties:
- number desktop: the virtual desktop this activity is associated with, or -1 for none
- number screen: the screen this activity is associated with, or -1 for none
- String name: the name of this activity
and the following methods:
- remove(): deletes this activity and all widgets inside of it
- Widget widgetById(number id): returns an object representing the widget with the given id
- Widget addWidget(String name): adds a new widget to the activity; the name maps to the X-KDE-PluginInfo-Name= entry
in the widget's .desktop file
- Widget addWidget(Widget widget): adds an existing widget to this activity; useful for moving widgets between Activities and Panels
- showConfigurationInteface(): shows the configuration user interface for this Activity or Panel on the screen
In addition to all of the above properties and functions, Panel objects also provide the folowing read/write properties:
- number length: the number of pixels along the screen edge used
- 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", "windowscover" or "windowsbelow"
- String alignment: right, left or center alignment of the panel (for vertical panels, right corrsponds to top and left to bottom)
- String location: returns the location of the activity (only relevant for Panels); valid values include "top", "bottom", "left", "right" and "floating"
Widgets
Widgets may be enumerated by calling the widgetIds property on a Activity or Panel object. With a widget id in hand, a Widget object can be retrieved by calling widgetById(id) on an Activity or Panel object. New Widgets can be created with add addWidget(String) function provided by Activity and Panel objects.
A Widget object provides the following read-only properties:
- number id: the id of the widget
- String type: the plugin type of this widget
- Array[String] configKeys: a list of all keys that are set in the current configuration
- Array[String] configGroups: a list of all the groups in the current configuration
- number index: the layout index of the widget; in a Panel this corresponds to the order in appears in
as well as the following read-write properties:
- QRectF geometry: the geometry of the widget (settable)
- String globalShortcut: the shortcut sequence (in the format used by QKeySequence, e.g. "Alt+F1") associated with this widget
- Array[String] currentConfigGroup: the current configuration group path, with each entry in the array representing a sub-group. This allows one to access trees of groups with code such as: widget.currentConfigGroup = new Array('topGroup', 'subGroupOfTopGroup'). An empty Array means the default (top-level) configuration group for the widget
and methods:
- remove(): deletes this widget
- readConfig(String key, any default): reads the value of key in the config with default
for the default value
- writeConfig(String key, any value): sets key to value in the config
- showConfigurationInteface(): shows the configuration user interface for this widget on the screen
Screen Geometry
Read-only properties:
- number screenCount: returns the number of screens connected to the computer
Functions:
- QRect screenGeometry(number screen): returns a rect object representing the geometry of a screen
Misc. Global Properties and Functions
Read-write properties:
- bool locked: whether the desktop shell and widgets are locked or not (settable)
Read-only property:
- boolean hasBattery: whether or not the system has the ability to run on battery power, e.g. a laptop or mobile device
Functions:
- sleep(number ms): sleeps the script for the specified number of millseconds