Neverendingo (Talk | contribs) m (Text replace - "</code>" to "</syntaxhighlight>") |
Shadeslayer (Talk | contribs) m |
||
| (7 intermediate revisions by 4 users not shown) | |||
| Line 20: | Line 20: | ||
* '''on update''': when plasma-desktop is started, it will check in | * '''on update''': when plasma-desktop is started, it will check in | ||
| − | + | <syntaxhighlight lang="bash"> | |
| + | `kde4-config --path data`/plasma-desktop/updates/ | ||
| + | </syntaxhighlight> | ||
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. | 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. | ||
| Line 82: | Line 84: | ||
template.findWidgets('systemtray') | template.findWidgets('systemtray') | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| + | |||
| + | |||
| + | Since just finding the widget is not enough, you can connect a callback to do additional operations, such as removing the widget : | ||
| + | |||
| + | <syntaxhighlight lang="javascript"> | ||
| + | removeWidget = function(widget, containment) | ||
| + | { | ||
| + | widget.remove() | ||
| + | } | ||
| + | |||
| + | var template = loadTemplate('org.kde.plasma-desktop.findWidgets') | ||
| + | template.findWidgets('systemtray', removeWidget) | ||
| + | </syntaxhighlight> | ||
| + | |||
==== Activity templates ==== | ==== Activity templates ==== | ||
| Line 108: | Line 124: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| − | The layout itself is still created from the layout.js file as usual, but this template also shows as a precreated activity to the user thanks to the X-Plasma-ContainmentLayout-ShowAsExisting key. Additionally, it starts applications in the newly created activity using the X-Plasma-ContainmentLayout-ExecuteOnCreation key. | + | The layout itself is still created from the layout.js file as usual, but this template also shows as a precreated activity to the user thanks to the <tt>X-Plasma-ContainmentLayout-ShowAsExisting</tt> key. Additionally, it starts applications in the newly created activity using the <tt>X-Plasma-ContainmentLayout-ExecuteOnCreation</tt> key. |
That key is a list of commands to execute, and it supports the following variables: | That key is a list of commands to execute, and it supports the following variables: | ||
| Line 141: | Line 157: | ||
New Activities can be created using the Activity constructor, like this: | New Activities can be created using the Activity constructor, like this: | ||
| − | + | <syntaxhighlight lang="javascript"> | |
| − | + | var activity = new Activity("folderview") | |
| + | </syntaxhighlight> | ||
The string passed into the constructor maps to the X-KDE-PluginInfo-Name= entry | The string passed into the constructor maps to the X-KDE-PluginInfo-Name= entry | ||
| Line 160: | Line 177: | ||
New Panels can be created using the Panel constructor, like this: | New Panels can be created using the Panel constructor, like this: | ||
| − | + | <syntaxhighlight lang="javascript"> | |
| − | + | var panel = new Panel("dock") | |
| − | + | </syntaxhighlight> | |
The string passed into the constructor maps to the X-KDE-PluginInfo-Name= entry | The string passed into the constructor maps to the X-KDE-PluginInfo-Name= entry | ||
in the plugin's .desktop file). | in the plugin's .desktop file). | ||
| Line 200: | Line 217: | ||
* '''remove()''': deletes this activity and all widgets inside of it | * '''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'' '''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 | + | * ''Widget'' '''addWidget(String name)''': adds a new widget to the activity; the name maps to the <tt>X-KDE-PluginInfo-Name=</tt> 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 | * ''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 | * '''showConfigurationInteface()''': shows the configuration user interface for this Activity or Panel on the screen | ||
* '''readConfig(String key, any default)''': (scriptingVersion >= 2) reads the value of key in the config with default for the default value | * '''readConfig(String key, any default)''': (scriptingVersion >= 2) reads the value of key in the config with default for the default value | ||
* '''writeConfig(String key, any value)''': (scriptingVersion >= 2) sets key to value in the config | * '''writeConfig(String key, any value)''': (scriptingVersion >= 2) sets key to value in the config | ||
| − | * '''readGlobalConfig(String key, any default)''': (scriptingVersion >= 2) reads the value of key in the global config with default | + | * '''readGlobalConfig(String key, any default)''': (scriptingVersion >= 2) reads the value of key in the global config with default for the default value |
| − | + | ||
* '''writeGlobalConfig(String key, any value)''': (scriptingVersion >= 2) sets key to value in the global config | * '''writeGlobalConfig(String key, any value)''': (scriptingVersion >= 2) sets key to value in the global config | ||
* '''reloadConfig()''': (scriptingVersion >= 2) causes the Activity or Panel to reload its configuration; reaction to configuration changes made using readConfig are usually activated on script exit, but this can be triggered earlier on a per-widget basis using this method | * '''reloadConfig()''': (scriptingVersion >= 2) causes the Activity or Panel to reload its configuration; reaction to configuration changes made using readConfig are usually activated on script exit, but this can be triggered earlier on a per-widget basis using this method | ||
| Line 223: | Line 238: | ||
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. | 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. | ||
| + | ==== Checking if a widget is installed ==== | ||
A list of all installed widget types can be retrieved the following read-only property: | A list of all installed widget types can be retrieved the following read-only property: | ||
* ''Array[String]'' '''knownWidgetTypes''' (scripting version >= 2) | * ''Array[String]'' '''knownWidgetTypes''' (scripting version >= 2) | ||
| + | This can be used most conveniently with the indexOf() method, like this: | ||
| + | |||
| + | <syntaxhighlight lang="javascript"> | ||
| + | if (knownWidgeTypes.indexOf('someWidgetPluginName') > -1) { | ||
| + | print("It is installed on this system!"); | ||
| + | } else { | ||
| + | print("It is not installed :("); | ||
| + | } | ||
| + | </syntaxhighlight> | ||
| + | |||
| + | ==== Widget Object API ==== | ||
A Widget object provides the following read-only properties: | A Widget object provides the following read-only properties: | ||
| Line 248: | Line 275: | ||
* '''remove()''': deletes this widget | * '''remove()''': deletes this widget | ||
| − | * '''readConfig(String key, any default)''': reads the value of key in the config with default | + | * '''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 | * '''writeConfig(String key, any value)''': sets key to value in the config | ||
| − | * '''readGlobalConfig(String key, any default)''': (scriptingVersion >= 2) reads the value of key in the global config with default | + | * '''readGlobalConfig(String key, any default)''': (scriptingVersion >= 2) reads the value of key in the global config with default for the default value |
| − | + | ||
* '''writeGlobalConfig(String key, any value)''': (scriptingVersion >= 2) sets key to value in the global config | * '''writeGlobalConfig(String key, any value)''': (scriptingVersion >= 2) sets key to value in the global config | ||
* '''reloadConfig()''': causes the widget to reload its configuration; reaction to configuration changes made using readConfig are usually activated on script exit, but this can be triggered earlier on a per-widget basis using this method | * '''reloadConfig()''': causes the widget to reload its configuration; reaction to configuration changes made using readConfig are usually activated on script exit, but this can be triggered earlier on a per-widget basis using this method | ||
| Line 266: | Line 291: | ||
=== Wallpaper Plugins === | === Wallpaper Plugins === | ||
| − | * ''Array[String => Array[String]]'' '''knownWallpaperPlugins()''': (scripting version >= 4) returns a list of all installed wallpaper plugins. | + | * ''Array[String => Array[String]]'' '''knownWallpaperPlugins()''': (scripting version >= 4) returns a list of all installed wallpaper plugins. The keys of the array are the wallpaper plugin names. The values are arrays containing the modes available for that wallpaper plugin. The mode array may be empty, as most wallpaper plugins only offer one mode. |
=== Locating Applications and Paths === | === Locating Applications and Paths === | ||
* ''boolean'' '''applicationExists(String name)''': (scripting version >= 4) searches $PATH first, then tries in the application menu system by application storage name (aka the .desktop file name), then Name= entries for apps with installed .desktop files, then GenericName= entries for same | * ''boolean'' '''applicationExists(String name)''': (scripting version >= 4) searches $PATH first, then tries in the application menu system by application storage name (aka the .desktop file name), then Name= entries for apps with installed .desktop files, then GenericName= entries for same | ||
* ''mixed'' '''defaultApplication(String kind [, boolean storageId = false])''': (scripting version >= 4) returns the executable (or if storageId is true, then the app menu system id, e.g. its .desktop file name) of the default app. The "kind" parameter may be a well-known application type including "browser", "mailer", "filemanager", "terminal", "imClient" and "windowmanager" (or any other entry in share/apps/kcm_componentchooser/kcm_*.desktop); it may also be a mimetype (e.g. "application/pdf"). On failure, it returns false. | * ''mixed'' '''defaultApplication(String kind [, boolean storageId = false])''': (scripting version >= 4) returns the executable (or if storageId is true, then the app menu system id, e.g. its .desktop file name) of the default app. The "kind" parameter may be a well-known application type including "browser", "mailer", "filemanager", "terminal", "imClient" and "windowmanager" (or any other entry in share/apps/kcm_componentchooser/kcm_*.desktop); it may also be a mimetype (e.g. "application/pdf"). On failure, it returns false. | ||
| − | * ''String'' '''applicationPath(String name)''': (scripting version >= 4) returns the full local path to a given application or .desktop file if it exists. | + | * ''String'' '''applicationPath(String name)''': (scripting version >= 4) returns the full local path to a given application or .desktop file if it exists. Example: |
| + | |||
| + | <syntaxhighlight lang="javascript"> | ||
| + | var desktopfile = "firefox.desktop" | ||
| + | var executable = "firefox" | ||
| + | if (applicationExists(executable)) { | ||
| + | print (executable + " exists " + " with this path: " + applicationPath(executable)) | ||
| + | print (executable + " .desktop file is located here : " + applicationPath(desktopfile)) | ||
| + | } else{ | ||
| + | print (executable + " does not exist ") | ||
| + | } | ||
| + | </syntaxhighlight> | ||
| + | |||
* ''String'' '''userDataPath([String type, String path])''': (scripting version >= 4) returns the default path for user data. Called with no parameters, it returns the user's home directory. If only one string is passed in, the standard directory for that type of data in the user's home directory will be located; the following values are recognized: | * ''String'' '''userDataPath([String type, String path])''': (scripting version >= 4) returns the default path for user data. Called with no parameters, it returns the user's home directory. If only one string is passed in, the standard directory for that type of data in the user's home directory will be located; the following values are recognized: | ||
** documents | ** documents | ||
| Line 466: | Line 503: | ||
==== Add a widget to systemtray ==== | ==== Add a widget to systemtray ==== | ||
You can not add widgets to the systemtray in a similar way like you would add them to a panel or containment using addWidget. Instead, to add, manage and remove them, you need to utilize writeConfig changing the currentConfigGroup. | You can not add widgets to the systemtray in a similar way like you would add them to a panel or containment using addWidget. Instead, to add, manage and remove them, you need to utilize writeConfig changing the currentConfigGroup. | ||
| − | <syntaxhighlight lang=" | + | <syntaxhighlight lang="cpp-qt"> |
| − | systray.currentConfigGroup = Array("Applets","0") | + | systray = panel.addWidget("systemtray") // First add a systemtray to your panel |
| − | + | systray.currentConfigGroup = Array("Applets","0") // then change the currentConfig Group | |
| + | |||
| + | // to the subnode [Applets][0]. Use any number you like(?) | ||
| + | </syntaxhighlight> | ||
Now you can “create” the plasmoid by adding a “plugin” configuration entry | Now you can “create” the plasmoid by adding a “plugin” configuration entry | ||
| − | <syntaxhighlight lang=" | + | <syntaxhighlight lang="cpp-qt"> |
| + | systray.writeConfig("plugin","notifier") // This will add a Device Notifier Plasmoid | ||
| + | </syntaxhighlight> | ||
You can modify the plasmoid’s configuration by using writeConfig. | You can modify the plasmoid’s configuration by using writeConfig. | ||
| − | <syntaxhighlight lang=" | + | <syntaxhighlight lang="cpp-qt"> |
| + | systray.writeConfig("property","value") | ||
| + | </syntaxhighlight> | ||
To change back to the top configuration level and thus edit the systemtray plasmoid itself pass an empty array to currentConfigGroup. | To change back to the top configuration level and thus edit the systemtray plasmoid itself pass an empty array to currentConfigGroup. | ||
It is possible to control and interact with a Plasma user interface shell such as a plasma-desktop or (starting in KDE SC 4.5) plasma-netbook 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.
A set of examples can be found here that demonstrate the use of various aspects of Plasma shell scripting.
Contributions of additional examples are welcome and an be sent to the Plasma development mailing list (plasma-devel at kde.org) for inclusion if you do not have commit rights to the kdeexamples module.
There are three ways that scripts can be executed in plasma-desktop:
| Note |
|---|
| For security reasons, scripts located in the user's home directory will not be run during this phase. |
KDE TechBase `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 |
|---|
| For security reasons, scripts located in the user's home directory will not be run during this phase. |
qdbus org.kde.plasma-desktop /MainApplication showInteractiveConsole
| Note |
|---|
| This method is not available for plasma-netbook. |
qdbus org.kde.plasma-desktop /MainApplication loadScriptInInteractiveConsole /path/to/file
Templates are named packages that contain scripts. This provides a way for common functionality to be easily reused, helping to increase consistency and lower maintenance costs. Templates can be loaded from other scripts by name and they are also used to populate some parts of the user interface, such as the entries in the Add Panels menu.
A template is a small set of files in a specified file hierarchy (or, in Plasma terms, a "Package"). In particular, a Template package contains the following files:
Templates are stored under share/apps/plasma/layout-templates and may be installed using `plasmapkg -t layout-template -i /path/to/package`. Template packages may also be provided as a .zip file with a .plasmalayout suffix.
The metadata.desktop file contains the usual .desktop entries such as Name and Icon but must also contain Type=Service and ServiceTypes=Plasma/LayoutTemplate entries. If the layout is specific to a given Plasma application, such as plasma-desktop, this can be specific using X-Plasma-Shell. X-Plasma-ContainmentCategories defines what kind of layout it is with possible values being panel and desktop. Finally a X-KDE-PluginInfo-Name entry is required to provide a globally unique internal name for the Template. Here is an example of a Template that provides a Panel layout for Plasma Netbook:
[Desktop Entry]
Encoding=UTF-8
Name=Cool Panel
Type=Service
ServiceTypes=Plasma/LayoutTemplate
X-Plasma-Shell=plasma-netbook
X-Plasma-ContainmentCategories=panel
X-KDE-PluginInfo-Author=Aaron Seigo
X-KDE-PluginInfo-Email=aseigo@kde.org
X-KDE-PluginInfo-Name=org.kde.CoolNetbookPanel
X-KDE-PluginInfo-Version=1.0
X-KDE-PluginInfo-Website=http://plasma.kde.org/
X-KDE-PluginInfo-Category=
X-KDE-PluginInfo-Depends=
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true
When running a template, two global variables will be accessible in read-only mode: templateName and templateComment. They will contain the Name and Comment fields of the above desktop file, and are translated if a localization is available.
A good example of the use of templates is the use case that triggered the creation of this feature: the desire to make it easy for users to re-create the default panel that is created on first start. There is a Template called org.kde.plasma-desktop.defaultPanel that ships with the KDE Plasma Workspace which contains the layout for the initial default panel. This is referenced by the default Plasma Desktop init script and, because it is marked as a Panel Template in the metadata.desktop file it also shows up to the user in the Add Panels menu. When selected by the user from the menu, the exact same panel that is created on desktop start up is created for them, complete with Plasma Widgets and configuration.
Another example of the usefulness of templates is the "Find Widgets" template. This template, which first shipped with Plasma Desktop v4.5, provides a function for finding widgets by name. It appears in the toolbar "Load" and "Use" menus in the Desktop Console in plasma-desktop, and makes finding widgets as simple as:
var template = loadTemplate('org.kde.plasma-desktop.findWidgets')
template.findWidgets('systemtray')
Since just finding the widget is not enough, you can connect a callback to do additional operations, such as removing the widget :
removeWidget = function(widget, containment)
{
widget.remove()
}
var template = loadTemplate('org.kde.plasma-desktop.findWidgets')
template.findWidgets('systemtray', removeWidget)
Probably the most user visible use of templates are "Activity templates". The structure of Activity templates is similar to the other use of templates, but a few extra features are provided in the metadata.desktop file. Here is an example of such an activity template:
[Desktop Entry]
Encoding=UTF-8
Name=Cool Activity Template
Icon=user-desktop
Type=Service
ServiceTypes=Plasma/LayoutTemplate
X-Plasma-Shell=plasma-desktop
X-Plasma-ContainmentCategories=desktop
X-Plasma-ContainmentLayout-ExecuteOnCreation=dolphin $desktop, gwenview $pictures
X-Plasma-ContainmentLayout-ShowAsExisting=true
X-KDE-PluginInfo-Author=John Doe
X-KDE-PluginInfo-Email=john@doe.org
X-KDE-PluginInfo-Name=org.kde.plasma-desktop.CoolTemplate
X-KDE-PluginInfo-Version=1.0
X-KDE-PluginInfo-Website=http://john.doe.org
X-KDE-PluginInfo-Category=
X-KDE-PluginInfo-Depends=
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true
The layout itself is still created from the layout.js file as usual, but this template also shows as a precreated activity to the user thanks to the X-Plasma-ContainmentLayout-ShowAsExisting key. Additionally, it starts applications in the newly created activity using the X-Plasma-ContainmentLayout-ExecuteOnCreation key.
That key is a list of commands to execute, and it supports the following variables:
They all expand into the path toward the user corresponding default folder.
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 |
|---|
| API compatibility is guaranteed from version to version starting with KDE Software Compilation v4.4.0. |
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:
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:
Functions:
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:
Functions:
Activity and Panel objects, once created by the script, or as returned by activityById, activityForScreen, or panelById) provide the following read-only properties:
as well as the following read/write properties:
and the following methods:
In addition to all of the above properties and functions, Panel objects also provide the folowing read/write properties:
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 list of all installed widget types can be retrieved the following read-only property:
This can be used most conveniently with the indexOf() method, like this:
if (knownWidgeTypes.indexOf('someWidgetPluginName') > -1) {
print("It is installed on this system!");
} else {
print("It is not installed :(");
}
A Widget object provides the following read-only properties:
as well as the following read-write properties:
and the following methods:
Read-only properties:
Functions:
var desktopfile = "firefox.desktop"
var executable = "firefox"
if (applicationExists(executable)) {
print (executable + " exists " + " with this path: " + applicationPath(executable))
print (executable + " .desktop file is located here : " + applicationPath(desktopfile))
} else{
print (executable + " does not exist ")
}
If a second string is passed in, it is considered a request for a specific path and the following types are recognized:
The second parameter should be a specific resource to find the path to. An example might be userDataPath("data", "plasma-desktop").
Read-write properties:
Read-only properties:
Functions:
A rectangle class is also provided for use with Widget, Panel and screen geometry properties and functions.
Read-only properites:
Read-write properties:
Constructors:
Functions:
Here you find a list of commonly used configuration keys to use with the writeConfig command. Where the documentation notes that a key is in a subgroup, remember to first use currentConfigGroup.
Here are some keys that can be used with all widgets:
Most of the settings listed below apply to all widgets dealing with date and time (clock, digital-clock, binary-clock, …) Settings for individual plasmoids can be found in their respective category and usually only affect the plasmoid’s appearance.
| Note |
|---|
| This applet is likely to be embedded to system tray. For Systrem Tray specific tasks, i. e. how to add, manage and remove plasmoids inside it, see sections below |
| Note |
|---|
| Auto-mount settings and device actions are not stored in this Plasmoid’s settings. |
The System Tray has some unique behaviors since it can host widgets and configuring it is not as easy as most other widgets, particularly when adding and removing widgets. This section will help you deal with its specific behavior.
| Note |
|---|
| Although notifications appear to be part of the System Tray, they are handled by a separate plasmoid which is embedded to the system tray. For its configuration keys, see section above |
You can not add widgets to the systemtray in a similar way like you would add them to a panel or containment using addWidget. Instead, to add, manage and remove them, you need to utilize writeConfig changing the currentConfigGroup.
systray = panel.addWidget("systemtray") // First add a systemtray to your panel
systray.currentConfigGroup = Array("Applets","0") // then change the currentConfig Group
// to the subnode [Applets][0]. Use any number you like(?)
Now you can “create” the plasmoid by adding a “plugin” configuration entry
systray.writeConfig("plugin","notifier") // This will add a Device Notifier Plasmoid
You can modify the plasmoid’s configuration by using writeConfig.
systray.writeConfig("property","value")
To change back to the top configuration level and thus edit the systemtray plasmoid itself pass an empty array to currentConfigGroup.
To remove a widget, simply delete the corresponding configuration group.
