ECMA Script Interaction With The Plasma Desktop Shell (plasma-desktop)
======================================================================

Overview
--------
It is possible to control and interact with plasma-desktop using ECMA Script
code. This scripting mechanism exposes containments, widgets and various aspects
of plasma-desktop configuration to the user using the widely known and used
ECMA Script language via the QtScript module.

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 first started any scripts in
  $APPDATA/plasma-desktop/init/ with a ".js" suffix are run. If there is more than one script,
  they are run serially in the alphabetical order of the file names.

  NOTE: For security reasons, scripts located in the user's home directory will NOT be
  automatically run during this phase.

* on update: when plasma-desktop is started, it will check in
  $APPDATA/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 this file is removed, then all the update
  scripts will be run again.

  NOTE: For security reasons, scripts located in the user's home directory will NOT be
  automatically run during this phase.

* interactively: an interactive scripting dialog can be requested either via
  the KRunner window with "desktop console" or directly via dbus with
  `qdbus org.kde.plasma-desktop /MainApplication showInteractiveConsole`.
  Code may be entered directly into this window for execution. Alternately,
  scripts from files can 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: Screen Geometry
--------------------
* screenCount(): returns the number of screens connected to the computer
* screenGeometry(int screen): returns a rect object representing the geometry of a screen

API: Activities
---------------
Activities (or in sightly more technical terms, desktop containments) can be enumerated,
created, destroyed and modified. In the global scope of the script, the following functions
are available:

* activityIds(): returns a list of integer ids of all existing Plasma activities
* activityById(int id): return an object representing the activity with the given id
* activityForScreen(int screen, int dekstop): returns an object representing the activity
  currently associated with the given screen and, optionally, the given desktop
* createActivity(string name): creates a new activity of type name (e.g. "desktop" or "folderview";
  this maps to the X-KDE-PluginInfo-Name= entry in the plugin's .desktop file) and returns an
  object representing it. On failure, an invalid object will be returned

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).

API: Panels
-----------
Panels can be enumerated, created, destroyed and modified. In the global script scope, the
following functions are available:

* panelIds: returns a list of integer ids of all existing Plasma panels
* panelById(int id): returns an object representing the Panel with the given id

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).

API: Activities and Panels
--------------------------
Activity and Panel objects (ones created by the script, or as returned by activityById, activityForScreen,
or panelById) provide the following properties:

* id: the integer id of this activity
* name: the name of this activity, may also be changed by assigning a new string to it (settable)
* screen: the screen this activity is associated with, or -1 for none (settable)
* desktop: the virtual desktop this activity is associated with, or -1 for none (settable)
* location: returns the location of the activity (only relevant for Panels) (settable)
* 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.
* widgetIds: a list of integer ids of all the widgets in this Activity

and the following methods:

* remove(): deletes this activity and all widgets inside of it
* widgetById(id): returns an object representing the widget with the given id
* 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
* addWidget(Object 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, Panel objects provide the folowing properties, all of which are settable:
* length: the number of pixels along the screen edge used
* height: the height (or for vertical panels, the width) of the panel
* hiding: the hiding mode of the panel, one of "none" (for no hiding), "autohide", "windowscover" or "windowsbelow"
* alignment: right, left or center alignment of the panel (for vertical panels, right corrsponds to top and left to bottom)

API: Miscelaneous
-----------------
* locked: whether the desktop shell and widgets are locked or not (settable)
* sleep(int): sleeps the script for the specified number of millseconds

API: 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 the
Activity or Panel.

A widget object provides the following properties:

* id: the id of the widget
* type: the plugin type of this widget
* configKeys: a list of all keys that are set in the current configuration
* configGroups: a list of all the groups in the current configuration
* geometry: the geometry of the widget (settable)
* index: the layout index of the widget; in a Panel this corresponds to the order in appears in

and methods:

* remove(): deletes this widget
* setConfigGroup(string group): sets the current configuration group
* readConfig(string key, variant default): reads the value of key in the config with default
  for the default value
* writeConfig(string key, variant value): sets key to value in the config
* showConfigurationInteface(): shows the configuration user interface for this widget on the screen


