KDE TechBase - User contributions [en]

Development/Tutorials/Plasma/JavaScript/API-PlasmoidObject

2013-02-07T09:46:31Z

Aseigo: /* Geometry */

= The Global plasmoid Object =
There is a global object available to the Plasmoid called, appropriately, "plasmoid". It has a number of useful properties (some of which are read only, but many of which are read/write), functions, constant values and callbacks. Each are enumerated below.
All of those are valid for both JavaScript and QML bindings.

= Callbacks =

See the section on Events above.

There are some events that are generated by Plasma for the Plasmoid. These can often be caught by providing a function assigned to a specific name in the plasmoid object. For instance, to get notified of form factor changes, one would provide a formFactorChanged method as follows:

<syntaxhighlight lang="javascript">
plasmoid.formFactorChanged = function() {

print("the form factor has changed to: " + plasmoid.formFactor())

}
</syntaxhighlight>

The following callbacks are used to notify the Plasmoid of changes in its running environment:

* '''configChanged()'''
* '''currentActivityChanged()'''
* '''formFactorChanged()'''
* '''immutabilityChanged()'''
* '''locationChanged()'''
* '''sizeChanged()'''

Other callbacks include:
* '''dataUpdated(String source, Map[String, Any] data)''': used to pass in DataEngine updates
* '''activate()''': called when the widget is activated by the user, e.g. by a keyboard shortcut. Useful for setting the focus on a specific input widget, for instance. (API v2)
* '''initExtenderItem(Extender extender)''': Called when an Extender should be set up. (API v2)
* '''popupEvent(boolean shown)''': called on PopupApplets when the popup is shown or hidden. (API v2)

In API v2, all of these callbacks can also be used as events. So, for instance, instead of implementing plasmoid.popupEvent, one could also write:
 
<syntaxhighlight lang="javascript">
plasmoid.addEventListener('popupEvent', function(shown) { print('shown? ' + shown) } )
</syntaxhighlight>
 
This would also suppress any calls to plasmoid.popupEvent.

Further documentation on these callbacks can be found in the relevant sections below.

= Environment =

A set of read-only properties (and in most cases notification functions) that tell the Plasmoid about its current environment:

* '''apiVersion''': the integer version of the Simplified JavaScript API in the current execution environment; can be used to change behaviour or usage of functions depending on the version number.

* '''formFactor''': one of Planar (e.g. on a desktop or in an application main view), Horizontal, Vertical or MediaCenter. When the form factor changes, the plasmoid.formFactorChanged function, if defined in the Plasmoid, is called.

* '''size''': the size of the Plasmoid, expressed in QSizeF (explained below). when it changes, plasmoid.sizeChanged() will be called.

* '''location''': one of Floating (no specific location), Desktop (on the application's main view are), FullScreen, LeftEdge, RightEdge, TopEdge or ButtomEdge. When the location changes, the plasmoid.locationChanged function, if defined in the Plasmoid, is called.

* '''immutable''': this property is set to true when the Plasmoid is set to not be movable or otherwise changeable, and false otherwise. Configuration is still usually allowed in this state. When the immutability changes, the plasmoid.immutabilityChanged function, if defined in the Plasmoid, is called.

* '''currentActivity''': the current contextual activity name. When the current activity changes, the plasmoid.currentActivityChanged function, if defined in the Plasmoid, is called.

* '''shouldConserveResources''': true if the plasmoid should not be doing anything that would create too much draw on power, e.g. when on a device with low battery power it may be a good idea not to run a computationally expensive but optional animation

* '''userConfiguring''': true if the user configuration interface is currently being displayed.

= Properties =
A set of read/write properties that allow the Plasmoid to set various visual or functional properties:

* ''AspectRatioMode'' '''aspectRatioMode''': defines how to treat the aspect ratio of a Plasmoid when resizing it. See the [[http://lxr.kde.org/source/kde/kde-runtime/plasma/scriptengines/javascript/plasmoid/appletinterface.h#120|AspectRatioMode]] documentation for values and their meaning.

* ''BackgroundHints'' '''backgroundHints''': defines how the background of the widget is rendered. See the [[#BackgroundHints|BackgroundHints]] documentation for values and their meaning.

* ''boolean'' '''busy''': set to true when the Plasmoid is currently processing or waiting for data and the user interface should be blocked while doing so; will generally show a full-Plasmoid animated overlay to denote business

* ''SizePolicy'' '''horizontalSizePolicy''': behaviour of the plasmoid in an horizontal layout such as a panel. It may be:
** ''Fixed'': The QWidget::sizeHint() is the only acceptable alternative, so the widget can never grow or shrink (e.g. the vertical direction of a push button).
** ''Minimum'': The sizeHint() is minimal, and sufficient. The widget can be expanded, but there is no advantage to it being larger (e.g. the horizontal direction of a push button). It cannot be smaller than the size provided by sizeHint().
** ''Maximum'': The sizeHint() is a maximum. The widget can be shrunk any amount without detriment if other widgets need the space (e.g. a separator line). It cannot be larger than the size provided by sizeHint().
** ''Preferred'': The sizeHint() is best, but the widget can be shrunk and still be useful. The widget can be expanded, but there is no advantage to it being larger than sizeHint() (the default QWidget policy).
** ''Expanding'': The sizeHint() is a sensible size, but the widget can be shrunk and still be useful. The widget can make use of extra space, so it should get as much space as possible (e.g. the horizontal direction of a horizontal slider).
** ''MinimumExpanding'': The sizeHint() is minimal, and sufficient. The widget can make use of extra space, so it should get as much space as possible (e.g. the horizontal direction of a horizontal slider).
** ''Ignored'': The sizeHint() is ignored. The widget will get as much space as possible.

* ''SizePolicy'' '''verticalSizePolicy''': behaviour of the plasmoid in a vertical layout such as a panel.

== PopupApplet specific ==
* ''QIcon'' '''popupIcon''': it will be used instead of the applet content when the applet is in a panel
* ''Object'' '''popupIconToolTip''': it contains the icon, mainText and subtext for the tooltip the applet will have when collapsed in an icon, properties:
** ''variant'' '''image''': the icon, it may be an icon name, an image path, a QIcon, QImage or a QPixmap
** ''String'' '''mainText''': the tooltip title
** ''String'' '''subText''': the tooltip descriptive subtext

<syntaxhighlight lang="javascript">
var data = new Object
data["image"] = "konqueror"
data["mainText"] = "ToolTip title"
data["subText"] = "ToolTip descriptive sub text"
plasmoid.popupIconToolTip = data
</syntaxhighlight>

* ''bool'' '''passivePopup''': if true when the popup is opened other windows can gain focus and the popup won't close

* ''bool'' '''popupShowing''': true when the popupapplet is iconified and its popup is open

== Containment specific ==
* ''Array(Object)'' '''applets''': List of all applets in the containment
* ''bool'' '''drawWallpaper''': Enable/disable the wallpaper painting by the containment
* ''enum'' '''containmentType''': one of
** ''DesktopContainment'': A desktop containment
** ''PanelContainment'': A desktop panel
** ''CustomContainment'': A containment that is neither a desktop nor a panel but something application specific
** ''CustomPanelContainment'': A customized desktop panel

* ''int'' '''screen''': Number of the screen this containment is in
* ''string'' '''activityName''': The name of the activity this containment belongs to.
* ''string'' '''activityId''': The id of the activity this containment belongs to.

The following API is only available from declarative containments.
* ''ToolBox'' '''toolBox()''': The toolbox of the Containment. The ToolBox is rendered as a separate item on the scene and provides access to the following properties:
** ''Array(QAction)'' '''actions''': A list of actions provided by the Containment.

= Geometry =

Read Only Properties:

* ''QRectF'' '''rect''': the current rect of the Plasmoid; note that the top left may be not be the origin point (0,0)

Functions:

* '''resize(width, height)''' - must not be called on widget creation (that will break external resizing; e.g. user interaction), and should only be called as a last resort during runtime. Almost always content should scale to the size of the plasmoid.
* '''setMinimumSize(width, height)''' - Not to be used from QML, where top level minimumWidth and minimumHeight properties are used instead
* '''setPreferredSize(width, height)''' - Not to be used from QML
* '''setBackgroundHints(background)''' - use '''NoBackground''' as value if you want to remove the default plasmoid background box.
* '''popupIcon(QIcon("some icon"))''' - set icon to show when the plasmoid is added to the taskbar. NOTE if the plasmoid is made in QML, you MUST specify a default size for the main Item. This size will be used for the plasmoid when added to the taskbar

= Painting and Layout =

To paint directly on to the canvas, a widget may implement the paintInterface function in the plasmoid object:

<syntaxhighlight lang="javascript">
plasmoid.paintInterface = function(painter) { /* painting code goes here*/ }
</syntaxhighlight>
 
See the Painting section below for information about helpful classes and functions that can be used when implementing a paintInterface function.

Read/Write Properties:

* ''Layout'' '''layout''': the QGraphicsLayout associated with the Plasmoid for laying out top level items; this property is read-write, though the property is not usually set as one can simply do "new LinearLayout" (or one of the other layout classes provided) and it will be automatically associated with the Plasmoid.

Functions:

* '''update()''': triggers a full repaint of the Plasmoid.
* '''update(QRectF rect)''' triggers a repaint of the rect area of the Plasmoid.
* '''failedToLaunch(bool failed[, string reason])''' sets the launch status of the Plasmoid; if set to true, the script will stop executing and the reason message, if any, will be displayed to the user.

= Access To Packaged Files =

Functions:

* ''string'' '''file(string type[, string fileName])''': returns the path to a file in the Plasmoid package of the given type, optionally with a file name to match, e.g. 
<syntaxhighlight lang="javascript">var path = plasmoid.file("mainscript")</syntaxhighlight>
 
or
 
<syntaxhighlight lang="javascript">var pm = new QPixmap(plasmoid.file("images", "mypixmap.png"))</syntaxhighlight>

* ''bool'' '''include(string filename)''': attempts to include the script defined from the package's code directory

= Configuration Data =
Configuration values can be defined using [[Development/Tutorials/Using_KConfig_XT|KConfig XT]] XML files in the {{path|contents/config/}} directory of the Plasmoid's package. The default file that is looked for and used is {{path|contents/config/main.xml}}.

== Accessing Configuration Data ==
Read-write properties:
* ''String'' '''activeConfig''': The current active configuration description. For instance, setting it to "foo" would cause the Plasmoid to try and reference the {{path|contents/config/foo.xml}} KConfigXT file. Setting this to an empty string will switch to the main.xml file.

Functions:
* ''any'' '''readConfig(String key)''': reads the value from the configuration data for the given key as defined by the currently active configuration.

* '''writeConfig(String key, any value) ''': writes a value to the configuration store under the given key

== User Customization ==

User customization can be offered by providing a Qt Designer file called {{path|contents/ui/config.ui}} in the Plasmoid's package.

Callbacks:
* '''configChanged()''': callback function called when the configuration is changed external to the Plasmoid, e.g. when the user changes settings in a configuration dialog.

= Context menu =

It's possible to add some items to the popup menu of the Plasmoid.

Functions:
* '''setAction(String name, String text, String icon, String shortcut)''': adds an item to the context menu with the given text and icon;
In pure JavaScript plasmoids you need to define '''plasmoid.action_<name>''' function, where <name> is the first argument for setAction call, and this function will be called each time user clicks the item.
Similarly in QML plasmoids you must define a function '''action_<name>''' in the root qml item that will handle the action click.
* '''setActionSeparator(String name)''': (API v5) adds a separator item to the context menu
* '''removeAction(String name)''': removes the item with <name>

Getting Started/Build/Distributions/openSUSE

2013-02-04T19:10:32Z

Aseigo: /* Required Packages */

= Introduction =

openSUSE has a very strong and active KDE team with a lot of information on their own wiki:
* [http://en.opensuse.org/Portal:KDE openSUSE KDE Portal]
* [http://en.opensuse.org/KDE_repositories openSUSE KDE package repositories]
* [http://en.opensuse.org/openSUSE:KDE_developers_guide openSUSE KDE Developers Guide] (Outdated)
* [http://en.opensuse.org/KDE openSUSE wiki KDE page]

= Required Packages =
Use the following command to install the needed packages:

<pre>
zypper si -d kdelibs4
</pre>

= Build =

This section describes how you can get kde to compile so that you can log in graphically (using kdm, the KDE display manager) and call konqueror (contained in KDEBASE, KDE's base package).

== kdesupport ==

You can install kdesupport and its dependencies from SUSE by adding the KDE:Distro:Stable repository from
the [http://download.opensuse.org/repositories/KDE:/Distro:/Stable/ openSUSE Build Service] to your repositories. For openSUSE 12.1 add this Repository to YaST/zypper:
http://download.opensuse.org/repositories/KDE:/Distro:/Stable/openSUSE_12.1/

For older versions of openSUSE do:
su
zypper ar -f http://download.opensuse.org/repositories/KDE:/Distro:/Stable/[YOUR openSUSE VERSION]

Now install kdesupport from openSUSE:
zypper install libqca2-devel libsoprano-devel libqimageblitz-devel strigi-devel

Please remember to skip any instructions from [[Getting_Started/Build]] that refer to kdesupport. Start to compile with kdelibs.

= Using openSUSE Unstable Repositories =

openSUSE, via its Build Service, provides a so-called unstable repository which contains weekly snapshots from KDE SVN trunk. These allow you to run a system install of unstable, but does not allow you to keep a stable system install while testing unstable in parallel.

== Requirements ==

You need a supported openSUSE version, that is, at the time of writing, openSUSE 11.4 or 12.1 or openSUSE Factory (the always-on-development branch of openSUSE).

== Installing packages from the unstable repository ==

Add the repository manually and perform an installation from the command line.

=== Addition of the repository ===

Add the repository. To do so, enter as root

zypper ar -f http://download.opensuse.org/repositories/KDE:/Unstable:/SC/YOUR_openSUSE_VERSION/ [ALIAS]

where YOUR_openSUSE_VERSION is either openSUSE_11.4, openSUSE_12.1, or openSUSE_Factory depending on what you are running. And ALIAS is whatever name you want to assign to the repository.

After that upgrade the packages to the unstable version:

zypper dup --from [ALIAS]

=== Post-installation steps ===

You may want to add some additional repositories to have compatible non KDE SC packages available.

zypper ar -f http://download.opensuse.org/repositories/KDE:/UpdatedApps/YOUR_openSUSE_VERSION/ [ALIAS]
zypper ar -f http://download.opensuse.org/repositories/KDE:/Extra/YOUR_openSUSE_VERSION/_KDE_Unstable_SC/ [ALIAS]

followed by the installation the packages you need:

zypper install [package]

Return to [[Getting_Started/Build|Building KDE]].

KDE System Administration/PlasmaDesktopScripting

2013-01-28T17:04:54Z

Aseigo: /* Locating Applications and Paths */

== ECMA Script Interaction With Plasma Shells ==

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.

== Examples ==

A set of examples can be found [https://projects.kde.org/projects/kde/kdeexamples/repository/revisions/master/show/plasma/javascript/plasma-shell-scripting 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.

== 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|For security reasons, scripts located in the user's home directory will '''not''' be run during this phase.}}

* '''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.

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

* '''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 <syntaxhighlight lang="bash">qdbus org.kde.plasma-desktop /MainApplication showInteractiveConsole</syntaxhighlight>

{{note|This method is not available for plasma-netbook.}}

: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
<syntaxhighlight lang="bash">qdbus org.kde.plasma-desktop /MainApplication loadScriptInInteractiveConsole /path/to/file</syntaxhighlight>

== Templates ==

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:

* metadata.desktop: a .desktop file describing the template
* contents/layout.js: a Javascript file containing the actual script

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:

<syntaxhighlight lang="ini">
[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
</syntaxhighlight>

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.

=== Examples of Usage ===

==== Creating panels ====
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.

==== Automating tasks ====
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:

<syntaxhighlight lang="javascript">
var template = loadTemplate('org.kde.plasma-desktop.findWidgets')
template.findWidgets('systemtray')
</syntaxhighlight>

==== Activity templates ====
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:

<syntaxhighlight lang="ini">
[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
</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 <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:
* $desktop
* $autostart
* $documents
* $music
* $video
* $downloads
* $pictures

They all expand into the path toward the user corresponding default folder.

== 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|API compatibility is guaranteed from version to version starting with KDE Software Compilation v4.4.0.}}

=== 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. 0.3
* ''String'' '''platformVersion''': the version of the KDE Platform, e.g. 0.3
* ''number'' '''scriptingVersion''': the version of the scripting API; e.g. in KDE SC 4.5 this is 2

=== 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:
<syntaxhighlight lang="javascript">
var activity = new Activity("folderview")
</syntaxhighlight>

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
* ''Array[String]'' '''knownActivityTypes''': (scripting version >= 2) 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:
* ''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.
* ''Array[Activity]'' '''activities()''': returns an array of all activities that currently exist

=== 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:
<syntaxhighlight lang="javascript">
var panel = new Panel("dock")
</syntaxhighlight>
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
* ''Array[String]'' '''knownPanelTypes''': (scripting version >= 2) 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.

Functions:
* ''Panel'' '''panelById(int id)''': returns an object representing the Panel that matches the given id
* ''Array[Panels]'' '''panels()''': returns an array of all panels that currently exist

=== Activities and Panels ===
Activity and Panel objects, once 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
* ''Array[String]'' '''configKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current configuration group
* ''Array[String]'' '''configGroups''': (scriptingVersion >= 2) a list of all the groups in the current configuration group
* ''Array[String]'' '''globalConfigKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current global configuration group
* ''Array[String]'' '''globalConfigGroups''': (scriptingVersion >= 2) a list of all the groups in the current global configuration group

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
* ''String'' '''wallpaperPlugin''': (scriptingVersion >= 2) the wallpaper plugin to use with the Activity
* ''String'' '''wallpaperMode''': (scriptingVersion >= 2) the wallpaper plugin mode to use with the Activity
* ''Array[String]'' '''currentConfigGroup''': (scriptingVersion >= 2) 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
* ''String'' '''version''': (scriptingVersion >= 2) the version of the Activity or Panel

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 <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
* '''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
* '''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 for the default value
* '''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
* ''Array[String]'' '''currentGlobalConfigGroup''': (scriptingVersion >= 2) the current global configuration group path, with each entry in the array representing a sub-group, similar to currentConfigGroup. However, global configuration is shared by all instances of panels and activities of the same type.
* ''Array[Widget]'' '''widgets([String type])''': (scriptingVersion >= 2) returns all the widgets in the Panel or Activity. If the optional type is specified, only widgets matching that type will be returned.

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.

==== Checking if a widget is installed ====
A list of all installed widget types can be retrieved the following read-only property:

* ''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:

* ''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
* ''Array[String]'' '''globalConfigKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current global configuration group
* ''Array[String]'' '''globalConfigGroups''': (scriptingVersion >= 2) a list of all the groups in the current global configuration group
* ''String'' '''version''': (scriptingVersion >= 2) the version of the Activity or Panel

as well as the following read-write properties:

* ''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
* ''Array[String]'' '''currentGlobalConfigGroup''': (scriptingVersion >= 2) the current global configuration group path, with each entry in the array representing a sub-group, similar to currentConfigGroup. However, global configuration is shared by all instances of widgets of the same type.
* ''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
* ''number'' '''index''': the layout index of the widget; in a Panel this corresponds to the order the widget appears in. Changing the value of the index will change the position of the widget in Panels and may do so in some Activities as well.

and the following 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
* '''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
* '''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
* '''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:
* ''QRectF'' '''screenGeometry(number screen)''': returns a rect object representing the geometry of a screen

=== 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 ===
* ''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.
* ''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:
** documents
** music
** video
** downloads
** pictures
** autostart
** desktop (should be considered deprecated for Plasma workspaces)

If a second string is passed in, it is considered a request for a specific path and the following types are recognized:
** apps - Applications menu (.desktop files).
** autostart - Autostart directories (both XDG and kde-specific)
** cache - Cached information (e.g. favicons, web-pages)
** cgi - CGIs to run from kdehelp.
** config - Configuration files.
** data - Where applications store data.
** emoticons - Emoticons themes
** exe - Executables in $prefix/bin. findExe() for a function that takes $PATH into account.
** html - HTML documentation.
** icon - Icons, see KIconLoader.
** kcfg - KConfigXT config files.
** lib - Libraries.
** locale - Translation files for KLocale.
** mime - Mime types defined by KDE-specific .desktop files.
** module - Module (dynamically loaded library).
** qtplugins - Qt plugins (dynamically loaded objects for Qt)
** services - Services.
** servicetypes - Service types.
** sound - Application sounds.
** templates - Templates for the "Create new file" functionality.
** wallpaper - Wallpapers.
** tmp - Temporary files (specific for both current host and current user)
** socket - UNIX Sockets (specific for both current host and current user)
** xdgconf-menu - Freedesktop.org standard location for menu layout (.menu) files.
** xdgdata-apps - Freedesktop.org standard location for application desktop files.
** xdgdata-dirs - Freedesktop.org standard location for menu descriptions (.directory files).
** xdgdata-mime - Freedesktop.org standard location for MIME type definitions.
** xdgdata-icon - Freedesktop.org standard location for icons.
** xdgdata-pixmap - Gnome-compatibility location for pixmaps.

The second parameter should be a specific resource to find the path to. An example might be userDataPath("data", "plasma-desktop").

=== Misc. Global Properties and Functions ===
Read-write properties:
* ''boolean'' '''locked''': whether the desktop shell and widgets are locked or not (settable)
* ''string'' '''theme''': (scripting version >= 3) the name of the desktop theme to use for the interface, e.g. default, Air, Oxygen, etc.

Read-only properties:
* ''boolean'' '''hasBattery''': whether or not the system has the ability to run on battery power, e.g. a laptop or mobile device
* ''boolean'' '''multihead''': (scripting version >= 3) true if the system is running with multiple screens in a "Xaphod" multiple display server configuration
* ''int'' '''multiheadScreen''': (scripting version >= 3) if multihead is true, contains the (real) screen id of the current screen

Functions:
* '''sleep(number ms)''': sleeps the script for the specified number of millseconds

=== QRectF ===
A rectangle class is also provided for use with Widget, Panel and screen geometry properties and functions.

Read-only properites:
* ''boolean'' '''empty''': true if the rectangle's width or height is less than, or equal to, 0; an empty rectangle is also invalid
* ''boolean'' '''null''': true if the rectangle has both the width and the height set to 0; a null rectangle is also empty and not valid
* ''boolean'' '''valid''': true if the rectangle has a width > 0 and height 0.

Read-write properties:
* ''number'' '''left'''
* ''number'' '''top'''
* ''number'' '''bottom'''
* ''number'' '''right'''
* ''number'' '''height'''
* ''number'' '''width'''
* ''number'' '''x'''
* ''number'' '''y'''

Constructors:
* '''QRectF'''
* '''QRectF(number x, number y, number width, number height)''': Sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.

Functions:
* '''adjust(number dx1, number dy1, number dx2, number dy2)''': adds dx1, dy1, dx2 and dy2 respectively to the existing coordinates of the rectangle
* ''QRectF'' '''adjusted(number dx1, number dy1, number dx2, number dy2)''': returns a new QRectF with dx1, dy1, dx2 and dy2 added respectively to the existing coordinates of the rectangle
* '''translate(number dx, number dy)''': translates the rect by dx, dy
* '''setCoords(number x1, number y1, number x2, number y2)''': sets the coordinates of the rectangle's top-left corner to (x1, y1), and the coordinates of its bottom-right corner to (x2, y2).
* '''setRect(number x, number y, number width, number height)''': sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.
* ''boolean'' '''contains(number x, number y)''': returns true if the rect contains the point (x, y)
* '''moveBottom(number delta)'': moves the bottom by delta pixels
* '''moveLeft(number delta)''': moves the left by delta pixels
* '''moveRight(number delta)''': moves the right by delta pixels
* '''moveTo(number x, number y)''': moves the top left of the rect to point (x, y)
* '''moveTop(number delta)''': moves the top by delta pixels

== Configuration Keys ==
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'''.

=== Common configuration keys ===
Here are some keys that can be used with all widgets:

* '''Share''' (true/false): Whether or not the widget is to be announces throughout the network (Share tab)

=== Common time and date keys ===
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.
* '''announceInterval''' (number ≥ 0): Interval in minutes that the time is read out loud
* '''calendarType''' (local/coptic/ethopian/gregorian/gregorian-proleptic/hebrew/hijri/indian-national/jalali/japanese/julian/minguo/thai): Calendar system to be used, defaults to local
* '''defaultTimezone''' (Local/…): Time zone to be used
* '''displayHolidays''' (true/false): Whether holidays are to be displayed
* '''holidayRegions''' (tbd): tbd
* '''holidayRegionaDaysOff''' (tbd): tbd
* '''timeZones''' (Europe/Andorra,…): Comma-separated list of timezones to be used (e. g. Europe/Andorra,Indian/Antananarivo,Asia/Aqtau)

=== Analog clock (clock) ===
* '''showSecondHand''' (true/false): self-explanatory
* '''showTimezoneString''' (true/false): self-explanatory

=== Battery status (battery) ===
* '''showBatteryString''' (true/false): Whether or not battery status is shown as overlay for the battery icon (if in systemtray or panel)
* '''showMultipleBatteries''' (true/false): Whether or not battery status is shown for each battery separately

=== Digital clock (digital-clock) ===
* '''plainClockColor''' (rrr,ggg,bbb): Color set for clock font (e. g. 192,0,0 - to be used with useCustomColor=true!)
* '''plainClockDrawShadow''' (true/false): Whether a shadow is to bed drawn (defaults to true)
* '''plainClockShadowColor''' (rrr,ggg,bbb): Color set for clock shadow (e. g. 64,97,128 - to be used with useCustomShadowColor=true!)
* '''plainClockFont''' (tbd): Font to be used for clock (e. g. Serif,12,-1,5,75,0,0,0,0,0)
* '''showDate''' (true/false): self-explanatory
* '''showDay''' (true/false): self-explanatory
* '''showSeconds''' (true/false): self-explanatory
* '''showTimezone''' (true/false): self-explanatory
* '''showYear''' (true/false): self-explanatory
* '''useCustomColor''' (true/false): Whether or not a custom color is to be used (use with plainClockColor=rrr,ggg,bbb!)
* '''useCustomShadowColor''' (true/false): Whether or not a custom shadow color is to be used (use with plainClockShadowColor=rrr,ggg,bbb!)

=== Folderview (folderview) ===
* '''alignToGrid''' (true/false): self-explanatory
* '''customIconSize''' (16/22/24/32/48/…): Use custom icon size for files/folders (use only default/common icon sizes, powers of 2)
* '''customLabel''': Use custom title rather than default path or place name
* '''drawShadows''' (true/false): Whether or not file labels are to draw shadows
* '''filter''' (0/1/2): Defines whether a filter is to be used or not (0 = No filter, 1 = Show only matching files, 2 = Hide matching files)
* '''filterFiles''': Wildcard filter to filter file names
* '''mimeFilter''': Comma-separated list of mimetypes to be filtered (shown/hidden depends on filter-setting)
* '''iconsLocked''' (true/false): Whether or not icons can be moved
* '''numTextLines''' (number > 0): Amount of lines a file name can have before it is truncated
* '''url''': Folder URL to be displayed (e. g. desktop:/// or file:///home/yourusername)
* '''sortColumn''' (-1/0/1/2/3/4/5): The way files and folders are sorted (-1 = No sorting, 0 = By name, 1 = By size, 2 = By type, 3 = By date)
* '''sortDirsFirst''' (true/false): Whether or not folders are displayed before files (defaults to true)
* '''textColor''' (rrr,ggg,bbb): Color the icon labels will have

=== Kickoff menu (launcher) ===
* '''SwitchTabsOnHover''' (true/false): self-explanatory
* '''ShowAppsByName''' (true/false): Apps are sorted by name rather than by description

=== Pager (pager) ===
* '''displayedText''' (0/1/2): Text to be shown on individual virtual desktops (0 = Workspace number, 1 = Workspace title, 2 = None)
* '''ShowWindowIcons''' (true/false): Whether or not the application icon is to be shown on each individual window
* '''currentDesktopSelected''' (0/1/2): Defines what should happen if the user clicks on the virtual desktop that is currently active (0 = Nothing, 1 = Show Workspace, i. e. minimize windows, 2 = Show Dashboard)
* '''rows''' (number > 0): Amount of rows the pager should have. (Note: ''This is a global option, so you need to use '''writeGlobalConfig''' instead'')

=== Notifications (notifications) ===
{{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}}
* '''AutoHidePopup''' (true/false): Whether or not popups are to be hidden automatiaclly
* '''ShowJobs''' (true/false): Whether or not jobs are to be shown (e. g. file transfer progress)
* '''ShowNotifications''' (true/false): Whether or not notifications are to be shown

=== Removable media notifier (notifier) ===
* '''ShowDevices''' (0/1/2): Defines what kind of devices are to be shown (0 = Removable media only, 1 = Non-removable media only, 2 = All)
{{note|Auto-mount settings and device actions are not stored in this Plasmoid’s settings.}}

=== Taskbar (tasks) ===
* '''groupingStrategy''' (0/1/2): Defines how taskbar entries are to be grouped (0 = Never, 1 = Manually, 2 = By Program Name)
* '''groupWhenFull''' (true/false): Only group when taskbar is full (to be used with groupingStrategy=2 only!)
* '''highlightWindows''' (true/false): Highlight a window if your mouse cursor is hovering its taskbar entry (requires Desktop Compositing and “Highlight windows” effect enabled to work)
* '''maxRows''' (number > 0): Amount of rows taskbar entries can take
* '''forceRows''' (true/false): Force row setting for taskbar entries
* '''showOnlyCurrentActivity''' (true/false): Show only windows from current activity
* '''showOnlyCurrentDesktop''' (true/false): Show only windows from current virtual desktop
* '''showOnlyCurrentScreen''' (true/false): Show only windows from current screen (multi monitor setup)
* '''showTooltip''' (true/false): Whether or not tooltips are to be shown
* '''sortingStrategy''' (0/1/2/3): How taskbar entries are to be sorted (0 = Never, 1 = Manually, 2 = Alphabetically, 3 = By Desktop)

=== System Tray ===
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.

==== Generic System Tray configuration keys ====
* '''DefaultAppletAdded''' (true/false): Remembers whether the default plasmoids (networkmanagement, device manager, notifications) have already been added(??)
* '''ShowApplicationStatus''' (true/false): Show system tray icons of applications that belong to the group “Applications”
* '''ShowCommunications''' (true/false): Show system tray icons of applications that belong to the group “Applications” (i. e. Messenger, IRC chat)
* '''ShowHardware''' (true/false): Show system tray icons of applications that belong to the group “Hardware” (i. e. volume control, printer applet)
* '''ShowSystemServices''' (true/false): Show system tray icons of applications that belong to the group “System Services” (i. e. Nepomuk Indexing Agent)
* '''ShowUnknown''' (true/false): Show system tray icons that do not belong into one of the categories mentioned above (or that do not use KDE’s system tray protocol and thus do not provide such information)
* '''alwaysShown''': Comma-separated list of widgets and entries that are to be shown all the time (e. g. KMix,notifier)
* '''hidden''': Comma-separated list of widgets and entries that are to be hidden all the time (e. g. Nepomuk Indexing Agent,Klipper,kmail)
{{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}}

==== 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.
<syntaxhighlight lang="cpp-qt">
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
<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.
<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.

==== Edit existing widgets in systemtray ====

==== Remove a widget from systemtray ====

To remove a widget, simply delete the corresponding configuration group.

KDE System Administration/PlasmaDesktopScripting

2013-01-28T15:53:17Z

Aseigo: /* Locating Applications and Paths */

== ECMA Script Interaction With Plasma Shells ==

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.

== Examples ==

A set of examples can be found [https://projects.kde.org/projects/kde/kdeexamples/repository/revisions/master/show/plasma/javascript/plasma-shell-scripting 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.

== 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|For security reasons, scripts located in the user's home directory will '''not''' be run during this phase.}}

* '''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.

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

* '''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 <syntaxhighlight lang="bash">qdbus org.kde.plasma-desktop /MainApplication showInteractiveConsole</syntaxhighlight>

{{note|This method is not available for plasma-netbook.}}

: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
<syntaxhighlight lang="bash">qdbus org.kde.plasma-desktop /MainApplication loadScriptInInteractiveConsole /path/to/file</syntaxhighlight>

== Templates ==

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:

* metadata.desktop: a .desktop file describing the template
* contents/layout.js: a Javascript file containing the actual script

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:

<syntaxhighlight lang="ini">
[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
</syntaxhighlight>

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.

=== Examples of Usage ===

==== Creating panels ====
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.

==== Automating tasks ====
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:

<syntaxhighlight lang="javascript">
var template = loadTemplate('org.kde.plasma-desktop.findWidgets')
template.findWidgets('systemtray')
</syntaxhighlight>

==== Activity templates ====
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:

<syntaxhighlight lang="ini">
[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
</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 <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:
* $desktop
* $autostart
* $documents
* $music
* $video
* $downloads
* $pictures

They all expand into the path toward the user corresponding default folder.

== 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|API compatibility is guaranteed from version to version starting with KDE Software Compilation v4.4.0.}}

=== 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. 0.3
* ''String'' '''platformVersion''': the version of the KDE Platform, e.g. 0.3
* ''number'' '''scriptingVersion''': the version of the scripting API; e.g. in KDE SC 4.5 this is 2

=== 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:
<syntaxhighlight lang="javascript">
var activity = new Activity("folderview")
</syntaxhighlight>

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
* ''Array[String]'' '''knownActivityTypes''': (scripting version >= 2) 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:
* ''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.
* ''Array[Activity]'' '''activities()''': returns an array of all activities that currently exist

=== 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:
<syntaxhighlight lang="javascript">
var panel = new Panel("dock")
</syntaxhighlight>
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
* ''Array[String]'' '''knownPanelTypes''': (scripting version >= 2) 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.

Functions:
* ''Panel'' '''panelById(int id)''': returns an object representing the Panel that matches the given id
* ''Array[Panels]'' '''panels()''': returns an array of all panels that currently exist

=== Activities and Panels ===
Activity and Panel objects, once 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
* ''Array[String]'' '''configKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current configuration group
* ''Array[String]'' '''configGroups''': (scriptingVersion >= 2) a list of all the groups in the current configuration group
* ''Array[String]'' '''globalConfigKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current global configuration group
* ''Array[String]'' '''globalConfigGroups''': (scriptingVersion >= 2) a list of all the groups in the current global configuration group

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
* ''String'' '''wallpaperPlugin''': (scriptingVersion >= 2) the wallpaper plugin to use with the Activity
* ''String'' '''wallpaperMode''': (scriptingVersion >= 2) the wallpaper plugin mode to use with the Activity
* ''Array[String]'' '''currentConfigGroup''': (scriptingVersion >= 2) 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
* ''String'' '''version''': (scriptingVersion >= 2) the version of the Activity or Panel

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 <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
* '''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
* '''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 for the default value
* '''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
* ''Array[String]'' '''currentGlobalConfigGroup''': (scriptingVersion >= 2) the current global configuration group path, with each entry in the array representing a sub-group, similar to currentConfigGroup. However, global configuration is shared by all instances of panels and activities of the same type.
* ''Array[Widget]'' '''widgets([String type])''': (scriptingVersion >= 2) returns all the widgets in the Panel or Activity. If the optional type is specified, only widgets matching that type will be returned.

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.

==== Checking if a widget is installed ====
A list of all installed widget types can be retrieved the following read-only property:

* ''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:

* ''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
* ''Array[String]'' '''globalConfigKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current global configuration group
* ''Array[String]'' '''globalConfigGroups''': (scriptingVersion >= 2) a list of all the groups in the current global configuration group
* ''String'' '''version''': (scriptingVersion >= 2) the version of the Activity or Panel

as well as the following read-write properties:

* ''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
* ''Array[String]'' '''currentGlobalConfigGroup''': (scriptingVersion >= 2) the current global configuration group path, with each entry in the array representing a sub-group, similar to currentConfigGroup. However, global configuration is shared by all instances of widgets of the same type.
* ''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
* ''number'' '''index''': the layout index of the widget; in a Panel this corresponds to the order the widget appears in. Changing the value of the index will change the position of the widget in Panels and may do so in some Activities as well.

and the following 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
* '''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
* '''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
* '''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:
* ''QRectF'' '''screenGeometry(number screen)''': returns a rect object representing the geometry of a screen

=== 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 ===
* ''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.
* ''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 (application + " 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:
** documents
** music
** video
** downloads
** pictures
** autostart
** desktop (should be considered deprecated for Plasma workspaces)

If a second string is passed in, it is considered a request for a specific path and the following types are recognized:
** apps - Applications menu (.desktop files).
** autostart - Autostart directories (both XDG and kde-specific)
** cache - Cached information (e.g. favicons, web-pages)
** cgi - CGIs to run from kdehelp.
** config - Configuration files.
** data - Where applications store data.
** emoticons - Emoticons themes
** exe - Executables in $prefix/bin. findExe() for a function that takes $PATH into account.
** html - HTML documentation.
** icon - Icons, see KIconLoader.
** kcfg - KConfigXT config files.
** lib - Libraries.
** locale - Translation files for KLocale.
** mime - Mime types defined by KDE-specific .desktop files.
** module - Module (dynamically loaded library).
** qtplugins - Qt plugins (dynamically loaded objects for Qt)
** services - Services.
** servicetypes - Service types.
** sound - Application sounds.
** templates - Templates for the "Create new file" functionality.
** wallpaper - Wallpapers.
** tmp - Temporary files (specific for both current host and current user)
** socket - UNIX Sockets (specific for both current host and current user)
** xdgconf-menu - Freedesktop.org standard location for menu layout (.menu) files.
** xdgdata-apps - Freedesktop.org standard location for application desktop files.
** xdgdata-dirs - Freedesktop.org standard location for menu descriptions (.directory files).
** xdgdata-mime - Freedesktop.org standard location for MIME type definitions.
** xdgdata-icon - Freedesktop.org standard location for icons.
** xdgdata-pixmap - Gnome-compatibility location for pixmaps.

The second parameter should be a specific resource to find the path to. An example might be userDataPath("data", "plasma-desktop").

=== Misc. Global Properties and Functions ===
Read-write properties:
* ''boolean'' '''locked''': whether the desktop shell and widgets are locked or not (settable)
* ''string'' '''theme''': (scripting version >= 3) the name of the desktop theme to use for the interface, e.g. default, Air, Oxygen, etc.

Read-only properties:
* ''boolean'' '''hasBattery''': whether or not the system has the ability to run on battery power, e.g. a laptop or mobile device
* ''boolean'' '''multihead''': (scripting version >= 3) true if the system is running with multiple screens in a "Xaphod" multiple display server configuration
* ''int'' '''multiheadScreen''': (scripting version >= 3) if multihead is true, contains the (real) screen id of the current screen

Functions:
* '''sleep(number ms)''': sleeps the script for the specified number of millseconds

=== QRectF ===
A rectangle class is also provided for use with Widget, Panel and screen geometry properties and functions.

Read-only properites:
* ''boolean'' '''empty''': true if the rectangle's width or height is less than, or equal to, 0; an empty rectangle is also invalid
* ''boolean'' '''null''': true if the rectangle has both the width and the height set to 0; a null rectangle is also empty and not valid
* ''boolean'' '''valid''': true if the rectangle has a width > 0 and height 0.

Read-write properties:
* ''number'' '''left'''
* ''number'' '''top'''
* ''number'' '''bottom'''
* ''number'' '''right'''
* ''number'' '''height'''
* ''number'' '''width'''
* ''number'' '''x'''
* ''number'' '''y'''

Constructors:
* '''QRectF'''
* '''QRectF(number x, number y, number width, number height)''': Sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.

Functions:
* '''adjust(number dx1, number dy1, number dx2, number dy2)''': adds dx1, dy1, dx2 and dy2 respectively to the existing coordinates of the rectangle
* ''QRectF'' '''adjusted(number dx1, number dy1, number dx2, number dy2)''': returns a new QRectF with dx1, dy1, dx2 and dy2 added respectively to the existing coordinates of the rectangle
* '''translate(number dx, number dy)''': translates the rect by dx, dy
* '''setCoords(number x1, number y1, number x2, number y2)''': sets the coordinates of the rectangle's top-left corner to (x1, y1), and the coordinates of its bottom-right corner to (x2, y2).
* '''setRect(number x, number y, number width, number height)''': sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.
* ''boolean'' '''contains(number x, number y)''': returns true if the rect contains the point (x, y)
* '''moveBottom(number delta)'': moves the bottom by delta pixels
* '''moveLeft(number delta)''': moves the left by delta pixels
* '''moveRight(number delta)''': moves the right by delta pixels
* '''moveTo(number x, number y)''': moves the top left of the rect to point (x, y)
* '''moveTop(number delta)''': moves the top by delta pixels

== Configuration Keys ==
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'''.

=== Common configuration keys ===
Here are some keys that can be used with all widgets:

* '''Share''' (true/false): Whether or not the widget is to be announces throughout the network (Share tab)

=== Common time and date keys ===
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.
* '''announceInterval''' (number ≥ 0): Interval in minutes that the time is read out loud
* '''calendarType''' (local/coptic/ethopian/gregorian/gregorian-proleptic/hebrew/hijri/indian-national/jalali/japanese/julian/minguo/thai): Calendar system to be used, defaults to local
* '''defaultTimezone''' (Local/…): Time zone to be used
* '''displayHolidays''' (true/false): Whether holidays are to be displayed
* '''holidayRegions''' (tbd): tbd
* '''holidayRegionaDaysOff''' (tbd): tbd
* '''timeZones''' (Europe/Andorra,…): Comma-separated list of timezones to be used (e. g. Europe/Andorra,Indian/Antananarivo,Asia/Aqtau)

=== Analog clock (clock) ===
* '''showSecondHand''' (true/false): self-explanatory
* '''showTimezoneString''' (true/false): self-explanatory

=== Battery status (battery) ===
* '''showBatteryString''' (true/false): Whether or not battery status is shown as overlay for the battery icon (if in systemtray or panel)
* '''showMultipleBatteries''' (true/false): Whether or not battery status is shown for each battery separately

=== Digital clock (digital-clock) ===
* '''plainClockColor''' (rrr,ggg,bbb): Color set for clock font (e. g. 192,0,0 - to be used with useCustomColor=true!)
* '''plainClockDrawShadow''' (true/false): Whether a shadow is to bed drawn (defaults to true)
* '''plainClockShadowColor''' (rrr,ggg,bbb): Color set for clock shadow (e. g. 64,97,128 - to be used with useCustomShadowColor=true!)
* '''plainClockFont''' (tbd): Font to be used for clock (e. g. Serif,12,-1,5,75,0,0,0,0,0)
* '''showDate''' (true/false): self-explanatory
* '''showDay''' (true/false): self-explanatory
* '''showSeconds''' (true/false): self-explanatory
* '''showTimezone''' (true/false): self-explanatory
* '''showYear''' (true/false): self-explanatory
* '''useCustomColor''' (true/false): Whether or not a custom color is to be used (use with plainClockColor=rrr,ggg,bbb!)
* '''useCustomShadowColor''' (true/false): Whether or not a custom shadow color is to be used (use with plainClockShadowColor=rrr,ggg,bbb!)

=== Folderview (folderview) ===
* '''alignToGrid''' (true/false): self-explanatory
* '''customIconSize''' (16/22/24/32/48/…): Use custom icon size for files/folders (use only default/common icon sizes, powers of 2)
* '''customLabel''': Use custom title rather than default path or place name
* '''drawShadows''' (true/false): Whether or not file labels are to draw shadows
* '''filter''' (0/1/2): Defines whether a filter is to be used or not (0 = No filter, 1 = Show only matching files, 2 = Hide matching files)
* '''filterFiles''': Wildcard filter to filter file names
* '''mimeFilter''': Comma-separated list of mimetypes to be filtered (shown/hidden depends on filter-setting)
* '''iconsLocked''' (true/false): Whether or not icons can be moved
* '''numTextLines''' (number > 0): Amount of lines a file name can have before it is truncated
* '''url''': Folder URL to be displayed (e. g. desktop:/// or file:///home/yourusername)
* '''sortColumn''' (-1/0/1/2/3/4/5): The way files and folders are sorted (-1 = No sorting, 0 = By name, 1 = By size, 2 = By type, 3 = By date)
* '''sortDirsFirst''' (true/false): Whether or not folders are displayed before files (defaults to true)
* '''textColor''' (rrr,ggg,bbb): Color the icon labels will have

=== Kickoff menu (launcher) ===
* '''SwitchTabsOnHover''' (true/false): self-explanatory
* '''ShowAppsByName''' (true/false): Apps are sorted by name rather than by description

=== Pager (pager) ===
* '''displayedText''' (0/1/2): Text to be shown on individual virtual desktops (0 = Workspace number, 1 = Workspace title, 2 = None)
* '''ShowWindowIcons''' (true/false): Whether or not the application icon is to be shown on each individual window
* '''currentDesktopSelected''' (0/1/2): Defines what should happen if the user clicks on the virtual desktop that is currently active (0 = Nothing, 1 = Show Workspace, i. e. minimize windows, 2 = Show Dashboard)
* '''rows''' (number > 0): Amount of rows the pager should have. (Note: ''This is a global option, so you need to use '''writeGlobalConfig''' instead'')

=== Notifications (notifications) ===
{{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}}
* '''AutoHidePopup''' (true/false): Whether or not popups are to be hidden automatiaclly
* '''ShowJobs''' (true/false): Whether or not jobs are to be shown (e. g. file transfer progress)
* '''ShowNotifications''' (true/false): Whether or not notifications are to be shown

=== Removable media notifier (notifier) ===
* '''ShowDevices''' (0/1/2): Defines what kind of devices are to be shown (0 = Removable media only, 1 = Non-removable media only, 2 = All)
{{note|Auto-mount settings and device actions are not stored in this Plasmoid’s settings.}}

=== Taskbar (tasks) ===
* '''groupingStrategy''' (0/1/2): Defines how taskbar entries are to be grouped (0 = Never, 1 = Manually, 2 = By Program Name)
* '''groupWhenFull''' (true/false): Only group when taskbar is full (to be used with groupingStrategy=2 only!)
* '''highlightWindows''' (true/false): Highlight a window if your mouse cursor is hovering its taskbar entry (requires Desktop Compositing and “Highlight windows” effect enabled to work)
* '''maxRows''' (number > 0): Amount of rows taskbar entries can take
* '''forceRows''' (true/false): Force row setting for taskbar entries
* '''showOnlyCurrentActivity''' (true/false): Show only windows from current activity
* '''showOnlyCurrentDesktop''' (true/false): Show only windows from current virtual desktop
* '''showOnlyCurrentScreen''' (true/false): Show only windows from current screen (multi monitor setup)
* '''showTooltip''' (true/false): Whether or not tooltips are to be shown
* '''sortingStrategy''' (0/1/2/3): How taskbar entries are to be sorted (0 = Never, 1 = Manually, 2 = Alphabetically, 3 = By Desktop)

=== System Tray ===
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.

==== Generic System Tray configuration keys ====
* '''DefaultAppletAdded''' (true/false): Remembers whether the default plasmoids (networkmanagement, device manager, notifications) have already been added(??)
* '''ShowApplicationStatus''' (true/false): Show system tray icons of applications that belong to the group “Applications”
* '''ShowCommunications''' (true/false): Show system tray icons of applications that belong to the group “Applications” (i. e. Messenger, IRC chat)
* '''ShowHardware''' (true/false): Show system tray icons of applications that belong to the group “Hardware” (i. e. volume control, printer applet)
* '''ShowSystemServices''' (true/false): Show system tray icons of applications that belong to the group “System Services” (i. e. Nepomuk Indexing Agent)
* '''ShowUnknown''' (true/false): Show system tray icons that do not belong into one of the categories mentioned above (or that do not use KDE’s system tray protocol and thus do not provide such information)
* '''alwaysShown''': Comma-separated list of widgets and entries that are to be shown all the time (e. g. KMix,notifier)
* '''hidden''': Comma-separated list of widgets and entries that are to be hidden all the time (e. g. Nepomuk Indexing Agent,Klipper,kmail)
{{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}}

==== 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.
<syntaxhighlight lang="cpp-qt">
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
<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.
<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.

==== Edit existing widgets in systemtray ====

==== Remove a widget from systemtray ====

To remove a widget, simply delete the corresponding configuration group.

KDE System Administration/PlasmaDesktopScripting

2012-10-01T12:18:30Z

Aseigo: /* Widgets */

== ECMA Script Interaction With Plasma Shells ==

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.

== Examples ==

A set of examples can be found [https://projects.kde.org/projects/kde/kdeexamples/repository/revisions/master/show/plasma/javascript/plasma-shell-scripting 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.

== 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|For security reasons, scripts located in the user's home directory will '''not''' be run during this phase.}}

* '''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.

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

* '''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 <syntaxhighlight lang="bash">qdbus org.kde.plasma-desktop /MainApplication showInteractiveConsole</syntaxhighlight>

{{note|This method is not available for plasma-netbook.}}

: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
<syntaxhighlight lang="bash">qdbus org.kde.plasma-desktop /MainApplication loadScriptInInteractiveConsole /path/to/file</syntaxhighlight>

== Templates ==

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:

* metadata.desktop: a .desktop file describing the template
* contents/layout.js: a Javascript file containing the actual script

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:

<syntaxhighlight lang="ini">
[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
</syntaxhighlight>

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.

=== Examples of Usage ===

==== Creating panels ====
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.

==== Automating tasks ====
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:

<syntaxhighlight lang="javascript">
var template = loadTemplate('org.kde.plasma-desktop.findWidgets')
template.findWidgets('systemtray')
</syntaxhighlight>

==== Activity templates ====
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:

<syntaxhighlight lang="ini">
[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
</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 <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:
* $desktop
* $autostart
* $documents
* $music
* $video
* $downloads
* $pictures

They all expand into the path toward the user corresponding default folder.

== 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|API compatibility is guaranteed from version to version starting with KDE Software Compilation v4.4.0.}}

=== 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. 0.3
* ''String'' '''platformVersion''': the version of the KDE Platform, e.g. 0.3
* ''number'' '''scriptingVersion''': the version of the scripting API; e.g. in KDE SC 4.5 this is 2

=== 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:
<syntaxhighlight lang="javascript">
var activity = new Activity("folderview")
</syntaxhighlight>

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
* ''Array[String]'' '''knownActivityTypes''': (scripting version >= 2) 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:
* ''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.
* ''Array[Activity]'' '''activities()''': returns an array of all activities that currently exist

=== 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:
<syntaxhighlight lang="javascript">
var panel = new Panel("dock")
</syntaxhighlight>
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
* ''Array[String]'' '''knownPanelTypes''': (scripting version >= 2) 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.

Functions:
* ''Panel'' '''panelById(int id)''': returns an object representing the Panel that matches the given id
* ''Array[Panels]'' '''panels()''': returns an array of all panels that currently exist

=== Activities and Panels ===
Activity and Panel objects, once 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
* ''Array[String]'' '''configKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current configuration group
* ''Array[String]'' '''configGroups''': (scriptingVersion >= 2) a list of all the groups in the current configuration group
* ''Array[String]'' '''globalConfigKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current global configuration group
* ''Array[String]'' '''globalConfigGroups''': (scriptingVersion >= 2) a list of all the groups in the current global configuration group

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
* ''String'' '''wallpaperPlugin''': (scriptingVersion >= 2) the wallpaper plugin to use with the Activity
* ''String'' '''wallpaperMode''': (scriptingVersion >= 2) the wallpaper plugin mode to use with the Activity
* ''Array[String]'' '''currentConfigGroup''': (scriptingVersion >= 2) 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
* ''String'' '''version''': (scriptingVersion >= 2) the version of the Activity or Panel

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 <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
* '''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
* '''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 for the default value
* '''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
* ''Array[String]'' '''currentGlobalConfigGroup''': (scriptingVersion >= 2) the current global configuration group path, with each entry in the array representing a sub-group, similar to currentConfigGroup. However, global configuration is shared by all instances of panels and activities of the same type.
* ''Array[Widget]'' '''widgets([String type])''': (scriptingVersion >= 2) returns all the widgets in the Panel or Activity. If the optional type is specified, only widgets matching that type will be returned.

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.

==== Checking if a widget is installed ====
A list of all installed widget types can be retrieved the following read-only property:

* ''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:

* ''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
* ''Array[String]'' '''globalConfigKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current global configuration group
* ''Array[String]'' '''globalConfigGroups''': (scriptingVersion >= 2) a list of all the groups in the current global configuration group
* ''String'' '''version''': (scriptingVersion >= 2) the version of the Activity or Panel

as well as the following read-write properties:

* ''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
* ''Array[String]'' '''currentGlobalConfigGroup''': (scriptingVersion >= 2) the current global configuration group path, with each entry in the array representing a sub-group, similar to currentConfigGroup. However, global configuration is shared by all instances of widgets of the same type.
* ''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
* ''number'' '''index''': the layout index of the widget; in a Panel this corresponds to the order the widget appears in. Changing the value of the index will change the position of the widget in Panels and may do so in some Activities as well.

and the following 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
* '''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
* '''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
* '''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:
* ''QRectF'' '''screenGeometry(number screen)''': returns a rect object representing the geometry of a screen

=== 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 ===
* ''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.
* ''String'' '''applicationPath(String name)''': (scripting version >= 4) returns the full local path to a given application or .desktop file if it exists.
* ''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
** music
** video
** downloads
** pictures
** autostart
** desktop (should be considered deprecated for Plasma workspaces)

If a second string is passed in, it is considered a request for a specific path and the following types are recognized:
** apps - Applications menu (.desktop files).
** autostart - Autostart directories (both XDG and kde-specific)
** cache - Cached information (e.g. favicons, web-pages)
** cgi - CGIs to run from kdehelp.
** config - Configuration files.
** data - Where applications store data.
** emoticons - Emoticons themes
** exe - Executables in $prefix/bin. findExe() for a function that takes $PATH into account.
** html - HTML documentation.
** icon - Icons, see KIconLoader.
** kcfg - KConfigXT config files.
** lib - Libraries.
** locale - Translation files for KLocale.
** mime - Mime types defined by KDE-specific .desktop files.
** module - Module (dynamically loaded library).
** qtplugins - Qt plugins (dynamically loaded objects for Qt)
** services - Services.
** servicetypes - Service types.
** sound - Application sounds.
** templates - Templates for the "Create new file" functionality.
** wallpaper - Wallpapers.
** tmp - Temporary files (specific for both current host and current user)
** socket - UNIX Sockets (specific for both current host and current user)
** xdgconf-menu - Freedesktop.org standard location for menu layout (.menu) files.
** xdgdata-apps - Freedesktop.org standard location for application desktop files.
** xdgdata-dirs - Freedesktop.org standard location for menu descriptions (.directory files).
** xdgdata-mime - Freedesktop.org standard location for MIME type definitions.
** xdgdata-icon - Freedesktop.org standard location for icons.
** xdgdata-pixmap - Gnome-compatibility location for pixmaps.

The second parameter should be a specific resource to find the path to. An example might be userDataPath("data", "plasma-desktop").

=== Misc. Global Properties and Functions ===
Read-write properties:
* ''boolean'' '''locked''': whether the desktop shell and widgets are locked or not (settable)
* ''string'' '''theme''': (scripting version >= 3) the name of the desktop theme to use for the interface, e.g. default, Air, Oxygen, etc.

Read-only properties:
* ''boolean'' '''hasBattery''': whether or not the system has the ability to run on battery power, e.g. a laptop or mobile device
* ''boolean'' '''multihead''': (scripting version >= 3) true if the system is running with multiple screens in a "Xaphod" multiple display server configuration
* ''int'' '''multiheadScreen''': (scripting version >= 3) if multihead is true, contains the (real) screen id of the current screen

Functions:
* '''sleep(number ms)''': sleeps the script for the specified number of millseconds

=== QRectF ===
A rectangle class is also provided for use with Widget, Panel and screen geometry properties and functions.

Read-only properites:
* ''boolean'' '''empty''': true if the rectangle's width or height is less than, or equal to, 0; an empty rectangle is also invalid
* ''boolean'' '''null''': true if the rectangle has both the width and the height set to 0; a null rectangle is also empty and not valid
* ''boolean'' '''valid''': true if the rectangle has a width > 0 and height 0.

Read-write properties:
* ''number'' '''left'''
* ''number'' '''top'''
* ''number'' '''bottom'''
* ''number'' '''right'''
* ''number'' '''height'''
* ''number'' '''width'''
* ''number'' '''x'''
* ''number'' '''y'''

Constructors:
* '''QRectF'''
* '''QRectF(number x, number y, number width, number height)''': Sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.

Functions:
* '''adjust(number dx1, number dy1, number dx2, number dy2)''': adds dx1, dy1, dx2 and dy2 respectively to the existing coordinates of the rectangle
* ''QRectF'' '''adjusted(number dx1, number dy1, number dx2, number dy2)''': returns a new QRectF with dx1, dy1, dx2 and dy2 added respectively to the existing coordinates of the rectangle
* '''translate(number dx, number dy)''': translates the rect by dx, dy
* '''setCoords(number x1, number y1, number x2, number y2)''': sets the coordinates of the rectangle's top-left corner to (x1, y1), and the coordinates of its bottom-right corner to (x2, y2).
* '''setRect(number x, number y, number width, number height)''': sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.
* ''boolean'' '''contains(number x, number y)''': returns true if the rect contains the point (x, y)
* '''moveBottom(number delta)'': moves the bottom by delta pixels
* '''moveLeft(number delta)''': moves the left by delta pixels
* '''moveRight(number delta)''': moves the right by delta pixels
* '''moveTo(number x, number y)''': moves the top left of the rect to point (x, y)
* '''moveTop(number delta)''': moves the top by delta pixels

== Configuration Keys ==
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'''.

=== Common configuration keys ===
Here are some keys that can be used with all widgets:

* '''Share''' (true/false): Whether or not the widget is to be announces throughout the network (Share tab)

=== Common time and date keys ===
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.
* '''announceInterval''' (number ≥ 0): Interval in minutes that the time is read out loud
* '''calendarType''' (local/coptic/ethopian/gregorian/gregorian-proleptic/hebrew/hijri/indian-national/jalali/japanese/julian/minguo/thai): Calendar system to be used, defaults to local
* '''defaultTimezone''' (Local/…): Time zone to be used
* '''displayHolidays''' (true/false): Whether holidays are to be displayed
* '''holidayRegions''' (tbd): tbd
* '''holidayRegionaDaysOff''' (tbd): tbd
* '''timeZones''' (Europe/Andorra,…): Comma-separated list of timezones to be used (e. g. Europe/Andorra,Indian/Antananarivo,Asia/Aqtau)

=== Analog clock (clock) ===
* '''showSecondHand''' (true/false): self-explanatory
* '''showTimezoneString''' (true/false): self-explanatory

=== Battery status (battery) ===
* '''showBatteryString''' (true/false): Whether or not battery status is shown as overlay for the battery icon (if in systemtray or panel)
* '''showMultipleBatteries''' (true/false): Whether or not battery status is shown for each battery separately

=== Digital clock (digital-clock) ===
* '''plainClockColor''' (rrr,ggg,bbb): Color set for clock font (e. g. 192,0,0 - to be used with useCustomColor=true!)
* '''plainClockDrawShadow''' (true/false): Whether a shadow is to bed drawn (defaults to true)
* '''plainClockShadowColor''' (rrr,ggg,bbb): Color set for clock shadow (e. g. 64,97,128 - to be used with useCustomShadowColor=true!)
* '''plainClockFont''' (tbd): Font to be used for clock (e. g. Serif,12,-1,5,75,0,0,0,0,0)
* '''showDate''' (true/false): self-explanatory
* '''showDay''' (true/false): self-explanatory
* '''showSeconds''' (true/false): self-explanatory
* '''showTimezone''' (true/false): self-explanatory
* '''showYear''' (true/false): self-explanatory
* '''useCustomColor''' (true/false): Whether or not a custom color is to be used (use with plainClockColor=rrr,ggg,bbb!)
* '''useCustomShadowColor''' (true/false): Whether or not a custom shadow color is to be used (use with plainClockShadowColor=rrr,ggg,bbb!)

=== Folderview (folderview) ===
* '''alignToGrid''' (true/false): self-explanatory
* '''customIconSize''' (16/22/24/32/48/…): Use custom icon size for files/folders (use only default/common icon sizes, powers of 2)
* '''customLabel''': Use custom title rather than default path or place name
* '''drawShadows''' (true/false): Whether or not file labels are to draw shadows
* '''filter''' (0/1/2): Defines whether a filter is to be used or not (0 = No filter, 1 = Show only matching files, 2 = Hide matching files)
* '''filterFiles''': Wildcard filter to filter file names
* '''mimeFilter''': Comma-separated list of mimetypes to be filtered (shown/hidden depends on filter-setting)
* '''iconsLocked''' (true/false): Whether or not icons can be moved
* '''numTextLines''' (number > 0): Amount of lines a file name can have before it is truncated
* '''url''': Folder URL to be displayed (e. g. desktop:/// or file:///home/yourusername)
* '''sortColumn''' (-1/0/1/2/3/4/5): The way files and folders are sorted (-1 = No sorting, 0 = By name, 1 = By size, 2 = By type, 3 = By date)
* '''sortDirsFirst''' (true/false): Whether or not folders are displayed before files (defaults to true)
* '''textColor''' (rrr,ggg,bbb): Color the icon labels will have

=== Kickoff menu (launcher) ===
* '''SwitchTabsOnHover''' (true/false): self-explanatory
* '''ShowAppsByName''' (true/false): Apps are sorted by name rather than by description

=== Pager (pager) ===
* '''displayedText''' (0/1/2): Text to be shown on individual virtual desktops (0 = Workspace number, 1 = Workspace title, 2 = None)
* '''ShowWindowIcons''' (true/false): Whether or not the application icon is to be shown on each individual window
* '''currentDesktopSelected''' (0/1/2): Defines what should happen if the user clicks on the virtual desktop that is currently active (0 = Nothing, 1 = Show Workspace, i. e. minimize windows, 2 = Show Dashboard)
* '''rows''' (number > 0): Amount of rows the pager should have. (Note: ''This is a global option, so you need to use '''writeGlobalConfig''' instead'')

=== Notifications (notifications) ===
{{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}}
* '''AutoHidePopup''' (true/false): Whether or not popups are to be hidden automatiaclly
* '''ShowJobs''' (true/false): Whether or not jobs are to be shown (e. g. file transfer progress)
* '''ShowNotifications''' (true/false): Whether or not notifications are to be shown

=== Removable media notifier (notifier) ===
* '''ShowDevices''' (0/1/2): Defines what kind of devices are to be shown (0 = Removable media only, 1 = Non-removable media only, 2 = All)
{{note|Auto-mount settings and device actions are not stored in this Plasmoid’s settings.}}

=== Taskbar (tasks) ===
* '''groupingStrategy''' (0/1/2): Defines how taskbar entries are to be grouped (0 = Never, 1 = Manually, 2 = By Program Name)
* '''groupWhenFull''' (true/false): Only group when taskbar is full (to be used with groupingStrategy=2 only!)
* '''highlightWindows''' (true/false): Highlight a window if your mouse cursor is hovering its taskbar entry (requires Desktop Compositing and “Highlight windows” effect enabled to work)
* '''maxRows''' (number > 0): Amount of rows taskbar entries can take
* '''forceRows''' (true/false): Force row setting for taskbar entries
* '''showOnlyCurrentActivity''' (true/false): Show only windows from current activity
* '''showOnlyCurrentDesktop''' (true/false): Show only windows from current virtual desktop
* '''showOnlyCurrentScreen''' (true/false): Show only windows from current screen (multi monitor setup)
* '''showTooltip''' (true/false): Whether or not tooltips are to be shown
* '''sortingStrategy''' (0/1/2/3): How taskbar entries are to be sorted (0 = Never, 1 = Manually, 2 = Alphabetically, 3 = By Desktop)

=== System Tray ===
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.

==== Generic System Tray configuration keys ====
* '''DefaultAppletAdded''' (true/false): Remembers whether the default plasmoids (networkmanagement, device manager, notifications) have already been added(??)
* '''ShowApplicationStatus''' (true/false): Show system tray icons of applications that belong to the group “Applications”
* '''ShowCommunications''' (true/false): Show system tray icons of applications that belong to the group “Applications” (i. e. Messenger, IRC chat)
* '''ShowHardware''' (true/false): Show system tray icons of applications that belong to the group “Hardware” (i. e. volume control, printer applet)
* '''ShowSystemServices''' (true/false): Show system tray icons of applications that belong to the group “System Services” (i. e. Nepomuk Indexing Agent)
* '''ShowUnknown''' (true/false): Show system tray icons that do not belong into one of the categories mentioned above (or that do not use KDE’s system tray protocol and thus do not provide such information)
* '''alwaysShown''': Comma-separated list of widgets and entries that are to be shown all the time (e. g. KMix,notifier)
* '''hidden''': Comma-separated list of widgets and entries that are to be hidden all the time (e. g. Nepomuk Indexing Agent,Klipper,kmail)
{{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}}

==== 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.
<syntaxhighlight lang="cpp-qt">
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
<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.
<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.

==== Edit existing widgets in systemtray ====

==== Remove a widget from systemtray ====

To remove a widget, simply delete the corresponding configuration group.

Development/Tutorials/Services/Plugins

2011-11-15T10:46:12Z

Aseigo: /* The plugin loading stuff */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Services/Plugins}}

{{TutorialBrowser|

series=Services|

name=Creating and Loading Plugins Using KService|

pre=[[../Traders|Traders: Querying the System]]

}}

== Abstract ==
Before starting with the code let's see which advantages we can undertake
developing a plugin structured application. First of all an application capable
of managing plugins can extend its features with apparently no limits. Anyway, rather than developing a plugin structured application because "it's so coool!!" the developer should think about the real advantages of this kind of development. For instance we can think about an archive manager application: the main program can delegate the creation/extraction/editing of each type of archive to specific plugins. This way we give modularity to the application so that supporting brand new archive types in the future will simply consist in writing the specific plugin and not rewriting the whole application. Ok, then let's stop talking.. and start coding =).

== The Text Editor Example ==
So, even if an archiving application would be nicer to look at, here we will examine a simple text editing application capable of plugin loading.
Each plugin will simply give a specific text editing feature.

== Creating a Plugin Interface Class ==
The main step in order to create a plugin structure is to define its base class.
This class will be inherited by every plugin and should give access to the key resources of the main application. In this example the main plugin class will inherit a KXMLGUIClient since every plugin will give access to its features through a gui element (a KAction in this case).

<syntaxhighlight lang="cpp-qt">
#include <kdemacros.h>
#include <kxmlguiclient.h>
#include <QObject>

class KTextEdit;

class KDE_EXPORT Plugin : public QObject , public KXMLGUIClient
{
Q_OBJECT

public:
Plugin(QObject *parent);
virtual ~Plugin();

/**
* @return KTextEdit pointing to the main application editor widget
*/
KTextEdit* editorInterface();

/**
* @internal Used by the main application to correctly set the editor.
* Do not call from within the reimplementation.
*/
void setEditorInterface(KTextEdit *);

private:
class PluginPrivate;
PluginPrivate *d;

};
</syntaxhighlight>

This base class will give the useful pointers needed by each plugin in order to manipulate the main application data. In this case we only give access to the main editor interface through editorInterface().

Here follows the implementation:

<syntaxhighlight lang="cpp-qt">
#include "plugin.h"
#include <KTextEdit>

class Plugin::PluginPrivate {

public:
PluginPrivate(Plugin *q):
q(q),
m_editor(0){}

Plugin *q;
KTextEdit *m_editor;
};

Plugin::Plugin(QObject *parent) : QObject(parent),
d(new PluginPrivate(this))
{}

Plugin::~Plugin()
{
delete d;
}

KTextEdit* Plugin::editorInterface()
{
return d->m_editor;
}

void Plugin::setEditorInterface(KTextEdit *editor)
{
d->m_editor = editor;
}

</syntaxhighlight>

Where plugin.h is the header file seen before.
The setEditorInterface allows the main application to set the pointer to the main KTextEditor. This way each programmer will be able to access the main text editing interface and interact with it as well.

== The Plugin Factory Macro ==
Every plugin will be made "visible and available" through the use of a macro.
So we better put this macro in our own myplugin_macros.h as follows.

<syntaxhighlight lang="cpp-qt">
#include <kdemacros.h>
#include <KPluginFactory>
#include <KPluginLoader>

#define TEXTEDITOR_PLUGIN_EXPORT( c ) \
K_PLUGIN_FACTORY( TextEditorFactory, registerPlugin< c >(); ) \
K_EXPORT_PLUGIN( TextEditorFactory("c") )
</syntaxhighlight>

This macro simply unifies two KDE macros that allow us the exportation of the plugin.

== Loading Plugins ==
Now let's get prepared to make our application find and load every compatible plugin. We'll make use of a simple helper that uses standard KDE methods in order to locate and load plugins. Here follows header and implementation

=== PLUGINLOADER.H ===

<syntaxhighlight lang="cpp-qt">
#include <QObject>

#include "plugintest_macros.h"

class Plugin;

class PluginLoader : public QObject
{
Q_OBJECT
public:
PluginLoader(QObject * parent);
virtual ~PluginLoader();

void loadAllPlugins();

signals:
void pluginLoaded(Plugin * plugin);
};
</syntaxhighlight>

=== PLUGINLOADER.CPP ===

<syntaxhighlight lang="cpp-qt">
#include "pluginloader.h"

#include "plugin.h"

#include <KServiceTypeTrader>
#include <KDebug>

PluginLoader::PluginLoader(QObject * parent)
: QObject(parent)
{
}

PluginLoader::~PluginLoader()
{
}

void PluginLoader::loadAllPlugins()
{
kDebug() << "Load all plugins";
KService::List offers = KServiceTypeTrader::self()->query("TextEditor/Plugin");

KService::List::const_iterator iter;
for(iter = offers.begin(); iter < offers.end(); ++iter)
{
QString error;
KService::Ptr service = *iter;

KPluginFactory *factory = KPluginLoader(service->library()).factory();

if (!factory)
{
//KMessageBox::error(0, i18n("<html>KPluginFactory could not load the plugin: %1</html>",
// service->library()));
kError(5001) << "KPluginFactory could not load the plugin:" << service->library();
continue;
}

Plugin *plugin = factory->create<Plugin>(this);

if (plugin) {
kDebug() << "Load plugin:" << service->name();
emit pluginLoaded(plugin);
} else {
kDebug() << error;
}
}
}
</syntaxhighlight>

The code shown simply queries SyCoCa for a plugin for the TextEditor. When creating a plugin a .desktop file is provided with the Service Type the plugin is designed for. We'll see later how to set the proper Service Type for our custom plugin. We emit the pluginLoaded signal when the plugin is properly loaded so that the application will integrate it in the GUI.

== Handling plugins by the Main Application ==
I'll just show pieces of code that handle plugin loading in the main window.
Let's assume we have a pointer to our KTextEdit simply called editor.

<syntaxhighlight lang="cpp-qt">
void MyMainWindow::loadPlugins()
{
PluginLoader *loader = new PluginLoader(this);
connect(loader, SIGNAL(pluginLoaded(Plugin*)), this, SLOT(addPlugin(Plugin*)));
loader->loadAllPlugins();
}
</syntaxhighlight>

So with this piece of code we ask PluginLoader to load all plugins and call the slot pluginLoaded we'll see now to implement the plugins in the interface.
The loadPlugins method is supposed to be called at the beginning of the application in order to load everything before the user can start using it. Of course you can decide what to do with your plugins and ignore this suggestion :).

<syntaxhighlight lang="cpp-qt">
void MyMainWindow::addPlugin(Plugin *plugin)
{
editor = plugin->editorInterface();
guiFactory()->addClient(plugin);
}
</syntaxhighlight>
Since our plugin inherits KXMLGuiClient we can provide any kind of gui client supported and KDE will automagically load it into our application. So this code snippet simply integrates our plugin with the main window.

== A Simple Plugin Example ==

Development/Tutorials/Plasma/JavaScript/API-UIElements

2011-11-11T09:34:14Z

Aseigo: /* Common Properties */

= User Interface Elements =

The Plasma framework provides a set of standard user interface elements such as pushbuttons and checkboxes for use in Plasmoids, and these are available from the Simplified Javascript API as well. These elements follow the Plasma style and other conventions so that widgets blend well both visually and functionally with other Plasma elements.

Note that some UI elements have functions that are synonymous with a read-write property. In those cases, the function can serve as a slot and be connected to signals for easy setting of the property.

= DataEngine-Aware UI Elements =
Some of the UI elements are able to accept data directly from DataEngines. These widgets will have a dataUpdated function and can be passed into the DataEngine::connectSource method successfully.

DataEngine-aware UI elements include:

* Label
* TextEdit
* Meter

= Common Properties =

By default, all of the Plasma user interface elements have the following properties:

* ''String'' '''objectName'''
* ''number'' '''opacity'''
* ''boolean'' '''enabled'''
* ''boolean'' '''visible'''
* ''QPointF'' '''pos'''
* ''number'' '''x'''
* ''number'' '''y'''
* ''number'' '''z'''
* ''number'' '''rotation'''
* ''number'' '''scale'''
* ''QPointF'' '''transformOriginPoint'''
* ''QPalette'' '''palette'''
* ''QFont'' '''font'''
* ''QSizeF'' '''size'''
* ''QtFocusPolicy'' '''focusPolicy'''
* ''QRectF'' '''geometry'''

Importantly, most elements also support:

* ''QSizeF'' '''preferredSize''': this size is used to control the default sizing of windows and other containers that the element may be shown in. This is particularly useful for, e.g., popupWidget in PopupApplets.

= Common Signals =

* '''opacityChanged()'''
* '''visibleChanged()'''
* '''enabledChanged()'''
* '''xChanged()'''
* '''yChanged()'''
* '''zChanged()'''
* '''rotationChanged()'''
* '''scaleChanged() '''

= UI Element Gallery =

== CSS Styleable UI Elements ==

Most UI Elements are able to have their appearance adjust using a CSS stylesheet. All of these elements have the following read/write property:

*''String'' '''styleSheet''': A CSS stylesheet describing visual properties to apply to the widget; see [http://doc.trolltech.com/4.5/stylesheet.html the Qt Documentation for more information]

=== CheckBox ===
Read-write properties:
* ''String'' '''text'''
* ''String'' '''image'''
* ''boolean'' '''checked'''
* '''toggled(bool)'''

=== ComboBox ===
Read-only properties:
* ''number'' '''count''': (API v 3) the number of items in the combobox

Read-write properties:
* ''String'' '''text''': the text of the currently selected item in the combobox
* ''number'' currentIndex: (API v 3) the index of the current item

Funtions:
* '''clear()'''

Signals:
* '''activated(String)'''
* '''textChanged(String)'''
* '''currentIndexChanged(number)'''

=== Frame ===
Read-write properties:
* ''Shadow'' '''frameShadow'''
* ''String'' '''text'''
* ''String'' '''image'''

Enumerations:
* '''Shadow'''
* '''Plain'''
* '''Raised'''
* '''Sunken'''

=== GroupBox ===
Read-write properties:
* ''String'' '''text'''

=== Label ===
Read-write properties:
* ''String'' '''text'''
* ''String'' '''image'''
* ''number'' '''alignment''' (see [[#QtAlignment]] for the valid values)
* ''boolean'' '''hasScaledContents'''
* ''boolean'' '''textIsSelectable''' (since 4.4.1)
* ''boolean'' '''wordWrap''' (API v2)

Functions:
* '''dataUpdated(String, Data)'''

Signals:
* '''linkActivated(String)''': emitted when a link is clicked; includes the URL of link that is clicked; this is only available when textIsSelectable
* '''linkHovered(String)''': emitted when a link is hovered

=== LineEdit ===
Read-write properties:
* ''String'' '''text'''
* ''boolean'' '''clearButtonShown'''

Signals:
* '''editingFinished()'''
* '''returnPressed()'''
* '''textEdited(String)'''
* '''textChanged(String)'''

=== PushButton ===
Read-write properties:
* ''String'' '''text'''
* ''String'' '''image'''
* ''QAction'' '''action'''
* ''QIcon'' '''icon'''
* ''boolean'' '''checkable'''
* ''boolean'' '''checked'''
* ''boolean'' '''down'''

Signals:
* '''pressed()'''
* '''released()'''
* '''clicked()'''
* '''toggled(bool)'''

=== RadioButton ===
Read-write properties:
* ''String'' '''text'''
* ''String'' '''image'''
* ''boolean'' '''checked'''

Signals:
* '''toggled(bool)'''

=== ScrollWidget ===
Read-write properties:
* ''QGraphicsWidget'' '''widget'''
* ''number'' '''horizontalScrollBarPolicy'''
* ''number'' '''verticalScrollBarPolicy'''
* ''QPointF'' '''scrollPosition'''
* ''QSizeF'' '''contentsSize'''
* ''QRectF'' '''viewportGeometry'''

Functions:
* '''ensureRectVisible(QRectF)'''
* '''ensureItemVisible(QGraphicsItem)'''
* '''registerAsDragHandle(QGraphicsWidget)'''
* '''unregisterAsDragHandle(QGraphicsWidget)'''

=== ScrollBar ===
Read-write properties:
* ''number'' '''singleStep'''
* ''number'' '''pageStep'''
* ''number'' '''value'''
* ''number'' '''minimum'''
* ''number'' '''maximum'''
* ''QtOrientation'' '''setOrientation'''

Functions:
* '''setValue(number)'''
* '''setOrientation(QtOrientation)'''

Signals:
* '''valueChanged(number)'''

=== Slider ===
Read-write properties:
* ''number'' '''maximum'''
* ''number'' '''minimum'''
* ''number'' '''value'''
* ''number'' '''orientation'''

Signals:
* '''sliderMoved(number)'''
* '''valueChanged(number)'''

Functions:
* '''setMaximum(number)'''
* '''setMinimum(number)'''
* '''setRange(number, number)'''
* '''setValue(number)'''
* '''setOrientation(QtOrientation)'''

=== SpinBox ===
Read-write properties:
* ''number'' '''maximum'''
* ''number'' '''minimum'''
* ''number'' '''value'''

Functins:
* '''setMaximum(number)'''
* '''setMinimum(number)'''
* '''setRange(number, number)'''
* '''setValue(number)'''

Signals:
* '''sliderMoved(number)'''
* '''valueChanged(number)'''
* '''editingFinished()'''

=== TabBar ===
Read-write properties:
* ''number'' '''currentIndex'''
* ''number'' '''count'''
* ''boolean'' '''tabBarShown'''

Functions:
* '''setCurrentIndex(number)'''
* '''insertTab(number, QIcon,String,QGraphicsLayoutItem)'''
* '''insertTab(number, QIcon,String)'''
* '''insertTab(number, String,QGraphicsLayoutItem)'''
* '''insertTab(number, String)'''
* '''addTab(QIcon,String,QGraphicsLayoutItem)'''
* '''addTab(QIcon,String)'''
* '''addTab(String,QGraphicsLayoutItem)'''
* '''addTab(String)'''
* '''removeTab(number)'''
* '''takeTab(number)'''
* '''tabAt(number)'''
* '''setTabText(number, String)'''
* '''tabText(number)'''
* '''setTabIcon(number, QIcon)'''
* '''tabIcon(number)'''

Signals:
* '''currentChanged(number)'''

=== TextEdit ===
Read-write properties:
* ''String'' '''text'''
* ''boolean'' '''readOnly'''

Functions:
* '''dataUpdated(String, Data)'''

Signals:
* '''textChanged()'''

=== ToolButton ===
:Read-write properties:

* ''''QAction'' '''action''': the action associated with this '''ToolButton'''
* ''''boolean'' '''autoRaise''': whether or not the ToolButton should raise automatically when the user interacts with it'''
* ''''String'' '''image''': path to an icon or image (e.g. in the widget's Package) to show on the ToolButton
* ''''String'' '''text''': the text shown on the ToolButton

API v2 adds:
* ''''boolean'' '''down''': whether or not the ToolButton is in the down position (since protocol version 2)

:Signals:
* '''clicked()'''
* '''pressed()'''
* '''released()'''

=== TreeView ===
Read-write properties:
* ''QAbstractModel'' '''model'''

=== VideoWidget ===
Read-writeproperties:
* ''String'' '''url'''
* ''number'' '''currentTime'''
* ''number'' '''totalTime'''
* ''number'' '''remainingTime'''
* ''Controls'' '''usedControls'''
* ''boolean'' '''controlsVisible'''

Functions:
* '''play()'''
* '''pause()'''
* '''stop()'''
* '''seek(number)'''

Signals:
* '''tick(number)'''
* '''aboutToFinish()'''
* '''nextRequested()'''
* '''previousRequested()'''

Enumerations:
* Controls
** NoControls
** Play
** Pause
** Stop
** PlayPause
** Previous
** Next
** Progress
** Volume
** OpenFile
** DefaultControls

== Other UI Elements ==

=== BusyWidget ===
Read-write properties:
* ''boolean'' '''running'''
* ''String'' '''label'''

Signals:
* '''clicked()'''

=== FlashingLabel ===
Read-write properties:
* ''boolean'' '''autohide'''
* ''QColor'' '''color'''
* ''number'' '''duration'''

Functins:
* '''kill()'''
* '''fadeIn()'''
* '''fadeOut()'''
* '''flash(String, number, QTextOption)'''
* '''flash(String ,number)'''
* '''flash(String)'''
* '''flash(QPixmap, number, QtAlignment)'''
* '''flash(QPixmap, number)'''
* '''flash(QPixmap)'''

=== GraphicsWidget (API v3) ===
This is just a plain element with no painting or other features. It is useful primarily as a place holder, especially to contain layouts for other elements.

=== IconWidget ===
Read-only properties:
* ''QSizeF'' '''iconSize''' - the actual size of the icon given the size of the IconWidget, space reserved (if any) for text displayed, etc.

Read-write properties:
* ''String'' '''text'''
* ''String'' '''infoText'''
* ''QIcon'' '''icon'''
* ''QColor'' '''textBackgroundColor'''
* ''String'' '''svg'''
* ''QAction'' '''action'''
* ''QtOrientation'' '''orientation'''
* ''number'' '''numDisplayLines'''

Functions:
* '''setPressed(boolean)'''
* '''setUnpressed()'''
* '''setIcon(String)'''

Signals:
* '''pressed(bool)'''
* '''clicked()'''
* '''doubleClicked()'''
* '''activated()'''
* '''changed()'''

=== ItemBackground ===
Read-write properties:
* ''QRectF'' '''target'''
* ''QGraphicsItem'' '''targetItem'''

Signals:
* '''appearanceChanged()'''
* '''animationStep(qreal)'''
* '''targetReached(QRectF)'''
* '''targetItemReached(QGraphicsItem)'''

=== Meter ===
Read-write properties:
* ''number'' '''minimum'''
* ''number'' '''maximum'''
* ''number'' '''value'''
* ''String'' '''svg'''
* ''MeterType'' '''meterType'''

Functions:
* '''dataUpdated(String, Data)'''

Enumerations:
* '''MeterType'''
** BarMeterHorizontal
** BarMeterVertical
** AnalogMeter

=== Separator ===
Read-write properties:
* ''QtOrientation'' '''orientation'''

=== SignalPlotter ===
Read-write properties:
* ''String'' '''title'''
* ''String'' '''unit'''
* ''boolean'' '''useAutoRange'''
* ''number'' '''horizontalScale'''
* ''boolean'' '''showVerticalLines'''
* ''QColor'' '''verticalLinesColor'''
* ''number'' '''verticalLinesDistance'''
* ''boolean'' '''verticalLinesScroll'''
* ''boolean'' '''showHorizontalLines'''
* ''QColor'' '''horizontalLinesColor'''
* ''QColor'' '''fontColor'''
* ''number'' '''horizontalLinesCount'''
* ''boolean'' '''showLabels'''
* ''boolean'' '''showTopBar'''
* ''QColor'' '''backgroundColor'''
* ''String'' '''svgBackground'''
* ''boolean'' '''thinFrame'''
* ''boolean'' '''stackPlots'''

=== SvgWidget ===
Read-write properties:
* ''Svg'' '''svg'''
* ''String'' '''elementID'''

Signals:
* '''clicked(QtMouseButton)'''

=== WebView ===
Read-only properties:
* ''QSizeF'' '''contentsSize'''
* ''QRectF'' '''viewportGeometry'''

Read-write properties:
* ''Url'' '''url'''
* ''String'' '''html'''
* ''boolean'' '''dragToScroll'''
* ''QPointF'' '''scrollPosition'''

Signals:
* '''loadProgress(number)'''
* '''loadFinished(bool)'''

= Layouts =

== LinearLayout ==
* ''number'' '''spacing'''
* ''QtOrientation'' '''orientation''' (''QtVertical'' or ''QtHorizontal'')
* ''function'' '''removeAt'''
* ''function'' '''addStretch'''
* ''function'' '''setStretchFactor'''
* ''function'' '''setAlignment'''
* ''function'' '''insertStretch'''
* ''function'' '''setItemSpacing'''
* ''function'' '''setContentsMargins'''
* ''function'' '''addItem'''
* ''function'' '''removeItem'''
* ''function'' '''insertItem'''
* ''function'' '''toString'''
* ''function'' '''activate''' (API v3)

== AnchorLayout ==
* ''number'' '''horizontalSpacing'''
* ''number'' '''verticalSpacing'''
* ''function'' '''setSpacing'''
* ''function'' '''removeAt'''
* ''function'' '''addAnchor'''
* ''function'' '''anchor'''
* ''function'' '''addAnchors'''
* ''function'' '''addCornerAnchors'''
* ''function'' '''toString'''
* ''function'' '''activate''' (API v3)

== GridLayout ==
* ''number '''horizontalSpacing'''
* ''number '''verticalSpacing'''
* ''function'' '''rowSpacing'''
* ''function'' '''setRowSpacing'''
* ''function'' '''columnSpacing'''
* ''function'' '''setColumnSpacing'''
* ''function'' '''rowMinimumHeight'''
* ''function'' '''setRowMinimumHeight'''
* ''function'' '''rowPreferredHeight'''
* ''function'' '''setRowPreferredHeight'''
* ''function'' '''rowMaximumHeight'''
* ''function'' '''setRowMaximumHeight'''
* ''function'' '''rowFixedHeight'''
* ''function'' '''setRowFixedHeight'''
* ''function'' '''columnMinimumWidth'''
* ''function'' '''setColumnMinimumWidth'''
* ''function'' '''columnPreferredWidth'''
* ''function'' '''setColumnPreferredWidth'''
* ''function'' '''columnMaximumWidth'''
* ''function'' '''setColumnMaximumWidth'''
* ''function'' '''columnFixedWidth'''
* ''function'' '''setColumnFixedWidth'''
* ''function'' '''remoteAt'''
* ''function'' '''setAlignment'''
* ''function'' '''setSpacing'''
* ''function'' '''setContentsMargins'''
* ''function'' '''addItem'''
* ''function'' '''toString'''
* ''function'' '''activate''' (API v3)

= Undocumented Properties and Functions =

There are a handful of other undocumented properties and functions available to UI elements. These are not supported or guaranteed to exist in future versions however, and as such should not be used or relied upon.

Development/Tutorials/Plasma/PackageOverview

2011-11-09T12:18:29Z

Aseigo: Created page with "== Introduction == Many times in a Plasma based application or addon there is the need to reference a set of files for consistent and easy access and redistribution. For instanc..."

== Introduction ==

Many times in a Plasma based application or addon there is the need to reference a set of files for consistent and easy access and redistribution. For instance, Plasma widgets (or "Plasmoids") written in an interpreted language (e.g. QML, Javascript, HTML, Ruby or Python) are often made up of several files containing code, images, configuration descriptions and other resources. These are distributed and shipped as one compressed file and at run time the contents are made easily available to the Plasmoid. This is the role that the Plasma Package plays.

A Plasma Package allows easy deployment and later referencing of a group of platform-independent files. Plasma Packages are used with wallpaper images and plugins, themes, Plasmoids, DataEngines, Runners, QML file sets, Plasma desktop scripting templates and other similar contexts. Plasma Package is therefore quite flexible and with very few rules can be extended to cover a wide variety of uses in applications that need a way to redistribute and/or reference sets of files easily.

Plasma Package is intended to be a simple system that does not include things more complex packaging systems such as the Debian package format or RPM provides. While Plasma Packages do not have the concept of things such as dependencies or architecture targets, it also does not require a complex system with a database and (slow) management applications.

== Plasma Package Format ==

Plasma Packages usually have two things in common: a {{path|metadata.desktop}} file and a {{path|contents/}} directory.

The {{path|metadata.desktop}} is an INI format file which contains a description of the contents of the package. This includes translatable strings for user visible text such as a name and description as well as content that is programmatically useful such as, in the case of Plasmoids, the scripting API used to write the Plasmoid the Package contains.

In the case of Plasmoids, the metadata.desktop contains the following mandatory fields:

* Name of the Plasmoid
* Author
* A version number for the Plasmoid
* Icon
** can be an icon from the user KDE theme;
** can be a file name (with extension) if you want to use a custom icon;
** omit this line if you do not want an icon.
* Used License
** This will be from a pre-selected list of possibilities.
** You can use a custom licence, specifying it in a file called COPYING.
** Should Plasma refuse to load improperly licensed Plasmoids?
* The API the plasmoid is written in (e.g. javascript, webkit, ruby, python, edje ..)
* Description of the Plasmoid giving the user a nice overview of the Plasmoid capabilities

Optionally these fields can be added:
* Category of widget that the Plasmoids belongs to, see [Projects/Plasma/PIG|the Plasma Interface Guidelies] for a lit of recognized category names
* Homepage for more information to the Plasmoid
* EMail of the author
* Release notes
* Required scripting version
* A minimum version number for Plasma
* path to the main code file, relative to contents/
* default size of the plasmoid (if unset, the default is 200,200)

An example file can be seen here:

<syntaxhighlight lang="ini">
[Desktop Entry]
Name=Analog Clock
Comment=An SVG themable clock
Icon=chronometer
Type=Service

X-Plasma-API=javascript
X-Plasma-MainScript=code/main.js
X-Plasma-DefaultSize=150,150

X-KDE-ServiceTypes=Plasma/Applet
X-KDE-PluginInfo-Author=John Doe
X-KDE-PluginInfo-Email=john.doe@kde.org
X-KDE-PluginInfo-Name=clock
X-KDE-PluginInfo-Version=pre0.1
X-KDE-PluginInfo-Website=http://plasma.kde.org/
X-KDE-PluginInfo-Category=Date and Time
X-KDE-PluginInfo-Depends=
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true
</syntaxhighlight>

{{path|meta.desktop}} files for other Plasma components such as DataEngines, Runners and Wallpapers are very similar. It is recommended when creating new package types to adhere to the general style above as much as possible for consistency.

Packages may add additional top-level contents directories. This is used by Plasmoids to allow device-specific files to be made available. A package may also have no special content directory at all, though this is discouraged since it makes accidental overwriting of files such has the metadata or hash files very easy.

What appears within the contents directories is up to the Package itself. For Plasmoids, the following structure is supported:

* $PlasmoidName-$PlasmoidVersion/ (root)
** {{path|metadata.desktop}}
** contents/
*** code/ ''files containing scripting code''
**** main ''the main file that will be loaded at plasmoid start (unless you specify a different name in metadata.desktop)''
*** images/ ''image files in svg, png or jpeg format''
*** locale/ ''translation files in a standard localization hierarchy; e.g. German translation would appear in locale/l10n/de/''
*** ui/ ''user interface files, such as Qt Designer layouts''
**** config.ui ''the main configuration dialog layout''
*** config/ ''KConfigXt files describing the configuration''
**** main.xml ''the main configuration description''
*** ... additional plasmoid-specific files

Plasmoids can then reference these resources directly as if that was all that existed in the file system with simple directives such as <syntaxhighlight lang="javascript">include("someOtherFile")</syntaxhighlight> which will cause a lookup in the {{path|contents/code/}} directory. Plasmoids (and other Plasma components) are sandboxed into their respective Packages, something that Plasma::Package enforces unless allowExternalPaths is set to true.

== Defining Formats ==

New formats can be defined programmatically using PackageStructure plugins. PackageStructure plugins call addDirectoryDefinition and addFileDefinition methods which define a key string that can be used to reference that resource, the path within the contents directories that it is expected to exist at, supported mimetypes, descriptions suitable for showing to a user (e.g. in an IDE or package creator tool) and whether or not the resource is required. Contents directories are also defined by the PackageStructure plugin.

The structure can be created dynamically at run-time depending on the package itself. This is accomplished by reimplementing the pathChanged method. This also allows one PackageStructure object to be re-used multiple times.

Together, these mechanisms allow for virtually unlimited flexibility in how a Package is structured on disk and what it contains. This makes Plasma Package suitable for the wide variety of use cases it currently fulfills.

== Signing Packages ==

A Plasma Package may be signed with a GPG key. First, a SHA1 hash of the metadata.desktop file and the contents directories must be created and placed in a file called contents.hash that resides at the top level. A GPG signature of the contents.hash file can then be placed in a file called contents.hash.sig. This can then be used to verify the contents of the package at runtime.

Hashes may be generated with the plasmapkg tool as of version 0.2 with the --hash command line option.

== Compression for Redistribution ==

A Plasma Package can be packed into one zip file that contains all the required files. The gzip format is also supported, though zip is generally recommended due to the ability to easily perform random access operations on zip archives. The resulting file is then suffixed with an appropriate identifying ending, such as ".plasmoid" in the case of plasmoids.

== Installation ==

Installation can be done by hand, but generally this is accomplished either by using Plasma::PackageStructure::installPackage or with the plasmapkg command line utility. When a Plasma Package is installed, the archive is uncompressed and stored under the package root defined by the Package's structure definition. By default, this is {{path|$APPDATA/plasma/packages}}. By default, the {{path|metadata.desktop}} is copied into the the services directory so that it can easily be found later by KTrader to find all Plasmoids whether they are written in C++ or an interpreted language.

Development/Tutorials/Plasma

2011-11-09T11:23:37Z

Aseigo: /* Packages */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Plasma}}

== QML ==
Plasmoids that use the QML (aka QtQuick) declarative language to describe their user interface while having the logic of the applet, in JavaScript (QML is essentially a forge between CSS and JavaScript).

This is now the '''recommended''' method of creating plasmoids, where possible. The plasmoid, or applet serves as the visualization for the data which a Plasma::DataEngine contains.

It allows easily the declaring of an interface and to easily create things like ListViews with native Plasma theming. It is what Plasma is leaning the most towards, especially in the Mobile, MediaCenter and KDM shells.

;[[Development/Tutorials/Plasma/QML/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in QML''

;[[Development/Tutorials/Plasma/QML/Basic_ListView|Basic List Plasmoid]]
:''Make a QML ListView which displays basic text objects as items. Utilizes native Plasma theming and animations.''

;[[Development/Tutorials/Plasma/QML/API|API Reference]]
:''The QML Plasmoid API. Useful for referencing what is available in the runtime, what are the differences with the pure JavaScript ScriptEngine, the differences between pure Qt QML and Plasma, and as a study aid for the tutorials above.''

== C++ ==

=== Plasmoids ===
;[[Development/Tutorials/Plasma/GettingStarted|Getting Started With Plasmoids]]
:''Creating your first plasmoid in C++ with SVG background, icon and text''

;[[Development/Tutorials/Plasma/GettingStarted..Some_More|Getting Started With Plasmoids..Some more]] :''A few more starter's tips.''

;[[Development/Tutorials/Plasma/UsingExtenders|How to use extenders in your Plasmoid]]
:''A simple example that shows how to use extenders in a Plasmoid.''

;[http://www.linux-magazine.com/w3/issue/114/036-040_plasma.pdf Creating Plasmoids]
:''May 2010 article from Linux Magazine''

;[http://www.ibm.com/developerworks/linux/library/l-kde-plasmoids/index.html Create Plasmoids using KDevelop]
:''Article explaining the structure of Plasma and how to create a Plasmoid''

;[http://community.kde.org/User:Mxttie#Adding_configuration Adding configuration to your plasmoid]
:''Article explaining how to add a configuration dialog to your plasmoid.''

=== DataEngines ===

;[[Development/Tutorials/Plasma/DataEngines|Writing a DataEngine]]
:''DataEngines provide a standardized interface to various (read only) data sources for visualizations to use. Learn what a DataEngine is and how to write one of your own.''

;[[Development/Tutorials/Plasma/Services|Writing a Service]]
:''Services provide a standardized interface for visualizations to perform "write operations". This can be for example, uploading pasted test to a pastebin service..''

=== PackageStructures ===

;[[Development/Tutorials/Plasma/PackageStructure|Writing a PackageStructure Plugin]]
:''PackageStructure plugins allow custom Packages to be defined, installed, removed and listed as well as provide access their contents at runtime. Packages may contain any kind of data addons, including scripts.''

=== Runners ===

;[[Development/Tutorials/Plasma/AbstractRunner|Creating Runners]]
:''Runners are plugins that provide action-based search functionality in the Plasma workspace "run command" dialog. These plugins can be used by any application that links again libplasma.''

=== Wallpapers ===

;[[Development/Tutorials/Plasma/WallpaperHelloWorld|Wallpaper Tutorial 1]]
:''This tutorial shows you how to make a simple Hello World plasma wallpaper plugin.''

;[[Development/Tutorials/Plasma/WallpaperConfiguration|Wallpaper Tutorial 2]]
:''This tutorial covers how to add configuration options to the wallpaper.''

=== Plasma Shells ===

;[[Development/Tutorials/Plasma/ShellDesign|Creating a Plasma Shell]]
:''This tutorial covers the essentials of writing a new Plasma shell from scratch. A must-read for anyone creating a new or modifying an existing Plasma Shell. Existing Plasma shells include Plasma Desktop, Plasma Netbook, Plasma Mobile, Plasma Media Center, Plasma Screensaver, Plasma KPart and Plasma KDM, and all follow the patterns documented here.''

== JavaScript ==

Plasma has built-in JavaScript (also known as ECMAScript, and often referred to as QtScript in the context of Qt) scripting support without requiring any external dependencies.

=== Plasmoids ===

;[[Development/Tutorials/Plasma/JavaScript/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in JavaScript''

;[[Development/Tutorials/Plasma/JavaScript/DataEngine|Getting Data]]
:''How to retreive data from a data engine''

;[[Development/Tutorials/Plasma/JavaScript/NowPlaying|Now Playing]]
:''Slightly more advanced data engine usage: displaying what's currently playing''

;[[Development/Tutorials/Plasma/JavaScript/SystemMonitor|System Monitor]]
:''How to access systemmonitor data engine''

;[[Development/Tutorials/Plasma/JavaScript/CheatSheet|Cheat Sheet]]
:''A cheat sheet, rather than a tutorial, of things to remember and watch out for when developing JavaScript plasmoids''

;[[Development/Tutorials/Plasma/JavaScript/API|API Reference]]
:''The Simplified JavaScript Plasmoid API. Useful for referencing what is available in the runtime and as a study aid for the tutorials above.''

=== Other Applications Of Javascript ===
;[[KDE_System_Administration/PlasmaDestkopScripting|Scripting Plasma Shells]]
:The KDE Plasma Desktop and Netbook provide means to manage the desktop shell (desktop, panels, widget) via scripts written in JavaScript. This article describes how to take advantage of this feature set as well as documents the full API. This is primarily a system administration tool, but may also be of interest to power users.

;[[Development/Tutorials/Plasma/JavaScript/Animations|Javascript Animations]]
:''How to write Animations using Javascript for use in Plasma applications''

;[[Development/Tutorials/Plasma/ComicPlugin|Creating Comic Plugins]]
:''This guide shows you how to create a comic plugin for the comic plasmoid.''

== Python ==

=== Plasmoids ===
;[[Development/Tutorials/Plasma/Python/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in Python''

;[[Development/Tutorials/Plasma/Python/Using widgets|Using widgets]]
:''Introduction to using Plasma widgets''

;[[Development/Tutorials/Plasma/Python/Using DataEngines|Using DataEngines]]
:''How to use DataEngines from a plasmoid''

=== DataEngines ===

;[[Development/Tutorials/Plasma/Python/Writing DataEngines|Writing DataEngines]]
:''How to write your own Plasma DataEngine''

;[[Development/Tutorials/Plasma/PythonPlasmoid|Writing a Plasmoid in Python]]
:''Writing a simple battery graph in python''

=== Runners ===

;[[Development/Tutorials/Plasma/PythonRunner|Writing a KRunner plugin in Python]]
:''Writing a simple krunner plugin in python''

== Ruby ==

=== Plasmoids ===

;[[Development/Tutorials/Plasma/Ruby/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in Ruby''

;[[Development/Tutorials/Plasma/Ruby/Using widgets|Using widgets]]
:''Introduction to using Plasma widgets''

;[[Development/Tutorials/Plasma/Ruby/SimplePasteApplet|Writing a simple paste applet]]
:''A tutorial explaining how to set up a plasmoid, create a simple paste applet using widgets and add Plasma features seen elsewhere. Complete with tips for those who have never programmed before.''

;[[Development/Tutorials/Plasma/Ruby/Blinker|Use SVG artwork in the simplest way possible]]
:''Follow a fellow student as he asks around about SVG usage and explains why the code examples work. This is a wiki so feel free to add your own insights until this tutorial can be considered complete.''

=== DataEngines ===

;[[Development/Tutorials/Plasma/Ruby/Writing DataEngines|Writing DataEngines]]
:''How to write your own Plasma DataEngine using Ruby''

== Web Technologies (HTML/JS/CSS) ==
;[[Development/Tutorials/Plasma/Web/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in HTML''

== Plasma integration for applications ==

;[[Development/Tutorials/Solid_Device_Actions|Creating a Device Notifier action]]
:''When your application is interested in removable hardware''

;[[Development/Tutorials/Plasma/ApplicationShell|Integrate Plasma in Applications]]
:''This tutorial shows you how to make an application dashboard based on Plasma technologies.''

== Packages ==

;[[Development/Tutorials/Plasma/PackageOverview|Plasma Packages]]
:''An overview of what makes up a Plasma Package and what they are and can be used for.''

;[[Development/Tutorials/Plasma/PackageStructure|Writing a PackageStructure Pluginin C++]]
:''PackageStructure plugins allow custom Packages to be defined, installed, removed and listed as well as provide access their contents at runtime. Packages may contain any kind of data addons, including scripts.''

== Themes ==

;[[Development/Tutorials/Plasma/Theme|Creating a Plasma Theme Quickstart]]
:''A quick guide to creating your first Plasma theme''

;[[Development/Tutorials/Plasma/ThemeDetails|The Plasma Theme Structure In Detail]]
:''A comprehensive guide to the contents of a Plasma SVG theme, including configuration options, wallpapers, on-disk layout, names of all standard SVG files and every element in them.''

== Activity Templates ==

;[[KDE_System_Administration/PlasmaDesktopScripting#Activity_templates|Creating a Plasma Activity Template Quickstart]]
:''A quick guide to creating your first Plasma Activity Template''

== Resources ==

* [[Projects/Plasma|Projects: Plasma]]
* [http://api.kde.org/4.x-api/kdelibs-apidocs/plasma/html/index.html Plasma api documentation]
* [http://techbase.kde.org/Projects/Plasma/Eclipse_Integration Plasma Eclipse Integration]
* The [https://mail.kde.org/mailman/listinfo/plasma-devel plasma-devel mailing list] and #plasma on IRC (irc.freenode.org).

Development/Tutorials/Plasma

2011-11-09T11:22:47Z

Aseigo: /* Themes */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Plasma}}

== QML ==
Plasmoids that use the QML (aka QtQuick) declarative language to describe their user interface while having the logic of the applet, in JavaScript (QML is essentially a forge between CSS and JavaScript).

This is now the '''recommended''' method of creating plasmoids, where possible. The plasmoid, or applet serves as the visualization for the data which a Plasma::DataEngine contains.

It allows easily the declaring of an interface and to easily create things like ListViews with native Plasma theming. It is what Plasma is leaning the most towards, especially in the Mobile, MediaCenter and KDM shells.

;[[Development/Tutorials/Plasma/QML/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in QML''

;[[Development/Tutorials/Plasma/QML/Basic_ListView|Basic List Plasmoid]]
:''Make a QML ListView which displays basic text objects as items. Utilizes native Plasma theming and animations.''

;[[Development/Tutorials/Plasma/QML/API|API Reference]]
:''The QML Plasmoid API. Useful for referencing what is available in the runtime, what are the differences with the pure JavaScript ScriptEngine, the differences between pure Qt QML and Plasma, and as a study aid for the tutorials above.''

== C++ ==

=== Plasmoids ===
;[[Development/Tutorials/Plasma/GettingStarted|Getting Started With Plasmoids]]
:''Creating your first plasmoid in C++ with SVG background, icon and text''

;[[Development/Tutorials/Plasma/GettingStarted..Some_More|Getting Started With Plasmoids..Some more]] :''A few more starter's tips.''

;[[Development/Tutorials/Plasma/UsingExtenders|How to use extenders in your Plasmoid]]
:''A simple example that shows how to use extenders in a Plasmoid.''

;[http://www.linux-magazine.com/w3/issue/114/036-040_plasma.pdf Creating Plasmoids]
:''May 2010 article from Linux Magazine''

;[http://www.ibm.com/developerworks/linux/library/l-kde-plasmoids/index.html Create Plasmoids using KDevelop]
:''Article explaining the structure of Plasma and how to create a Plasmoid''

;[http://community.kde.org/User:Mxttie#Adding_configuration Adding configuration to your plasmoid]
:''Article explaining how to add a configuration dialog to your plasmoid.''

=== DataEngines ===

;[[Development/Tutorials/Plasma/DataEngines|Writing a DataEngine]]
:''DataEngines provide a standardized interface to various (read only) data sources for visualizations to use. Learn what a DataEngine is and how to write one of your own.''

;[[Development/Tutorials/Plasma/Services|Writing a Service]]
:''Services provide a standardized interface for visualizations to perform "write operations". This can be for example, uploading pasted test to a pastebin service..''

=== PackageStructures ===

;[[Development/Tutorials/Plasma/PackageStructure|Writing a PackageStructure Plugin]]
:''PackageStructure plugins allow custom Packages to be defined, installed, removed and listed as well as provide access their contents at runtime. Packages may contain any kind of data addons, including scripts.''

=== Runners ===

;[[Development/Tutorials/Plasma/AbstractRunner|Creating Runners]]
:''Runners are plugins that provide action-based search functionality in the Plasma workspace "run command" dialog. These plugins can be used by any application that links again libplasma.''

=== Wallpapers ===

;[[Development/Tutorials/Plasma/WallpaperHelloWorld|Wallpaper Tutorial 1]]
:''This tutorial shows you how to make a simple Hello World plasma wallpaper plugin.''

;[[Development/Tutorials/Plasma/WallpaperConfiguration|Wallpaper Tutorial 2]]
:''This tutorial covers how to add configuration options to the wallpaper.''

=== Plasma Shells ===

;[[Development/Tutorials/Plasma/ShellDesign|Creating a Plasma Shell]]
:''This tutorial covers the essentials of writing a new Plasma shell from scratch. A must-read for anyone creating a new or modifying an existing Plasma Shell. Existing Plasma shells include Plasma Desktop, Plasma Netbook, Plasma Mobile, Plasma Media Center, Plasma Screensaver, Plasma KPart and Plasma KDM, and all follow the patterns documented here.''

== JavaScript ==

Plasma has built-in JavaScript (also known as ECMAScript, and often referred to as QtScript in the context of Qt) scripting support without requiring any external dependencies.

=== Plasmoids ===

;[[Development/Tutorials/Plasma/JavaScript/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in JavaScript''

;[[Development/Tutorials/Plasma/JavaScript/DataEngine|Getting Data]]
:''How to retreive data from a data engine''

;[[Development/Tutorials/Plasma/JavaScript/NowPlaying|Now Playing]]
:''Slightly more advanced data engine usage: displaying what's currently playing''

;[[Development/Tutorials/Plasma/JavaScript/SystemMonitor|System Monitor]]
:''How to access systemmonitor data engine''

;[[Development/Tutorials/Plasma/JavaScript/CheatSheet|Cheat Sheet]]
:''A cheat sheet, rather than a tutorial, of things to remember and watch out for when developing JavaScript plasmoids''

;[[Development/Tutorials/Plasma/JavaScript/API|API Reference]]
:''The Simplified JavaScript Plasmoid API. Useful for referencing what is available in the runtime and as a study aid for the tutorials above.''

=== Other Applications Of Javascript ===
;[[KDE_System_Administration/PlasmaDestkopScripting|Scripting Plasma Shells]]
:The KDE Plasma Desktop and Netbook provide means to manage the desktop shell (desktop, panels, widget) via scripts written in JavaScript. This article describes how to take advantage of this feature set as well as documents the full API. This is primarily a system administration tool, but may also be of interest to power users.

;[[Development/Tutorials/Plasma/JavaScript/Animations|Javascript Animations]]
:''How to write Animations using Javascript for use in Plasma applications''

;[[Development/Tutorials/Plasma/ComicPlugin|Creating Comic Plugins]]
:''This guide shows you how to create a comic plugin for the comic plasmoid.''

== Python ==

=== Plasmoids ===
;[[Development/Tutorials/Plasma/Python/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in Python''

;[[Development/Tutorials/Plasma/Python/Using widgets|Using widgets]]
:''Introduction to using Plasma widgets''

;[[Development/Tutorials/Plasma/Python/Using DataEngines|Using DataEngines]]
:''How to use DataEngines from a plasmoid''

=== DataEngines ===

;[[Development/Tutorials/Plasma/Python/Writing DataEngines|Writing DataEngines]]
:''How to write your own Plasma DataEngine''

;[[Development/Tutorials/Plasma/PythonPlasmoid|Writing a Plasmoid in Python]]
:''Writing a simple battery graph in python''

=== Runners ===

;[[Development/Tutorials/Plasma/PythonRunner|Writing a KRunner plugin in Python]]
:''Writing a simple krunner plugin in python''

== Ruby ==

=== Plasmoids ===

;[[Development/Tutorials/Plasma/Ruby/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in Ruby''

;[[Development/Tutorials/Plasma/Ruby/Using widgets|Using widgets]]
:''Introduction to using Plasma widgets''

;[[Development/Tutorials/Plasma/Ruby/SimplePasteApplet|Writing a simple paste applet]]
:''A tutorial explaining how to set up a plasmoid, create a simple paste applet using widgets and add Plasma features seen elsewhere. Complete with tips for those who have never programmed before.''

;[[Development/Tutorials/Plasma/Ruby/Blinker|Use SVG artwork in the simplest way possible]]
:''Follow a fellow student as he asks around about SVG usage and explains why the code examples work. This is a wiki so feel free to add your own insights until this tutorial can be considered complete.''

=== DataEngines ===

;[[Development/Tutorials/Plasma/Ruby/Writing DataEngines|Writing DataEngines]]
:''How to write your own Plasma DataEngine using Ruby''

== Web Technologies (HTML/JS/CSS) ==
;[[Development/Tutorials/Plasma/Web/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in HTML''

== Plasma integration for applications ==

;[[Development/Tutorials/Solid_Device_Actions|Creating a Device Notifier action]]
:''When your application is interested in removable hardware''

;[[Development/Tutorials/Plasma/ApplicationShell|Integrate Plasma in Applications]]
:''This tutorial shows you how to make an application dashboard based on Plasma technologies.''

== Packages ==

;[Development/Tutorials/Plasma/PackageOverview|Plasma Packages]]
:''An overview of what makes up a Plasma Package and what they are and can be used for.''

;[[Development/Tutorials/Plasma/PackageStructure|Writing a PackageStructure Pluginin C++]]
:''PackageStructure plugins allow custom Packages to be defined, installed, removed and listed as well as provide access their contents at runtime. Packages may contain any kind of data addons, including scripts.''

== Themes ==

;[[Development/Tutorials/Plasma/Theme|Creating a Plasma Theme Quickstart]]
:''A quick guide to creating your first Plasma theme''

;[[Development/Tutorials/Plasma/ThemeDetails|The Plasma Theme Structure In Detail]]
:''A comprehensive guide to the contents of a Plasma SVG theme, including configuration options, wallpapers, on-disk layout, names of all standard SVG files and every element in them.''

== Activity Templates ==

;[[KDE_System_Administration/PlasmaDesktopScripting#Activity_templates|Creating a Plasma Activity Template Quickstart]]
:''A quick guide to creating your first Plasma Activity Template''

== Resources ==

* [[Projects/Plasma|Projects: Plasma]]
* [http://api.kde.org/4.x-api/kdelibs-apidocs/plasma/html/index.html Plasma api documentation]
* [http://techbase.kde.org/Projects/Plasma/Eclipse_Integration Plasma Eclipse Integration]
* The [https://mail.kde.org/mailman/listinfo/plasma-devel plasma-devel mailing list] and #plasma on IRC (irc.freenode.org).

Development/Tutorials/Plasma

2011-11-09T11:20:42Z

Aseigo: /* DataEngines */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Plasma}}

== QML ==
Plasmoids that use the QML (aka QtQuick) declarative language to describe their user interface while having the logic of the applet, in JavaScript (QML is essentially a forge between CSS and JavaScript).

This is now the '''recommended''' method of creating plasmoids, where possible. The plasmoid, or applet serves as the visualization for the data which a Plasma::DataEngine contains.

It allows easily the declaring of an interface and to easily create things like ListViews with native Plasma theming. It is what Plasma is leaning the most towards, especially in the Mobile, MediaCenter and KDM shells.

;[[Development/Tutorials/Plasma/QML/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in QML''

;[[Development/Tutorials/Plasma/QML/Basic_ListView|Basic List Plasmoid]]
:''Make a QML ListView which displays basic text objects as items. Utilizes native Plasma theming and animations.''

;[[Development/Tutorials/Plasma/QML/API|API Reference]]
:''The QML Plasmoid API. Useful for referencing what is available in the runtime, what are the differences with the pure JavaScript ScriptEngine, the differences between pure Qt QML and Plasma, and as a study aid for the tutorials above.''

== C++ ==

=== Plasmoids ===
;[[Development/Tutorials/Plasma/GettingStarted|Getting Started With Plasmoids]]
:''Creating your first plasmoid in C++ with SVG background, icon and text''

;[[Development/Tutorials/Plasma/GettingStarted..Some_More|Getting Started With Plasmoids..Some more]] :''A few more starter's tips.''

;[[Development/Tutorials/Plasma/UsingExtenders|How to use extenders in your Plasmoid]]
:''A simple example that shows how to use extenders in a Plasmoid.''

;[http://www.linux-magazine.com/w3/issue/114/036-040_plasma.pdf Creating Plasmoids]
:''May 2010 article from Linux Magazine''

;[http://www.ibm.com/developerworks/linux/library/l-kde-plasmoids/index.html Create Plasmoids using KDevelop]
:''Article explaining the structure of Plasma and how to create a Plasmoid''

;[http://community.kde.org/User:Mxttie#Adding_configuration Adding configuration to your plasmoid]
:''Article explaining how to add a configuration dialog to your plasmoid.''

=== DataEngines ===

;[[Development/Tutorials/Plasma/DataEngines|Writing a DataEngine]]
:''DataEngines provide a standardized interface to various (read only) data sources for visualizations to use. Learn what a DataEngine is and how to write one of your own.''

;[[Development/Tutorials/Plasma/Services|Writing a Service]]
:''Services provide a standardized interface for visualizations to perform "write operations". This can be for example, uploading pasted test to a pastebin service..''

=== PackageStructures ===

;[[Development/Tutorials/Plasma/PackageStructure|Writing a PackageStructure Plugin]]
:''PackageStructure plugins allow custom Packages to be defined, installed, removed and listed as well as provide access their contents at runtime. Packages may contain any kind of data addons, including scripts.''

=== Runners ===

;[[Development/Tutorials/Plasma/AbstractRunner|Creating Runners]]
:''Runners are plugins that provide action-based search functionality in the Plasma workspace "run command" dialog. These plugins can be used by any application that links again libplasma.''

=== Wallpapers ===

;[[Development/Tutorials/Plasma/WallpaperHelloWorld|Wallpaper Tutorial 1]]
:''This tutorial shows you how to make a simple Hello World plasma wallpaper plugin.''

;[[Development/Tutorials/Plasma/WallpaperConfiguration|Wallpaper Tutorial 2]]
:''This tutorial covers how to add configuration options to the wallpaper.''

=== Plasma Shells ===

;[[Development/Tutorials/Plasma/ShellDesign|Creating a Plasma Shell]]
:''This tutorial covers the essentials of writing a new Plasma shell from scratch. A must-read for anyone creating a new or modifying an existing Plasma Shell. Existing Plasma shells include Plasma Desktop, Plasma Netbook, Plasma Mobile, Plasma Media Center, Plasma Screensaver, Plasma KPart and Plasma KDM, and all follow the patterns documented here.''

== JavaScript ==

Plasma has built-in JavaScript (also known as ECMAScript, and often referred to as QtScript in the context of Qt) scripting support without requiring any external dependencies.

=== Plasmoids ===

;[[Development/Tutorials/Plasma/JavaScript/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in JavaScript''

;[[Development/Tutorials/Plasma/JavaScript/DataEngine|Getting Data]]
:''How to retreive data from a data engine''

;[[Development/Tutorials/Plasma/JavaScript/NowPlaying|Now Playing]]
:''Slightly more advanced data engine usage: displaying what's currently playing''

;[[Development/Tutorials/Plasma/JavaScript/SystemMonitor|System Monitor]]
:''How to access systemmonitor data engine''

;[[Development/Tutorials/Plasma/JavaScript/CheatSheet|Cheat Sheet]]
:''A cheat sheet, rather than a tutorial, of things to remember and watch out for when developing JavaScript plasmoids''

;[[Development/Tutorials/Plasma/JavaScript/API|API Reference]]
:''The Simplified JavaScript Plasmoid API. Useful for referencing what is available in the runtime and as a study aid for the tutorials above.''

=== Other Applications Of Javascript ===
;[[KDE_System_Administration/PlasmaDestkopScripting|Scripting Plasma Shells]]
:The KDE Plasma Desktop and Netbook provide means to manage the desktop shell (desktop, panels, widget) via scripts written in JavaScript. This article describes how to take advantage of this feature set as well as documents the full API. This is primarily a system administration tool, but may also be of interest to power users.

;[[Development/Tutorials/Plasma/JavaScript/Animations|Javascript Animations]]
:''How to write Animations using Javascript for use in Plasma applications''

;[[Development/Tutorials/Plasma/ComicPlugin|Creating Comic Plugins]]
:''This guide shows you how to create a comic plugin for the comic plasmoid.''

== Python ==

=== Plasmoids ===
;[[Development/Tutorials/Plasma/Python/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in Python''

;[[Development/Tutorials/Plasma/Python/Using widgets|Using widgets]]
:''Introduction to using Plasma widgets''

;[[Development/Tutorials/Plasma/Python/Using DataEngines|Using DataEngines]]
:''How to use DataEngines from a plasmoid''

=== DataEngines ===

;[[Development/Tutorials/Plasma/Python/Writing DataEngines|Writing DataEngines]]
:''How to write your own Plasma DataEngine''

;[[Development/Tutorials/Plasma/PythonPlasmoid|Writing a Plasmoid in Python]]
:''Writing a simple battery graph in python''

=== Runners ===

;[[Development/Tutorials/Plasma/PythonRunner|Writing a KRunner plugin in Python]]
:''Writing a simple krunner plugin in python''

== Ruby ==

=== Plasmoids ===

;[[Development/Tutorials/Plasma/Ruby/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in Ruby''

;[[Development/Tutorials/Plasma/Ruby/Using widgets|Using widgets]]
:''Introduction to using Plasma widgets''

;[[Development/Tutorials/Plasma/Ruby/SimplePasteApplet|Writing a simple paste applet]]
:''A tutorial explaining how to set up a plasmoid, create a simple paste applet using widgets and add Plasma features seen elsewhere. Complete with tips for those who have never programmed before.''

;[[Development/Tutorials/Plasma/Ruby/Blinker|Use SVG artwork in the simplest way possible]]
:''Follow a fellow student as he asks around about SVG usage and explains why the code examples work. This is a wiki so feel free to add your own insights until this tutorial can be considered complete.''

=== DataEngines ===

;[[Development/Tutorials/Plasma/Ruby/Writing DataEngines|Writing DataEngines]]
:''How to write your own Plasma DataEngine using Ruby''

== Web Technologies (HTML/JS/CSS) ==
;[[Development/Tutorials/Plasma/Web/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in HTML''

== Plasma integration for applications ==

;[[Development/Tutorials/Solid_Device_Actions|Creating a Device Notifier action]]
:''When your application is interested in removable hardware''

;[[Development/Tutorials/Plasma/ApplicationShell|Integrate Plasma in Applications]]
:''This tutorial shows you how to make an application dashboard based on Plasma technologies.''

== Themes ==

;[[Development/Tutorials/Plasma/Theme|Creating a Plasma Theme Quickstart]]
:''A quick guide to creating your first Plasma theme''

;[[Development/Tutorials/Plasma/ThemeDetails|The Plasma Theme Structure In Detail]]
:''A comprehensive guide to the contents of a Plasma SVG theme, including configuration options, wallpapers, on-disk layout, names of all standard SVG files and every element in them.''

== Activity Templates ==

;[[KDE_System_Administration/PlasmaDesktopScripting#Activity_templates|Creating a Plasma Activity Template Quickstart]]
:''A quick guide to creating your first Plasma Activity Template''

== Resources ==

* [[Projects/Plasma|Projects: Plasma]]
* [http://api.kde.org/4.x-api/kdelibs-apidocs/plasma/html/index.html Plasma api documentation]
* [http://techbase.kde.org/Projects/Plasma/Eclipse_Integration Plasma Eclipse Integration]
* The [https://mail.kde.org/mailman/listinfo/plasma-devel plasma-devel mailing list] and #plasma on IRC (irc.freenode.org).

Development/Tutorials/Plasma

2011-11-09T11:19:30Z

Aseigo: /* Ruby */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Plasma}}

== QML ==
Plasmoids that use the QML (aka QtQuick) declarative language to describe their user interface while having the logic of the applet, in JavaScript (QML is essentially a forge between CSS and JavaScript).

This is now the '''recommended''' method of creating plasmoids, where possible. The plasmoid, or applet serves as the visualization for the data which a Plasma::DataEngine contains.

It allows easily the declaring of an interface and to easily create things like ListViews with native Plasma theming. It is what Plasma is leaning the most towards, especially in the Mobile, MediaCenter and KDM shells.

;[[Development/Tutorials/Plasma/QML/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in QML''

;[[Development/Tutorials/Plasma/QML/Basic_ListView|Basic List Plasmoid]]
:''Make a QML ListView which displays basic text objects as items. Utilizes native Plasma theming and animations.''

;[[Development/Tutorials/Plasma/QML/API|API Reference]]
:''The QML Plasmoid API. Useful for referencing what is available in the runtime, what are the differences with the pure JavaScript ScriptEngine, the differences between pure Qt QML and Plasma, and as a study aid for the tutorials above.''

== C++ ==

=== Plasmoids ===
;[[Development/Tutorials/Plasma/GettingStarted|Getting Started With Plasmoids]]
:''Creating your first plasmoid in C++ with SVG background, icon and text''

;[[Development/Tutorials/Plasma/GettingStarted..Some_More|Getting Started With Plasmoids..Some more]] :''A few more starter's tips.''

;[[Development/Tutorials/Plasma/UsingExtenders|How to use extenders in your Plasmoid]]
:''A simple example that shows how to use extenders in a Plasmoid.''

;[http://www.linux-magazine.com/w3/issue/114/036-040_plasma.pdf Creating Plasmoids]
:''May 2010 article from Linux Magazine''

;[http://www.ibm.com/developerworks/linux/library/l-kde-plasmoids/index.html Create Plasmoids using KDevelop]
:''Article explaining the structure of Plasma and how to create a Plasmoid''

;[http://community.kde.org/User:Mxttie#Adding_configuration Adding configuration to your plasmoid]
:''Article explaining how to add a configuration dialog to your plasmoid.''

=== DataEngines ===

;[[Development/Tutorials/Plasma/DataEngines|Writing a DataEngine]]
:''DataEngines provide a standardized interface to various (read only) data sources for visualizations to use. Learn what a DataEngine is and how to write one of your own.''

;[[Development/Tutorials/Plasma/Services|Writing a Service]]
:''Services provide a standardized interface for visualizations to perform "write operations". This can be for example, uploading pasted test to a pastebin service..''

;[[Development/Tutorials/Plasma/PackageStructure|Writing a PackageStructure Plugin]]
:''PackageStructure plugins allow custom Packages to be defined, installed, removed and listed as well as provide access their contents at runtime. Packages may contain any kind of data addons, including scripts.''

=== Runners ===

;[[Development/Tutorials/Plasma/AbstractRunner|Creating Runners]]
:''Runners are plugins that provide action-based search functionality in the Plasma workspace "run command" dialog. These plugins can be used by any application that links again libplasma.''

=== Wallpapers ===

;[[Development/Tutorials/Plasma/WallpaperHelloWorld|Wallpaper Tutorial 1]]
:''This tutorial shows you how to make a simple Hello World plasma wallpaper plugin.''

;[[Development/Tutorials/Plasma/WallpaperConfiguration|Wallpaper Tutorial 2]]
:''This tutorial covers how to add configuration options to the wallpaper.''

=== Plasma Shells ===

;[[Development/Tutorials/Plasma/ShellDesign|Creating a Plasma Shell]]
:''This tutorial covers the essentials of writing a new Plasma shell from scratch. A must-read for anyone creating a new or modifying an existing Plasma Shell. Existing Plasma shells include Plasma Desktop, Plasma Netbook, Plasma Mobile, Plasma Media Center, Plasma Screensaver, Plasma KPart and Plasma KDM, and all follow the patterns documented here.''

== JavaScript ==

Plasma has built-in JavaScript (also known as ECMAScript, and often referred to as QtScript in the context of Qt) scripting support without requiring any external dependencies.

=== Plasmoids ===

;[[Development/Tutorials/Plasma/JavaScript/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in JavaScript''

;[[Development/Tutorials/Plasma/JavaScript/DataEngine|Getting Data]]
:''How to retreive data from a data engine''

;[[Development/Tutorials/Plasma/JavaScript/NowPlaying|Now Playing]]
:''Slightly more advanced data engine usage: displaying what's currently playing''

;[[Development/Tutorials/Plasma/JavaScript/SystemMonitor|System Monitor]]
:''How to access systemmonitor data engine''

;[[Development/Tutorials/Plasma/JavaScript/CheatSheet|Cheat Sheet]]
:''A cheat sheet, rather than a tutorial, of things to remember and watch out for when developing JavaScript plasmoids''

;[[Development/Tutorials/Plasma/JavaScript/API|API Reference]]
:''The Simplified JavaScript Plasmoid API. Useful for referencing what is available in the runtime and as a study aid for the tutorials above.''

=== Other Applications Of Javascript ===
;[[KDE_System_Administration/PlasmaDestkopScripting|Scripting Plasma Shells]]
:The KDE Plasma Desktop and Netbook provide means to manage the desktop shell (desktop, panels, widget) via scripts written in JavaScript. This article describes how to take advantage of this feature set as well as documents the full API. This is primarily a system administration tool, but may also be of interest to power users.

;[[Development/Tutorials/Plasma/JavaScript/Animations|Javascript Animations]]
:''How to write Animations using Javascript for use in Plasma applications''

;[[Development/Tutorials/Plasma/ComicPlugin|Creating Comic Plugins]]
:''This guide shows you how to create a comic plugin for the comic plasmoid.''

== Python ==

=== Plasmoids ===
;[[Development/Tutorials/Plasma/Python/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in Python''

;[[Development/Tutorials/Plasma/Python/Using widgets|Using widgets]]
:''Introduction to using Plasma widgets''

;[[Development/Tutorials/Plasma/Python/Using DataEngines|Using DataEngines]]
:''How to use DataEngines from a plasmoid''

=== DataEngines ===

;[[Development/Tutorials/Plasma/Python/Writing DataEngines|Writing DataEngines]]
:''How to write your own Plasma DataEngine''

;[[Development/Tutorials/Plasma/PythonPlasmoid|Writing a Plasmoid in Python]]
:''Writing a simple battery graph in python''

=== Runners ===

;[[Development/Tutorials/Plasma/PythonRunner|Writing a KRunner plugin in Python]]
:''Writing a simple krunner plugin in python''

== Ruby ==

=== Plasmoids ===

;[[Development/Tutorials/Plasma/Ruby/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in Ruby''

;[[Development/Tutorials/Plasma/Ruby/Using widgets|Using widgets]]
:''Introduction to using Plasma widgets''

;[[Development/Tutorials/Plasma/Ruby/SimplePasteApplet|Writing a simple paste applet]]
:''A tutorial explaining how to set up a plasmoid, create a simple paste applet using widgets and add Plasma features seen elsewhere. Complete with tips for those who have never programmed before.''

;[[Development/Tutorials/Plasma/Ruby/Blinker|Use SVG artwork in the simplest way possible]]
:''Follow a fellow student as he asks around about SVG usage and explains why the code examples work. This is a wiki so feel free to add your own insights until this tutorial can be considered complete.''

=== DataEngines ===

;[[Development/Tutorials/Plasma/Ruby/Writing DataEngines|Writing DataEngines]]
:''How to write your own Plasma DataEngine using Ruby''

== Web Technologies (HTML/JS/CSS) ==
;[[Development/Tutorials/Plasma/Web/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in HTML''

== Plasma integration for applications ==

;[[Development/Tutorials/Solid_Device_Actions|Creating a Device Notifier action]]
:''When your application is interested in removable hardware''

;[[Development/Tutorials/Plasma/ApplicationShell|Integrate Plasma in Applications]]
:''This tutorial shows you how to make an application dashboard based on Plasma technologies.''

== Themes ==

;[[Development/Tutorials/Plasma/Theme|Creating a Plasma Theme Quickstart]]
:''A quick guide to creating your first Plasma theme''

;[[Development/Tutorials/Plasma/ThemeDetails|The Plasma Theme Structure In Detail]]
:''A comprehensive guide to the contents of a Plasma SVG theme, including configuration options, wallpapers, on-disk layout, names of all standard SVG files and every element in them.''

== Activity Templates ==

;[[KDE_System_Administration/PlasmaDesktopScripting#Activity_templates|Creating a Plasma Activity Template Quickstart]]
:''A quick guide to creating your first Plasma Activity Template''

== Resources ==

* [[Projects/Plasma|Projects: Plasma]]
* [http://api.kde.org/4.x-api/kdelibs-apidocs/plasma/html/index.html Plasma api documentation]
* [http://techbase.kde.org/Projects/Plasma/Eclipse_Integration Plasma Eclipse Integration]
* The [https://mail.kde.org/mailman/listinfo/plasma-devel plasma-devel mailing list] and #plasma on IRC (irc.freenode.org).

Development/Tutorials/Plasma

2011-11-09T11:18:56Z

Aseigo: /* Python */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Plasma}}

== QML ==
Plasmoids that use the QML (aka QtQuick) declarative language to describe their user interface while having the logic of the applet, in JavaScript (QML is essentially a forge between CSS and JavaScript).

This is now the '''recommended''' method of creating plasmoids, where possible. The plasmoid, or applet serves as the visualization for the data which a Plasma::DataEngine contains.

It allows easily the declaring of an interface and to easily create things like ListViews with native Plasma theming. It is what Plasma is leaning the most towards, especially in the Mobile, MediaCenter and KDM shells.

;[[Development/Tutorials/Plasma/QML/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in QML''

;[[Development/Tutorials/Plasma/QML/Basic_ListView|Basic List Plasmoid]]
:''Make a QML ListView which displays basic text objects as items. Utilizes native Plasma theming and animations.''

;[[Development/Tutorials/Plasma/QML/API|API Reference]]
:''The QML Plasmoid API. Useful for referencing what is available in the runtime, what are the differences with the pure JavaScript ScriptEngine, the differences between pure Qt QML and Plasma, and as a study aid for the tutorials above.''

== C++ ==

=== Plasmoids ===
;[[Development/Tutorials/Plasma/GettingStarted|Getting Started With Plasmoids]]
:''Creating your first plasmoid in C++ with SVG background, icon and text''

;[[Development/Tutorials/Plasma/GettingStarted..Some_More|Getting Started With Plasmoids..Some more]] :''A few more starter's tips.''

;[[Development/Tutorials/Plasma/UsingExtenders|How to use extenders in your Plasmoid]]
:''A simple example that shows how to use extenders in a Plasmoid.''

;[http://www.linux-magazine.com/w3/issue/114/036-040_plasma.pdf Creating Plasmoids]
:''May 2010 article from Linux Magazine''

;[http://www.ibm.com/developerworks/linux/library/l-kde-plasmoids/index.html Create Plasmoids using KDevelop]
:''Article explaining the structure of Plasma and how to create a Plasmoid''

;[http://community.kde.org/User:Mxttie#Adding_configuration Adding configuration to your plasmoid]
:''Article explaining how to add a configuration dialog to your plasmoid.''

=== DataEngines ===

;[[Development/Tutorials/Plasma/DataEngines|Writing a DataEngine]]
:''DataEngines provide a standardized interface to various (read only) data sources for visualizations to use. Learn what a DataEngine is and how to write one of your own.''

;[[Development/Tutorials/Plasma/Services|Writing a Service]]
:''Services provide a standardized interface for visualizations to perform "write operations". This can be for example, uploading pasted test to a pastebin service..''

;[[Development/Tutorials/Plasma/PackageStructure|Writing a PackageStructure Plugin]]
:''PackageStructure plugins allow custom Packages to be defined, installed, removed and listed as well as provide access their contents at runtime. Packages may contain any kind of data addons, including scripts.''

=== Runners ===

;[[Development/Tutorials/Plasma/AbstractRunner|Creating Runners]]
:''Runners are plugins that provide action-based search functionality in the Plasma workspace "run command" dialog. These plugins can be used by any application that links again libplasma.''

=== Wallpapers ===

;[[Development/Tutorials/Plasma/WallpaperHelloWorld|Wallpaper Tutorial 1]]
:''This tutorial shows you how to make a simple Hello World plasma wallpaper plugin.''

;[[Development/Tutorials/Plasma/WallpaperConfiguration|Wallpaper Tutorial 2]]
:''This tutorial covers how to add configuration options to the wallpaper.''

=== Plasma Shells ===

;[[Development/Tutorials/Plasma/ShellDesign|Creating a Plasma Shell]]
:''This tutorial covers the essentials of writing a new Plasma shell from scratch. A must-read for anyone creating a new or modifying an existing Plasma Shell. Existing Plasma shells include Plasma Desktop, Plasma Netbook, Plasma Mobile, Plasma Media Center, Plasma Screensaver, Plasma KPart and Plasma KDM, and all follow the patterns documented here.''

== JavaScript ==

Plasma has built-in JavaScript (also known as ECMAScript, and often referred to as QtScript in the context of Qt) scripting support without requiring any external dependencies.

=== Plasmoids ===

;[[Development/Tutorials/Plasma/JavaScript/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in JavaScript''

;[[Development/Tutorials/Plasma/JavaScript/DataEngine|Getting Data]]
:''How to retreive data from a data engine''

;[[Development/Tutorials/Plasma/JavaScript/NowPlaying|Now Playing]]
:''Slightly more advanced data engine usage: displaying what's currently playing''

;[[Development/Tutorials/Plasma/JavaScript/SystemMonitor|System Monitor]]
:''How to access systemmonitor data engine''

;[[Development/Tutorials/Plasma/JavaScript/CheatSheet|Cheat Sheet]]
:''A cheat sheet, rather than a tutorial, of things to remember and watch out for when developing JavaScript plasmoids''

;[[Development/Tutorials/Plasma/JavaScript/API|API Reference]]
:''The Simplified JavaScript Plasmoid API. Useful for referencing what is available in the runtime and as a study aid for the tutorials above.''

=== Other Applications Of Javascript ===
;[[KDE_System_Administration/PlasmaDestkopScripting|Scripting Plasma Shells]]
:The KDE Plasma Desktop and Netbook provide means to manage the desktop shell (desktop, panels, widget) via scripts written in JavaScript. This article describes how to take advantage of this feature set as well as documents the full API. This is primarily a system administration tool, but may also be of interest to power users.

;[[Development/Tutorials/Plasma/JavaScript/Animations|Javascript Animations]]
:''How to write Animations using Javascript for use in Plasma applications''

;[[Development/Tutorials/Plasma/ComicPlugin|Creating Comic Plugins]]
:''This guide shows you how to create a comic plugin for the comic plasmoid.''

== Python ==

=== Plasmoids ===
;[[Development/Tutorials/Plasma/Python/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in Python''

;[[Development/Tutorials/Plasma/Python/Using widgets|Using widgets]]
:''Introduction to using Plasma widgets''

;[[Development/Tutorials/Plasma/Python/Using DataEngines|Using DataEngines]]
:''How to use DataEngines from a plasmoid''

=== DataEngines ===

;[[Development/Tutorials/Plasma/Python/Writing DataEngines|Writing DataEngines]]
:''How to write your own Plasma DataEngine''

;[[Development/Tutorials/Plasma/PythonPlasmoid|Writing a Plasmoid in Python]]
:''Writing a simple battery graph in python''

=== Runners ===

;[[Development/Tutorials/Plasma/PythonRunner|Writing a KRunner plugin in Python]]
:''Writing a simple krunner plugin in python''

== Ruby ==
;[[Development/Tutorials/Plasma/Ruby/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in Ruby''

;[[Development/Tutorials/Plasma/Ruby/Using widgets|Using widgets]]
:''Introduction to using Plasma widgets''

;[[Development/Tutorials/Plasma/Ruby/SimplePasteApplet|Writing a simple paste applet]]
:''A tutorial explaining how to set up a plasmoid, create a simple paste applet using widgets and add Plasma features seen elsewhere. Complete with tips for those who have never programmed before.''

;[[Development/Tutorials/Plasma/Ruby/Writing DataEngines|Writing DataEngines]]
:''How to write your own Plasma DataEngine using Ruby''

;[[Development/Tutorials/Plasma/Ruby/Blinker|Use SVG artwork in the simplest way possible]]
:''Follow a fellow student as he asks around about SVG usage and explains why the code examples work. This is a wiki so feel free to add your own insights until this tutorial can be considered complete.''

== Web Technologies (HTML/JS/CSS) ==
;[[Development/Tutorials/Plasma/Web/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in HTML''

== Plasma integration for applications ==

;[[Development/Tutorials/Solid_Device_Actions|Creating a Device Notifier action]]
:''When your application is interested in removable hardware''

;[[Development/Tutorials/Plasma/ApplicationShell|Integrate Plasma in Applications]]
:''This tutorial shows you how to make an application dashboard based on Plasma technologies.''

== Themes ==

;[[Development/Tutorials/Plasma/Theme|Creating a Plasma Theme Quickstart]]
:''A quick guide to creating your first Plasma theme''

;[[Development/Tutorials/Plasma/ThemeDetails|The Plasma Theme Structure In Detail]]
:''A comprehensive guide to the contents of a Plasma SVG theme, including configuration options, wallpapers, on-disk layout, names of all standard SVG files and every element in them.''

== Activity Templates ==

;[[KDE_System_Administration/PlasmaDesktopScripting#Activity_templates|Creating a Plasma Activity Template Quickstart]]
:''A quick guide to creating your first Plasma Activity Template''

== Resources ==

* [[Projects/Plasma|Projects: Plasma]]
* [http://api.kde.org/4.x-api/kdelibs-apidocs/plasma/html/index.html Plasma api documentation]
* [http://techbase.kde.org/Projects/Plasma/Eclipse_Integration Plasma Eclipse Integration]
* The [https://mail.kde.org/mailman/listinfo/plasma-devel plasma-devel mailing list] and #plasma on IRC (irc.freenode.org).

Development/Tutorials/Plasma

2011-11-09T11:18:20Z

Aseigo: /* C++ */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Plasma}}

== QML ==
Plasmoids that use the QML (aka QtQuick) declarative language to describe their user interface while having the logic of the applet, in JavaScript (QML is essentially a forge between CSS and JavaScript).

This is now the '''recommended''' method of creating plasmoids, where possible. The plasmoid, or applet serves as the visualization for the data which a Plasma::DataEngine contains.

It allows easily the declaring of an interface and to easily create things like ListViews with native Plasma theming. It is what Plasma is leaning the most towards, especially in the Mobile, MediaCenter and KDM shells.

;[[Development/Tutorials/Plasma/QML/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in QML''

;[[Development/Tutorials/Plasma/QML/Basic_ListView|Basic List Plasmoid]]
:''Make a QML ListView which displays basic text objects as items. Utilizes native Plasma theming and animations.''

;[[Development/Tutorials/Plasma/QML/API|API Reference]]
:''The QML Plasmoid API. Useful for referencing what is available in the runtime, what are the differences with the pure JavaScript ScriptEngine, the differences between pure Qt QML and Plasma, and as a study aid for the tutorials above.''

== C++ ==

=== Plasmoids ===
;[[Development/Tutorials/Plasma/GettingStarted|Getting Started With Plasmoids]]
:''Creating your first plasmoid in C++ with SVG background, icon and text''

;[[Development/Tutorials/Plasma/GettingStarted..Some_More|Getting Started With Plasmoids..Some more]] :''A few more starter's tips.''

;[[Development/Tutorials/Plasma/UsingExtenders|How to use extenders in your Plasmoid]]
:''A simple example that shows how to use extenders in a Plasmoid.''

;[http://www.linux-magazine.com/w3/issue/114/036-040_plasma.pdf Creating Plasmoids]
:''May 2010 article from Linux Magazine''

;[http://www.ibm.com/developerworks/linux/library/l-kde-plasmoids/index.html Create Plasmoids using KDevelop]
:''Article explaining the structure of Plasma and how to create a Plasmoid''

;[http://community.kde.org/User:Mxttie#Adding_configuration Adding configuration to your plasmoid]
:''Article explaining how to add a configuration dialog to your plasmoid.''

=== DataEngines ===

;[[Development/Tutorials/Plasma/DataEngines|Writing a DataEngine]]
:''DataEngines provide a standardized interface to various (read only) data sources for visualizations to use. Learn what a DataEngine is and how to write one of your own.''

;[[Development/Tutorials/Plasma/Services|Writing a Service]]
:''Services provide a standardized interface for visualizations to perform "write operations". This can be for example, uploading pasted test to a pastebin service..''

;[[Development/Tutorials/Plasma/PackageStructure|Writing a PackageStructure Plugin]]
:''PackageStructure plugins allow custom Packages to be defined, installed, removed and listed as well as provide access their contents at runtime. Packages may contain any kind of data addons, including scripts.''

=== Runners ===

;[[Development/Tutorials/Plasma/AbstractRunner|Creating Runners]]
:''Runners are plugins that provide action-based search functionality in the Plasma workspace "run command" dialog. These plugins can be used by any application that links again libplasma.''

=== Wallpapers ===

;[[Development/Tutorials/Plasma/WallpaperHelloWorld|Wallpaper Tutorial 1]]
:''This tutorial shows you how to make a simple Hello World plasma wallpaper plugin.''

;[[Development/Tutorials/Plasma/WallpaperConfiguration|Wallpaper Tutorial 2]]
:''This tutorial covers how to add configuration options to the wallpaper.''

=== Plasma Shells ===

;[[Development/Tutorials/Plasma/ShellDesign|Creating a Plasma Shell]]
:''This tutorial covers the essentials of writing a new Plasma shell from scratch. A must-read for anyone creating a new or modifying an existing Plasma Shell. Existing Plasma shells include Plasma Desktop, Plasma Netbook, Plasma Mobile, Plasma Media Center, Plasma Screensaver, Plasma KPart and Plasma KDM, and all follow the patterns documented here.''

== JavaScript ==

Plasma has built-in JavaScript (also known as ECMAScript, and often referred to as QtScript in the context of Qt) scripting support without requiring any external dependencies.

=== Plasmoids ===

;[[Development/Tutorials/Plasma/JavaScript/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in JavaScript''

;[[Development/Tutorials/Plasma/JavaScript/DataEngine|Getting Data]]
:''How to retreive data from a data engine''

;[[Development/Tutorials/Plasma/JavaScript/NowPlaying|Now Playing]]
:''Slightly more advanced data engine usage: displaying what's currently playing''

;[[Development/Tutorials/Plasma/JavaScript/SystemMonitor|System Monitor]]
:''How to access systemmonitor data engine''

;[[Development/Tutorials/Plasma/JavaScript/CheatSheet|Cheat Sheet]]
:''A cheat sheet, rather than a tutorial, of things to remember and watch out for when developing JavaScript plasmoids''

;[[Development/Tutorials/Plasma/JavaScript/API|API Reference]]
:''The Simplified JavaScript Plasmoid API. Useful for referencing what is available in the runtime and as a study aid for the tutorials above.''

=== Other Applications Of Javascript ===
;[[KDE_System_Administration/PlasmaDestkopScripting|Scripting Plasma Shells]]
:The KDE Plasma Desktop and Netbook provide means to manage the desktop shell (desktop, panels, widget) via scripts written in JavaScript. This article describes how to take advantage of this feature set as well as documents the full API. This is primarily a system administration tool, but may also be of interest to power users.

;[[Development/Tutorials/Plasma/JavaScript/Animations|Javascript Animations]]
:''How to write Animations using Javascript for use in Plasma applications''

;[[Development/Tutorials/Plasma/ComicPlugin|Creating Comic Plugins]]
:''This guide shows you how to create a comic plugin for the comic plasmoid.''

== Python ==

;[[Development/Tutorials/Plasma/Python/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in Python''

;[[Development/Tutorials/Plasma/Python/Using widgets|Using widgets]]
:''Introduction to using Plasma widgets''

;[[Development/Tutorials/Plasma/Python/Using DataEngines|Using DataEngines]]
:''How to use DataEngines from a plasmoid''

;[[Development/Tutorials/Plasma/Python/Writing DataEngines|Writing DataEngines]]
:''How to write your own Plasma DataEngine''

;[[Development/Tutorials/Plasma/PythonPlasmoid|Writing a Plasmoid in Python]]
:''Writing a simple battery graph in python''

;[[Development/Tutorials/Plasma/PythonRunner|Writing a KRunner plugin in Python]]
:''Writing a simple krunner plugin in python''

== Ruby ==
;[[Development/Tutorials/Plasma/Ruby/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in Ruby''

;[[Development/Tutorials/Plasma/Ruby/Using widgets|Using widgets]]
:''Introduction to using Plasma widgets''

;[[Development/Tutorials/Plasma/Ruby/SimplePasteApplet|Writing a simple paste applet]]
:''A tutorial explaining how to set up a plasmoid, create a simple paste applet using widgets and add Plasma features seen elsewhere. Complete with tips for those who have never programmed before.''

;[[Development/Tutorials/Plasma/Ruby/Writing DataEngines|Writing DataEngines]]
:''How to write your own Plasma DataEngine using Ruby''

;[[Development/Tutorials/Plasma/Ruby/Blinker|Use SVG artwork in the simplest way possible]]
:''Follow a fellow student as he asks around about SVG usage and explains why the code examples work. This is a wiki so feel free to add your own insights until this tutorial can be considered complete.''

== Web Technologies (HTML/JS/CSS) ==
;[[Development/Tutorials/Plasma/Web/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in HTML''

== Plasma integration for applications ==

;[[Development/Tutorials/Solid_Device_Actions|Creating a Device Notifier action]]
:''When your application is interested in removable hardware''

;[[Development/Tutorials/Plasma/ApplicationShell|Integrate Plasma in Applications]]
:''This tutorial shows you how to make an application dashboard based on Plasma technologies.''

== Themes ==

;[[Development/Tutorials/Plasma/Theme|Creating a Plasma Theme Quickstart]]
:''A quick guide to creating your first Plasma theme''

;[[Development/Tutorials/Plasma/ThemeDetails|The Plasma Theme Structure In Detail]]
:''A comprehensive guide to the contents of a Plasma SVG theme, including configuration options, wallpapers, on-disk layout, names of all standard SVG files and every element in them.''

== Activity Templates ==

;[[KDE_System_Administration/PlasmaDesktopScripting#Activity_templates|Creating a Plasma Activity Template Quickstart]]
:''A quick guide to creating your first Plasma Activity Template''

== Resources ==

* [[Projects/Plasma|Projects: Plasma]]
* [http://api.kde.org/4.x-api/kdelibs-apidocs/plasma/html/index.html Plasma api documentation]
* [http://techbase.kde.org/Projects/Plasma/Eclipse_Integration Plasma Eclipse Integration]
* The [https://mail.kde.org/mailman/listinfo/plasma-devel plasma-devel mailing list] and #plasma on IRC (irc.freenode.org).

Development/Tutorials/Plasma

2011-11-09T11:16:24Z

Aseigo:

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Plasma}}

== QML ==
Plasmoids that use the QML (aka QtQuick) declarative language to describe their user interface while having the logic of the applet, in JavaScript (QML is essentially a forge between CSS and JavaScript).

This is now the '''recommended''' method of creating plasmoids, where possible. The plasmoid, or applet serves as the visualization for the data which a Plasma::DataEngine contains.

It allows easily the declaring of an interface and to easily create things like ListViews with native Plasma theming. It is what Plasma is leaning the most towards, especially in the Mobile, MediaCenter and KDM shells.

;[[Development/Tutorials/Plasma/QML/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in QML''

;[[Development/Tutorials/Plasma/QML/Basic_ListView|Basic List Plasmoid]]
:''Make a QML ListView which displays basic text objects as items. Utilizes native Plasma theming and animations.''

;[[Development/Tutorials/Plasma/QML/API|API Reference]]
:''The QML Plasmoid API. Useful for referencing what is available in the runtime, what are the differences with the pure JavaScript ScriptEngine, the differences between pure Qt QML and Plasma, and as a study aid for the tutorials above.''

== C++ ==

;[[Development/Tutorials/Plasma/GettingStarted|Getting Started With Plasmoids]]
:''Creating your first plasmoid in C++ with SVG background, icon and text''

;[[Development/Tutorials/Plasma/GettingStarted..Some_More|Getting Started With Plasmoids..Some more]] :''A few more starter's tips.''

;[[Development/Tutorials/Plasma/DataEngines|Writing a DataEngine]]
:''DataEngines provide a standardized interface to various (read only) data sources for visualizations to use. Learn what a DataEngine is and how to write one of your own.''

;[[Development/Tutorials/Plasma/Services|Writing a Service]]
:''Services provide a standardized interface for visualizations to perform "write operations". This can be for example, uploading pasted test to a pastebin service..''

;[[Development/Tutorials/Plasma/PackageStructure|Writing a PackageStructure Plugin]]
:''PackageStructure plugins allow custom Packages to be defined, installed, removed and listed as well as provide access their contents at runtime. Packages may contain any kind of data addons, including scripts.''

;[[Development/Tutorials/Plasma/UsingExtenders|How to use extenders in your Plasmoid]]
:''A simple example that shows how to use extenders in a Plasmoid.''

;[[Development/Tutorials/Plasma/AbstractRunner|Creating Runners]]
:''Runners are plugins that provide action-based search functionality in the Plasma workspace "run command" dialog. These plugins can be used by any application that links again libplasma.''

;[[Development/Tutorials/Plasma/WallpaperHelloWorld|Wallpaper Tutorial 1]]
:''This tutorial shows you how to make a simple Hello World plasma wallpaper plugin.''

;[[Development/Tutorials/Plasma/WallpaperConfiguration|Wallpaper Tutorial 2]]
:''This tutorial covers how to add configuration options to the wallpaper.''

;[[Development/Tutorials/Plasma/ShellDesign|Creating a Plasma Shell]]
:''This tutorial covers the essentials of writing a new Plasma shell from scratch. A must-read for anyone creating a new or modifying an existing Plasma Shell. Existing Plasma shells include Plasma Desktop, Plasma Netbook, Plasma Mobile, Plasma Media Center, Plasma Screensaver, Plasma KPart and Plasma KDM, and all follow the patterns documented here.''

;[http://www.linux-magazine.com/w3/issue/114/036-040_plasma.pdf Creating Plasmoids]
:''May 2010 article from Linux Magazine''

;[http://www.ibm.com/developerworks/linux/library/l-kde-plasmoids/index.html Create Plasmoids using KDevelop]
:''Article explaining the structure of Plasma and how to create a Plasmoid''

;[http://community.kde.org/User:Mxttie#Adding_configuration Adding configuration to your plasmoid]
:''Article explaining how to add a configuration dialog to your plasmoid.''

== JavaScript ==

Plasma has built-in JavaScript (also known as ECMAScript, and often referred to as QtScript in the context of Qt) scripting support without requiring any external dependencies.

=== Plasmoids ===

;[[Development/Tutorials/Plasma/JavaScript/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in JavaScript''

;[[Development/Tutorials/Plasma/JavaScript/DataEngine|Getting Data]]
:''How to retreive data from a data engine''

;[[Development/Tutorials/Plasma/JavaScript/NowPlaying|Now Playing]]
:''Slightly more advanced data engine usage: displaying what's currently playing''

;[[Development/Tutorials/Plasma/JavaScript/SystemMonitor|System Monitor]]
:''How to access systemmonitor data engine''

;[[Development/Tutorials/Plasma/JavaScript/CheatSheet|Cheat Sheet]]
:''A cheat sheet, rather than a tutorial, of things to remember and watch out for when developing JavaScript plasmoids''

;[[Development/Tutorials/Plasma/JavaScript/API|API Reference]]
:''The Simplified JavaScript Plasmoid API. Useful for referencing what is available in the runtime and as a study aid for the tutorials above.''

=== Other Applications Of Javascript ===
;[[KDE_System_Administration/PlasmaDestkopScripting|Scripting Plasma Shells]]
:The KDE Plasma Desktop and Netbook provide means to manage the desktop shell (desktop, panels, widget) via scripts written in JavaScript. This article describes how to take advantage of this feature set as well as documents the full API. This is primarily a system administration tool, but may also be of interest to power users.

;[[Development/Tutorials/Plasma/JavaScript/Animations|Javascript Animations]]
:''How to write Animations using Javascript for use in Plasma applications''

;[[Development/Tutorials/Plasma/ComicPlugin|Creating Comic Plugins]]
:''This guide shows you how to create a comic plugin for the comic plasmoid.''

== Python ==

;[[Development/Tutorials/Plasma/Python/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in Python''

;[[Development/Tutorials/Plasma/Python/Using widgets|Using widgets]]
:''Introduction to using Plasma widgets''

;[[Development/Tutorials/Plasma/Python/Using DataEngines|Using DataEngines]]
:''How to use DataEngines from a plasmoid''

;[[Development/Tutorials/Plasma/Python/Writing DataEngines|Writing DataEngines]]
:''How to write your own Plasma DataEngine''

;[[Development/Tutorials/Plasma/PythonPlasmoid|Writing a Plasmoid in Python]]
:''Writing a simple battery graph in python''

;[[Development/Tutorials/Plasma/PythonRunner|Writing a KRunner plugin in Python]]
:''Writing a simple krunner plugin in python''

== Ruby ==
;[[Development/Tutorials/Plasma/Ruby/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in Ruby''

;[[Development/Tutorials/Plasma/Ruby/Using widgets|Using widgets]]
:''Introduction to using Plasma widgets''

;[[Development/Tutorials/Plasma/Ruby/SimplePasteApplet|Writing a simple paste applet]]
:''A tutorial explaining how to set up a plasmoid, create a simple paste applet using widgets and add Plasma features seen elsewhere. Complete with tips for those who have never programmed before.''

;[[Development/Tutorials/Plasma/Ruby/Writing DataEngines|Writing DataEngines]]
:''How to write your own Plasma DataEngine using Ruby''

;[[Development/Tutorials/Plasma/Ruby/Blinker|Use SVG artwork in the simplest way possible]]
:''Follow a fellow student as he asks around about SVG usage and explains why the code examples work. This is a wiki so feel free to add your own insights until this tutorial can be considered complete.''

== Web Technologies (HTML/JS/CSS) ==
;[[Development/Tutorials/Plasma/Web/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in HTML''

== Plasma integration for applications ==

;[[Development/Tutorials/Solid_Device_Actions|Creating a Device Notifier action]]
:''When your application is interested in removable hardware''

;[[Development/Tutorials/Plasma/ApplicationShell|Integrate Plasma in Applications]]
:''This tutorial shows you how to make an application dashboard based on Plasma technologies.''

== Themes ==

;[[Development/Tutorials/Plasma/Theme|Creating a Plasma Theme Quickstart]]
:''A quick guide to creating your first Plasma theme''

;[[Development/Tutorials/Plasma/ThemeDetails|The Plasma Theme Structure In Detail]]
:''A comprehensive guide to the contents of a Plasma SVG theme, including configuration options, wallpapers, on-disk layout, names of all standard SVG files and every element in them.''

== Activity Templates ==

;[[KDE_System_Administration/PlasmaDesktopScripting#Activity_templates|Creating a Plasma Activity Template Quickstart]]
:''A quick guide to creating your first Plasma Activity Template''

== Resources ==

* [[Projects/Plasma|Projects: Plasma]]
* [http://api.kde.org/4.x-api/kdelibs-apidocs/plasma/html/index.html Plasma api documentation]
* [http://techbase.kde.org/Projects/Plasma/Eclipse_Integration Plasma Eclipse Integration]
* The [https://mail.kde.org/mailman/listinfo/plasma-devel plasma-devel mailing list] and #plasma on IRC (irc.freenode.org).

Development/Tutorials/Plasma

2011-11-09T11:15:11Z

Aseigo:

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Plasma}}

== QML ==
Plasmoids that use the QML (aka QtQuick) declarative language to describe their user interface while having the logic of the applet, in JavaScript (QML is essentially a forge between CSS and JavaScript).

This is now the '''recommended''' method of creating plasmoids, where possible. The plasmoid, or applet serves as the visualization for the data which a Plasma::DataEngine contains.

It allows easily the declaring of an interface and to easily create things like ListViews with native Plasma theming. It is what Plasma is leaning the most towards, especially in the Mobile, MediaCenter and KDM shells.

;[[Development/Tutorials/Plasma/QML/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in QML''

;[[Development/Tutorials/Plasma/QML/Basic_ListView|Basic List Plasmoid]]
:''Make a QML ListView which displays basic text objects as items. Utilizes native Plasma theming and animations.''

;[[Development/Tutorials/Plasma/QML/API|API Reference]]
:''The QML Plasmoid API. Useful for referencing what is available in the runtime, what are the differences with the pure JavaScript ScriptEngine, the differences between pure Qt QML and Plasma, and as a study aid for the tutorials above.''

== C++ ==

;[[Development/Tutorials/Plasma/GettingStarted|Getting Started With Plasmoids]]
:''Creating your first plasmoid in C++ with SVG background, icon and text''

;[[Development/Tutorials/Plasma/GettingStarted..Some_More|Getting Started With Plasmoids..Some more]] :''A few more starter's tips.''

;[[Development/Tutorials/Plasma/DataEngines|Writing a DataEngine]]
:''DataEngines provide a standardized interface to various (read only) data sources for visualizations to use. Learn what a DataEngine is and how to write one of your own.''

;[[Development/Tutorials/Plasma/Services|Writing a Service]]
:''Services provide a standardized interface for visualizations to perform "write operations". This can be for example, uploading pasted test to a pastebin service..''

;[[Development/Tutorials/Plasma/PackageStructure|Writing a PackageStructure Plugin]]
:''PackageStructure plugins allow custom Packages to be defined, installed, removed and listed as well as provide access their contents at runtime. Packages may contain any kind of data addons, including scripts.''

;[[Development/Tutorials/Plasma/UsingExtenders|How to use extenders in your Plasmoid]]
:''A simple example that shows how to use extenders in a Plasmoid.''

;[[Development/Tutorials/Plasma/AbstractRunner|Creating Runners]]
:''Runners are plugins that provide action-based search functionality in the Plasma workspace "run command" dialog. These plugins can be used by any application that links again libplasma.''

;[[Development/Tutorials/Plasma/WallpaperHelloWorld|Wallpaper Tutorial 1]]
:''This tutorial shows you how to make a simple Hello World plasma wallpaper plugin.''

;[[Development/Tutorials/Plasma/WallpaperConfiguration|Wallpaper Tutorial 2]]
:''This tutorial covers how to add configuration options to the wallpaper.''

;[[Development/Tutorials/Plasma/ShellDesign|Creating a Plasma Shell]]
:''This tutorial covers the essentials of writing a new Plasma shell from scratch. A must-read for anyone creating a new or modifying an existing Plasma Shell. Existing Plasma shells include Plasma Desktop, Plasma Netbook, Plasma Mobile, Plasma Media Center, Plasma Screensaver, Plasma KPart and Plasma KDM, and all follow the patterns documented here.''

;[http://www.linux-magazine.com/w3/issue/114/036-040_plasma.pdf Creating Plasmoids]
:''May 2010 article from Linux Magazine''

;[http://www.ibm.com/developerworks/linux/library/l-kde-plasmoids/index.html Create Plasmoids using KDevelop]
:''Article explaining the structure of Plasma and how to create a Plasmoid''

;[http://community.kde.org/User:Mxttie#Adding_configuration Adding configuration to your plasmoid]
:''Article explaining how to add a configuration dialog to your plasmoid.''

;[[Development/Tutorials/Plasma/ApplicationShell|Integrate Plasma in Applications]]
:''This tutorial shows you how to make an application dashboard based on Plasma technologies.''

== JavaScript ==

Plasma has built-in JavaScript (also known as ECMAScript, and often referred to as QtScript in the context of Qt) scripting support without requiring any external dependencies.

=== Plasmoids ===

;[[Development/Tutorials/Plasma/JavaScript/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in JavaScript''

;[[Development/Tutorials/Plasma/JavaScript/DataEngine|Getting Data]]
:''How to retreive data from a data engine''

;[[Development/Tutorials/Plasma/JavaScript/NowPlaying|Now Playing]]
:''Slightly more advanced data engine usage: displaying what's currently playing''

;[[Development/Tutorials/Plasma/JavaScript/SystemMonitor|System Monitor]]
:''How to access systemmonitor data engine''

;[[Development/Tutorials/Plasma/JavaScript/CheatSheet|Cheat Sheet]]
:''A cheat sheet, rather than a tutorial, of things to remember and watch out for when developing JavaScript plasmoids''

;[[Development/Tutorials/Plasma/JavaScript/API|API Reference]]
:''The Simplified JavaScript Plasmoid API. Useful for referencing what is available in the runtime and as a study aid for the tutorials above.''

=== Other Applications Of Javascript ===
;[[KDE_System_Administration/PlasmaDestkopScripting|Scripting Plasma Shells]]
:The KDE Plasma Desktop and Netbook provide means to manage the desktop shell (desktop, panels, widget) via scripts written in JavaScript. This article describes how to take advantage of this feature set as well as documents the full API. This is primarily a system administration tool, but may also be of interest to power users.

;[[Development/Tutorials/Plasma/JavaScript/Animations|Javascript Animations]]
:''How to write Animations using Javascript for use in Plasma applications''

;[[Development/Tutorials/Plasma/ComicPlugin|Creating Comic Plugins]]
:''This guide shows you how to create a comic plugin for the comic plasmoid.''

== Python ==

;[[Development/Tutorials/Plasma/Python/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in Python''

;[[Development/Tutorials/Plasma/Python/Using widgets|Using widgets]]
:''Introduction to using Plasma widgets''

;[[Development/Tutorials/Plasma/Python/Using DataEngines|Using DataEngines]]
:''How to use DataEngines from a plasmoid''

;[[Development/Tutorials/Plasma/Python/Writing DataEngines|Writing DataEngines]]
:''How to write your own Plasma DataEngine''

;[[Development/Tutorials/Plasma/PythonPlasmoid|Writing a Plasmoid in Python]]
:''Writing a simple battery graph in python''

;[[Development/Tutorials/Plasma/PythonRunner|Writing a KRunner plugin in Python]]
:''Writing a simple krunner plugin in python''

== Ruby ==
;[[Development/Tutorials/Plasma/Ruby/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in Ruby''

;[[Development/Tutorials/Plasma/Ruby/Using widgets|Using widgets]]
:''Introduction to using Plasma widgets''

;[[Development/Tutorials/Plasma/Ruby/SimplePasteApplet|Writing a simple paste applet]]
:''A tutorial explaining how to set up a plasmoid, create a simple paste applet using widgets and add Plasma features seen elsewhere. Complete with tips for those who have never programmed before.''

;[[Development/Tutorials/Plasma/Ruby/Writing DataEngines|Writing DataEngines]]
:''How to write your own Plasma DataEngine using Ruby''

;[[Development/Tutorials/Plasma/Ruby/Blinker|Use SVG artwork in the simplest way possible]]
:''Follow a fellow student as he asks around about SVG usage and explains why the code examples work. This is a wiki so feel free to add your own insights until this tutorial can be considered complete.''

== Web Technologies (HTML/JS/CSS) ==
;[[Development/Tutorials/Plasma/Web/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in HTML''

== Plasma integration for applications ==

;[[Development/Tutorials/Solid_Device_Actions|Creating a Device Notifier action]]
:''When your application is interested in removable hardware''

== Themes ==

;[[Development/Tutorials/Plasma/Theme|Creating a Plasma Theme Quickstart]]
:''A quick guide to creating your first Plasma theme''

;[[Development/Tutorials/Plasma/ThemeDetails|The Plasma Theme Structure In Detail]]
:''A comprehensive guide to the contents of a Plasma SVG theme, including configuration options, wallpapers, on-disk layout, names of all standard SVG files and every element in them.''

== Activity Templates ==

;[[KDE_System_Administration/PlasmaDesktopScripting#Activity_templates|Creating a Plasma Activity Template Quickstart]]
:''A quick guide to creating your first Plasma Activity Template''

== Resources ==

* [[Projects/Plasma|Projects: Plasma]]
* [http://api.kde.org/4.x-api/kdelibs-apidocs/plasma/html/index.html Plasma api documentation]
* [http://techbase.kde.org/Projects/Plasma/Eclipse_Integration Plasma Eclipse Integration]
* The [https://mail.kde.org/mailman/listinfo/plasma-devel plasma-devel mailing list] and #plasma on IRC (irc.freenode.org).

Development/Tutorials/Plasma/JavaScript/API-PlasmoidObject

2011-10-27T14:44:35Z

Aseigo: /* Context menu */

Development/Tutorials/Plasma/JavaScript/API-PlasmoidObject

2011-10-27T14:43:13Z

Aseigo: /* Context menu */

Development/Tutorials/Plasma/QML/API

2011-09-23T13:49:39Z

Aseigo: /* Data Engines */

= Introduction to the Plasmoid QML Declarative API =

This document provides an overview/reference of the Declarative QML API for Plasmoids. It isn't a full binding to all of Qt or KDE's libraries, but a focused set of bindings designed to make writing Plasmoids fast and easy, while remaining powerful.

The API in this documentation covers the API of the Plasma specific QML components, so only the Declarative part of the API.

The QML ScriptEngine is bassed upon the Plasma JavaScript engine, making the API of the JavaScript part identical to the one of the JavaScript plasmoids engine.
To see the api of the global ''Plasmoid'' object, see the [http://techbase.kde.org/Development/Tutorials/Plasma/JavaScript/API#The_Global_plasmoid_Object JavaScript API] documentation.
(TODO: the JavaScript api paged should probably be copied and stripped down the imperative bits not present there, it would make harder to update tough)

== What Is a Declarative Plasmoid? ==

To denote that this Plasmoid is a Declarative widget, ensure that in the metadata.desktop file there is this line:

X-Plasma-API=declarativeappletscript

What follows is a description of the Plasma declarative classes instantiable from QML.

= Main Plasma QML Classes =

== Data Engines ==
While it's possible to fetch data from a Plasma DataEngine in the same way as the [http://techbase.kde.org/Development/Tutorials/Plasma/JavaScript/API#DataEngine JavaScript API], it is preferrable to use the following declarative classes:

=== DataSource ===
DataSource is a receiver for a dataEngine and can be declared inside QML:

<syntaxhighlight lang="javascript">
import org.kde.plasma.core 0.1 as PlasmaCore

PlasmaCore.DataSource {
id: dataSource
engine: "time"
connectedSources: ["Local"]
interval: 500
}
</syntaxhighlight>

==== Properties ====
It has the following properties:
* bool '''valid''' (read only): true when the DataSource is successfully connected to a data engine
* int '''interval''': interval of polling of the dataengine, if 0 (default value, so no need to specify if you don't need it) no polling will be executed
* string '''engine''': the plugin name of the dataengine to load, e.g. "nowplaying", etc.
* Array(string) '''connectedSources''': all the sources of the dataengine we are connected to (and whose data will appear in the '''data''' property)
* Array(string) '''sources''' (read only): all the sources available from the dataengine
* variant map '''data''' (read only): It's the most important property, it's a map of all the data available from the dataengine: its structure will be as follows:
** each key of the map will be a source name, in '''connectedSources'''
** each value will be a variant hash, so an hash with strings as keys and any variant as value
** example: dataSource.data["Local"]["Time"] indicates the '''Time''' key of the dataengine source called "Local"

==== Signals ====
It has the following signals:

Note that javascript/qml applies the 'on' prefix to signals. So the actual signal name in C++ which is e.g. '''newData''(...) becomes '''onNewData'''(...).

* '''onNewData'''(String sourceName, Plasma::DataEngine::Data data)
* '''onSourceAdded'''(String source)
* '''onSourceRemoved'''(String source)
* '''onSourceConnected'''(String source)
* '''onSourceDisconnected'''(String source)
* '''onIntervalChanged'''()
* '''onEngineChanged'''()
* '''onDataChanged'''()
* '''onConnectedSourcesChanged'''()
* '''onSourcesChanged'''()

==== Methods ====
It has the following methods:
* StringList keysForSource(String source): lists all the keys corresponding to a certain source: for instance in the "time" dataengine, for the "Local" source, keys will be:
** "Timezone Continent"
** "Offset"
** "Timezone"
** "Time"
** "Date"
** "Timezone City"
* Service serviceForSource(String source): returns a Plasma service that corresponds a given source: see the section about services for how to use it.
* void connectSource(String source): adds to '''connectedSources''' the new source
* void disconnectSource(String source): removes that source from '''connectedSources'''

=== Service ===
Due to their imperative nature, Plasma Services are not instantiated as QML classes, but rather created out of a '''DataSource''' with the method '''serviceForSource''' and used in the JavaScript portions of the QML files.
This following example is a simplified version from the Now Playing QML widget in the kdeexamples git repository:

<syntaxhighlight lang="javascript">
var service = dataSource.serviceForSource(activeSource)
var operation = service.operationDescription("seek")
operation.seconds = 10

var job = service.startOperationCall(operation)
</syntaxhighlight>
Here dataSource is the id of a DataSource object, and activeSource is a source contained in one of its '''connectedSources'''.
The service provides an operation called "seek", with a parameter called "seconds", that can be written on it as a property of a JavaScript object.

=== ServiceJob ===
If is necessary to monitor the result of a Service operation, it's possible to connect to the '''finished''' signal provided by the job return paramenter of the '''startOperationCall''' service method.
The '''finished''' signal has the same job as parameter, from which is possible to check the variant '''result''' property, to check the result.

=== DataModel ===
Some data engines return as their data something that can be interpreted as a list of items, rather than simple key/value pairs.
QML provides some item views such as '''ListView''', '''GridView''' and '''Repeater'''.
The '''DataModel''' QML object can provide, based on a DataSource a model suitable for those QML item views.

It has the following properties:
* DataSource '''dataSource''': the id of an existing (and connected) DataSource
* String '''sourceFilter''': it's a regular expression. If the DataSource is connected to more than one source, only inserts data from sources matching this filter expression in the model. To, for example, have a source watch all sources beginning with say "name:", the required regexp would be sourceFilter: "name:.*"
* String '''keyRoleFilter''': it's a regular expression. Only data with keys that match this filter expression will be inserted in the model
* int '''count''' (read only): how many items are in the model

Example:

<syntaxhighlight lang="javascript">
ListView {
model: PlasmaCore.DataModel {
dataSource: microblogSource
keyRoleFilter: "[\\d]*"
}
delegate: Text {
text: title
}
}
</syntaxhighlight>

In the example, ''microblogSource'' is the id of a DataSource, and inserts in the model only entries that have a number as the key name (matched with [\\d]*, in this case tweets ids)

Each item in the model will have the form of a variant hash: all the keys of the hash will be registered as model role names, in the example, "title" is a role of the model containing a string (also reachable with model["title"]).

A special reserved role will always be present: '''"DataEngineSource"''': it will contain the name of the data engine source that gave origin to this item. Therefore, if you want merely the string of the current source that the model is at...do model["DataEngineSource"].

Note that view.currentItem holds the item currently selected. However, due to (http://bugreports.qt.nokia.com/browse/QTBUG-16347) this does not work in PathView. A workaround is to make your own.

=== SortFilterModel ===
SortFilterModel is a proxy model for easy sorting and/or filtering of the items in a DataModel (or any other QAbstractItemModel subclass that has been registered in QML with setContextProperty from a C++ application)
Properties:
* model '''sourceModel'''
* String '''filterRegExp'''
* String '''filterRole'''
* String '''sortRole'''
* Qt::SortOrder '''sortOrder'''
* int '''count''' (read only)

== Popup Applet ==
So you want your QML applet to be a popup applet, like the device notifier (an icon in the panel shows and expands the applet)?

Why, that's easy.

To change your plasmoid from being a regular boring one, in your '''metadata.desktop''', simply change this following line:

<syntaxhighlight lang="ini">
ServiceTypes=Plasma/Applet
</syntaxhighlight>

To:

<syntaxhighlight lang="ini">
ServiceTypes=Plasma/Applet,Plasma/PopupApplet
</syntaxhighlight>

Then in the main QML item's Component.onCompleted, do:

NOTE: the below code presently has no affect, yet the icons seems to get retrieved from the desktop file (FIXME - is this needed? It has no affect presently).

<syntaxhighlight lang="javascript">
plasmoid.popupIcon("konqueror")
</syntaxhighlight>

== Plasma Themes ==

=== Theme ===
This class instantiable from QML provides access to the Plasma Theme colors and other facilities such as fonts.
It has the following properties:
* String '''themeName''' (read only)
* QFont '''font''' (read only)
* bool '''windowTranslucentEnabled''' (read only)
* Url '''homepage''' (read only)
* bool '''useGlobalSettings''' (read only)
* QString '''wallpaperPath''' (read only)
* color '''textColor''' (read only)
* color '''highlightColor''' (read only)
* color '''backgroundColor''' (read only)
* color '''buttonTextColor''' (read only)
* color '''buttonBackgroundColor''' (read only)
* color '''linkColor''' (read only)
* color '''visitedLinkColor''' (read only)
* color '''visitedLinkColor''' (read only)
* color '''buttonHoverColor''' (read only)
* color '''buttonFocusColor''' (read only)
* color '''viewTextColor''' (read only)
* color '''viewBackgroundColor''' (read only)
* color '''viewHoverColor''' (read only)
* color '''viewFocusColor''' (read only)
* String '''styleSheet''' (read only)

=== Svg ===
Declaring a Svg element instantiates a Plasma Svg instance. This class doesn't draw anything. For drawing, SvgItem is used.
Properties:
* QSize '''size'''
* bool '''multipleImages'''
* String '''imagePath''' can be anything in the '''desktoptheme/''' folder. For more information on what is available, see [http://techbase.kde.org/Projects/Plasma/Theme#Current_Theme_Elements Plasma Theme Elements]
* bool '''usingRenderingCache'''

Methods:
* QPixmap pixmap(QString elementID)
* void resize(qreal width, qreal height)
* void resize(): resets the image to its default dimension
* QSize elementSize(QString elementId)
* QRectF elementRect(QString elementId)
* bool hasElement(QString elementId)
* bool isValid(): true if valid svg file

Sample Code:
<syntaxhighlight lang="javascript">
PlasmaCore.Svg {
id: mySvg
imagePath: "widgets/line"
}
</syntaxhighlight>

=== SvgItem ===
It's a graphical element that will actually paint a Svg instance.
Properties:
* String '''elementId''': what element to render. If null, the whole svg will be rendered
* Svg '''svg''': instance of the Svg class mentioned above
* QSizeF '''naturalSize''' (read only): default size of the Svg
* bool '''smooth''': paint with antialias (default false)

Sample Code:

<syntaxhighlight lang="javascript">
PlasmaCore.SvgItem {
id: mySvgItem
anchors {
top: parent.top
left: parent.left
}

width: 300
height: 3

svg: mySvg
elementId: "horizontal-line"
}
</syntaxhighlight>

=== FrameSvgItem ===
It's a graphical element that paints a Plasma::FrameSvg, so a rectangular image composed by 9 elements contained in a Svg file, useful for things like buttons and frames.

Flags
* EnabledBorders: combination of TopBorder | BottomBorder | LeftBorder | RightBorder, NoBorder if no border of the frame is enabled

Properties:
* String '''imagePath''': path of the file relative to the Plasma Theme, for instance "widgets/background"
* String '''prefix''': a FrameSvg can contain multiple frames, for instance a button contains "normal", "raised" and "pressed"
* Margins '''margins''' (read only): the margins of the frame, see documentation below
* EnabledBorders '''enabledBorders''': what borders are enabled

==== Margins ====
Properties:
* real '''left''' (read only)
* real '''top''' (read only)
* real '''right''' (read only)
* real '''bottom''' (read only)

Sample Code:

<syntaxhighlight lang="javascript">
PlasmaCore.FrameSvgItem {
id: myFrameSvgItem
anchors.fill: parent
imagePath: "translucent/dialogs/background"
}
</syntaxhighlight>

== Top Level windows ==

=== Dialog ===
Dialog instantiates a Plasma::Dialog, it will be a Plasma themed top level window that can contain any QML component.

Properties:
* Item mainItem: the Item contained in the Dialog, it can be any QML Item instance
* bool '''visible''': if the window (not the mainItem) is visible
* int '''x''': x position of the window in screen coordinates
* int '''y''': y position of the window in screen coordinates
* int '''width''' (read only): total width of the dialog, including margins
* int '''height''' (read only): total height of the dialog, including margins
* int '''windowFlags''': Qt window flags of the Dialog
* Margins '''margins''' (read only): margins of the Dialog

Methods:
* QPoint popupPosition(Item item, Qt::Alignment alignment=Qt::AlignLeft): the suggested position for the Dialog if it has to be correctly placed as popup of the QML item passed as parameter.
* void setAttribute(Qt::WindowAttribute attribute, bool on): set an attribute for the dialog window

==== Margins ====
Properties:
* real '''left''' (read only)
* real '''top''' (read only)
* real '''right''' (read only)
* real '''bottom''' (read only)

=== ToolTip ===
Declaring a ToolTip instance makes it possible to use Plasma tooltips with any QML item.

Properties:
* Item '''target''': the QML item we want to show a tooltip of
* String '''mainText'''
* String '''subText'''
* String '''image''': freedesktop compliant icon name as image of the tooltip

= Plasma QtComponents (4.8) =
TODO

KDE System Administration/Kiosk/Keys

2011-08-09T17:36:26Z

Aseigo: /* plasma-desktop */

This article contains a listing of known keys that can be used with Kiosk and what they do. How to actually use these keys and other capabilities of Kiosk such as URL restrictions, creating assigning profiles, etc. is covered in the [[../Introduction|Introduction to Kiosk]] article.

Which configuration file to put these entries in depends on whether you wish to make them global to all applications or specific to one application. To make the restrictions valid for all applications, put them in {{path|kdeglobals}}. To enable a restriction for a specific applications place them in the application-specific configuration, e.g. {{path|konquerorrc}} for Konqueror.

== Application Action Restrictions ==

These keys disable actions that are commonly found in KDE applications. To use these actions, create a section in {{path|kdeglobals}} that looks like this:

<syntaxhighlight lang="ini">
[KDE Action Restrictions][$i]
action/<key>=false
</syntaxhighlight>

{|
|-
! Key !! Menu !! Action
|-
|action/file_new || File || New
|-
|action/file_open || File || Open
|-
|action/file_open_recent || File || Open Recent File
|-
|action/file_save || File || Save
|-
|action/file_save_as || File || Save As
|-
|action/file_revert || File || Revert
|-
|action/file_close || File || Close
|-
|action/file_print || File || Print
|-
|action/file_print_preview || File || Print Preview
|-
|action/file_mail || File || Email File
|-
|action/file_quit || File || Quit
|-
|action/edit_undo || Edit || Undo
|-
|action/edit_redo || Edit || Redo
|-
|action/edit_cut || Edit || Cut
|-
|action/edit_copy || Edit || Copy
|-
|action/edit_paste || Edit || Paste
|-
|action/edit_select_all || Edit || Select All
|-
|action/edit_deselect || Edit || Deselect
|-
|action/edit_find || Edit || Find
|-
|action/edit_find_next || Edit || Find Next
|-
|action/edit_find_last || Edit || Find last
|-
|action/edit_replace || Edit || Replace
|-
|action/view_actual_size || View || 100% Zoom
|-
|action/view_fit_to_page || View || Fit To Page (zooming)
|-
|action/view_fit_to_width || View || Fit To Width (zooming)
|-
|action/view_fit_to_height || View || Fit To Height (zooming)
|-
|action/view_zoom_in || View || Zoom In
|-
|action/view_zoom_out || View || Zoom Out
|-
|action/view_zoom || View || Zoom
|-
|action/view_redisplay || View || Refresh
|-
|action/go_up || Go || Up
|-
|action/go_back || Go || Back
|-
|action/go_forward || Go || Forward
|-
|action/go_home || Go || Home
|-
|action/go_previous || Go || Previous
|-
|action/go_next || Go || Next
|-
|action/go_goto || Go || Go To...
|-
|action/go_goto_page || Go || Go To Page...
|-
|action/go_goto_line || Go || Go To Line...
|-
|action/go_first || Go || Go To Start
|-
|action/go_last || Go || Go To End
|-
|action/bookmarks || Bookmarks || Also disables action/bookmark_add and action/bookmark_edit
|-
|action/bookmark_add || Bookmarks || Add Bookmark
|-
|action/bookmark_edit || Bookmarks || Edit Bookmarks
|-
|action/tools_spelling || Tools || Check Spelling
|-
|action/options_show_menubar || Settings || Show/hide Menubar
|-
|action/options_show_toolbar || Settings || Show/hide Toolbar, will also disable the "Toolbars" submenu if present
|-
|action/options_show_statusbar || Settings || Show/hide statusbar
|-
|action/options_save_Settings || Settings || Save Settings
|-
|action/options_configure || Settings || Configure application
|-
|action/options_configure_keybinding || Settings || Configure Shortcuts
|-
|action/options_configure_toolbars || Settings || Configure Toolbars
|-
|action/options_configure_notifications || Settings || Configure Notifications
|-
|action/fullscreen || Settings || Enter full screen mode
|-
|action/help || Help || Not yet fully implemented
|-
|action/help_contents || Help || Application handbook
|-
|action/help_whats_this || Help || Go into "what's this" mode
|-
|action/help_report_bug || Help || Report a bug
|-
|action/help_about_app || Help || Show about application dialog
|-
|action/help_about_kde || Help || Show about KDE dialog
|}

=== KCalc ===

By marking the kcalcrc config file as immutable, the "Configure" button
will not be shown.

=== File Manager ===

{|
|-
! Key !! Action
|-
|action/editfiletype || Edit associated applications
|-
|action/properties || File properties
|-
|action/openwith || Open file with action
|-
|action/openintab || Open link in a new tab
|-
|action/kdesktop_rmb || RMB menu, see note below
|-
|action/iconview_preview || Show preview thumbnails in icons, though it leaves the actual setting untouched. To disable previews (as opposed to simply disabling the user to change the setting) you also need to add the following lines to konqiconviewrc:
<syntaxhighlight lang="ini">
[Settings]
PreviewsEnabled[$i]=false
</syntaxhighlight>
|-
|action/sharefile || Disables file sharing from the UI, but you may also want to disable filesharing altogether.
|-
|action/sendURL || Send Link Address
|-
|action/sendPage || Send File
|-
|action/devnew || Create New -> Device
|-
|action/incIconSize || Increase icon size
|-
|action/decIconSize || Decrease icon size
|-
|action/go || Entire go menu
|-
|action/configdesktop || Configure desktop in RMB menu, see also Control Module Restrictions
|-
|action/executeshellcommand || In Konqueror Tools menu, see also <tt>shell_access</tt>
|-
|action/show_dot || Disables the option to toggle showing hidden files, the actual setting remains unaffected. To disable showing hidden files, add the following lines to konqiconviewrc:
<syntaxhighlight lang="ini">
[Settings]
ShowDotFiles[$i]=false
</syntaxhighlight>
|}

=== Konsole ===

These keys can appear in {{path|kdeglobals}}, {{path|konsolepartrc}} or {{path|konsolerc}}.

{|
|-
! Key !! Action
|-
|action/konsole_rmb || Context menus
|-
|action/settings || Disable the entire settings menu
|-
|action/show_menubar || Show/hide the menubar
|-
|action/show_toolbar || Show/hide the toolbar
|-
|action/scrollbar || Show/hide the scrollbar
|-
|action/bell || Configure bell actions
|-
|action/font || Configure font
|-
|action/keyboard || Set keyboard type
|-
|action/schema || Select the schema to use
|-
|action/size || Set the terminal size
|-
|action/history || Configure history
|-
|action/save_default || Save settings as defaults
|-
|action/save_sessions_profile || Save sessions profile
|-
|action/send_signal || Send a signal to the current terminal
|-
|action/bookmarks || Bookmarks menu
|-
|action/add_bookmark || Add a bookmark
|-
|action/edit_bookmarks || Edit bookmarks
|-
|action/clear_terminal || Clear the current terminal
|-
|action/reset_clear_terminal || Clear and reset the current terminal
|-
|action/find_history || Find in history
|-
|action/find_next || Find next item in history
|-
|action/find_previous || Find previous item in history
|-
|action/save_history || Save history to disk
|-
|action/clear_history || Clear history of current terminal
|-
|action/clear_all_histories || Clear histories of all terminals
|-
|action/detach_session || Detach current tab
|-
|action/rename_session || Rename current session
|-
|action/zmodem_upload || ZModem uploading
|-
|action/monitor_activity || Monitor current terminal for activity
|-
|action/monitor_silence || Monitor current terminal for silence
|-
|action/send_input_to_all_sessions || Replicate input to all sessions
|-
|action/close_session || Close current terminal session
|-
|action/new_session || Create a new terminal session
|-
|action/activate_menu || Activate menubar
|-
|action/list_sessions || Session list menu
|-
|action/move_session_left || Shift tab to the left
|-
|action/move_session_right || Shift tab to the right
|-
|action/previous_session || Go to tab to the left
|-
|action/next_session || Go to tab to the right
|-
|action/switch_to_session_# || Go to tab numbered #, where # is a number between 1 and 12 inclusive.
|-
|action/bigger_font || Increase font size
|-
|action/smaller_font || Decrease font size
|-
|action/toggle_bidi || Turn bidirectional text support on or off
|}

=== KWin ===

{|
|-
! Key !! Action
|-
|-
| action/kwin_rmb || Context menus on window titlebar and frame
|}

=== Plasma ===
Locking down the entire config with [$i] will cause everything to be immutable. Locking a Containment group will render that one group of widgets to be immutable, and locking a widget itself will cause it to not be movable as well as otherwise locked.

In addition the following resource restrictions are available:

==== All Plasma apps ====
Any application that links to libplasma supports the following resource restriction keys (the version number in parentheses is the version of the KDE Software Compilation that the key debuted in):

;plasma/allow_configure_when_locked (4.4)
:Whether widgets and containments can be configured when immutable / locked. The default is true as a convenience to users.

;plasma/containment_actions (4.4)
:Whether or not to allow Plasma mouse actions on containments (usually menus that pop up on mouse clicks)

;plasma/containment_context_menu (4.4)
:Whether a context menu should be shown on containments; this can be used to shut off the desktop context menu in plasma-desktop, for instance

;plasma/external_script_extensions (4.5)
:Whether or not to allow external scripting extensions to APIs beyond the built-in extensions and API.

==== plasma-desktop ====
The plasma-desktop binary (the desktop and panels part of the KDE Plasma Workspace) supports the following resource restriction keys (the version number in parentheses is the version of the KDE Software Compilation that the key debuted in)::

;plasma-desktop/scripting_console (>= 4.4.0)
:Whether the plasma desktop scripting console is accessible or not.

;plasma-desktop/add_activities (>= 4.7.1)
:Whether the user may add new activities or not

=== Using D-Bus To Find More Actions ===

== Authorizing {{path|.desktop}} Files ==

Application {{path|.desktop}} files can have an additional field <tt>X-KDE-AuthorizeAction</tt>.

If this field is present the {{path|.desktop}} file is only considered valid if the action(s) mentioned in this field has been authorized. If multiple actions are listed they should be separated by commas (',').

If the {{path|.desktop}} file of an application lists one or more actions this way and the user has no authorization for even one of these actions then the application will not appear in the KDE menu, will not allow execution via that {{path|.desktop}} file and will not be used by KDE for opening files of associated mimetypes.

== File Dialog ==

These keys disable actions that are found in the KDE file dialog. To use them, create a section in {{path|kdeglobals}} that looks like this:

<syntaxhighlight lang="ini">
[KDE Action Restrictions][$i]
action/<key>=false
</syntaxhighlight>

{|
|-
! Key !! Action
|-
|-
| action/home || Go to home directory
|-
| action/up || Go to parent directory
|-
| action/back || Go to previous directory
|-
| action/forward || Go to next directory
|-
| action/reload || Reload directory
|-
| action/mkdir || Create new directory
|-
| action/toggleSpeedbar || Show/hide sidebar
|-
| action/sorting menu || Sorting options
|-
| action/short view || Select short view
|-
| action/detailed view || Select detailed view
|-
| action/show hidden || Show/hide hidden files
|-
| action/preview || Show/hide preview
|-
| action/separate dirs || Show/hide separate directories
|}

== Printing ==

There are several keys that restrict various aspects of the KDE print dialog and printing system. To use them, create a configuration section like this:

<syntaxhighlight lang="ini">
[KDE Resource Restrictions][$i]
print/<resource key>=false
</syntaxhighlight>

Note how each of the printing keys start with <tt>print</tt> in the configuration file.

;print/copies
:Disables the panel that allows users to make more than one copy.

;print/dialog
:Disables the complete print dialog. Selecting the print option will immediately print the selected document using default settings. Make sure that a system wide default printer has been selected. No application specific settings are honored when this restriction is activated.

;print/options
:Disables the button to select additional print options.

;print/properties
:Disables the button to change printer properties or to add a new printer.

;print/selection
:Disables the options that allows selecting a (pseudo) printer or change any of the printer properties. Make sure that a proper default printer has been selected before disabling this option. Disabling this option also disables <tt>print/system</tt>, <tt>print/options</tt> and <tt>print/properties</tt>.

;print/system
:Disables the option to select the printing system backend, e.g. CUPS. It is recommended to disable this option once the correct printing system has been configured.

== Resource Restrictions ==

KDE applications can take advantage of many types of resources such as configuration data, caches, plugin registries, etc. These are loaded from both system-wide as well as from per-user locations on disk. It is possible to restrict use of the per-user resources directories, preventing users from adding to or altering existing shared resources.

This is accomplished by creating a section like this in a configuration file:

<syntaxhighlight lang="ini">
[KDE Resource Restrictions][$i]
<resource key>=false
</syntaxhighlight>

The following resources can be used as keys and controlled in this manner:

{|
|-
! Key !! Directory !! Provides
|-
|all || n/a || All resources listed in this table
|-
|autostart || {{path|share/autostart}} || Apps to start on login
|-
|data || {{path|share/apps}} || Application data
|-
|data_<appname> || {{path|share/apps}} || Application data for the application named <appname>
|-
|html || {{path|share/doc/HTML}} || HTML files
|-
|icon || {{path|share/icon}} || Icons
|-
|config || {{path|share/config}} || Application configurations
|-
|pixmap || {{path|share/pixmaps}} || Images
|-
|xdgdata-apps || {{path|share/applications}} || Application .desktop files
|-
|sound || {{path|share/sounds}} || Sound files
|-
|locale || {{path|share/locale}} || Localization data
|-
|services || {{path|share/services}} || Protocols, plugins, kparts, control panels, etc. registry
|-
|servicetypes || {{path|share/servicetypes}} || Plugin definitions, referenced in services registry entries
|-
|mime || {{path|share/mimelnk}} || Mimetype definitions
|-
|wallpaper || {{path|share/wallpapers}} || Desktop wallpaper images
|-
|templates || {{path|share/templates}} || Document templates
|-
|exe || {{path|bin}} || Executable files
|-
|lib || {{path|lib}} || Libraries
|}

== Screensavers ==
In {{path|kdeglobals}} in the <tt>[KDE Action Restrictions]</tt> group:

;opengl_screensavers
:defines whether OpenGL screensavers are allowed to be used.

;manipulatescreen_screensavers
:defines whether screensavers that manipulate an image of the screen (e.g. moving chunks of the screen around) are allowed to be used.

=== Automatic Log-out ===
In {{path|kscreensaverrc}}:

<syntaxhighlight lang="ini">
[ScreenSaver]
AutoLogout=true
AutoLogoutTimeout=600
</syntaxhighlight>

The timeout is the time in seconds that the user must be idle for before the logout process is automatically started. Be careful with this capability as it can lead to data loss if the user has unsaved files open.

== Session Capability Restrictions ==

These keys apply to various capabilities associated with a desktop session and are not application specific. To use them, create a section in {{path|kdeglobals}} that looks like this:

<syntaxhighlight lang="ini">
[KDE Action Restrictions][$i]
<key>=false
</syntaxhighlight>

;custom_config
:Whether the <tt>--config</tt> command line option should be honored. The <tt>--config</tt> command line option can be used to circumvent locked-down configuration files.

;editable_desktop_icons
:define whether icons on the desktop can be moved, renamed, deleted or added. You might want to set the path for the desktop to some read-only directory as well instead of {{path|$HOME/Desktop}}.

;lineedit_text_completion
:Defines whether input lines should have the potential to remember any previously entered data and make suggestions based on this when typing. When a single account is shared by multiple people you may wish to disable this out of privacy concerns.

;lock_screen
:whether the user will be able to lock the screen.

;logout
:whether the user will be able to logout from KDE.

;movable_toolbars
:define whether toolbars may be moved around by the user. See also <tt>action/options_show_toolbar</tt>.

;run_command
:whether the "Run Command" (Alt-F2) option is available.

;run_desktop_files
:defines whether users may execute desktop files that are not part of the default desktop, KDE menu, registered services and autostarting services.
* The default desktop includes the files under {{path|$KDEDIR/share/kdesktop/Desktop}} but '''not''' the files under {{path|$HOME/Desktop}}.
* The KDE menu includes all files under {{path|$KDEDIR/share/applnk}} and {{path|$XDGDIR/applications}}
* Registered services includes all files under {{path|$KDEDIR/share/services}}
* Autostarting services include all files under {{path|$KDEDIR/share/autostart}} but '''not''' the files under {{path|$KDEHOME/Autostart}}

;shell_access
:Whether a shell suitable for entering random commands may be started. This also determines whether the "Run Command" option (Alt-F2) can be used to run shell-commands and arbitrary executables. Likewise, executables placed in the user's Autostart folder will no longer be executed. Applications can still be autostarted by placing <tt>.desktop</tt> files in the {{path|$KDEHOME/Autostart}} or {{path|$KDEDIR/share/autostart}} directory. See also <tt>run_desktop_files</tt>.

:You probably also want to activate the following resource restictions:
*"appdata_kdesktop" - To restrict the default desktop.
*"apps" - To restrict the KDE menu.
*"xdgdata-apps" - To restrict the KDE menu.
*"services" - To restrict registered services.
*"autostart" - To restrict autostarting services.
:Otherwise users can still execute .desktop files by placing them in e.g. {{path|$KDEHOME/share/kdesktop/Desktop}}

;skip_drm
:defines if the user may omit DRM checking.

;start_new_session
:defines whether the user may start a second X session. See also the documentation on [http://docs.kde.org/en/HEAD/kdebase/kdm/ kdm configuration].

;switch_user
:defines whether user switching via kdm is allowed. See also the documentation on [http://docs.kde.org/en/HEAD/kdebase/kdm/ kdm configuration].

Contribute

2011-07-19T08:22:30Z

Aseigo:

{{Template:I18n/Language Navigation Bar|Contribute}}
This page intends to give an overview of the different aspects of KDE development in particular for programming related issues. '''The KDE project welcomes anyone willing to help'''.

{{note|There are a lot of ways to get involved in KDE development, which can be summed up in several categories:
:''Documentation, Translation, Development, Usability, Accessibility, Artwork, Promotion
'''Not a coder? See KDE's pages on [http://kde.org/community/getinvolved/ how to get involved] to see other ways you can help. Also see: [[Contribute/Bugsquad|Bugsquad]]!'''
}}

== News and Mail Sources ==
The general direction of the KDE project is determined by those who do the work - there is no single high level plan for what KDE will look like in the future.

If you want to find out what is currently happening, then there are a number of sources you might like to consider:
; [http://www.kde.org/mailinglists/ Mailing Lists]
: Probably the best way to find out what's going on in KDE development. Archives are available [http://lists.kde.org here]

; [http://commitfilter.kde.org/ CommitFilter]
: Receive notification of commits to the KDE source code repositories in areas that interest you.

; [http://commit-digest.org/ KDE Commit-Digest]
: Weekly summary of commits to projects in the KDE source code repositories.

; [http://dot.kde.org/ The Dot]
: The KDE news site.

== Reporting Bugs ==

The easiest way to contribute to KDE is to [http://userbase.kde.org/Asking_Questions#Reporting_KDE_Bugs report any bugs] you find in KDE using the [https://bugs.kde.org/ KDE Bug Tracking System] (also known as Bugzilla).

If the application you are using crashes then the Dr Konqi utility will appear and guide you through the process of reporting the crash. Learn more by reading [[Development/Tutorials/Debugging/How_to_create_useful_crash_reports|how to create useful crash reports]].

== Getting Started with Coding ==
Getting started at coding for KDE is a matter of finding something to fix, and fixing it. You may want to consult the module overview to help find what you are looking for; once you have fixed something, you will want to send in a patch. If you do that a few times, you may want to apply for a KDE Contributor account so you can improve things directly.
* [[Contribute/List of KDE Modules|Module overview]]
* [[Contribute/Send Patches|Sending patches]]
* [[Contribute/Get a Contributor Account|Applying for a KDE Contributor Account]]
* [[Contribute/First Steps with your KDE SVN Account|First steps with your new Contributor account]]

=== C++ ===
KDE is mostly written in C++. If you are not familiar with C++, you should do at least some work on it. There are a number of good books on C++ - an excellent source is [http://mindview.net/Books/TICPP/ThinkingInCPP2e.html Bruce Eckel's "Thinking in C++"], which is available both as a free download and as a printed document. It isn't essential to understand everything before you start in KDE, but you do need to understand basic syntax and operations.

=== Qt ===
To become proficient with KDE coding, you should understand the Qt toolkit. If you are not familiar with Qt, you should work through the tutorials included with [http://doc.qt.nokia.com/latest Qt Reference Documentation].

If you need a gentler introduction to Qt, or would just like an alternative view, then you may wish to look at the [http://qt4.digitalfanatics.org/tiqt/ The Independent Qt Tutorial] (Currently offline due to book contract).

If you prefer to learn Qt by reading a traditional book, take a look at the [http://qt.nokia.com/developer/books/ Books about Qt page]. More suggestions on becoming familiar with Qt4 are available [http://doc.qt.nokia.com/latest/how-to-learn-qt.html How to Learn Qt page].

=== KDE ===
A range of information on KDE techniques is available in the [[Development/Tutorials|tutorial section]]. Note that some of these tutorials still target KDE3, though they should be at least partly applicable.

You will also find useful information on KDE coding in the [[Development/FAQs|FAQs]] section. This information may also be somewhat dated for KDE4, however much of it is broadly applicable, even outside KDE.

You can also read [[Development/Further Information#Books|KDE coding books]].

Last, but by no means least, KDE comes with extensive class (Application Programmer Interface) documentation. This is available in the
[[Development/Tutorials/API Documentation|KDE API Reference Manuals]] section, which also contains a number of useful links on how to write or update the class documentation. You can also generate these on your own machine, or refer to a more up-to-date online version at [http://api.kde.org/ API Reference].

A more detailed description of the steps above is available in our [http://quality.kde.org/develop/howto/howtohack.php Programming Guide].

== Getting Involved in Bug Hunting and Application Quality ==

There is a large number of applications within KDE, and not all of them have a maintainer dedicated to managing bugs and generally helping out with all the issues associated with turning some working code into a polished application.

If you are interested in helping out with KDE, but don't know where to start, becoming a member of the KDE Quality Team might appeal to you - see the [http://quality.kde.org Quality Team website] for more information. Note that you do not need any programming skills to become involved. In particular developers regularly publish so-called [http://community.kde.org/KDE/Junior_Jobs Junior Jobs] to encourage new contributions.

Of course, you can become involved in bug hunting without being part of the KDE Quality Team - just create yourself an account on the KDE [http://bugs.kde.org bug tracking system], and start searching / sorting through the bugs. Again, you don't have to have programming skills - it helps the programmers enormously just to have a procedure that allows a bug to be consistently reproduced.

The [[Contribute/Bugsquad|Bugsquad]] tries to keep track of bugs in KDE software and make sure that valid bugs are noticed by developers. You do not need any programming knowledge to be in the Bugsquad; in fact it is a great way to return something to the KDE community if you cannot program.

==Getting Answers to Your Questions==
If your question concerns KDE development, your options are pretty much the same general user ones, with some modifications:
::* '''Read the Developer FAQ'''. Many common developer questions have been answered in the [[Development/FAQs|KDE Developer FAQ]]
::* '''Search/browse KDE websites'''. A lot of questions can also be answered from the KDE websites, and the documentation included on it. You can search all the KDE websites on the homepage. In addition, you can browse the [http://techbase.kde.org KDE TechBase website]. And if possible, help edit it for clarity, and use the talk page if something is unclear.
::* '''Search mailing lists'''. A lot of questions have already been answered on the KDE mailing lists, particular the lists kde-devel, kde2-porting, kde-core-devel, kde-games-devel, kfm-devel and koffice-devel. You can search these lists either at [http://lists.kde.org/ lists.kde.org]. You should always search for your answer before asking questions on the mailing lists. When you ask a question on a mailing list you are emailing thousands of people -- please do this only if the answer is not available through a simple search.
::* '''Search engines'''. Do not forget about your favorite search engine. One of the best search engines is Google. With Google you can also [http://groups.google.com/ search] the great bulk of Usenet news sites, which is also particularly helpful, especially for general programming and gcc-related questions.
::* '''Read the source code'''. http://websvn.kde.org and https://projects.kde.org/ are available to help browse code. Read some commit logs and diffs for the code you might want to work with, It adds perspective.
::* '''Ask on KDE mailing lists'''. If you still do not have an answer, try asking your question on one of the KDE mailing lists listed above.
::::* For questions relating to core development or third-party KDE development, unless you are particularly interested in [http://konqueror.kde.org/ Konqueror], [http://www.koffice.org/ KOffice], games or Java development, your main choice is [mailto:kde-devel@kde.org kde-devel] [mailto:kde-devel-request@kde.org?subject=subscribe (subscribe)].
::::* For questions relating to Konqueror development, your main choice is [mailto:kfm-devel@kde.org kfm-devel] [mailto:kfm-devel@kde.org?subject=subscribe (subscribe)]
::::* For questions relating to KOffice development, your main choice is [mailto:koffice-devel@kde.org koffice-devel] [mailto:koffice-devel-request@kde.org?subject=subscribe (subscribe)]
::::* For questions relating to games development, your main choice is [mailto:kde-games-devel@kde.org kde-games-devel] [mailto:kde-games-devel-request@kde.org?subject=subscribe (subscribe)]
::::* For questions relating to [http://qt.nokia.com/ Qt development], please use the fine [http://lists.trolltech.com/qt-interest/ Qt mailing list].
A full list of KDE mailing lists is available [http://www.kde.org/mailinglists/ here] and [http://mail.kde.org/mailman/listinfo here].

Contribute/First Steps with your KDE SVN Account

2011-07-19T08:21:13Z

Aseigo:

{{warning|This page is yet to be reviewed for changes required by the migration to Git. Information and commands on this page may no longer be valid and should be used with care. Please see the [[Development/Git|KDE Git hub page]] for more details. }}

{{improve}}
This tutorial is about what to do when you are a fresh owner of a new contributor account for KDE.

== Notations ==
* ''SVN'' is used to describe an SVN server, mostly KDE's non-anonymous or anonymous SVN servers.
* The lower case word ''svn'' is used to describe the program named svn, which the user can use to access SVN.
* By ''username'' the name of your KDE SVN account is meant (also known as ''login'').

== Preliminary ==

This tutorial assumes that you have [[Contribute/Get a Contributor Account|applied for a KDE Contributor account as described here]] and that you have received a positive answer with the information associated with your new account.

== Read First! ==

Now you have a KDE Contributor account.

Please note that the answer email will have an explanation about how to use the account. (This explanation is also the file [http://websvn.kde.org/trunk/kde-common/svn/svn_instructions.txt?view=markup kde-common/svn/svn_instructions.txt].) It contains also topics not discussed here. So please read this email.

In case of conflicting instructions, please follow those of the '''email''', not the ones of this tutorial.

== Changed URLs ==

Until now, you have worked with one of the anonymous servers. Now that you have a KDE Contributor account, you will not use that anonymous server anymore. Therefore the base URL to the SVN server changes for you.

For the standard anonymous SVN of KDE, it was: {{path|svn://anonsvn.kde.org}} assuming that you have not used an anonymous SVN mirror. If you have used another anonymous SVN server for KDE, then please use its URL instead.

{{Note|If you are unsure which SVN anonymous server you have used, use the <tt>svn info</tt> command to get the server URL.}}

Now the new base URL for your access to the KDE SVN server will be:
svn+ssh://username@svn.kde.org/home/kde
where <tt>username</tt> is the name that was given to your KDE SVN account.

== Changing The URLs of the Modules of Your Local SVN Copy ==
This only applies if you have local copies of SVN files that were taken from an anonymous SVN Server, otherwise skip this.

To use the KDE SVN server instead of one of the anonymous SVN servers, you need to tell each module of your local SVN copy that you want to change the server. SVN does this with the command
svn switch --relocate

Assuming that you are processing the kdelibs module, you have to use:
svn switch --relocate svn://anonsvn.kde.org/home/kde/trunk/KDE/kdelibs svn+ssh://username@svn.kde.org/home/kde/trunk/KDE/kdelibs

For other modules than kdelibs (or for branches or for tags), you have to change the relative module path; similarly, if you used another anonymous server.

Be careful on what URLs you type, as SVN will only replace the exact old URL by the exact new URL. So if you mistype one of the URLs, it will not work later. (If you have already fallen into this pitfall, it is not a problem, just use relocate again to replace the wrong URL with the right one.)

You will be asked to accept the SSL certificate on the first attempt to access the server.

<syntaxhighlight lang="bash">
$ svn switch --relocate svn://anonsvn.kde.org/home/kde/trunk/KDE/kdelibs svn+ssh://username@svn.kde.org/home/kde/trunk/KDE/kdelibs
The authenticity of host 'svn.kde.org (195.135.221.74)' can't be established.
RSA key fingerprint is 86:f3:66:06:20:74:81:d0:1b:b4:2f:25:03:f7:8e:fb.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'svn.kde.org,195.135.221.74' (RSA) to the list of known hosts.
</syntaxhighlight>

Ensure that the fingerprint matches that in the document [http://techbase.kde.org/Getting_Started/Sources/Using_Subversion_with_KDE#The_KDE_repository_structure Using Subversion with KDE]. (Normally, the SHA1 fingerprint is used for HTTPS.)

== First Test ==

The following steps are described using the command line tool <tt>svn</tt>. Personally, I find it better to start with it, as you know immediately where the problems are. Of course, after you have made your first test, you may use whatever tool that you prefer.

Then you should be ready to start. The best test is to try to update a small directory. So change to a (small) directory of your local copy of KDE and type: <syntaxhighlight lang="bash">svn update</syntaxhighlight>

Alternatively, if you have no local copies installed, you can just checkout a module.
<syntaxhighlight lang="bash">svn checkout YOUR_URL</syntaxhighlight>
Obviously, replace YOUR_URL with the correct path.

Now you can use the SVN commands on KDE's main SVN.

{{note|If you know CVS, you will perhaps wonder that there is no <tt>cvs login</tt>, Subversion has chosen not to have such a way to login. The login is done at the first connection, where authentication is needed.}}

== Default Editor ==

This section is only useful if you plan to use the <tt>svn</tt> program. If you always plan to use a GUI front-end, you can skip this section.

When committing, <tt>svn</tt> wants some text for commenting the commit. You can either specify it directly with the <tt>-m</tt> parameter or by a file with <tt>-F</tt> or <tt>--file</tt>. If you do neither of both, <tt>svn</tt> will run an editor to ask for a comment.

* TODO: improve this section
* TODO: better ask the user to modify the svn configuration files?

This editor is taken either from the svn configuration files or if not defined there from the environment variables: first <tt>$SVN_EDITOR</tt>, then <tt>$VISUAL</tt>, then <tt>$EDITOR</tt> depending which one is defined.

So maybe you should check your environment variables:
<syntaxhighlight lang="bash">
echo $SVN_EDITOR
echo $VISUAL
echo $EDITOR
</syntaxhighlight>

Check that their settings suit you for your work with svn. If they do not suit you, check your file {{path|~/.bashrc}} and add something like:
<syntaxhighlight lang="bash">export SVN_EDITOR=mcedit</syntaxhighlight>
Here it sets mcedit, replace it with your favorite editor. Of course you can set <tt>$EDITOR</tt> instead if you want to change the default editor for you.

Be careful that if you do not set a command line editor but one that needs X-Window, you will need to run svn always in a X-Window terminal. It might suit you, it might not. Your choice!

== Subversion Configuration ==

For proper of ''svn status'' and ''svn diff'' on KDE sources, you might want to follow the instructions from [http://developer.kde.org/documentation/other/developer-faq.html#q1.5.2 the developer FAQ] for setting up {{path|~/.subversion/config}}.

== Committing ==

Now a few words about how to commit.

First be sure that the code that you want to commit is right. If you are not certain about a patch, or have some doubts, consider perhaps sending your patch to the relevant mailing list or to the relevant developer if you know who he is.

Also when committing, please give a useful message with the commit. Think about what you would like to find in, say, two years. (One day, you will probably find out that meaningless commit entries like "Fix" or "Here too" are going to drive you crazy when you have to debug a problem.)

Good code is not always only about questions like: "Does the code compile?" The code must also fit in what is planned. For example if a new code fixes just one little bug but the maintainer of the code is currently doing a re-write, he will perhaps not be pleased that something has been committed, because he will have to fix all conflicts between the newly committed code and his new code.

So the best is to communicate (if possible early) to avoid any surprise. A surprised developer is highly at risk of giving a rude answer or at least not a pleasant answer. This is avoidable by communication. Of course, a developer might ask to leave the code alone. Please respect that! (Of course, it does not mean that you should not argue.)

== Commit-Digest ==

The [http://www.commit-digest.org KDE Commit-Digest] is a weekly overview of the commits to KDE's subversion server. Now that you have a SVN account, you will probably see your own name in there soon!

The digest features a small statistics section. To improve the accuracy of those, you should add some information, like age or country, about yourself, which you can do [http://commit-digest.org/data here].

== Commit-Filter ==
[http://commitfilter.kde.org/ Commit-Filter] is a service which allows you to monitor folders (or authors) in SVN for changes, and have each commit's diff emailed to you. This is very useful if you are interested in getting involved in a certain sub-project of KDE and want to keep up with its development.

Please use reply-to-all when responding to those emails.

== Links ==

; Subversion
: [[Getting_Started/Sources/Using_Subversion_with_KDE|Using Subversion with KDE]]

;i18n
:[[Development/Tutorials/Localization/i18n|What is i18n and how to use it]]

; I18N/L10N
: [http://developer.kde.org/documentation/library/kdeqt/kde3arch/kde-i18n-howto.html KDE Programmer's i18n howto]

Development/FAQs/General FAQ

2011-07-19T08:19:19Z

Aseigo:

{{Template:I18n/Language Navigation Bar|Development/FAQs/General FAQ}}
==I want to start this new application. What do you advise?==
We all agree that there are plenty of KDE applications that need to be written. But there are also a lot of existing kde applications that need your help.

To see the areas where help is needed, check [http://www.kde.org/jobs/ this page].

Before starting a new application, it's always a good idea to check [http://www.kde-apps.org/ KDE-Apps.org] for existing applications and to ask on the [https://mail.kde.org/mailman/listinfo/kde-devel kde-devel] mailing-list whether someone is already working on a similar project.

==I am a developer, how can I contribute to KDE?==
KOffice and KDevelop, despite being very praised, have very few developers, so you might check there. There is no need to be a KDE core-developer to help. KDE is very modular so you can perfectely improve one area without knowing how the whole system works.

You can also ask on [https://mail.kde.org/mailman/listinfo/kde-devel kde-devel] if someone needs help on an application.
Use the latest version of KDE and spot things that are needed. A theme generator? A konsole schema editor? Improve a game? There is always a small feature missing. Go and implement it!

Are you familiar or attracted with a specific field? See if there is a related application that could use your help. Or write one. KDE needs more non-geek oriented applications.

==I am not a developer, how can I help?==
There are plenty of tasks that don't require development skills. Write reviews of applications for the promoting of KDE (see the [https://mail.kde.org/mailman/listinfo/kde-promo kde-promo] mailing-list), help the documentation team (see [http://l10n.kde.org/docs/ i18n.kde.org/doc]), help the translations (see [http://l10n.kde.org/ i18n.kde.org]), help to filter the incoming bugs (see [https://bugs.kde.org/ bugs.kde.org]).

==Where can I find images of Konqi the dragon?==
The Konqi for some people SDK is at [ftp://ftp.kde.org/pub/kde/devel/konqi_sdk.tar.bz2 ftp.kde.org/pub/kde/devel/konqi_sdk.tar.bz2] 
It was posted to artist.kde.org before that site ceased to be updated.

Further images are on [http://kde.org/stuff/clipart.php KDE merchandise].

==What is the level required to contribute to KDE? What should I learn? What should I read?==
You need to know C++. Read the Qt tutorials and browse the Qt docs to get familiar with what's available with Qt. Then read the KDE tutorials and browse architecture and documentation. You can also read the KDE Book, it can not harm. But you don't have to be familiar with the whole KDE architecture to become a kde developer. Using kde's technologies is quite easy, so concentrate on what you really need, you can learn the other bits later on.
[http://techbase.kde.org KDE TechBase] and [http://doc.qt.nokia.com/ doc.qt.nokia.com] (also in your {{path|$QTDIR/doc/html}}) are invaluable resources, take advantage of them.
Then, browse the source, look for the examples directories, see how the other did code their applications. Reading and writing code is the best way to learn.

==How do I get KDE software from the KDE git or SVN repositories?==
See the "Building and Running KDE Software From Source" section on the [[Getting_Started]] page.

==Can I access KDE source code online?==
Yes
* Browse http://websvn.kde.org/ and https://projects.kde.org/
* Search the source code at http://lxr.kde.org/search
* Browse API docs generated from the source code at http://api.kde.org/

==What should I put in my .subversion/config?==
<syntaxhighlight lang="text">[miscellany]
global-ignores = *.moc *.moc.cc *.moc.cpp config.log config.status \
config.cache *.gmo .deps .libs SunWS_cache *.lo *.la *.rpo *.la.closure \
*_la_closure.cpp *_la_closure.cc *_la_closure.cxx *.all_cc.cc *.all_cpp.cpp \
*.all_C.C *.all_cxx.cxx *_meta_unload.cc *_meta_unload.h *_meta_unload.cpp \
*_meta_unload.C *_meta_unload.cxx index.cache.bz2 .memdump Makefile.rules.in \
Makefile.calls.in Makefile.rules Makefile.calls autom4te.cache *.kidl \
*.o *.lo *.la #*# .*.rej *.rej *.pyc</syntaxhighlight>
And to make svn diff ignore whitespace, and print function names:
<syntaxhighlight lang="text">[helpers]
diff-cmd = /usr/local/bin/_svndiff</syntaxhighlight>

with the following in {{path|/usr/local/bin/_svndiff}}:
<syntaxhighlight lang="text">#!/bin/sh
exec /usr/bin/diff -b -u -p "$@"</syntaxhighlight>

Don't forget to make {{path|/usr/local/bin/_svndiff}} executable.

==I want to put my app in KDE==
There are three requirements:
* your app must compile with the latest version of KDE (git master or SVN trunk).
* your app must be stable.
* your app must be maintained. You will probably get a good deal of bug reports and wishes. People expect you to fix the bugs and implement the wishes that make sense.
See also the next question.

==Is it better to develop inside or outside KDE?==
As core developer Waldo Bastian explains in a copyrighted mail:
----
:Being part of KDE means that you have to work together with others. Such cooperation brings along advantages but it also brings along responsibilities.
: 
:Some of those advantages are: your code ends up on all distro's, people might fix your bugs, you get free translations and documentation, you get tons of bugreports.
: 
:On the other side there are disadvantages and responsibilities: you will have to communicate with other developers about your work, other people might make changes to your code, you will have to respect release freezes, you get tons of bugreports and people actually expect that you fix them as well (what are they smoking?), people expect you to maintain your code.
: 
:You can't chose for the advantages and ignore the responsibilities that come with it, it's a complete package, it's both or nothing.
: 
:In general it should be the author of a piece of software that chooses to put his application in KDE's repositories. We usualy don't put software in KDE's repositories unless the author wishes to do so. The other way around, if the author prefers to work on his application elsewhere then that's his right as well. Unless there is a split in the actual group of people working on the application it makes no sense to fork the development of an application because of that.
: 
:'''BUT'''... by putting your code under and open source license and putting it in a KDE repository you give the world at large, as well as KDE in particular, the irrevocable right to use your code. And KDE will use that right at its discretion to protect the interests of KDE, even if that goes against the wishes of the author at that point in time.
----
It is important to know that but don't be afraid. Usually, things work very well. In 5 years, it has only happened once that a developer had his work put kept in KDE while he wanted to remove it.

==How do I get write access to KDE repositories?==
See full article at [[Contribute/Get_a_Contributor_Account|Contribute > Get a KDE Contributor Account]].

Go to [[http://identity.kde.org KDE Identity]] , fill out the form and describe why you need write access. Make sure to specify your full name and e-mail address.

Please also include the name of your bugs.kde.org account, if non-existent please create one so that it can be given usual developer rights. Closing bugs.kde.org reports with keywords in commit comments only works if the email address of your KDE Identity and bugs.kde.org accounts match. You can change your bugs.kde.org address in the Bugzilla user settings.

Git requires use of an ssh key, and new accounts for SVN must also choose the svn+ssh protocol. Send a public ssh key (e.g. {{path|~/.ssh/id_dsa.pub}})

See also [[#How do I create a SSH key?]]

If you are contributing to an application that is not yours, it is a good idea to first submitting your coding as patches to the author and let him apply them. If the author is not maintaining his application, you might become the new maintainer...

Although there are few restrictions on repository commit rights, we expect you not to distrupt other developers' code without their consent. You must also respect the feature freezes of the release schedule (published on developer.kde.org)

A detailed list of rules you should follow when committing to KDE repositories are listed in the [[/Policies/SVN_Commit_Policy|KDE Commit Policy]].

==My app is not stable but I would like to have it in KDE==
As a first step, we can put it in playground, which is essentially "kde-alpha". Develop it there and when it is ready, request that your app to be moved to the appropriate KDE package or the extragear module.

==I don't want to lose my SVN history.==
This is no longer possible with Subversion. Maybe in the future, if the server is upgraded and allows that. Note that for git this is not an issue.

==What is kdebindings?==
It contains Qt bindings for Ruby, PHP, C# to use Qt classes with those langages, KDE bindings for Ruby, C#, python to use KDE classes with those langages, and XParts to embed non-KDE apps as a KPart. Check the [[Development/Languages|binding page]] of TechBase.

==Does the feature freeze apply to playground?==
No, playground are not a released packages. The same is true for kdereview and extragear: they are not frozen and released. But if you want your app to move to a package, ask for it before the beta-release.

==Can I have a stable and an unstable KDE on the same computer?==
Yes, check the Building 2 Versions documentation.

==How do I know which version of Qt/KDE I am using?==

<tt>kde-config</tt> and all kde programs accept <tt>--version</tt> as argument.

==Qt-copy or Qt from qt.nokia.com : if one were doing a clean build of trunk, which would be preferable?==
You can use either. They are binary compatible (forward and backward). There can be, however, a few bugfixes in qt-copy over the most recent Qt release. Especially if building from qt-copy, pay attention to the apply-patches script.

==How can I checkout a single directory from a SVN module?==
Checkout the top-level dir with 'svn co -N /modulename', 'cd modulename', 'svn up admin' to get the admin/ dir and then finally checkout the dir you want with 'svn up subdir'

For instance, to get only reaktivate from playground/utils:
svn co -N /playground/utils; svn up reaktivate
Then compile as usual.

The same answer applies to the question "How do I get a single language out of kde-i18n?".

If you don't know the name of the directory you want to check out, you can browse websvn.kde.org to find it.

==How can I get one of the KDE application as a standalone tarball?==
kdesdk/scripts/svn2dist is a script to extract an application from the KDE source tree and package it as a standalone application.

==How do I close my own bug reports?==
If you reported a bug that is fixed in a new release of KDE but is still reported as open, you can close it. It might happen because your bug is the same as another one, or simply because the developer fixed something without noticing that it would correct your bug.

You can do that from your Subversion commit. To do so, append to your commit message a line like this:

<tt>BUG: XXXXX</tt> 
Where <tt>XXXXX</tt> is the bug report you want to close. If the report you're closing is adding a new feature, you can use FEATURE instead of BUG. 
Managing a bug list is a huge task for the developers and they usually have a lot of bugs listed, some being fixed already without their knowledge, some being unreproducible, some without enough information to be corrected, etc. If you can help by managing and updating the list of outstanding bugs, you will be gladly welcome. And you will receive an even happier welcome if you provide a patch.

==How do I create a SSH key?==
SSH makes use of two keys: a private key and a public key. You should keep the private key secret at all times and only place it on machines over which you have direct control. Public, shared, and community machines are not suitable environments to store SSH private keys. Take action to help prevent theft of your SSH private key data. Setting a password on your SSH private key will help reduce the risks involved with private key theft.

Generate a key pair for each major location you work from. This helps to reduce the impact when your key gets stolen.
When someone obtains access to your private key, your key can be abused in attempts to compromise KDE servers. Well known open source projects have been compromised this way in the past, YOU must help us to make sure that this doesn't happen with KDE servers as well. For that reason it is important to notify sysadmin (at) kde (dot) org immediately when you notice that someone may have had access to your private key for example when a computer on which it was stored has been hacked or infected with a virus, worm or trojan.

If you choose to make a backup of your SSH private key data, please ensure that any such backup is stored in a secure manner as well.

For the practical part, the following command can be used to generate a SSH private/public key pair with
ssh-keygen -t dsa
This will create a private key as {{path|~/.ssh/id_dsa}} and a public key as {{path|~/.ssh/id_dsa.pub}}.

There are times when you may want to use a key of a different name to the default, perhaps to use seperate keys for different projects. To let SSH know which key you want to use for KDE.org, you can keep a list of servers and their corresponding keys in ~/.ssh/config. For example,
Host svn.kde.org
IdentityFile ~/.ssh/id_dsa_kde
In order to use SSH to access KDE servers you need to send your public key to sysadmin (at) kde (dot) org.

==How can I monitor changes made by others?==
The [https://mail.kde.org/mailman/listinfo/kde-commits kde-commits] mailinglist carries automatic notifications for all changes made in the KDE repositories. The KDE-Commits mailinglist is very high traffic. An alternative is [http://commitfilter.kde.org/ CommitFilter] which allows you to get notification for only those areas that interest you.
[[Category:FAQs]]

Policies/Application Lifecycle

2011-07-19T08:10:06Z

Aseigo:

{{warning|This page is yet to be reviewed for changes required by the migration to Git. Information and commands on this page may no longer be valid and should be used with care. Please see the [[Development/Git|KDE Git hub page]] for more details. }}

When you want to start a new application (or remove an old application), you want to know where you should place it in the Subversion repository. This document describes where to go in which stage of your application.

See [[#Stage 3: The end]] for instructions on how to deal with old, unmaintained applications.

In a diagram it all comes down to:

[[Image:svnguidelines.png]]

=== Stage 1: The start ===
The start of a new application can take place on a local disk, in a local repository or any other way. Another option is provided by KDE in the special {{path|/trunk/playground}} folder in the repository where everyone is free to commit ones own application. You can [[Contribute/Get_a_Contributor_Account | request an KDE Contributor account]] and after that you can import your project in the subfolder of your choice. Applications in playground are organized in folders like KDE is itself. For example, games are in {{path|/trunk/playground/games}}. In each of these folders, there is a {{path|doc}} folder where you should put the docbook documentation of your application.

It is not meant as a backup area, so you should not develop your application somewhere else and only sync the changes now and then to KDE's repository.

As soon as you start releasing your software and match the criteria for the next stage, you should consider moving your application folder to the next stage. When doing this move, don't forget to move also its documentation folder.

Because playground is something like an 'experimental' area, there is only a small amount of applications that make it to the next stage. To keep the playground area accessible and a bit organized, we have created a {{path|/tag/unmaintained/N}} (where 'N' is the KDE major version the application was written for; e.g. 4 for KDE4 applications). If you do not want to continue your application, move it to that place in the repository. If you do not know how, contact the current contactperson which is mentioned at the bottom of this document.

Whenever an application has not received a commit for one complete year, you will be contacted via email to discuss if you want to continue the application or if it has died. In the latter case or when the email bounces, it will be moved to {{path|/tag/unmaintained/N/}}.

=== Stage 2: Stable ===
When you have made one of more releases and want to continue to develop it, the term 'playground' does no longer apply to you. That is the right time to move out of here. There are two options to move to: extragear and one of the KDE main modules. If you want to move to one of the KDE main modules, you will get released with KDE. That also means you have to respect that release schedule. The fact you want your program in KDE main modules is not enough and others have to agree is valuable to have it.
In extragear you are on your own. You make the releases whenever you want and you have to talk to the translators about your release schedule. In the future it might be possible to be released together with the KDE main modules. But at this moment this is not possible.

Whatever you choose, there are some rules to follow before you are allowed to move to either location:
* There should be user documentation in docbook format. If you need help, you can ask for help to the KDE Documentation team: [https://mail.kde.org/mailman/listinfo/kde-doc-english kde-doc-english@kde.org].
* There should be developers documentation in the form of apidox for libraries you can check this at [http://www.englishbreakfastnetwork.org/ ebn]
* There should be no krazy code checker issues reported. Again, you can check that at [http://www.englishbreakfastnetwork.org/ ebn]. There is also a [[Development/Tutorials/Code_Checking|tutorial on using Krazy]] available here on TechBase.
* If possible, there should have been a basic usability review of your application. Usability people are hard to get, so this is not crucial.
* You should have checked for basic problems with a profiler. I hope we will get a tutorial on how to do this soon
* Your application should be [[Development/Tutorials/Localization/i18n|completely translatable]].

When you decide you want to move to this second stage, use `svn mv` to move your application to {{path|/trunk/kdereview}} and announce the move on '''kde-core-devel@kde.org''' (no, project mailing lists are not good enough). In the announcement address the above issues and state where you want your application to move to (which KDE main module or extragear). Extragear only requires general approval on kde-core-devel. A main module requires approval from the community who manages that module (e.g. the kdepim module requires approval from the kdepim community). Don't forget to move the documentation of your application to {{path|/trunk/kdereview/doc}}. Some suggestions for reviewers to consider when reviewing new applications and library code are on [[Policies/Suggested_Review_Criteria]].

The move to kdereview starts a two week review period during which the community can object to your proposal or request additional changes. If there are no objections or requested changes after this two week period, you are allowed to move your application to the place you requested. If your intention is to move to a main module you must additionally get approval from the [[Projects/Release_Team#Module_Coordinators|module coordinator(s)]] who manage that module.

If changes are requested, you can leave your application in kdereview while you are actively working on those issues. If you lack the time to work on the changes, move your application back to playground. Once the requested changes are completed, announce to kde-core-devel that you have completed the requested changes and wait for another week for objections.

Kdereview is only meant as a transitional place from playground to the main modules or extrager. In no case can kdereview be a permanent place to develop your application.

=== Stage 3: The end ===
Whenever you decide to stop developing the application and that leaves the application without developers, please announce that to kde-core-devel. If nobody stands up to take over maintainership within two weeks, the application has to be moved to the {{path|/tags/unmaintained/N/}} area as every application in the KDE main modules and in extragear needs to have a maintainer to stay there.

=== Translations ===
For each move of code and documentation in subversion, the translation files of each language need to move as well. Because this requires a complete checkout of the l10n folder and some knowledge about the structure, you can ask the i18n team ('''kde-i18n-doc@kde.org''') to move them. Send a simple mail with the information required to do the move, for example: 'move {{path|/playground/somewhere/someapp}} to {{path|/kdereview/someapp}}'.
If you want to help out with these kinds of moves, please send a mail! You are welcome to help out.

=== Contact ===
If you need any help regarding this, please contact Tom Albers ('''tomalbers@kde.nl''')

[[Category:Policies]]

Contribute/Get a Contributor Account

2011-07-19T08:03:37Z

Aseigo: moved Contribute/Get a SVN Account to Contribute/Get a Contributor Account: SVN is no longer what we use, so make this more generic.

{{Template:I18n/Language Navigation Bar|Contribute/Get a SVN Account}}
This tutorial is about how to apply for a commit account for KDE so that you may change files (code, documentation files, art, etc.) in KDE's git and svn repositories.

== The short answer: how to get read-write access ==

KDE Contributor accounts are managed through [http://identity.kde.org/ KDE Identity]. You can request Developer Access in the website's menu upon registering and logging into your account.

== KDE Respositories ==

To have write access to KDE's git and SVN servers, you have to use KDE's main git and SVN server. Anonymous git and SVN uses mirrors of this server. Note that SVN does not allow you to read from one server and write to another, while git does. For a tutorial on using KDE's git services, see [[/Development/Git|this tutorial]].

To be able to write to files stored in KDE's git and SVN repositories, you need an account. An account is made up of a username (normally your family name), a password, an ssh key and an email address. The username is for getting in, the password and ssh keys are for authenticating and the email address for knowing who to contact if another developer wants to contact the account holder.

A KDE commit account allows you to write to nearly anywhere in the KDE repositories with a few exceptions, such as the www module. (Of course, exceptions can be made for this as well.)

'''Note''': you can see the accounts in [http://websvn.kde.org/trunk/kde-common/accounts kde-common/accounts]. That is the list of all accounts. Yes, '''the account list is public''', for example on [http://websvn.kde.org WebSVN].

== Who Can Apply For a KDE Contributor Account? ==

Normally, any developer who has done some work on projects hosted by KDE can apply for a KDE Contributor account.

Translators should get approval from their team leader so that they can organize how the work is being done in his/her team. Please mention the approval from the team leader when requesting the account.

Please also [[Policies/SVN Commit Policy|read the KDE commit policy]]. You must accept these rules when using your future KDE Contributor account. Please also familiarize yourself with the [http://www.kde.org/code-of-conduct/ KDE Code of Conduct] which describes the social foundations within KDE.

Also please apply for an account only if you think that you will work on KDE for a somewhat longer time. If you know that you will only work for a couple of weeks and then never again, please consider not applying for a KDE Contributor account but instead continue to send patches directly to developers.

The limitations are not there to exclude anyone - they are there to ensure that the maintenance of accounts remains reasonable.

Of course, to be clear: ''the KDE's sysadmins have the last word about whether or not to create a KDE SVN account for somebody''.

== SSH ==

You need an SSH public key in order to access your KDE Contributor account. If you already have one, you can skip the next subsection and go to [[#Setting up the SVN+SSH protocol|Setting up the SVN+SSH protocol]].

=== Generating the SSH keys ===

To be able to use your KDE Contributor account with SSH, you need a SSH public key. Please notice that it is '''not''' a GPG (OpenPGP) key, which is completely unrelated!

The password in the sense of this documentation is the '''public key''' that you are creating.

For more information on how to create a pair of SSH keys, please refer to a [http://www.openbsd.org/cgi-bin/man.cgi?query=ssh-keygen SSH documentation] or book.

The command to create a pair of keys is '''ssh-keygen''' and it requires the type of key you will create, either DSA or RSA - both are fine.

To create a new pair of keys, use <syntaxhighlight lang="bash">ssh-keygen -t dsa</syntaxhighlight> or <syntaxhighlight lang="bash">ssh-keygen -t rsa</syntaxhighlight>

There is also a type called RSA1 which was used in version 1 of the SSH protocol. See the [http://www.openbsd.org/cgi-bin/man.cgi?query=ssh-keygen ssh documentation] for more details.

You can then accept the default filename for your key (either {{path|$HOME/.ssh/id_dsa}} or {{path|$HOME/.ssh/id_rsa}}, depending on the type of key you have chosen). After that, a passphrase is asked. It is recommended that you do not leave it blank.

Now that you are finished generating your key pair, you will have two files: a private key and a public key. If you have accepted the default filename, they will be respectively {{path|$HOME/.ssh/id_dsa}} and {{path|$HOME/.ssh/id_dsa.pub}} or {{path|$HOME/.ssh/id_rsa}} and {{path|$HOME/.ssh/id_rsa.pub}}, depending on the type of key you have specified.

The private key '''must''' remain secret, do not publish it to anyone under any circumstance.

The public key can be published and shall be sent when you are applying for a KDE SVN account.

You should also set up <tt>ssh-agent</tt> so you do not have to type the password every time you connect via SSH. There are several tutorials available explaining how to do this, for example [http://mah.everybody.org/docs/ssh this one]. [http://www.gentoo.org/proj/en/keychain Keychain] is a program that makes this task easier.

'''Note''': if you already have an ssh key, you can just use the existing key instead of creating a new one.

{{tip|
If you want to use SVN with SSH with another user than the one who created the keys, you need to copy <tt>$HOME/.ssh/id_dsa.pub</tt> and <tt>$HOME/.ssh/id_dsa</tt> or <tt>$HOME/.ssh/id_rsa.pub</tt> and <tt>$HOME/.ssh/id_rsa</tt> to the other user's <tt>$HOME/.ssh</tt> directory.

You should probably also backup those files.
}}

=== Setting up the SVN+SSH protocol ===

Once you created your key, you'll have to tell SSH that this one should be used for all connections to KDE sites. For SVN access, add the following lines to the <tt>~/.ssh/config</tt> file. Replace USERNAME with yours.

<pre>
Host *.kde.org
User USERNAME
IdentityFile ~/.ssh/id_dsa
</pre>

The linked IdentityFile must belong to the public key you send in when applying for the SVN account. But it is ''not'' the public key (<tt>*.pub</tt>).

Note that git requires no such configuration.

== Apply for an account ==

Now you are ready to apply for for a KDE Contributor account. Go to [https://identity.kde.org/ https://identity.kde.org/svnaccount/] and create an account if you don't have one already. If you already have an account, you can use that. After you entered the site you will find a form which you can fill in to apply for an account.

When you register on identity.kde.org, you will need to enter your name and an e-mail address, which has to be your own (a normal address or a KDE Mail address). Of course, do not forget that '''this email address becomes public''' (at least by [http://websvn.kde.org WebSVN]) so you will unfortunately get some spam as a result.

Also note that this email address should be the same one that you use on [http://bugs.kde.org bugs.kde.org]. If you don't have an account in [http://bugs.kde.org bugs.kde.org], please create one so that it can be given usual developer rights. Closing bug reports with keywords in commit comments only works if the email address associated with your KDE Contributor account and [http://bugs.kde.org bugs.kde.org] accounts match.

After that, you must choose a username for your KDE Contributor account between the suggestions presented to you. Please notice it is not possible to propose something else such as a nickname, as the username must be as close as possible to someone's real name.

If you ask for a KDE email address one day, this will be the base for your address. For example: <tt>username@kde.org</tt>. (Note, however, that KDE email addresses are not granted so easily anymore, as too many people have ranted with a KDE address and other people thought that it was the official position of the KDE Team. In the meantime, [http://www.kdemail.net KDE Mail] was created for if you need a permanent address.)

When applying for developer access you have to provide your public SSH key. This key will be added to your profile. You can always add more keys or delete keys you don't use anymore from your profile page on identity.kde.org.

The form also holds a field ''Why do you want an account?'', where you can explain what you want to do with your future KDE SVN account, like for example developing a certain application, making documentations or being the team leader of a translation.

Also note that the form will ask you who has encouraged you to apply. He or she will also get an email to verify your request.

== Updating An Existing Account ==

If you already have a KDE Contributor account but want to update the ssh key, you should go to [https://identity.kde.org/ identity.kde.org] and change the keys in your profile.

== And Now? ==

After having sent the form and clicking the link in the email, you have to wait for the answer (typically within two or three days).

Once you have confirmation that your account has been created, you need to adapt your local copy to the new server. See the [[Contribute/First Steps with your KDE SVN Account|next tutorial]] for your first steps with your new account.

Please add your geographical location (what country are you in?) and other details at the [http://commit-digest.org/data/ Commit Digest data page] so that the Commit Digest can accurately reflect who is working where.

Talk:Contribute/Get a Contributor Account

2011-07-19T08:03:37Z

Aseigo: moved Talk:Contribute/Get a SVN Account to Talk:Contribute/Get a Contributor Account: SVN is no longer what we use, so make this more generic.

On OSX 10.5,

perl -e 'print crypt("pass","\$1\$xyz\$")."\n";'
-- $1dwWckNooiek

and

perl -e 'print crypt("pass","\$1\$abc\$")."\n";'
-- $1dwWckNooiek

They are the same...

[[Special:Contributions/98.235.188.137|98.235.188.137]] 16:08, 22 November 2008 (UTC)

Contribute/Get a SVN Account

2011-07-19T08:03:37Z

Aseigo: moved Contribute/Get a SVN Account to Contribute/Get a Contributor Account: SVN is no longer what we use, so make this more generic.

#REDIRECT [[Contribute/Get a Contributor Account]]

Talk:Contribute/Get a SVN Account

2011-07-19T08:03:37Z

Aseigo: moved Talk:Contribute/Get a SVN Account to Talk:Contribute/Get a Contributor Account: SVN is no longer what we use, so make this more generic.

#REDIRECT [[Talk:Contribute/Get a Contributor Account]]

Contribute/Get a Contributor Account

2011-07-19T08:02:08Z

Aseigo:

Development/Tutorials/Plasma/ApplicationShell

2011-07-13T10:37:22Z

Aseigo: /* The Shell */

This page looks at the steps it takes to embed a Plasma shell inside of your application as a dashboard or summary page.

== The Shell ==
The core of the dashboard's logic is in a KPart in kdebase-runtime called '''plasma-kpart'''. This KPart is loaded like any other ReadOnly KPart:
<pre>
// this routine will find and load our Part. it finds the Part by
// name which is a bad idea usually.. but it's alright in this
// case since our Part is made for this Shell
KService::Ptr service = KService::serviceByDesktopPath( "plasma-kpart.desktop" );

if (service) {
// now that the Part is loaded, we cast it to a Part to get
// our hands on it
m_part = service->createInstance<KParts::ReadOnlyPart>(0, args);
if (m_part) {
// tell the KParts::MainWindow that this is indeed the main widget
// If you have something better to do with the widget, this is where
// you would do it.
setCentralWidget(m_part->widget());

// and integrate the part's GUI with the shell's
createGUI(m_part);

} else {
// For whatever reason the part didn't load
KMessageBox::error(this, i18n("Could not instantiate our Part!"));
qApp->quit();
}
} else {
// if we couldn't find our Part, we exit since the Shell by
// itself can't do anything useful
KMessageBox::error(this, i18n("Could not find our Part!"));
qApp->quit();
// we return here, cause qApp->quit() only means "exit the
// next time we enter the event loop...
return;
}
</pre>

== The Applets ==
There are two ways to approach writing applets, and some thought should go into this before writing your applets.

=== Plasma::Applet-based applets ===
The first is to use the standard method of writing Plasma applets, and provide a DataEngine which your applets can use to communicate with your application, either via DBus (allowing you to use the applets on the desktop and in other shells) or intra-process signal/slots using a DataEngine provided by the [[#Communicating With Your Application|PluginLoader infrastructure]].
* Pros:
** Applets can be scripted in Javascript or Python
** Applets get all of the For Free benefits of being subclasses of Plasma::Applet
* Cons:
** Requires writing applets from scratch

=== QWidget-based Applets ===
The second method is to wrap QWidgets inside of a Plasma::Applet using a QGraphicsProxyWidget. This is most useful if your application has an existing dashboard which is not based on Plasma. These widgets would be created within your application, and loaded using the [[#Communicating With Your Application|PluginLoader infrastructure]].
* Pros:
** No need to learn a new API to build widgets
** Closer integration with applications
** Can re-use pre-existing applets
* Cons:
** No Plasma theming
** No access to DataEngines and other Plasma services

== Communicating With Your Application ==
New in KDE Development Platform 4.6 is a class called Plasma::PluginLoader, a class which contains, unsurprisingly, most of Plasma's plugin loading logic. Plasma::Applet, Plasma::DataEngine, Plasma::Service, and Plasma::AbstractRunner all ask Plasma::PluginLoader to provide these plugins for them, and Plasma::PluginLoader can be subclassed for use by your application.
Plasma::PluginLoader itself is a class with a mix of normal methods, static methods and protected virtual methods:
* Plasma::* load* -- The main loading methods which are called by their respective classes in libplasma.
* static void setPluginLoader() and static Plasma::PluginLoader* pluginLoader() -- These are the setters and getters of the application-specific subclass of Plasma::PluginLoader.
* protected virtual internal* -- These are the methods which application-specific subclasses of Plasma::PluginLoader will implement. Their non-virtual counterparts call the application-specific implementations of these methods that are in the Plasma::PluginLoader specified by the application in setPluginLoader.

The long and short of this is that application developers can inject their own Applets, DataEngines, Services and other Plasma objects into a Plasma shell and allow them to do things which plugins loaded through KDE's Plugin system could not do. Users of Plasma::PluginLoader also get many things for free, such as the easy loading and saving of applets, which would have to be done manually if an application chose to only use Plasma::Containment::addApplet().

All that a developer needs to do is to subclass Plasma::PluginLoader and implement the internalAdd* methods which they want to provide plugins for.

See [http://quickgit.kde.org/?p=kdeexamples.git&a=tree&h=c974192b5d47aa475e8fd0677c6ee8fdafe49158&hb=4459b79a52c3228a8a92ad2f169d406c244966da&f=plasma/c%20%20/kpart kdeexamples/plasma/c++/kpart] for an example of these communication methods.

Development/Tutorials/Plasma/ApplicationShell

2011-07-13T10:36:48Z

Aseigo: /* The Shell */

This page looks at the steps it takes to embed a Plasma shell inside of your application as a dashboard or summary page.

== The Shell ==
The core of the dashboard's logic is in a KPart in kdebase-runtime called '''plasma-kpart'''. This KPart is loaded like any other ReadOnly KPart:
<pre>
// this routine will find and load our Part. it finds the Part by
// name which is a bad idea usually.. but it's alright in this
// case since our Part is made for this Shell
KService::Ptr service = KService::serviceByDesktopPath( "plasma-kpart.desktop" );

if (service)
{
// now that the Part is loaded, we cast it to a Part to get
// our hands on it
m_part = service->createInstance<KParts::ReadOnlyPart>(0, args);
if (m_part)
{
// tell the KParts::MainWindow that this is indeed the main widget
// If you have something better to do with the widget, this is where
// you would do it.
setCentralWidget(m_part->widget());

// and integrate the part's GUI with the shell's
createGUI(m_part);

}
else
{
// For whatever reason the part didn't load
KMessageBox::error(this, i18n("Could not instantiate our Part!"));
qApp->quit();
}
}
else
{
// if we couldn't find our Part, we exit since the Shell by
// itself can't do anything useful
KMessageBox::error(this, i18n("Could not find our Part!"));
qApp->quit();
// we return here, cause qApp->quit() only means "exit the
// next time we enter the event loop...
return;
}
</pre>

== The Applets ==
There are two ways to approach writing applets, and some thought should go into this before writing your applets.

=== Plasma::Applet-based applets ===
The first is to use the standard method of writing Plasma applets, and provide a DataEngine which your applets can use to communicate with your application, either via DBus (allowing you to use the applets on the desktop and in other shells) or intra-process signal/slots using a DataEngine provided by the [[#Communicating With Your Application|PluginLoader infrastructure]].
* Pros:
** Applets can be scripted in Javascript or Python
** Applets get all of the For Free benefits of being subclasses of Plasma::Applet
* Cons:
** Requires writing applets from scratch

=== QWidget-based Applets ===
The second method is to wrap QWidgets inside of a Plasma::Applet using a QGraphicsProxyWidget. This is most useful if your application has an existing dashboard which is not based on Plasma. These widgets would be created within your application, and loaded using the [[#Communicating With Your Application|PluginLoader infrastructure]].
* Pros:
** No need to learn a new API to build widgets
** Closer integration with applications
** Can re-use pre-existing applets
* Cons:
** No Plasma theming
** No access to DataEngines and other Plasma services

== Communicating With Your Application ==
New in KDE Development Platform 4.6 is a class called Plasma::PluginLoader, a class which contains, unsurprisingly, most of Plasma's plugin loading logic. Plasma::Applet, Plasma::DataEngine, Plasma::Service, and Plasma::AbstractRunner all ask Plasma::PluginLoader to provide these plugins for them, and Plasma::PluginLoader can be subclassed for use by your application.
Plasma::PluginLoader itself is a class with a mix of normal methods, static methods and protected virtual methods:
* Plasma::* load* -- The main loading methods which are called by their respective classes in libplasma.
* static void setPluginLoader() and static Plasma::PluginLoader* pluginLoader() -- These are the setters and getters of the application-specific subclass of Plasma::PluginLoader.
* protected virtual internal* -- These are the methods which application-specific subclasses of Plasma::PluginLoader will implement. Their non-virtual counterparts call the application-specific implementations of these methods that are in the Plasma::PluginLoader specified by the application in setPluginLoader.

The long and short of this is that application developers can inject their own Applets, DataEngines, Services and other Plasma objects into a Plasma shell and allow them to do things which plugins loaded through KDE's Plugin system could not do. Users of Plasma::PluginLoader also get many things for free, such as the easy loading and saving of applets, which would have to be done manually if an application chose to only use Plasma::Containment::addApplet().

All that a developer needs to do is to subclass Plasma::PluginLoader and implement the internalAdd* methods which they want to provide plugins for.

See [http://quickgit.kde.org/?p=kdeexamples.git&a=tree&h=c974192b5d47aa475e8fd0677c6ee8fdafe49158&hb=4459b79a52c3228a8a92ad2f169d406c244966da&f=plasma/c%20%20/kpart kdeexamples/plasma/c++/kpart] for an example of these communication methods.

Development/Tutorials/Plasma/JavaScript/API

2011-06-24T12:37:53Z

Aseigo:

Development/Tutorials/Plasma/JavaScript/API

2011-06-24T12:25:20Z

Aseigo: /* API */

Development/Tutorials/Plasma/JavaScript/API-LaunchApp

2011-06-24T12:24:10Z

Aseigo: Created page with '= LaunchApp = This Extension adds methods to the global plasmoid object that allow launching applications, running commands and opening files and urls. * ...'

= LaunchApp =

This [[../API-Extensions|Extension]] adds methods to the global plasmoid object that allow launching applications, running commands and opening files and urls.

* ''bool'' '''runApplication(string application[, array files])''' Runs an application by name (can reference an installed .desktop file as well as an executable in the user's $PATH) with an optional array of files. The file array may contain either Urls or strings. Returns true on success, false on failure.
* ''bool'' '''runCommand(string exe[, array args])''' Runs the executable with the given arguments. Returns true on success, false on failure.
* ''bool'' '''openUrl([string|Url] url)''': Opens the url in the default application (or asks the user if there is no default application for the file). The url parameter may be either a string or a Url. Returns true on success, false on failure.
* ''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.
* ''String'' '''applicationPath(String name)''': (scripting version >= 4) returns the full local path to a given application or .desktop file if it exists.

Development/Tutorials/Plasma/JavaScript/API-HTTP

2011-06-24T12:24:02Z

Aseigo: Created page with '= HTTP = This Extension provides access to data and files via http and https using asynchronous IOJob objects. Functions: * ''IOJob'' ''...'

= HTTP =

This [[../API-Extensions|Extension]] provides access to data and files via http and https using asynchronous [[../API-IOJobs|IOJob]] objects.

Functions:
* ''IOJob'' '''getUrl(Url url)''': attempts to fetch the file using an IOJob
* ''IOJob'' '''getUrl(String url)''': attempts to fetch the file using an IOJob
* ''bool'' '''openUrl([string|Url] url)''': (API v4) Opens the url in the default application (or asks the user if there is no default application for the file). The url parameter may be either a string or a Url. Returns true on success, false on failure.

Development/Tutorials/Plasma/JavaScript/API-NetworkIO

2011-06-24T12:23:39Z

Aseigo: Created page with ' = NetworkIO = This Extension provides access to data over the network using asynchronous IOJob objects. Functions: * ''IOJob'' '''getUr...'

= NetworkIO =
This [[../API-Extensions|Extension]] provides access to data over the network using asynchronous [[../API-IOJobs|IOJob]] objects.

Functions:
* ''IOJob'' '''getUrl(Url url)''': attempts to fetch the file using an IOJob
* ''IOJob'' '''getUrl(String url)''': attempts to fetch the file using an IOJob

Development/Tutorials/Plasma/JavaScript/API-LocalIO

2011-06-24T12:23:17Z

Aseigo: /* LocalIO */

= LocalIO =
This [[../API-Extensions|Extension]] provides access to local files using asynchronous [[../API-IOJobs|IOJob]] objects.

Functions:
* ''IOJob'' '''getUrl(Url url)''': attempts to fetch the file using an IOJob
* ''IOJob'' '''getUrl(String url)''': attempts to fetch the file using an IOJob
* ''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
** music
** video
** downloads
** pictures
** autostart
** desktop (should be considered deprecated for Plasma workspaces)

If a second string is passed in, it is considered a request for a specific path and the following types are recognized:
** apps - Applications menu (.desktop files).
** autostart - Autostart directories (both XDG and kde-specific)
** cache - Cached information (e.g. favicons, web-pages)
** cgi - CGIs to run from kdehelp.
** config - Configuration files.
** data - Where applications store data.
** emoticons - Emoticons themes
** exe - Executables in $prefix/bin. findExe() for a function that takes $PATH into account.
** html - HTML documentation.
** icon - Icons, see KIconLoader.
** kcfg - KConfigXT config files.
** lib - Libraries.
** locale - Translation files for KLocale.
** mime - Mime types defined by KDE-specific .desktop files.
** module - Module (dynamically loaded library).
** qtplugins - Qt plugins (dynamically loaded objects for Qt)
** services - Services.
** servicetypes - Service types.
** sound - Application sounds.
** templates - Templates for the "Create new file" functionality.
** wallpaper - Wallpapers.
** tmp - Temporary files (specific for both current host and current user)
** socket - UNIX Sockets (specific for both current host and current user)
** xdgconf-menu - Freedesktop.org standard location for menu layout (.menu) files.
** xdgdata-apps - Freedesktop.org standard location for application desktop files.
** xdgdata-dirs - Freedesktop.org standard location for menu descriptions (.directory files).
** xdgdata-mime - Freedesktop.org standard location for MIME type definitions.
** xdgdata-icon - Freedesktop.org standard location for icons.
** xdgdata-pixmap - Gnome-compatibility location for pixmaps.

The second parameter should be a specific resource to find the path to. An example might be userDataPath("data", "plasma-desktop").

Development/Tutorials/Plasma/JavaScript/API-LocalIO

2011-06-24T12:21:59Z

Aseigo: Created page with ' = LocalIO = This Extension provides access to local files. Functions: * ''IOJob'' '''getUrl(Url url)''': attempts to fetch the file using an IOJob * ''I...'

= LocalIO =
This [[../API-Extensions|Extension]] provides access to local files.

Functions:
* ''IOJob'' '''getUrl(Url url)''': attempts to fetch the file using an IOJob
* ''IOJob'' '''getUrl(String url)''': attempts to fetch the file using an IOJob
* ''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
** music
** video
** downloads
** pictures
** autostart
** desktop (should be considered deprecated for Plasma workspaces)

If a second string is passed in, it is considered a request for a specific path and the following types are recognized:
** apps - Applications menu (.desktop files).
** autostart - Autostart directories (both XDG and kde-specific)
** cache - Cached information (e.g. favicons, web-pages)
** cgi - CGIs to run from kdehelp.
** config - Configuration files.
** data - Where applications store data.
** emoticons - Emoticons themes
** exe - Executables in $prefix/bin. findExe() for a function that takes $PATH into account.
** html - HTML documentation.
** icon - Icons, see KIconLoader.
** kcfg - KConfigXT config files.
** lib - Libraries.
** locale - Translation files for KLocale.
** mime - Mime types defined by KDE-specific .desktop files.
** module - Module (dynamically loaded library).
** qtplugins - Qt plugins (dynamically loaded objects for Qt)
** services - Services.
** servicetypes - Service types.
** sound - Application sounds.
** templates - Templates for the "Create new file" functionality.
** wallpaper - Wallpapers.
** tmp - Temporary files (specific for both current host and current user)
** socket - UNIX Sockets (specific for both current host and current user)
** xdgconf-menu - Freedesktop.org standard location for menu layout (.menu) files.
** xdgdata-apps - Freedesktop.org standard location for application desktop files.
** xdgdata-dirs - Freedesktop.org standard location for menu descriptions (.directory files).
** xdgdata-mime - Freedesktop.org standard location for MIME type definitions.
** xdgdata-icon - Freedesktop.org standard location for icons.
** xdgdata-pixmap - Gnome-compatibility location for pixmaps.

The second parameter should be a specific resource to find the path to. An example might be userDataPath("data", "plasma-desktop").

Development/Tutorials/Plasma/JavaScript/API-Extensions

2011-06-24T12:21:29Z

Aseigo: Created page with '== Using Extensions == An API extension is a security controlled set of functions and objects that are loaded on demand. These extensions are requested by the widget by listing t...'

== Using Extensions ==
An API extension is a security controlled set of functions and objects that are loaded on demand. These extensions are requested by the widget by listing the required and the optional extensions (if any) it wants loaded in its metadata.desktop file. This way, even prior to the widget being loaded, Plasma can know what it will want.

Required extensions are requested using the X-Plasma-RequiredExtensions key, and optional extensions with the X-Plasma-OptionalExtensions. For example:

<code ini>
X-Plasma-RequiredExtensions=FileDialog,MyCustomQScriptExtension
X-Plasma-OptionalExtensions=LaunchApp,HTTP
</code>

The Simplified Javascript Engine then decides if the widget will actually get that extension or not. Failure to load a required extension will result in script execution being aborted.

== Available Extensions ==

* [[../API-FileDialog|File Dialog]]
* [[../API-LocalIO|Local IO]]
* [[../API-NetworkIO|Network IO]]
* [[../API-HTTP|HTTP]]
* [[../API-LaunchApp|Launching Applications]]

Development/Tutorials/Plasma/JavaScript/API

2011-06-24T12:21:08Z

Aseigo:

Development/Tutorials/Plasma/JavaScript/API-FileDialog

2011-06-24T12:19:12Z

Aseigo: Created page with '= FileDialog = This Extension provides access to open and save dialog classes: OpenFileDialog and SaveFileDialog. Both are non-modal and run asynchronously...'

= FileDialog =

This [[../API-Extensions|Extension]] provides access to open and save dialog classes: OpenFileDialog and SaveFileDialog. Both are non-modal and run asynchronously, so the signals must be used. Other than the name difference (and resulting UI variance) the API for each is identical:

* Constructors
** '''OpenFileDialog'''
** '''SaveFileDialog'''
* Properties
** Read Only
*** ''array(Url)'' '''urls''': the selected file, as a Url object
*** ''Url'' '''baseUrl''', the current path (minus filename) as a Url
*** ''string '''file''': the selected file, as a string
*** ''array(string)'' '''files''': selected files (plural), as an array of strings
** Read/Write
*** ''Url'' '''url''': the current Url, can be read from when the user is done or assigned before to set the starting path
*** ''string'' '''filter''': a string representing the mimetype filter; e.g. "*.cpp|C++ Source Files\n*.h|Header files" or "*.cpp" or "*.cpp|*h"
*** ''boolean'' '''localOnly''': true to show only local files, false if network locations are Ok as well
*** ''boolean'' '''directoriesOnly''': true to only allow selection of a directory (not a file)
*** ''boolean'' '''existingOnly''': true if only existing files/directories may be selected
* Functions
** '''show()''': when called, the dialog will be shown to the user
* Signals
** '''accepted(FileDialogProxy)'''': emitted when the file dialog has been successfully accepted by the user with one or more files/directories.
** '''finished(FileDialogProxy)''': emitted when the file dialog closes, included when cancelled/closed without being accepted

Development/Tutorials/Plasma/JavaScript/API-Addons

2011-06-24T12:15:53Z

Aseigo: /* Addons (API V3) */

== Addons (API V3) ==
Plasmoids may also have plugins of their own, also written in Javascript, and which are shipped separately to the Plasmoid. These are referred to as "Addons" and are packaged similarly to a Plasmoid. For more information on creating Javascript Addons, visit the [[.Development/Plasma/JavascriptAddons|Javascript Addons tutorial]].

It is possible to list, load and be notified of new Addons having been installed for your Plasmoid.

* ''Array[AddonInformation]'' '''listAddons(string type)''': an array of available addons of the provided type. The type name maps to the X-KDE-PluginInfo-Category entry in the Addon's metadata.desktop file.
* ''boolean'' '''loadAddon(String type, String id)''': load the addon with the given id and type, return true on success. In order to be notified when the addon is successfully created, add an event listener to the "addCreated" event.

The following are the Addon events which are recognized by the Plasmoid along with the type of event objects (if any) that are passed to registered event listeners that are registered with addEventListener:

* addonCreated: Object addOn
* newAddonsAvaiable

= AddonInformation (API V3) =

The AddonInformation object contains the following read-only properties:

* ''String'' '''id''': the id of the Addon. Can be used with loadAddon
* ''String'' '''name''': a string suitable for showing the user, such as in a configuration dialog

Development/Tutorials/Plasma/JavaScript/API-Addons

2011-06-24T12:14:34Z

Aseigo: Created page with '== Addons (API V3) == Plasmoids may also have plugins of their own, also written in Javascript, and which are shipped separately to the Plasmoid. These are referred to as "Addons...'

== Addons (API V3) ==
Plasmoids may also have plugins of their own, also written in Javascript, and which are shipped separately to the Plasmoid. These are referred to as "Addons" and are packaged similarly to a Plasmoid. For more information on creating Javascript Addons, visit the [[/JavascriptAddons|Javascript Addons tutorial]].

It is possible to list, load and be notified of new Addons having been installed for your Plasmoid.

* ''Array[AddonInformation]'' '''listAddons(string type)''': an array of available addons of the provided type. The type name maps to the X-KDE-PluginInfo-Category entry in the Addon's metadata.desktop file.
* ''boolean'' '''loadAddon(String type, String id)''': load the addon with the given id and type, return true on success. In order to be notified when the addon is successfully created, add an event listener to the "addCreated" event.

The following are the Addon events which are recognized by the Plasmoid along with the type of event objects (if any) that are passed to registered event listeners that are registered with addEventListener:

* addonCreated: Object addOn
* newAddonsAvaiable

= AddonInformation (API V3) =

The AddonInformation object contains the following read-only properties:

* ''String'' '''id''': the id of the Addon. Can be used with loadAddon
* ''String'' '''name''': a string suitable for showing the user, such as in a configuration dialog

Development/Tutorials/Plasma/JavaScript/API

2011-06-24T12:10:54Z

Aseigo:

Development/Tutorials/Plasma/JavaScript/API-Misc

2011-06-24T12:10:38Z

Aseigo: Created page with '= Url = Represents a local or remote address. To create a new Url (or assign to an existing one), use the following syntax: <code javascript>var url = new Url("http://kde.org")<...'

= Url =
Represents a local or remote address. To create a new Url (or assign to an existing one), use the following syntax:

<code javascript>var url = new Url("http://kde.org")</code>

Read-only properties:
* ''string'' '''toString''': the URL as a String object

Read-write properties (each representing a portion of the full URL):
* ''string'' '''protocol'''
* ''string'' '''host'''
* ''string'' '''path'''
* ''string'' '''user'''
* ''string'' '''password'''

= ByteArray =
This class provides an array of bytes. This is often used by data centric objects, such as the Job classes returned by getUrl.

Read-only properties:
* ''number'' '''length''': the size of the array (number of bytes)

Functions:
* '''chop(number numBytes)''': chops numBytes from the end of the array
* ''bool'' '''equals(ByteArray other)'''
* ''ByteArray '''left(number len)''': return len bytes from the left of the array
* ''ByteArray '''mid(number pos, number len)''': returns an array of bytes starting a post and length len (if len is -1, it returns all remaining bytes)
* ''ByteArray '''remove(number pos, number len)''': removes len bytes starting at index pos from the array and returns it
* ''ByteArray '''right(number len)''': returns len bytes from the right of the array
* ''ByteArray '''simplified()''': returns a byte array that has whitespace removed from the start and the end, and which has each sequence of internal whitespace replaced with a single space
* ''ByteArray '''toBase64()''': returns the array encoded in base64
* ''ByteArray '''toLower()''': returns a lowercased copy of the array
* ''ByteArray '''toUpper()''': returns an uppercased copy of the array
* ''ByteArray '''trimmed()''': returns a copy of the array with whitespace remove from the start and end
* truncate(number pos): truncates the array at index pos
* ''String'' '''toLatin1String()''': returns a Latin1-ized string based on the array
* ''String'' '''toUtf8()''': (API v3) returns a string from the contents of the array using a Utf8 conversation
* ''String'' '''valueOf()''': returns the raw data in the array as a string

= GraphicsItem =
This class represents an item on the canvas. Support is only provided so that GraphicsItem objects returned or taken by other objects work. There is no meaningful API provided directly in the JavaScript runtime for these objects and they should not need to be used directly.

= QSizePolicy =
The QSizePolicy class is a layout attribute describing horizontal and vertical resizing policy. This can be set on any graphics widget that you have using the enums provided for this (QtSizePolicy ), for example:

button = new PushButton();
button.sizePolicy = QSizePolicy(QSizePolicyMaximum, QSizePolicyFixed);

This is useful when your widgets are being laid out by a layout (specially the anchor layout).

* ''QtSizePolicy '' '''horizontalPolicy''': The horizontal component of the size policy.
* ''QtSizePolicy '' '''verticalPolicy''': The vertical component of the size policy.
* ''number'' '''horizontalStretch''': The horizontal stretch factor of the size policy.
* ''number'' '''verticalStretch''': The vertical stretch factor of the size policy.

Development/Tutorials/Plasma/JavaScript/API-Timers

2011-06-24T12:10:00Z

Aseigo: Created page with '= QTimer = Read-write properties: * ''boolean'' '''active''': true if active, false if not * ''boolean'' '''singleShot''': true if the timer will fire once when started, false i...'

= QTimer =

Read-write properties:
* ''boolean'' '''active''': true if active, false if not
* ''boolean'' '''singleShot''': true if the timer will fire once when started, false if it will fire repeatedly until stopped
* ''boolean'' '''interval''': the interval in milliseconds that the timer will trigger

Functions:
* '''start(int msec)''': starts the timer with msec as the interval
* '''start()''': starts the timer with the default interval
* '''stop()''': stops the timer

Signals:
* '''timeout()''': this signal is emitted whenever the timer interval is reached

Development/Tutorials/Plasma/JavaScript/API-IOJobs

2011-06-24T12:09:20Z

Aseigo: Created page with '= IOJob = This object is returned by input/output access for asynchronous file and data access (see the section on Extensions for documentation on getUrl). It is used by connect...'

= IOJob =

This object is returned by input/output access for asynchronous file and data access (see the section on Extensions for documentation on getUrl). It is used by connecting Javascript functions in your code to the relevant signals.

Functions:
* '''kill()'''
* '''suspend()'''
* '''resume()'''

Signals:
* '''data(IOJob job, ByteArray data)''': emitted whenever data arrives. If data is empty (data.length == 0) then the transmission has completed.
* '''dataReq(IOJob job, ByteArray data)''': when sending data, this signal is emitted when data is requested; add the data to be sent ot the data member, or leave it empty to signal that the process is complete and there is no more data to send
* '''finished(IOJob job)''': emitted when the transmission has completed
* '''suspended(IOJob job)''': emitted when the job has been suspeneded
* '''resumed(IOJob job)'''
* '''canceled(IOJob job)'''
* '''connected(IOJob job)'''
* '''redirection(IOJob job, Url to)'''
* '''permanentRedirection(IOJob job, Url from, Url to)'''
* '''mimetype(IOJob job, String mimetype)'''

Development/Tutorials/Plasma/JavaScript/API-Print

2011-06-24T12:08:54Z

Aseigo: Created page with '= Print and Debug = * '''print(string message)''': prints message to console * '''debug(string message)''': print message to console if it is running in a KDE debug build'

= Print and Debug =

* '''print(string message)''': prints message to console
* '''debug(string message)''': print message to console if it is running in a KDE debug build

Development/Tutorials/Plasma/JavaScript/API-DataEnginesServices

2011-06-24T12:05:32Z

Aseigo: Created page with 'DataEngines and Services provide access to various types of data and the ability to interact with them via asynchronous services with a convenient and consistent API. See the [[D...'

DataEngines and Services provide access to various types of data and the ability to interact with them via asynchronous services with a convenient and consistent API. See the [[Development/Tutorials/Plasma/JavaScript/DataEngine|JavaScript Plasmoid DataEngine tutorials]] for examples on how to use DataEngines and Services in your Plasmoids.

= Global Functions to Access DataEngines and Services =
* dataEngine(string name): returns a DataEngine object
* service(string dataEngineName, string sourceName): returns a ServiceObject, see also DataEngine::serviceForSource

= DataEngine =
Read-only properties:
* ''Array[String]'' '''sources'''
* ''boolean'' '''valid'''
* ''String'' '''icon'''
* ''String'' '''name'''

Signals:
* '''sourceAdded(String sourceName)'''
* '''sourceRemoved(String sourceName)'''

Functions:
* '''serviceForSource(String sourceName)'''
* '''connectSource(String sourceName, Object connectTo[, number interval[, IntervalAlignment alignment] ])''': if the object passed in as the object to connect to is the plasmoid object, then the plasmoid.dataUpdated(String source, Map[String, Any] data) callback will be called if it exists
* '''connectAllSources(Object connectTo[, number interval[, IntervalAlignment alignment] ])''': if the object passed in as the object to connect to is the plasmoid object, then the plasmoid.dataUpdated(String source, Map[String, Any] data) callback will be called if it exists
* '''disconnectSource(String sourceName, Object connectedTo)''': if the object passed in as the object to connect to is the plasmoid object, then the plasmoid.dataUpdated(String source, Map[String, Any] data) callback will be called if it exists
* '''Data query(String sourceName)'''

The following functions are only of interest to DataEngine reimplementations (e.g. JavaScript DataEngines):

* '''scheduleSourcesUpdated()'''
* '''removeSource(String)'''
* '''updateAllSources()'''
* '''forceImmediateUpdateOfAllVisualizations()'''
* '''DataContainer containerForSource(String)'''

= Service =
* function finished(Plasma::ServiceJob*)
* function operationsChanged()
* function serviceReady(Plasma::Service*)
* function setDestination(QString)
* function destination()
* function operationNames()
* function operationDescription(QString)
* function startOperationCall(KConfigGroup,QObject*)
* function startOperationCall(KConfigGroup)
* function isOperationEnabled(QString)
* function name()
* function associateWidget(QWidget*,QString)
* function disassociateWidget(QWidget*)
* function associateWidget(QGraphicsWidget*,QString)
* function disassociateWidget(QGraphicsWidget*)
* function parametersFromDescription(KConfigGroup)

Development/Tutorials/Plasma/JavaScript/API

2011-06-24T12:02:51Z

Aseigo:

Development/Tutorials/Plasma/JavaScript/API-Painting

2011-06-24T12:00:47Z

Aseigo: /* Pixmaps */

= Painting =

See the "[[../API-PlasmoidObject|Painting and Layout]]" section, part of the Global Plasmoid object chapter, for information on using these classes within a widget.

= Pixmaps =

The QPixmap object allows widgets to use pixmaps for painting. Widgets may include pixmaps in various common formats (PNG, JPEG, GIF, etc.) in the contents/images/ directory of the Plasmoid package and load them by passing the name of the file into the pixmap constructor:
<code javascript>
var pixmap = new QPixmap("myimage.png")
</code>
In addition to being used as a file load, some objects return or take pixmaps and the QPixmap object facilitates that as well.

Read-only properties:
* ''boolean'' '''null''': true if the pixmap is empty
* ''QRectF'' '''rect''': the rect of the pixmap

Functions:
* ''QPixmap'' '''scaled(number width, number height): returns a scaled version of the pixmap with width and height dimensions.

= Icons =

(Since 4.4.1)

The QIcon object provides simple access to icons. They can be constructed using a String or a QPixmap, with the String version either loading a file from disk if given an absolute path (useful for loading icons from the Plasmoid's package) or from the desktop icon theme if given just a name (e.g. "file-open").

Read-only properties:
* ''boolean'' '''null''': true if the icon is empty

Functions:
* '''addPixmap(QPixmap)''': adds another pixmap to this icon
* '''addFile(String)''': adds another file to this icon

= SVG Images =

Plasma makes heavy usage of SVG images. More information on this industry standard scalable vector format can be found here:

:http://www.w3.org/Graphics/SVG/

Free and Open Source Software tools for creating SVGs include Inkscape and Karbon13. Widgets may include their own SVG files in the contents/images/ directory or may use SVG images that are part of the standard Plasma Desktop Theme as documented here:

:http://techbase.kde.org/Projects/Plasma/Theme

Two classes are provide: Svg and FrameSvg. Svg allows loading and painting entire SVG documents or individual elements in an SVG document. FrameSvg extends Svg with methods to paint bordered frames from specially crafted SVG documents (see the Plasma Desktop Theme documentation for more information on this).

==Svg==
Constructors:
*'''Svg(string fileName)'''': fileName can be a file in the desktop theme or the plasmoid package

Read-only properties:
*''QSizeF'' '''size''': the current size of the svg

Read-write properties:
* ''boolean'' '''multipleImages''': whether or not the svg contains multiple separate images
* ''string'' '''imagePath''': the file path, including name of the svg
* ''boolean'' '''usingRenderingCache'': whether or not to cache rendered pixmaps; improves performance (at the cost of some disk and memory usage) for SVG data that is repeatedly rendered

Functions:
* ''QSizeF'' elementSize(String svgElemen)'''
* ''QRectF'' elementRect(String svgElemen)'''
* ''boolean'' '''hasElement(String svgElement)'''
* '''elementAtPoint(QPoint pos)'''
* ''boolean'' '''isValid()'''
* ''QPixmap'' '''pixmap(String svgElement)''': a pixmap of the element in the svg rendered to the current size
* ''QPixmap'' '''pixmap()''': a pixmap of the entire svg rendered to the current size
* '''paint(QPainter painter, QPointF point)'''
* '''paint(QPainter painter, QPointF point, String svgElement)'''
* '''paint(QPainter painter, number x, number y)'''
* '''paint(QPainter painter, number x, number y, String svgElement)'''
* '''paint(QPainter painter, QRectF destination)'''
* '''paint(QPainter painter, QRectF destination, String svgElement)'''
* '''paint(QPainter painter, number y, number width, number height)'''
* '''paint(QPainter painter, number x, number y, number width, number height, QString svgElement)'''
* '''resize(number width, number height)
* '''resize(QSizeF size)'''
* '''resize()''': resizes the SVG to the document size defined in the SVG itself

Signals:
* '''repaintNeeded()''': emitted when the SVG is in need of a repaint, such as when the theme changes and the SVG has reloaded its data

==FrameSvg==
Constructors:
* '''FrameSvg(String fileName)''': fileName can be a file in the desktop theme or the plasmoid package

Read-only properties:
* ''boolean'' '''multipleImages''': whether or not the svg contains multiple separate images

Functions:
* '''setEnabledBorders(EnabledBorders borders)''': sets which borders are enabled when painting
* ''EnabledBorders'' '''enabledBorders()''': the borders which are enabled when painting
* '''resizeFrame(QSizeF size)''': resizes the frame to size
* ''QSizeF'' '''frameSize()''': the size of the current frame
* ''number'' '''marginSize(MarginEdge margin)''': the size of the margin for a given edge
* '''getMargins(number left, number top, number right, number bottom)''': stores the margin values in the variables passed in
* ''QRectF'' '''contentsRect()''': the rect containing the contents, e.g. the size of the SVG minus the space required by the enabled borders
* '''setElementPrefix(Location)''': sets the frame element for the given location if it exists
* '''setElementPrefix(String prefix)''': sets the element prefix
* ''boolean'' '''hasElementPrefix(String prefix)''': returns true if the SVG contains a frame with the given prefix
* ''boolean'' '''hasElementPrefix(Location location)''': true if the SVG contains a frame element for the given location
* '''prefix()'''
* '''mask()'''
* '''setCacheAllRenderedFrames(bool)'''
* '''cacheAllRenderedFrames()'''
* ''QPixmap'' '''framePixmap()''': a pixmap containing the current frame at the current size
* '''paintFrame(QPainter painter)'''
* '''paintFrame(QPainter painter, QPointF target)'''
* '''paintFrame(QPainter painter, QRectF target)'''
* '''paintFrame(QPainter painter, QRectF target, QRectF source)'''

Enumerations
* '''EnabledBorder'''
** NoBorder
** TopBorder
** BottomBorder
** LeftBorder
** RightBorder
** AllBorders

= Painting on the Canvas =

== QColor ==

*Constructors:
** QColor
** QColor(string colorName)
** QColor(number red, number green, number blue, number alpha)

Functions:
* '''setThemeColor(ThemeColor color)''': sets the color to the appropriate ThemeColor

Read/write properties:
* ''number'' '''red'''
* ''number'' '''green'''
* ''number'' '''blue'''
* ''number'' '''alpha'''
* ''boolean'' '''valid'''

== QFont ==

*Constructors:
**QFont
**QFont(string fontName)
**QFont(string fontName, number pointSize)
**QFont(string fontName, number pointSize, number weight)
**QFont(string fontName, number pointSize, number weight, boolean italic)
*string key
*string lastResortFamily
*string lastResortFont
*string defaultFamily
*boolean exactMatch
*string toString
*boolean bold
*string family
*boolean fixedPitch
*undefined fromString
*boolean italic
*boolean kerning
*boolean overline
*number pixelSize
*number pointSize
*number pointSizeF
*boolean strikeOut
*number stretch
*boolean underline
*number weight
*function isCopyOf
*function resolve

==QPainter ==
* Constructors
** QPainter
** QPainter(object paintDevice): used to start a painter on a specific QWidget; rarely if ever needed in a JavaScript Plasmoid
* object background
* number backgroundMode
* object brush
* undefined setBrush
* object brushOrigin
* undefined clipping
* object clipPath
* object clipRegion
* number compositionMode
* object font
* number layoutDirection
* number opacity
* object pen
* number renderHints
* undefined transform
* object viewport
* boolean viewTransformEnabled
* object window
* object worldMatrix
* object worldTransform
* boolean worldMatrixEnabled
* object combinedMatrix
* object combinedTransform
* boolean active
* function begin
* function end
* function boundingRect
* function drawChord
* function drawConvexPolygon
* function drawArc
* function drawEllipse
* function drawImage
* function drawLine
* function drawLines
* function drawPath
* function drawPicture
* function drawPie
* function drawPixmap
* function drawPoint
* function drawPoints
* function drawPolygon
* function drawPolyline
* function drawRect
* function drawRects
* function drawRoundRect
* function drawText
* function drawTiledPixmap
* function eraseRect
* function fillPath
* function fillRect
* function resetMatrix
* function resetTransform
* function restore
* function rotate
* function save
* function scale
* function setClipRect
* function setRenderHint
* function shear
* function strokePath
* function testRenderHint
* function toString
* function translate

== QPen ==
*Constructors:
**QPen
* object brush
* object color
* number capStyle
* number joinStyle
* number style
* number dashOffset
* number miterLimit
* number width
* boolean solid
* number red
* number green
* number blue
* number alpha
* boolean valid

== QRectF ==
Read-only properties:
* ''boolean'' '''empty''': true if the rectangle's width or height is less than, or equal to, 0; an empty rectangle is also invalid
* ''boolean'' '''null''': true if the rectangle has both the width and the height set to 0; a null rectangle is also empty and not valid
* ''boolean'' '''valid''': true if the rectangle has a width > 0 and height 0.

Read-write properties:
* ''number'' '''left'''
* ''number'' '''top'''
* ''number'' '''bottom'''
* ''number'' '''right'''
* ''number'' '''height'''
* ''number'' '''width'''
* ''number'' '''x'''
* ''number'' '''y'''

Constructors:
* '''QRectF'''
* '''QRectF(number x, number y, number width, number height)''': Sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.

Functions:
* '''adjust(number dx1, number dy1, number dx2, number dy2)''': adds dx1, dy1, dx2 and dy2 respectively to the existing coordinates of the rectangle
* ''QRectF'' '''adjusted(number dx1, number dy1, number dx2, number dy2)''': returns a new QRectF with dx1, dy1, dx2 and dy2 added respectively to the existing coordinates of the rectangle
* '''translate(number dx, number dy)''': translates the rect by dx, dy
* '''setCoords(number x1, number y1, number x2, number y2)''': sets the coordinates of the rectangle's top-left corner to (x1, y1), and the coordinates of its bottom-right corner to (x2, y2).
* '''setRect(number x, number y, number width, number height)''': sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.
* ''boolean'' '''contains(number x, number y)''': returns true if the rect contains the point (x, y)
* '''moveBottom(number delta)'': moves the bottom by delta pixels
* '''moveLeft(number delta)''': moves the left by delta pixels
* '''moveRight(number delta)''': moves the right by delta pixels
* '''moveTo(number x, number y)''': moves the top left of the rect to point (x, y)
* '''moveTop(number delta)''': moves the top by delta pixels

== QSizeF ==

*Constructors:
**QSizeF
**QSizeF(number width, number height)
*number height
*number width

== QPoint ==

Constructors:
* '''QPoint'''
* '''QPoint(number x, number y)'''

Read-only properties:
* ''bool'' '''null'''
* ''number'' '''manhattanLength '''

Read-write propertie:
* ''number'' '''x '''
* ''number'' '''y'''

Development/Tutorials/Plasma/JavaScript/API-Painting

2011-06-24T12:00:38Z

Aseigo: /* Painting */

= Painting =

See the "[[../API-PlasmoidObject|Painting and Layout]]" section, part of the Global Plasmoid object chapter, for information on using these classes within a widget.

= Pixmaps =

The QPixmap object allows widgets to use pixmaps for painting. Widgets may include pixmaps in various common formats (PNG, JPEG, GIF, etc.) in the contents/images/ directory of the Plasmoid package and load them by passing the name of the file into the pixmap constructor:
<code javascript>
var pixmap = new QPixmap("myimage.png")
</code>
In addition to being used as a file load, some objects return or take pixmaps and the QPixmap object facilitates that as well.

Read-only properties:
* ''boolean'' '''null''': true if the pixmap is empty
* ''QRectF'' '''rect''': the rect of the pixmap

Functions:
* ''QPixmap'' '''scaled(number width, number height);;: returns a scaled version of the pixmap with width and height dimensions.

= Icons =

(Since 4.4.1)

The QIcon object provides simple access to icons. They can be constructed using a String or a QPixmap, with the String version either loading a file from disk if given an absolute path (useful for loading icons from the Plasmoid's package) or from the desktop icon theme if given just a name (e.g. "file-open").

Read-only properties:
* ''boolean'' '''null''': true if the icon is empty

Functions:
* '''addPixmap(QPixmap)''': adds another pixmap to this icon
* '''addFile(String)''': adds another file to this icon

= SVG Images =

Plasma makes heavy usage of SVG images. More information on this industry standard scalable vector format can be found here:

:http://www.w3.org/Graphics/SVG/

Free and Open Source Software tools for creating SVGs include Inkscape and Karbon13. Widgets may include their own SVG files in the contents/images/ directory or may use SVG images that are part of the standard Plasma Desktop Theme as documented here:

:http://techbase.kde.org/Projects/Plasma/Theme

Two classes are provide: Svg and FrameSvg. Svg allows loading and painting entire SVG documents or individual elements in an SVG document. FrameSvg extends Svg with methods to paint bordered frames from specially crafted SVG documents (see the Plasma Desktop Theme documentation for more information on this).

==Svg==
Constructors:
*'''Svg(string fileName)'''': fileName can be a file in the desktop theme or the plasmoid package

Read-only properties:
*''QSizeF'' '''size''': the current size of the svg

Read-write properties:
* ''boolean'' '''multipleImages''': whether or not the svg contains multiple separate images
* ''string'' '''imagePath''': the file path, including name of the svg
* ''boolean'' '''usingRenderingCache'': whether or not to cache rendered pixmaps; improves performance (at the cost of some disk and memory usage) for SVG data that is repeatedly rendered

Functions:
* ''QSizeF'' elementSize(String svgElemen)'''
* ''QRectF'' elementRect(String svgElemen)'''
* ''boolean'' '''hasElement(String svgElement)'''
* '''elementAtPoint(QPoint pos)'''
* ''boolean'' '''isValid()'''
* ''QPixmap'' '''pixmap(String svgElement)''': a pixmap of the element in the svg rendered to the current size
* ''QPixmap'' '''pixmap()''': a pixmap of the entire svg rendered to the current size
* '''paint(QPainter painter, QPointF point)'''
* '''paint(QPainter painter, QPointF point, String svgElement)'''
* '''paint(QPainter painter, number x, number y)'''
* '''paint(QPainter painter, number x, number y, String svgElement)'''
* '''paint(QPainter painter, QRectF destination)'''
* '''paint(QPainter painter, QRectF destination, String svgElement)'''
* '''paint(QPainter painter, number y, number width, number height)'''
* '''paint(QPainter painter, number x, number y, number width, number height, QString svgElement)'''
* '''resize(number width, number height)
* '''resize(QSizeF size)'''
* '''resize()''': resizes the SVG to the document size defined in the SVG itself

Signals:
* '''repaintNeeded()''': emitted when the SVG is in need of a repaint, such as when the theme changes and the SVG has reloaded its data

==FrameSvg==
Constructors:
* '''FrameSvg(String fileName)''': fileName can be a file in the desktop theme or the plasmoid package

Read-only properties:
* ''boolean'' '''multipleImages''': whether or not the svg contains multiple separate images

Functions:
* '''setEnabledBorders(EnabledBorders borders)''': sets which borders are enabled when painting
* ''EnabledBorders'' '''enabledBorders()''': the borders which are enabled when painting
* '''resizeFrame(QSizeF size)''': resizes the frame to size
* ''QSizeF'' '''frameSize()''': the size of the current frame
* ''number'' '''marginSize(MarginEdge margin)''': the size of the margin for a given edge
* '''getMargins(number left, number top, number right, number bottom)''': stores the margin values in the variables passed in
* ''QRectF'' '''contentsRect()''': the rect containing the contents, e.g. the size of the SVG minus the space required by the enabled borders
* '''setElementPrefix(Location)''': sets the frame element for the given location if it exists
* '''setElementPrefix(String prefix)''': sets the element prefix
* ''boolean'' '''hasElementPrefix(String prefix)''': returns true if the SVG contains a frame with the given prefix
* ''boolean'' '''hasElementPrefix(Location location)''': true if the SVG contains a frame element for the given location
* '''prefix()'''
* '''mask()'''
* '''setCacheAllRenderedFrames(bool)'''
* '''cacheAllRenderedFrames()'''
* ''QPixmap'' '''framePixmap()''': a pixmap containing the current frame at the current size
* '''paintFrame(QPainter painter)'''
* '''paintFrame(QPainter painter, QPointF target)'''
* '''paintFrame(QPainter painter, QRectF target)'''
* '''paintFrame(QPainter painter, QRectF target, QRectF source)'''

Enumerations
* '''EnabledBorder'''
** NoBorder
** TopBorder
** BottomBorder
** LeftBorder
** RightBorder
** AllBorders

= Painting on the Canvas =

== QColor ==

*Constructors:
** QColor
** QColor(string colorName)
** QColor(number red, number green, number blue, number alpha)

Functions:
* '''setThemeColor(ThemeColor color)''': sets the color to the appropriate ThemeColor

Read/write properties:
* ''number'' '''red'''
* ''number'' '''green'''
* ''number'' '''blue'''
* ''number'' '''alpha'''
* ''boolean'' '''valid'''

== QFont ==

*Constructors:
**QFont
**QFont(string fontName)
**QFont(string fontName, number pointSize)
**QFont(string fontName, number pointSize, number weight)
**QFont(string fontName, number pointSize, number weight, boolean italic)
*string key
*string lastResortFamily
*string lastResortFont
*string defaultFamily
*boolean exactMatch
*string toString
*boolean bold
*string family
*boolean fixedPitch
*undefined fromString
*boolean italic
*boolean kerning
*boolean overline
*number pixelSize
*number pointSize
*number pointSizeF
*boolean strikeOut
*number stretch
*boolean underline
*number weight
*function isCopyOf
*function resolve

==QPainter ==
* Constructors
** QPainter
** QPainter(object paintDevice): used to start a painter on a specific QWidget; rarely if ever needed in a JavaScript Plasmoid
* object background
* number backgroundMode
* object brush
* undefined setBrush
* object brushOrigin
* undefined clipping
* object clipPath
* object clipRegion
* number compositionMode
* object font
* number layoutDirection
* number opacity
* object pen
* number renderHints
* undefined transform
* object viewport
* boolean viewTransformEnabled
* object window
* object worldMatrix
* object worldTransform
* boolean worldMatrixEnabled
* object combinedMatrix
* object combinedTransform
* boolean active
* function begin
* function end
* function boundingRect
* function drawChord
* function drawConvexPolygon
* function drawArc
* function drawEllipse
* function drawImage
* function drawLine
* function drawLines
* function drawPath
* function drawPicture
* function drawPie
* function drawPixmap
* function drawPoint
* function drawPoints
* function drawPolygon
* function drawPolyline
* function drawRect
* function drawRects
* function drawRoundRect
* function drawText
* function drawTiledPixmap
* function eraseRect
* function fillPath
* function fillRect
* function resetMatrix
* function resetTransform
* function restore
* function rotate
* function save
* function scale
* function setClipRect
* function setRenderHint
* function shear
* function strokePath
* function testRenderHint
* function toString
* function translate

== QPen ==
*Constructors:
**QPen
* object brush
* object color
* number capStyle
* number joinStyle
* number style
* number dashOffset
* number miterLimit
* number width
* boolean solid
* number red
* number green
* number blue
* number alpha
* boolean valid

== QRectF ==
Read-only properties:
* ''boolean'' '''empty''': true if the rectangle's width or height is less than, or equal to, 0; an empty rectangle is also invalid
* ''boolean'' '''null''': true if the rectangle has both the width and the height set to 0; a null rectangle is also empty and not valid
* ''boolean'' '''valid''': true if the rectangle has a width > 0 and height 0.

Read-write properties:
* ''number'' '''left'''
* ''number'' '''top'''
* ''number'' '''bottom'''
* ''number'' '''right'''
* ''number'' '''height'''
* ''number'' '''width'''
* ''number'' '''x'''
* ''number'' '''y'''

Constructors:
* '''QRectF'''
* '''QRectF(number x, number y, number width, number height)''': Sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.

Functions:
* '''adjust(number dx1, number dy1, number dx2, number dy2)''': adds dx1, dy1, dx2 and dy2 respectively to the existing coordinates of the rectangle
* ''QRectF'' '''adjusted(number dx1, number dy1, number dx2, number dy2)''': returns a new QRectF with dx1, dy1, dx2 and dy2 added respectively to the existing coordinates of the rectangle
* '''translate(number dx, number dy)''': translates the rect by dx, dy
* '''setCoords(number x1, number y1, number x2, number y2)''': sets the coordinates of the rectangle's top-left corner to (x1, y1), and the coordinates of its bottom-right corner to (x2, y2).
* '''setRect(number x, number y, number width, number height)''': sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.
* ''boolean'' '''contains(number x, number y)''': returns true if the rect contains the point (x, y)
* '''moveBottom(number delta)'': moves the bottom by delta pixels
* '''moveLeft(number delta)''': moves the left by delta pixels
* '''moveRight(number delta)''': moves the right by delta pixels
* '''moveTo(number x, number y)''': moves the top left of the rect to point (x, y)
* '''moveTop(number delta)''': moves the top by delta pixels

== QSizeF ==

*Constructors:
**QSizeF
**QSizeF(number width, number height)
*number height
*number width

== QPoint ==

Constructors:
* '''QPoint'''
* '''QPoint(number x, number y)'''

Read-only properties:
* ''bool'' '''null'''
* ''number'' '''manhattanLength '''

Read-write propertie:
* ''number'' '''x '''
* ''number'' '''y'''

Development/Tutorials/Plasma/JavaScript/API-Painting

2011-06-24T11:59:29Z

Aseigo: Created page with ' == Painting == See the "Painting and Layout" section, part of the Global Plasmoid object chapter, for infor...'

== Painting ==

See the "[[Development/Tutorials/Plasma/JavaScript/API#Painting_and_Layout|Painting and Layout]]" section, part of the Global Plasmoid object chapter, for information on using these classes within a widget.

= Pixmaps =

The QPixmap object allows widgets to use pixmaps for painting. Widgets may include pixmaps in various common formats (PNG, JPEG, GIF, etc.) in the contents/images/ directory of the Plasmoid package and load them by passing the name of the file into the pixmap constructor:
<code javascript>
var pixmap = new QPixmap("myimage.png")
</code>
In addition to being used as a file load, some objects return or take pixmaps and the QPixmap object facilitates that as well.

Read-only properties:
* ''boolean'' '''null''': true if the pixmap is empty
* ''QRectF'' '''rect''': the rect of the pixmap

Functions:
* ''QPixmap'' '''scaled(number width, number height);;: returns a scaled version of the pixmap with width and height dimensions.

= Icons =

(Since 4.4.1)

The QIcon object provides simple access to icons. They can be constructed using a String or a QPixmap, with the String version either loading a file from disk if given an absolute path (useful for loading icons from the Plasmoid's package) or from the desktop icon theme if given just a name (e.g. "file-open").

Read-only properties:
* ''boolean'' '''null''': true if the icon is empty

Functions:
* '''addPixmap(QPixmap)''': adds another pixmap to this icon
* '''addFile(String)''': adds another file to this icon

= SVG Images =

Plasma makes heavy usage of SVG images. More information on this industry standard scalable vector format can be found here:

:http://www.w3.org/Graphics/SVG/

Free and Open Source Software tools for creating SVGs include Inkscape and Karbon13. Widgets may include their own SVG files in the contents/images/ directory or may use SVG images that are part of the standard Plasma Desktop Theme as documented here:

:http://techbase.kde.org/Projects/Plasma/Theme

Two classes are provide: Svg and FrameSvg. Svg allows loading and painting entire SVG documents or individual elements in an SVG document. FrameSvg extends Svg with methods to paint bordered frames from specially crafted SVG documents (see the Plasma Desktop Theme documentation for more information on this).

==Svg==
Constructors:
*'''Svg(string fileName)'''': fileName can be a file in the desktop theme or the plasmoid package

Read-only properties:
*''QSizeF'' '''size''': the current size of the svg

Read-write properties:
* ''boolean'' '''multipleImages''': whether or not the svg contains multiple separate images
* ''string'' '''imagePath''': the file path, including name of the svg
* ''boolean'' '''usingRenderingCache'': whether or not to cache rendered pixmaps; improves performance (at the cost of some disk and memory usage) for SVG data that is repeatedly rendered

Functions:
* ''QSizeF'' elementSize(String svgElemen)'''
* ''QRectF'' elementRect(String svgElemen)'''
* ''boolean'' '''hasElement(String svgElement)'''
* '''elementAtPoint(QPoint pos)'''
* ''boolean'' '''isValid()'''
* ''QPixmap'' '''pixmap(String svgElement)''': a pixmap of the element in the svg rendered to the current size
* ''QPixmap'' '''pixmap()''': a pixmap of the entire svg rendered to the current size
* '''paint(QPainter painter, QPointF point)'''
* '''paint(QPainter painter, QPointF point, String svgElement)'''
* '''paint(QPainter painter, number x, number y)'''
* '''paint(QPainter painter, number x, number y, String svgElement)'''
* '''paint(QPainter painter, QRectF destination)'''
* '''paint(QPainter painter, QRectF destination, String svgElement)'''
* '''paint(QPainter painter, number y, number width, number height)'''
* '''paint(QPainter painter, number x, number y, number width, number height, QString svgElement)'''
* '''resize(number width, number height)
* '''resize(QSizeF size)'''
* '''resize()''': resizes the SVG to the document size defined in the SVG itself

Signals:
* '''repaintNeeded()''': emitted when the SVG is in need of a repaint, such as when the theme changes and the SVG has reloaded its data

==FrameSvg==
Constructors:
* '''FrameSvg(String fileName)''': fileName can be a file in the desktop theme or the plasmoid package

Read-only properties:
* ''boolean'' '''multipleImages''': whether or not the svg contains multiple separate images

Functions:
* '''setEnabledBorders(EnabledBorders borders)''': sets which borders are enabled when painting
* ''EnabledBorders'' '''enabledBorders()''': the borders which are enabled when painting
* '''resizeFrame(QSizeF size)''': resizes the frame to size
* ''QSizeF'' '''frameSize()''': the size of the current frame
* ''number'' '''marginSize(MarginEdge margin)''': the size of the margin for a given edge
* '''getMargins(number left, number top, number right, number bottom)''': stores the margin values in the variables passed in
* ''QRectF'' '''contentsRect()''': the rect containing the contents, e.g. the size of the SVG minus the space required by the enabled borders
* '''setElementPrefix(Location)''': sets the frame element for the given location if it exists
* '''setElementPrefix(String prefix)''': sets the element prefix
* ''boolean'' '''hasElementPrefix(String prefix)''': returns true if the SVG contains a frame with the given prefix
* ''boolean'' '''hasElementPrefix(Location location)''': true if the SVG contains a frame element for the given location
* '''prefix()'''
* '''mask()'''
* '''setCacheAllRenderedFrames(bool)'''
* '''cacheAllRenderedFrames()'''
* ''QPixmap'' '''framePixmap()''': a pixmap containing the current frame at the current size
* '''paintFrame(QPainter painter)'''
* '''paintFrame(QPainter painter, QPointF target)'''
* '''paintFrame(QPainter painter, QRectF target)'''
* '''paintFrame(QPainter painter, QRectF target, QRectF source)'''

Enumerations
* '''EnabledBorder'''
** NoBorder
** TopBorder
** BottomBorder
** LeftBorder
** RightBorder
** AllBorders

= Painting on the Canvas =

== QColor ==

*Constructors:
** QColor
** QColor(string colorName)
** QColor(number red, number green, number blue, number alpha)

Functions:
* '''setThemeColor(ThemeColor color)''': sets the color to the appropriate ThemeColor

Read/write properties:
* ''number'' '''red'''
* ''number'' '''green'''
* ''number'' '''blue'''
* ''number'' '''alpha'''
* ''boolean'' '''valid'''

== QFont ==

*Constructors:
**QFont
**QFont(string fontName)
**QFont(string fontName, number pointSize)
**QFont(string fontName, number pointSize, number weight)
**QFont(string fontName, number pointSize, number weight, boolean italic)
*string key
*string lastResortFamily
*string lastResortFont
*string defaultFamily
*boolean exactMatch
*string toString
*boolean bold
*string family
*boolean fixedPitch
*undefined fromString
*boolean italic
*boolean kerning
*boolean overline
*number pixelSize
*number pointSize
*number pointSizeF
*boolean strikeOut
*number stretch
*boolean underline
*number weight
*function isCopyOf
*function resolve

==QPainter ==
* Constructors
** QPainter
** QPainter(object paintDevice): used to start a painter on a specific QWidget; rarely if ever needed in a JavaScript Plasmoid
* object background
* number backgroundMode
* object brush
* undefined setBrush
* object brushOrigin
* undefined clipping
* object clipPath
* object clipRegion
* number compositionMode
* object font
* number layoutDirection
* number opacity
* object pen
* number renderHints
* undefined transform
* object viewport
* boolean viewTransformEnabled
* object window
* object worldMatrix
* object worldTransform
* boolean worldMatrixEnabled
* object combinedMatrix
* object combinedTransform
* boolean active
* function begin
* function end
* function boundingRect
* function drawChord
* function drawConvexPolygon
* function drawArc
* function drawEllipse
* function drawImage
* function drawLine
* function drawLines
* function drawPath
* function drawPicture
* function drawPie
* function drawPixmap
* function drawPoint
* function drawPoints
* function drawPolygon
* function drawPolyline
* function drawRect
* function drawRects
* function drawRoundRect
* function drawText
* function drawTiledPixmap
* function eraseRect
* function fillPath
* function fillRect
* function resetMatrix
* function resetTransform
* function restore
* function rotate
* function save
* function scale
* function setClipRect
* function setRenderHint
* function shear
* function strokePath
* function testRenderHint
* function toString
* function translate

== QPen ==
*Constructors:
**QPen
* object brush
* object color
* number capStyle
* number joinStyle
* number style
* number dashOffset
* number miterLimit
* number width
* boolean solid
* number red
* number green
* number blue
* number alpha
* boolean valid

== QRectF ==
Read-only properties:
* ''boolean'' '''empty''': true if the rectangle's width or height is less than, or equal to, 0; an empty rectangle is also invalid
* ''boolean'' '''null''': true if the rectangle has both the width and the height set to 0; a null rectangle is also empty and not valid
* ''boolean'' '''valid''': true if the rectangle has a width > 0 and height 0.

Read-write properties:
* ''number'' '''left'''
* ''number'' '''top'''
* ''number'' '''bottom'''
* ''number'' '''right'''
* ''number'' '''height'''
* ''number'' '''width'''
* ''number'' '''x'''
* ''number'' '''y'''

Constructors:
* '''QRectF'''
* '''QRectF(number x, number y, number width, number height)''': Sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.

Functions:
* '''adjust(number dx1, number dy1, number dx2, number dy2)''': adds dx1, dy1, dx2 and dy2 respectively to the existing coordinates of the rectangle
* ''QRectF'' '''adjusted(number dx1, number dy1, number dx2, number dy2)''': returns a new QRectF with dx1, dy1, dx2 and dy2 added respectively to the existing coordinates of the rectangle
* '''translate(number dx, number dy)''': translates the rect by dx, dy
* '''setCoords(number x1, number y1, number x2, number y2)''': sets the coordinates of the rectangle's top-left corner to (x1, y1), and the coordinates of its bottom-right corner to (x2, y2).
* '''setRect(number x, number y, number width, number height)''': sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.
* ''boolean'' '''contains(number x, number y)''': returns true if the rect contains the point (x, y)
* '''moveBottom(number delta)'': moves the bottom by delta pixels
* '''moveLeft(number delta)''': moves the left by delta pixels
* '''moveRight(number delta)''': moves the right by delta pixels
* '''moveTo(number x, number y)''': moves the top left of the rect to point (x, y)
* '''moveTop(number delta)''': moves the top by delta pixels

== QSizeF ==

*Constructors:
**QSizeF
**QSizeF(number width, number height)
*number height
*number width

== QPoint ==

Constructors:
* '''QPoint'''
* '''QPoint(number x, number y)'''

Read-only properties:
* ''bool'' '''null'''
* ''number'' '''manhattanLength '''

Read-write propertie:
* ''number'' '''x '''
* ''number'' '''y'''

Development/Tutorials/Plasma/JavaScript/API-Animations

2011-06-24T11:58:28Z

Aseigo: Created page with '== Animations == = Creating Animation Objects = An Animation object can be retrieved by calling the ''Animation'' '''animation(string type)''' function. The ''string'' correspon...'

== Animations ==

= Creating Animation Objects =
An Animation object can be retrieved by calling the ''Animation'' '''animation(string type)''' function. The ''string'' corresponds to the type of animation, which are listed below.

New Animation objects are associated with (and therefore will animate) the Plasmoid by default. By setting the widgetToAnimate property, however, it can be assigned to animate any QGraphicsWidget desired (e.g. Plasma widgets such as push buttons, sliders, etc) .

= Enumerations =
All Animation objects have the following enumerations:

== MovementDirection ==
* '''MoveUp'''
* '''MoveUpRight'''
* '''MoveRight'''
* '''MoveDownRight'''
* '''MoveDown'''
* '''MoveDownLeft'''
* '''MoveLeft'''
* '''MoveUpLeft'''

== Reference ==
The reference point, relative to the target widget, for the animation.
* '''Center'''
* '''Up'''
* '''Down'''
* '''Left'''
* '''Right'''

== State ==
* '''Paused'''
* '''Running'''
* '''Stopped'''

= Common API =
With the exception of Pause and Property animations, all animations support the following read/write properties:

* ''AnimationDirection'' '''direction''': the direction the animation should play: AnimationForward or AnimationBackward
* ''int'' '''duration''': length of the animation in ms.
* ''EasingCurveType'' '''easingCurveType''': The easing curve to use in the animation
* ''QGraphicsWidget'' '''targetWidget''': the QGraphicsWidget (e.g. a Plasma::Widget) that this animation should operate on

= Animation Groups =
Animations may be put into groups for convenient sequential or parallel running. Sequential groups, where the animations run one after the other, are handled by the '''AnimationGroup''' class. Parallel aniations, where the animations run simultaneously, are handled the '''ParallelAnimationGroup''' class.

Animations are added to a group by calling '''add(Animation)''' on the group object. Groups may also be added to other groups.

= Custom Animations =
Custom animation types can be defined using Javascript files that are included as part of the Plasmoid's package in the {{path|contents/animations/}} directory. To learn how to create such animations and access them from your Plasmoid, visit the [[Development/Tutorials/Plasma/JavaScript/Animations|Javascript Animations tutorial]].

= Standard Animation Types =
Below is a list of all current standard animation types and their particular read/write properties:

== Fade ==
* ''number'' '''startOpacity''': the opacity, between 0 and 1, that the target widget starts at when the animation begins
* ''number'' '''targetOpacity''': the opacity, between 0 and 1, that the target widget will be at the end of the animation

== Geometry ==
* ''QRectF'' '''startGeometry''': the geometry that the target widget should start with
* ''QRectF'' '''targetGeometry''': the geometry the target widget will have at the end of the animation

== Grow ==
* ''number'' '''factor''': the factor by which the target widget will grow to by the end of the animation

== Pause ==
* ''number'' '''duration''': the number of milliseconds to pause for

== Property ==
Animates an object (must be a QObject internally, which includes all Plasma Widgets) by manipulating one of its properties. Property animations have the following read/write properties:

* ''any'' '''startValue'''
* ''any'' '''endValue'''
* ''ByteArray'' '''propertyName'''
* ''QObject'' '''targetObject'''
* ''number'' '''duration'''
* ''EasingCurve'' '''easingCurve'''

== Pulser ==
* ''number'' '''targetScale''': the maximum scale of the pulse-shadow item, relative to the target widget

== Rotate ==
* ''QtAxis'' '''axis''': the axis along which to rotate the item
* ''Reference'' '''reference''': the reference point around which to rotate the target widget
* ''number'' '''angle''': the number of degrees to rotate the item

== RotateStacked ==
* ''MovementDirection'' '''movementDirection''': the direction to rotate the widgets in the stack around
* ''QGraphicsLayoutItem'' '''layout'''
* ''Reference'' '''reference''': the reference point around which to rotate the target widget
* ''QGraphicsWidget'' '''backingWidget''': the widget in the "back" to rotate to the front of the target widget

== Slide ==
* ''MovementDirection'' '''movementDirection''': the direction to slide the widget
* ''number'' '''distance''': the distance to slide the widget

== Zoom ==
* ''number'' '''zoom''': the factor by which to zoom the target widget

= QEasingCurve =
Used to set the progress shape of Animation objects, this class has the following read-only properties:

* ''string'' '''toString'''
* ''number'' '''valueForProgress(number progress)''': returns effective progress for the easing curve at progress. While progress must be between 0 and 1, the returned effective progress can be outside those bounds.

as well as the following read/write property:

* ''EasingCurveType'' '''type''': the shape of this easing curve

and the following enumeration:

* '''EasingCurveType'''
** Linear
** InQuad
** OutQuad
** InOutQuad
** OutInQuad
** InCubic
** OutCubic
** InOutCubic
** OutInCubic
** InQuart
** OutQuart
** InOutQuart
** OutInQuart
** InQuint
** OutQuint
** InOutQuint
** OutInQuint
** InSize
** OutSine
** InOutSine
** OutInSine
** InExpo
** OutExpo
** InOutExpo
** OutInExpo
** InCirc
** OutCirc
** InOutCirc
** InOutCirc
** OutInCirc
** InElastic
** OutElastic
** InOutElastic
** OutInElastic
** InBack
** OutBack
** InOutBack
** OutInBack
** InBounc
** OutBounce
** InOutBounce
** OutInBounce
** InCurve
** OutCurve
** SineCurve
** CosineCurve

Development/Tutorials/Plasma/JavaScript/API-UIElements

2011-06-24T11:57:15Z

Aseigo: Created page with '= User Interface Elements = The Plasma framework provides a set of standard user interface elements such as pushbuttons and checkboxes for use in Plasmoids, and these are availa...'

= User Interface Elements =

The Plasma framework provides a set of standard user interface elements such as pushbuttons and checkboxes for use in Plasmoids, and these are available from the Simplified Javascript API as well. These elements follow the Plasma style and other conventions so that widgets blend well both visually and functionally with other Plasma elements.

Note that some UI elements have functions that are synonymous with a read-write property. In those cases, the function can serve as a slot and be connected to signals for easy setting of the property.

= DataEngine-Aware UI Elements =
Some of the UI elements are able to accept data directly from DataEngines. These widgets will have a dataUpdated function and can be passed into the DataEngine::connectSource method successfully.

DataEngine-aware UI elements include:

* Label
* TextEdit
* Meter

= Common Properties =

By default, all of the Plasma user interface elements have the following properties:

* ''String'' '''objectName'''
* ''number'' '''opacity'''
* ''boolean'' '''enabled'''
* ''boolean'' '''visible'''
* ''QPointF'' '''pos'''
* ''number'' '''x'''
* ''number'' '''y'''
* ''number'' '''z'''
* ''number'' '''rotation'''
* ''number'' '''scale'''
* ''QPointF'' '''transformOriginPoint'''
* ''QPalette'' '''palette'''
* ''QFont'' '''font'''
* ''QSizeF'' '''size'''
* ''QtFocusPolicy'' '''focusPolicy'''
* ''QRectF'' '''geometry'''

= Common Signals =

* '''opacityChanged()'''
* '''visibleChanged()'''
* '''enabledChanged()'''
* '''xChanged()'''
* '''yChanged()'''
* '''zChanged()'''
* '''rotationChanged()'''
* '''scaleChanged() '''

= UI Element Gallery =

== CSS Styleable UI Elements ==

Most UI Elements are able to have their appearance adjust using a CSS stylesheet. All of these elements have the following read/write property:

*''String'' '''styleSheet''': A CSS stylesheet describing visual properties to apply to the widget; see [http://doc.trolltech.com/4.5/stylesheet.html the Qt Documentation for more information]

=== CheckBox ===
Read-write properties:
* ''String'' '''text'''
* ''String'' '''image'''
* ''boolean'' '''checked'''
* '''toggled(bool)'''

=== ComboBox ===
Read-only properties:
* ''number'' '''count''': (API v 3) the number of items in the combobox

Read-write properties:
* ''String'' '''text''': the text of the currently selected item in the combobox
* ''number'' currentIndex: (API v 3) the index of the current item

Funtions:
* '''clear()'''

Signals:
* '''activated(String)'''
* '''textChanged(String)'''
* '''currentIndexChanged(number)'''

=== Frame ===
Read-write properties:
* ''Shadow'' '''frameShadow'''
* ''String'' '''text'''
* ''String'' '''image'''

Enumerations:
* '''Shadow'''
* '''Plain'''
* '''Raised'''
* '''Sunken'''

=== GroupBox ===
Read-write properties:
* ''String'' '''text'''

=== Label ===
Read-write properties:
* ''String'' '''text'''
* ''String'' '''image'''
* ''number'' '''alignment''' (see [[#QtAlignment]] for the valid values)
* ''boolean'' '''hasScaledContents'''
* ''boolean'' '''textIsSelectable''' (since 4.4.1)
* ''boolean'' '''wordWrap''' (API v2)

Functions:
* '''dataUpdated(String, Data)'''

Signals:
* '''linkActivated(String)''': emitted when a link is clicked; includes the URL of link that is clicked; this is only available when textIsSelectable
* '''linkHovered(String)''': emitted when a link is hovered

=== LineEdit ===
Read-write properties:
* ''String'' '''text'''
* ''boolean'' '''clearButtonShown'''

Signals:
* '''editingFinished()'''
* '''returnPressed()'''
* '''textEdited(String)'''
* '''textChanged(String)'''

=== PushButton ===
Read-write properties:
* ''String'' '''text'''
* ''String'' '''image'''
* ''QAction'' '''action'''
* ''QIcon'' '''icon'''
* ''boolean'' '''checkable'''
* ''boolean'' '''checked'''
* ''boolean'' '''down'''

Signals:
* '''pressed()'''
* '''released()'''
* '''clicked()'''
* '''toggled(bool)'''

=== RadioButton ===
Read-write properties:
* ''String'' '''text'''
* ''String'' '''image'''
* ''boolean'' '''checked'''

Signals:
* '''toggled(bool)'''

=== ScrollWidget ===
Read-write properties:
* ''QGraphicsWidget'' '''widget'''
* ''number'' '''horizontalScrollBarPolicy'''
* ''number'' '''verticalScrollBarPolicy'''
* ''QPointF'' '''scrollPosition'''
* ''QSizeF'' '''contentsSize'''
* ''QRectF'' '''viewportGeometry'''

Functions:
* '''ensureRectVisible(QRectF)'''
* '''ensureItemVisible(QGraphicsItem)'''
* '''registerAsDragHandle(QGraphicsWidget)'''
* '''unregisterAsDragHandle(QGraphicsWidget)'''

=== ScrollBar ===
Read-write properties:
* ''number'' '''singleStep'''
* ''number'' '''pageStep'''
* ''number'' '''value'''
* ''number'' '''minimum'''
* ''number'' '''maximum'''
* ''QtOrientation'' '''setOrientation'''

Functions:
* '''setValue(number)'''
* '''setOrientation(QtOrientation)'''

Signals:
* '''valueChanged(number)'''

=== Slider ===
Read-write properties:
* ''number'' '''maximum'''
* ''number'' '''minimum'''
* ''number'' '''value'''
* ''number'' '''orientation'''

Signals:
* '''sliderMoved(number)'''
* '''valueChanged(number)'''

Functions:
* '''setMaximum(number)'''
* '''setMinimum(number)'''
* '''setRange(number, number)'''
* '''setValue(number)'''
* '''setOrientation(QtOrientation)'''

=== SpinBox ===
Read-write properties:
* ''number'' '''maximum'''
* ''number'' '''minimum'''
* ''number'' '''value'''

Functins:
* '''setMaximum(number)'''
* '''setMinimum(number)'''
* '''setRange(number, number)'''
* '''setValue(number)'''

Signals:
* '''sliderMoved(number)'''
* '''valueChanged(number)'''
* '''editingFinished()'''

=== TabBar ===
Read-write properties:
* ''number'' '''currentIndex'''
* ''number'' '''count'''
* ''boolean'' '''tabBarShown'''

Functions:
* '''setCurrentIndex(number)'''
* '''insertTab(number, QIcon,String,QGraphicsLayoutItem)'''
* '''insertTab(number, QIcon,String)'''
* '''insertTab(number, String,QGraphicsLayoutItem)'''
* '''insertTab(number, String)'''
* '''addTab(QIcon,String,QGraphicsLayoutItem)'''
* '''addTab(QIcon,String)'''
* '''addTab(String,QGraphicsLayoutItem)'''
* '''addTab(String)'''
* '''removeTab(number)'''
* '''takeTab(number)'''
* '''tabAt(number)'''
* '''setTabText(number, String)'''
* '''tabText(number)'''
* '''setTabIcon(number, QIcon)'''
* '''tabIcon(number)'''

Signals:
* '''currentChanged(number)'''

=== TextEdit ===
Read-write properties:
* ''String'' '''text'''
* ''boolean'' '''readOnly'''

Functions:
* '''dataUpdated(String, Data)'''

Signals:
* '''textChanged()'''

=== ToolButton ===
:Read-write properties:

* ''''QAction'' '''action''': the action associated with this '''ToolButton'''
* ''''boolean'' '''autoRaise''': whether or not the ToolButton should raise automatically when the user interacts with it'''
* ''''String'' '''image''': path to an icon or image (e.g. in the widget's Package) to show on the ToolButton
* ''''String'' '''text''': the text shown on the ToolButton

API v2 adds:
* ''''boolean'' '''down''': whether or not the ToolButton is in the down position (since protocol version 2)

:Signals:
* '''clicked()'''
* '''pressed()'''
* '''released()'''

=== TreeView ===
Read-write properties:
* ''QAbstractModel'' '''model'''

=== VideoWidget ===
Read-writeproperties:
* ''String'' '''url'''
* ''number'' '''currentTime'''
* ''number'' '''totalTime'''
* ''number'' '''remainingTime'''
* ''Controls'' '''usedControls'''
* ''boolean'' '''controlsVisible'''

Functions:
* '''play()'''
* '''pause()'''
* '''stop()'''
* '''seek(number)'''

Signals:
* '''tick(number)'''
* '''aboutToFinish()'''
* '''nextRequested()'''
* '''previousRequested()'''

Enumerations:
* Controls
** NoControls
** Play
** Pause
** Stop
** PlayPause
** Previous
** Next
** Progress
** Volume
** OpenFile
** DefaultControls

== Other UI Elements ==

=== BusyWidget ===
Read-write properties:
* ''boolean'' '''running'''
* ''String'' '''label'''

Signals:
* '''clicked()'''

=== FlashingLabel ===
Read-write properties:
* ''boolean'' '''autohide'''
* ''QColor'' '''color'''
* ''number'' '''duration'''

Functins:
* '''kill()'''
* '''fadeIn()'''
* '''fadeOut()'''
* '''flash(String, number, QTextOption)'''
* '''flash(String ,number)'''
* '''flash(String)'''
* '''flash(QPixmap, number, QtAlignment)'''
* '''flash(QPixmap, number)'''
* '''flash(QPixmap)'''

=== GraphicsWidget (API v3) ===
This is just a plain element with no painting or other features. It is useful primarily as a place holder, especially to contain layouts for other elements.

=== IconWidget ===
Read-only properties:
* ''QSizeF'' '''iconSize''' - the actual size of the icon given the size of the IconWidget, space reserved (if any) for text displayed, etc.

Read-write properties:
* ''String'' '''text'''
* ''String'' '''infoText'''
* ''QIcon'' '''icon'''
* ''QColor'' '''textBackgroundColor'''
* ''String'' '''svg'''
* ''QAction'' '''action'''
* ''QtOrientation'' '''orientation'''
* ''number'' '''numDisplayLines'''

Functions:
* '''setPressed(boolean)'''
* '''setUnpressed()'''
* '''setIcon(String)'''

Signals:
* '''pressed(bool)'''
* '''clicked()'''
* '''doubleClicked()'''
* '''activated()'''
* '''changed()'''

=== ItemBackground ===
Read-write properties:
* ''QRectF'' '''target'''
* ''QGraphicsItem'' '''targetItem'''

Signals:
* '''appearanceChanged()'''
* '''animationStep(qreal)'''
* '''targetReached(QRectF)'''
* '''targetItemReached(QGraphicsItem)'''

=== Meter ===
Read-write properties:
* ''number'' '''minimum'''
* ''number'' '''maximum'''
* ''number'' '''value'''
* ''String'' '''svg'''
* ''MeterType'' '''meterType'''

Functions:
* '''dataUpdated(String, Data)'''

Enumerations:
* '''MeterType'''
** BarMeterHorizontal
** BarMeterVertical
** AnalogMeter

=== Separator ===
Read-write properties:
* ''QtOrientation'' '''orientation'''

=== SignalPlotter ===
Read-write properties:
* ''String'' '''title'''
* ''String'' '''unit'''
* ''boolean'' '''useAutoRange'''
* ''number'' '''horizontalScale'''
* ''boolean'' '''showVerticalLines'''
* ''QColor'' '''verticalLinesColor'''
* ''number'' '''verticalLinesDistance'''
* ''boolean'' '''verticalLinesScroll'''
* ''boolean'' '''showHorizontalLines'''
* ''QColor'' '''horizontalLinesColor'''
* ''QColor'' '''fontColor'''
* ''number'' '''horizontalLinesCount'''
* ''boolean'' '''showLabels'''
* ''boolean'' '''showTopBar'''
* ''QColor'' '''backgroundColor'''
* ''String'' '''svgBackground'''
* ''boolean'' '''thinFrame'''
* ''boolean'' '''stackPlots'''

=== SvgWidget ===
Read-write properties:
* ''Svg'' '''svg'''
* ''String'' '''elementID'''

Signals:
* '''clicked(QtMouseButton)'''

=== WebView ===
Read-only properties:
* ''QSizeF'' '''contentsSize'''
* ''QRectF'' '''viewportGeometry'''

Read-write properties:
* ''Url'' '''url'''
* ''String'' '''html'''
* ''boolean'' '''dragToScroll'''
* ''QPointF'' '''scrollPosition'''

Signals:
* '''loadProgress(number)'''
* '''loadFinished(bool)'''

= Layouts =

== LinearLayout ==
* ''number'' '''spacing'''
* ''QtOrientation'' '''orientation''' (''QtVertical'' or ''QtHorizontal'')
* ''function'' '''removeAt'''
* ''function'' '''addStretch'''
* ''function'' '''setStretchFactor'''
* ''function'' '''setAlignment'''
* ''function'' '''insertStretch'''
* ''function'' '''setItemSpacing'''
* ''function'' '''setContentsMargins'''
* ''function'' '''addItem'''
* ''function'' '''removeItem'''
* ''function'' '''insertItem'''
* ''function'' '''toString'''
* ''function'' '''activate''' (API v3)

== AnchorLayout ==
* ''number'' '''horizontalSpacing'''
* ''number'' '''verticalSpacing'''
* ''function'' '''setSpacing'''
* ''function'' '''removeAt'''
* ''function'' '''addAnchor'''
* ''function'' '''anchor'''
* ''function'' '''addAnchors'''
* ''function'' '''addCornerAnchors'''
* ''function'' '''toString'''
* ''function'' '''activate''' (API v3)

== GridLayout ==
* ''number '''horizontalSpacing'''
* ''number '''verticalSpacing'''
* ''function'' '''rowSpacing'''
* ''function'' '''setRowSpacing'''
* ''function'' '''columnSpacing'''
* ''function'' '''setColumnSpacing'''
* ''function'' '''rowMinimumHeight'''
* ''function'' '''setRowMinimumHeight'''
* ''function'' '''rowPreferredHeight'''
* ''function'' '''setRowPreferredHeight'''
* ''function'' '''rowMaximumHeight'''
* ''function'' '''setRowMaximumHeight'''
* ''function'' '''rowFixedHeight'''
* ''function'' '''setRowFixedHeight'''
* ''function'' '''columnMinimumWidth'''
* ''function'' '''setColumnMinimumWidth'''
* ''function'' '''columnPreferredWidth'''
* ''function'' '''setColumnPreferredWidth'''
* ''function'' '''columnMaximumWidth'''
* ''function'' '''setColumnMaximumWidth'''
* ''function'' '''columnFixedWidth'''
* ''function'' '''setColumnFixedWidth'''
* ''function'' '''remoteAt'''
* ''function'' '''setAlignment'''
* ''function'' '''setSpacing'''
* ''function'' '''setContentsMargins'''
* ''function'' '''addItem'''
* ''function'' '''toString'''
* ''function'' '''activate''' (API v3)

= Undocumented Properties and Functions =

There are a handful of other undocumented properties and functions available to UI elements. These are not supported or guaranteed to exist in future versions however, and as such should not be used or relied upon.

Development/Tutorials/Plasma/JavaScript/API-Enumerations

2011-06-24T11:54:08Z

Aseigo: Created page with '== Global Enumerations == In the global namespace are a set of useful enumerations that can be used with various classes in the Simplified Javascript Plasmoid API. These include:...'

== Global Enumerations ==
In the global namespace are a set of useful enumerations that can be used with various classes in the Simplified Javascript Plasmoid API. These include:

= AspectRatioMode =
* '''IgnoreAspectRatio''': The Plasmoid can be freely resized
* '''KeepAspectRatio''': The Plasmoid keeps a fixed aspect ratio
* '''Square: The Plasmoid is always a square
* '''ConstrainedSquare''': The Plasmoid is no wider (in horizontal formfactors) or no higher (in vertical ones) than a square
* '''FixedSize''': The Plasmoid cannot be resized

= FormFactor =
* '''Planar''': The Plasmoid lives in a plane and has two degrees of freedom to grow. Optimize for desktop, laptop or tablet usage: a high resolution screen 1-3 feet distant from the viewer.
* '''MediaCenter''': As with Plasmoid the applet lives in a but the interface should be optimized for medium-to-high resolution screens that 5-15 feet distant from the viewer. Sometimes referred to as a "ten foot interface".
* '''Horizontal''': The Plasmoid is constrained vertically, but can expand horizontally.
* '''Vertical''': The Plasmoid is constrained horizontally, but can expand vertically.

= Location =
* '''Floating''': Free floating. Neither geometry or z-ordering is described precisely by this value.
* '''Desktop''': On the planar desktop layer, extending across the full screen from edge to edge
* '''FullScreen'''
* '''TopEdge'''
* '''BottomEdge'''
* '''LeftEdge'''
* '''RightEdge'''

= AnimationDirection =
* '''AnimationForward'''
* '''AnimationBackward'''

= BackgroundHints =
* '''NoBackground'''
* '''StandardBackground'''
* '''TranslucentBackground'''
* '''DefaultBackground'''

= QtAlignment =
* QtAlignLeft
* QtAlignRight
* QtAlignHCenter
* QtAlignJustify
* QtAlignTop
* QtAlignBottom
* QtAlignVCenter

If you need to align something in the center (both horizontally and vertically) you can sum the constans.

= QtAnchorPoint =
* QtAnchorLeft
* QtAnchorRight
* QtAnchorBottom
* QtAnchorTop
* QtAnchorHorizontalCenter
* QtAnchorVerticalCenter

= QtCorner =
* QtTopLeftCorner
* QtTopRightCorner
* QtBottomLeftCorner
* QtBottomRightCorner

= QtMouseButton =
* QtNoButton
* QtLeftButton
* QtRightButton
* QtMidButton
* QtXButton1
* QtXButton2

= QtOrientation =
* QtHorizontal
* QtVertical

= QtScrollBarPolicy =
* QtScrollBarAsNeeded
* QtScrollBarAlwaysOff
* QtScrollBarAlwaysOn

= QtSizePolicy =
* QSizePolicyFixed
* QSizePolicyMinimum
* QSizePolicyMaximum
* QSizePolicyPreferred
* QSizePolicyExpanding
* QSizePolicyMinimumExpanding
* QSizePolicyIgnored

= Theme Colors (API v3) =
* TextColor
* HighlightColor
* BackgroundColor
* ButtonTextColor
* ButtonBackgroundColor
* LinkColor
* VisitedLinkColor

= Status =
* UnknownStatus The status is unknown
* PassiveStatus The Item is passive
* ActiveStatus The Item is active
* NeedsAttentionStatus The Item needs attention
* AcceptingInputStatus The Item is accepting input

Development/Tutorials/Plasma/JavaScript/API-PlasmoidObject

2011-06-24T11:52:47Z

Aseigo:

Development/Tutorials/Plasma/JavaScript/API-PlasmoidObject

2011-06-24T11:50:59Z

Aseigo: Created page with '== The Global plasmoid Object == There is a global object available to the Plasmoid called, appropriately, "plasmoid". It has a number of useful properties (some of which are r...'

== The Global plasmoid Object ==

There is a global object available to the Plasmoid called, appropriately, "plasmoid". It has a number of useful properties (some of which are read only, but many of which are read/write), functions, constant values and callbacks. Each are enumerated below.

=== Callbacks ===

See the section on Events above.

There are some events that are generated by Plasma for the Plasmoid. These can often be caught by providing a function assigned to a specific name in the plasmoid object. For instance, to get notified of form factor changes, one would provide a formFactorChanged method as follows: <code javascript="javascript">
plasmoid.formFactorChanged = function() {

print("the form factor has changed to: " + plasmoid.formFactor())

}
</code>

The following callbacks are used to notify the Plasmoid of changes in its running environment:

* '''configChanged()'''
* '''currentActivityChanged()'''
* '''formFactorChanged()'''
* '''immutabilityChanged()'''
* '''locationChanged()'''
* '''sizeChanged()'''

Other callbacks include:
* '''dataUpdated(String source, Map[String, Any] data)''': used to pass in DataEngine updates
* '''activate()''': called when the widget is activated by the user, e.g. by a keyboard shortcut. Useful for setting the focus on a specific input widget, for instance. (API v2)
* '''initExtenderItem(Extender extender)''': Called when an Extender should be set up. (API v2)
* '''popupEvent(boolean shown)''': called on PopupApplets when the popup is shown or hidden. (API v2)

In API v2, all of these callbacks can also be used as events. So, for instance, instead of implementing plasmoid.popupEvent, one could also write:

<code javascript>plasmoid.addEventListener('popupEvent', function(shown) { print('shown? ' + shown) } )</code>

This would also suppress any calls to plasmoid.popupEvent.

Further documentation on these callbacks can be found in the relevant sections below.

=== Environment ===

A set of read-only properties (and in most cases notification functions) that tell the Plasmoid about its current environment:

* '''apiVersion''': the integer version of the Simplified JavaScript API in the current execution environment; can be used to change behaviour or usage of functions depending on the version number.

* '''formFactor''': one of Planar (e.g. on a desktop or in an application main view), Horizontal, Vertical or MediaCenter. When the form factor changes, the plasmoid.formFactorChanged function, if defined in the Plasmoid, is called.

* '''size''': the size of the Plasmoid, expressed in QSizeF (explained below). when it changes, plasmoid.sizeChanged() will be called.

* '''location''': one of Floating (no specific location), Desktop (on the application's main view are), FullScreen, LeftEdge, RightEdge, TopEdge or ButtomEdge. When the location changes, the plasmoid.locationChanged function, if defined in the Plasmoid, is called.

* '''immutable''': this property is set to true when the Plasmoid is set to not be movable or otherwise changeable, and false otherwise. Configuration is still usually allowed in this state. When the immutability changes, the plasmoid.immutabilityChanged function, if defined in the Plasmoid, is called.

* '''currentActivity''': the current contextual activity name. When the current activity changes, the plasmoid.currentActivityChanged function, if defined in the Plasmoid, is called.

* '''shouldConserveResources''': true if the plasmoid should not be doing anything that would create too much draw on power, e.g. when on a device with low battery power it may be a good idea not to run a computationally expensive but optional animation

* '''userConfiguring''': true if the user configuration interface is currently being displayed.

=== Properties ===
A set of read/write properties that allow the Plasmoid to set various visual or functional properties:

* ''AspectRatioMode'' '''aspectRatioMode''': defines how to treat the aspect ratio of a Plasmoid when resizing it. See the [[#AspectRatioMode|AspectRatioMode]] documentation for values and their meaning.

* ''BackgroundHints'' '''backgroundHints''': defines how the background of the widget is rendered. See the [[#BackgroundHints|BackgroundHints]] documentation for values and their meaning.

* ''boolean'' '''busy''': set to true when the Plasmoid is currently processing or waiting for data and the user interface should be blocked while doing so; will generally show a full-Plasmoid animated overlay to denote business

=== Geometry ===

Read Only Properties:

* ''QRectF'' '''rect''': the current rect of the Plasmoid; note that the top left may be not be the origin point (0,0)

Functions:

* '''resize(width, height)'''
* '''setMinimumSize(width, height)'''
* '''setPreferredSize(width, height)'''
* '''setBackgroundHints(background)''' - use '''NoBackground''' as value if you want to remove the default plasmoid background box.
* '''popupIcon(QIcon("some icon"))''' - set icon to show when the plasmoid is added to the taskbar. NOTE if the plasmoid is made in QML, you MUST specify a default size for the main Item. This size will be used for the plasmoid when added to the taskbar

=== Painting and Layout ===

To paint directly on to the canvas, a widget may implement the paintInterface function in the plasmoid object:
<code javascript>
plasmoid.paintInterface = function(painter) { /* painting code goes here*/ }
</code>
See the Painting section below for information about helpful classes and functions that can be used when implementing a paintInterface function.

Read/Write Properties:

* ''Layout'' '''layout''': the QGraphicsLayout associated with the Plasmoid for laying out top level items; this property is read-write, though the property is not usually set as one can simply do "new LinearLayout" (or one of the other layout classes provided) and it will be automatically associated with the Plasmoid.

Functions:

* '''update()''': triggers a full repaint of the Plasmoid.
* '''update(QRectF rect)''' triggers a repaint of the rect area of the Plasmoid.
* '''failedToLaunch(bool failed[, string reason])''' sets the launch status of the Plasmoid; if set to true, the script will stop executing and the reason message, if any, will be displayed to the user.

=== Access To Packaged Files ===

Functions:

* ''string'' '''file(string type[, string fileName])''': returns the path to a file in the Plasmoid package of the given type, optionally with a file name to match, e.g. <code javascript>var path = plasmoid.file("mainscript")</code> or <code javascript>var pm = new QPixmap(plasmoid.file("images", "mypixmap.png"))</code>

* ''bool'' '''include(string filename)''': attempts to include the script defined from the package's code directory

=== Configuration Data ===
Configuration values can be defined using [[Development/Tutorials/Using_KConfig_XT|KConfig XT]] XML files in the {{path|contents/config/}} directory of the Plasmoid's package. The default file that is looked for and used is {{path|contents/config/main.xml}}.

==== Accessing Configuration Data ====
Read-write properties:
* ''String'' '''activeConfig''': The current active configuration description. For instance, setting it to "foo" would cause the Plasmoid to try and reference the {{path|contents/config/foo.xml}} KConfigXT file. Setting this to an empty string will switch to the main.xml file.

Functions:
* ''any'' '''readConfig(String key)''': reads the value from the configuration data for the given key as defined by the currently active configuration.

* '''writeConfig(String key, any value) ''': writes a value to the configuration store under the given key

==== User Customization ====

User customization can be offered by providing a Qt Designer file called {{path|contents/ui/config.ui}} in the Plasmoid's package.

Callbacks:
* '''configChanged()''': callback function called when the configuration is changed external to the Plasmoid, e.g. when the user changes settings in a configuration dialog.

=== Context menu ===

It's possible to add some items to the popup menu of the Plasmoid.

Functions:
* '''setAction(name, text, icon, shortcut)''': adds an item to the context menu with the given text and icon; you need to define '''plasmoid.action_<name>''' function, where <name> is the first argument for setAction call, and this function will be called each time user clicks the item

* '''removeAction(name)''': removes the item

Development/Tutorials/Plasma/JavaScript/API-Events

2011-06-24T11:45:53Z

Aseigo: Created page with '= Events = Starting in API v2, it is possible register functions as event handlers. To register an event handler, use: * '''addEventListener(String event, Function listener)'''...'

= Events =

Starting in API v2, it is possible register functions as event handlers. To register an event handler, use:

* '''addEventListener(String event, Function listener)'''

The event parameter is the name of the event (see list at end of section for known events) and the handler parameter is the function that will be called whenever the event occurs. Event names are not case sensitive. An event object will be passed into the handler, and the type and behavior of that object is event specific.

Any number of event handlers may be added to a given event, and one handler may be registered to any number of events. The order of execution of event handlers is not guaranteed.

To remove an event handler, use:

* '''removeEventListener(String event, Function listener)'''

The function passed in will no longer be called as a result of the event occurring. Any currently pending calls to the listener are still made, however.

If an event handler is registered using addEventListener, then any callback in the global plasmoid object that may be related to the same event will be suppressed. For instance, if an event handler is registered using addEventListener for the paintInterface event, then plasmoid.paintInterface will not be called.

= Input Events (API v2) =

Following are the input events which are recognized on the Plasmoid along with the type of event object passed in to registered event listeners:

* HoverEnter: HoverEvent Object
* HoverLeave: HoverEvent Object
* HoverMove: HoverEvent Object
* KeyPress: KeyEvent Object
* KeyRelease: KeyEvent Object
* MouseDoubleClick: MouseEvent Object
* MouseMove: MouseEvent Object
* MousePress: MouseEvent Object
* MouseRelease: MouseEvent Object
* Wheel: WheelEvent Object

Example:

<code javascript>
// anonymous function as a listener on KeyPress
plasmoid.addEventListener('KeyPress', function(a) { print(a.key) })

function output()
{
print('Hover Event!')
}

function hovered(event)
{
plasmoid.busy = true
plasmoid.removeEventListener('HoverEnter', output)
}

function unhovered(event)
{
plasmoid.busy = false
}

plasmoid.addEventListener('HoverEnter', hovered)
plasmoid.addEventListener('HoverLeave', unhovered)
plasmoid.addEventListener('HoverEnter', output)
plasmoid.addEventListener('HoverLeave', output)
</code>

= HoverEvent (API v2) =

= KeyEvent (API v2) =

= MouseEvent (API v2) =

= WheelEvent (API v2) =

= Addon Events (API v3) =

The following two events are used in conjuction with Addons. See the [[API-Addons|Addons documentation]] for more information on Addons.

* addonCreated: Object addOn
* newAddonsAvailable

Development/Tutorials/Plasma/QML/API

2011-06-22T07:58:48Z

Aseigo: /* ToolTip */

= Introduction to the Plasmoid QML Declarative API =

This document provides an overview/reference of the Declarative QML API for Plasmoids. It isn't a full binding to all of Qt or KDE's libraries, but a focused set of bindings designed to make writing Plasmoids fast and easy, while remaining powerful.

The API in this documentation covers the API of the Plasma specific QML components, so only the Declarative part of the API.

The QML ScriptEngine is bassed upon the Plasma JavaScript engine, making the API of the JavaScript part identical to the one of the JavaScript plasmoids engine.
To see the api of the global ''Plasmoid'' object, see the [http://techbase.kde.org/Development/Tutorials/Plasma/JavaScript/API#The_Global_plasmoid_Object JavaScript API] documentation.
(TODO: the JavaScript api paged should probably be copied and stripped down the imperative bits not present there, it would make harder to update tough)

== What Is a Declarative Plasmoid? ==

To denote that this Plasmoid is a Declarative widget, ensure that in the metadata.desktop file there is this line:

X-Plasma-API=declarativeappletscript

What follows is a description of the Plasma declarative classes instantiable from QML.

= Main QML classes =

== Data engines ==
While it's possible to fetch data from a Plasma DataEngine in the same way as the [http://techbase.kde.org/Development/Tutorials/Plasma/JavaScript/API#DataEngine JavaScript API], however it is preferrable to use the following declarative classes:

=== DataSource ===
DataSource is a receiver for a dataEngine and can be declared inside QML:
<code>
import org.kde.plasma.core 0.1 as PlasmaCore

PlasmaCore.DataSource {
id: dataSource
engine: "time"
connectedSources: ["Local"]
interval: 500
}
</code>

It has the following properties:
* bool '''valid''' (read only): true when the DataSource is successfully connected to a data engine
* int '''interval''': interval of polling of the dataengine, if 0 no polling will be executed
* string '''engine''': the plugin name of the dataengine to load
* Array(string) '''connectedSources''': all the sources of the dataengine we are connected to (and whose data will appear in the '''data''' property)
* Array(string) '''sources''' (read only): all the sources available from the dataengine
* variant map '''data''' (read only): It's the most important property, it's a map of all the data available from the dataengine: its structure will be as follows:
** each key of the map will be a source name, in '''connectedSources'''
** each value will be a variant hash, so an hash with strings as keys and any variant as value
** example: dataSource.data["Local"]["Time"] indicates the '''Time''' key of the dataengine source called "Local"

It has the following methods:
* StringList keysForSource(String source): lists all the keys corresponding to a certain source: for instance in the "time" dataengine, for the "Local" source, keys will be:
** "Timezone Continent"
** "Offset"
** "Timezone"
** "Time"
** "Date"
** "Timezone City"
* Service serviceForSource(String source): returns a Plasma service that corresponds a given source: see the section about services for how to use it.
* void connectSource(String source): adds to '''connectedSources''' the new source
* void disconnectSource(String source): removes that source from '''connectedSources'''

=== Service ===
Due to their imperative nature, Plasma Services are not instantiated as QML classes, but rather created out of a '''DataSource''' with the method '''serviceForSource''' and used in the JavaScript portions of the QML files.
This following example is a simplified version from the Now Playing QML widget in the kdeexamples git repository:
<code>
var service = dataSource.serviceForSource(activeSource)
var operation = service.operationDescription("seek")
operation.seconds = 10

var job = service.startOperationCall(operation)
</code>
Here dataSource is the id of a DataSource object, and activeSource is a source contained in one of its '''connectedSources'''.
The service provides an operation called "seek", with a parameter called "seconds", that can be written on it as a property of a JavaScript object.

=== ServiceJob ===
If is necessary to monitor the result of a Service operation, it's possible to connect to the '''finished''' signal provided by the job return paramenter of the '''startOperationCall''' service method.
The '''finished''' signal has the same job as parameter, from which is possible to check the variant '''result''' property, to check the result.

=== DataModel ===
Some data engines return as their data something that can be interpreted as a list of items, rather than simple key/value pairs.
QML provides some item views such as '''ListView''', '''GridView''' and '''Repeater'''.
The '''DataModel''' QML object can provide, based on a DataSource a model suitable for those QML item views.

It has the following properties:
* DataSource '''dataSource''': the id of an existing (and connected) DataSource
* String '''sourceFilter''': it's a regular expression. If the DataSource is connected to more than one source, only inserts data from sources matching this filter expression in the model
* String '''keyRoleFilter''': it's a regular expression. Only data with keys that match this filter expression will be inserted in the model
* int '''count''' (read only): how many items are in the model

Example:
<code>
ListView {
model: PlasmaCore.DataModel {
dataSource: microblogSource
keyRoleFilter: "[\\d]*"
}
delegate: Text {
text: title
}
}
</code>

In the example, ''microblogSource'' is the id of a DataSource, and inserts in the model only entries that have a number as the key name (matched with [\\d]*, in this case tweets ids)

Each item in the model will have the form of a variant hash: all the keys of the hash will be registered as model role names, in the example, "title" is a role of the model containing a string (also reachable with model["title"]).

A special reserved role will always be present: '''"DataEngineSource"''': it will contain the name of the data engine source that gave origin to this item.

=== SortFilterModel ===
SortFilterModel is a proxy model for easy sorting and/or filtering of the items in a DataModel (or any other QAbstractItemModel subclass that has been registered in QML with setContextProperty from a C++ application)
Properties:
* model '''sourceModel'''
* String '''filterRegExp'''
* String '''filterRole'''
* String '''sortRole'''
* Qt::SortOrder '''sortOrder'''
* int '''count''' (read only)

== Plasma Themes ==

=== Theme ===
This class instantiable from QML provides access to the Plasma Theme colors and other facilities such as fonts.
It has the following properties:
* String '''themeName''' (read only)
* QFont '''font''' (read only)
* bool '''windowTranslucentEnabled''' (read only)
* Url '''homepage''' (read only)
* bool '''useGlobalSettings''' (read only)
* QString '''wallpaperPath''' (read only)
* color '''textColor''' (read only)
* color '''highlightColor''' (read only)
* color '''backgroundColor''' (read only)
* color '''buttonTextColor''' (read only)
* color '''buttonBackgroundColor''' (read only)
* color '''linkColor''' (read only)
* color visitedLinkColor''' (read only)
* color '''visitedLinkColor''' (read only)
* color '''buttonHoverColor''' (read only)
* color '''buttonFocusColor''' (read only)
* color '''viewTextColor''' (read only)
* color '''viewBackgroundColo''' (read only)r
* color '''viewHoverColor''' (read only)
* color '''viewFocusColor''' (read only)
* String '''styleSheet''' (read only)

=== Svg ===
Declaring a Svg element instantiates a Plasma Svg instance. This class doesn't draw anything, for drawing, SvgItem is used.
Properties:
* QSize '''size'''
* bool '''multipleImages'''
* String '''imagePath'''
* bool '''usingRenderingCache'''

Methods:
* QPixmap pixmap(QString elementID)
* void resize(qreal width, qreal height)
* void resize(): resets the image to its default dimension
* QSize elementSize(QString elementId)
* QRectF elementRect(QString elementId)
* bool hasElement(QString elementId)
* bool isValid(): true if valid svg file

=== SvgItem ===
It's a graphical element that will actually paint a Svg instance.
Properties:
* String '''elementId''': what element to render. If null, the whole svg will be rendered
* Svg '''svg''': instance of the Svg class mentioned above
* QSizeF '''naturalSize''' (read only): default size of the Svg
* bool '''smooth''': paint with antialias (default false)

=== FrameSvgItem ===
It's a graphical elenent that paints a Plasma::FrameSvg, so a ractangular image composed by 9 elements contained in a Svg file, useful for things like buttons and frames.

Flags
* EnabledBorders: combination of TopBorder | BottomBorder | LeftBorder | RightBorder, NoBorder if no border of the frame is enabled

Properties:
* String '''imagePath''': path of the file relative to the Plasma Theme, for instance "widgets/background"
* String '''prefix''': a FrameSvg can contain multiple frames, for instance a button contains "normal", "raised" and "pressed"
* Margins '''margins''' (read only): the margins of the frame, see documentation below
* EnabledBorders '''enabledBorders''': what borders are enabled

==== Margins ====
Properties:
* real '''left''' (read only)
* real '''top''' (read only)
* real '''right''' (read only)
* real '''bottom''' (read only)

== Top Level windows ==

=== Dialog ===
Dialog instantiates a Plasma::Dialog, it will be a Plasma themed top level window that can contain any QML component.

Properties:
* Item mainItem: the Item contained in the Dialog, it can be any QML Item instance
* bool '''visible''': if the window (not the mainItem) is visible
* int '''x''': x position of the window in screen coordinates
* int '''y''': y position of the window in screen coordinates
* int '''width''' (read only): total width of the dialog, including margins
* int '''height''' (read only): total height of the dialog, including margins
* int '''windowFlags''': Qt window flags of the Dialog
* Margins '''margins''' (read only): margins of the Dialog

Methods:
* QPoint popupPosition(Item item, Qt::Alignment alignment=Qt::AlignLeft): the suggested position for the Dialog if it has to be correctly placed as popup of the QML item passed as parameter.
* void setAttribute(Qt::WindowAttribute attribute, bool on): set an attribute for the dialog window

==== Margins ====
Properties:
* real '''left''' (read only)
* real '''top''' (read only)
* real '''right''' (read only)
* real '''bottom''' (read only)

=== ToolTip ===
Declaring a ToolTip instance makes it possible to use Plasma tooltips with any QML item.

Properties:
* Item '''target''': the QML item we want to show a tooltip of
* String '''mainText'''
* String '''subText'''
* String '''image''': freedesktop compliant icon name as image of the tooltip

= Plasma QtComponents (4.8) =
TODO

Development/Tutorials/Plasma/QML/GettingStarted

2011-06-22T07:57:36Z

Aseigo: /* QML Basics */

== Abstract ==

Writing a plasma applet in QML is very easy, in fact, with KDE 4.6 and Qt 4.7 it just works.

== QML Basics ==

It is recommended that you have read through the [http://doc.qt.nokia.com/4.7/qtquick.html Qt QML Tutorials], as there are quite a few and they are explained thoroughly. There is also a list of all [http://doc.qt.nokia.com/4.7/qdeclarativeelements.html standard QML elements].

See the [https://projects.kde.org/projects/kde/kdeexamples KDE Examples] repository for more KDE-related helpful resources.

=== Root Item ===

The root item can be anything that inherits QGraphicsItem. For example, in this case it is QGraphicsWidget which is a plasmoid. It can also simply be an Item. I also noticed that PathView does not respond to mouse inputs automatically (so flicking doesn't work). Probably because events are being intercepted. So take note, it'll have to be e.g. an Item, for that case.

=== Layouts ===

==== Row and Column ====

==== Anchors ====
Anchor layouts offer a nice way of grouping UI elements nicely together. The idea is that you connect edges or corners of one element to the edge or corner of another widget.
Some examples:
<nowiki>

import QtQuick 1.0
import org.kde.plasma.core 0.1 as PlasmaCore

Item {
width: 200
heigt: 300

Text {
id: first
text: i18n("1st line")
anchors { top: parent.top;
left: parent.left;
right: parent.right;
}
}
Text {
id: second
text: i18n("2nd line")
anchors { top: first.bottom;
left: parent.left;
right: parent.right;
bottom: parent.bottom;
}
}
}
</nowiki>

=== Buttons ===

=== Animations ===

== Package Structure ==

You create a .desktop file and the .qml file. They have to be in the usual plasma package structure.

plasmoid-qml/metadata.desktop
plasmoid-qml/contents/ui/main.qml

=== <tt>metadata.desktop</tt> ===
<code ini>
[Desktop Entry]
Name=Hello QML
Comment=A hello world widget in QML
Icon=chronometer

X-Plasma-API=declarativeappletscript
X-Plasma-MainScript=ui/main.qml
X-Plasma-DefaultSize=200,100

X-KDE-PluginInfo-Author=Frederik Gladhorn
X-KDE-PluginInfo-Email=gladhorn@kde.org
X-KDE-PluginInfo-Website=http://plasma.kde.org/
X-KDE-PluginInfo-Category=Examples
X-KDE-PluginInfo-Name=org.kde.hello-qml
X-KDE-PluginInfo-Version=0.0

X-KDE-PluginInfo-Depends=
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true
X-KDE-ServiceTypes=Plasma/Applet
Type=Service
</code>

=== <tt>main.qml</tt> ===
<code javascript>
import QtQuick 1.0

Text {
text: "Hello world!";
}
</code>

== Installing ==
You can install your plasmoid:
plasmapkg --install plasmoid-qml

== plasmoidviewer ==
You can run it in plasmoidviewer as usual:
plasmoidviewer plasmoid-qml

== qmlviewer ==
It's possible to use Plasma specific imports in qml files loaded by qmlviewer:

qmlviewer -I /usr/lib/kde4/imports/ plasmoid-qml/contents/qml/main.qml

Where the -I is the path to the plasma plugin for qml. Try to look for the path of
/usr/lib/kde4/imports/org/kde/plasma/graphicswidgets/libgraphicswidgetsbindingsplugin.so
and use everything up to org of that path.

Hovewer it's '''strongly discouraged''' to use qmlviewer to develop plasmoids, because some features won't be available there:
* localization with i18n()
* access to the global ''plasmoid'' object
* device specific qml files imported with plasmapackage:// urls
* bindings for qicons, KJobs, services and KConfig

= Features only available in Plasma widgets =
In order to have a better integration with the KDE platform and to reach an higher degree of expressivity, the stock features of QML have been expanded with the following features, that strictly follow the Plasmoid JavaScript API:

== Plasmoid object ==
Every QML plasmoid will have an object called ''plasmoid'', that will give access to the configuration, the formfactor, immutability and so on. It offers the same api as the object with the same name in the Javascript API.

== Localization ==
It's possible to localize strings with the usual i18n(), i18nc(), i18np() global functions

== Extra types ==
Some extra types are available from withing JavaScript, namely

* KConfigGroup: it's an object with its cnfig keys readable and writable as properties
* QIcon: can be constructed with QIcon("fdo name") such as QIcon("konqueror")
* KJob
* Plasma Service api

= Plasma specific imports =
To use some Plasma specific features is necessary to use some particular QML imports.

== Plasma Core ==
org.kde.plasma.core
This is the import that lets you access to the most important Plasma Core features.

=== DataSource ===
Used to connect to a dataengine

=== DataModel ===
Attaches to a DataSource, makes possible to use a dataengine as a model for a QML ListView, GridView, PathView and so on

=== Svg ===
Loads a Plasma Svg, it's not the visual item

=== SvgItem ===
Visual item that paints a Svg

=== FrameSvg ===
Loads a Plasma FrameSvg, it's not the visual item.

=== FrameSvgItem ===
Visual item that displays a Plasma FrameSvg

== Extra Qt features ==
org.kde.qtextraimports

* QPixmapItem
* QImageItem
* QIconItem

== Plasma Widgets in QML ==
To use standard plasma widgets (e.g. Plasma::LineEdit, etc.), you simply add an import line for them.
All properties, signals and slots from ordinary Plasma widgets are available there.
Those widgets are provided as a transition tool, intended to be replaced by the Plasma version of QtComponents.

<code javascript>
import QtQuick 1.0
import org.kde.plasma.graphicswidgets 0.1 as PlasmaWidgets

Item {
width: 64
height: 64
PlasmaWidgets.IconWidget {
id: icon
Component.onCompleted: setIcon("flag-red")
anchors.centerIn: parent
}
}
</code>

Development/Tutorials/Plasma/JavaScript/DataEngine

2011-06-09T10:18:04Z

Aseigo:

{{TutorialBrowser|

series=JavaScript Plasmoids|

name=Getting Data|

pre=[[../GettingStarted|Getting Started: Creating and running your first plasmoid in JavaScript]]|

next=[[../NowPlaying|Now Playing: Advanced DataEngine Usage Example]]|

reading=[[../API|JavaScript Plasmoid API reference]]
}}

== Abstract ==

Now that you've [[Development/Tutorials/Plasma/JavaScript/GettingStarted|seen how to create a JavaScript plasmoid]], we're going to move on to getting data into it.

Plasma has a data abstraction mechanism called DataEngines. You can ask for a DataEngine by name, request a source from it (again, by name) and you get data back from it, either at fixed intervals or whenever it is updated by the DataEngine internally. The data is a map (which is the same as an object in JavaScript) of string keys to data.

In this example, we'll get the local time from the time engine.

== Connecting Engines to plasmoid.dataUpdated ==

Our <tt>contents/code/main.js</tt> will have the following content:

<code>
layout = new LinearLayout(plasmoid);

label = new Label();
layout.addItem(label);

plasmoid.dataUpdated = function(name, data) {
label.text = data.Time;
}

dataEngine("time").connectSource("Local", plasmoid, 500);
</code>

There are two new things in this plasmoid. We've implemented <tt>plasmoid.dataUpdated</tt>, and connected a data engine source to it.

If you connect a data engine source to <tt>object</tt>, when there is an update for that source the method <tt>object.dataUpdated</tt> is called with two arguments: the name of the source and a map containing the data provided by the source.

In this case, <tt>plasmoid.dataUpdated</tt> gets called with <tt>"Local"</tt> as the first argument and the following object as the second argument (on my machine right now):
<code>
{
Timezone_Continent: 'Europe',
Offset: 3600,
Timezone: 'Europe/London',
Time: new Date('Sun May 17 20:06:20 2009 GMT+0100'),
Timezone_City: 'Guernsey'
}
</code>

The last line of the script does the actual connection. We select the <tt>"time"</tt> data engine and request the <tt>"Local"</tt> source from it, which provide the local time. We tell it to connect to the <tt>plasmoid</tt> object and force an update every 500ms (every half a second).

If we left off the last parameter to <tt>connectSource</tt> (ie: didn't provide an update interval), then the source would be updated when there was new data available. This doesn't make much sense for a clock, where the time is continually changing, so would actually get no updates at all if you did this. However, there are other data engines (such as the "soliddevice" engine) where you only want to be notified when something changed, and in this case you would leave off the update interval.

== Connecting Engines to Plasma Interface Elements ==
A number of Plasma interface elements support connecting DataEngines directly to them. These include:

* Label
* Meter
* TextEdit

With these widgets, one can simply direct the DataEngine to update the widget directly and it will attempt to display the data. So in our example we could also write it as:

<code>
layout = new LinearLayout(plasmoid);

label = new Label();
layout.addItem(label);

dataEngine("time").connectSource("Local", label, 500);
</code>

While this is not as flexible as implementing <tt>plasmoid.dataUpdated</tt>, it can be a useful technique.

== Connecting Engines to Arbitrary Functions ==

It is also possible to connect DataEngines to any Javascript function by passing it in as an argument to connectSource. The function can be "in-line" such as in this example:

<code>dataEngine("time").connectSource("Local", function(source, data) { print(source); } )</code>

or reference a function elsewhere in the script as seen here:

<code>function printSourceName(source, data) { print(source); }

dataEngine("time").connectSource("Local", printSourceName)</code>

== Disconnecting Engines ==

To disconnect a source, use the disconnectSource function from a DataEngine object. disconnectSource is symmetrical to connectSource and takes the name of the source and the target. The only difference is that disconnectSource does not take an optional time parameter as connectSource does.

<code>dataEngine("time").connectSource("Local", plasmoid);</code>

== Pro tip: plasmaengineexplorer ==

To find out what engines are available and what sources they provide, run
<code>
plasmaengineexplorer
</code>

You can choose from any of the installed data engines and request a source, including setting an update interval. Just remember that when you are reading the data in JavaScript, spaces in the keys provided by the sources are replaced by underscores. So each source in the <tt>time</tt> engine provides a "Timezone Continent" key, but in JavaScript you would access that as <tt>data.Timezone_Continent</tt> or <tt>data["Timezone_Continent"]</tt>.

Development/Tutorials/Plasma/JavaScript/API

2011-05-27T09:39:36Z

Aseigo: /* Extensions */

= Introduction to the Plasmoid JavaScript API =

This document provides an overview/reference of the Simplified JavaScript API for Plasmoids. The "Simplified" refers to the fact that it isn't a full binding to all of Qt or KDE's libraries, but a highly focused set of bindings designed to make writing Plasmoids fast and easy, while remaining powerful.

The API in this documentation covers the JavaScript API as it appears in the KDE Software Compilation as of version 4.4, unless otherwise noted. This API ships as part of the KDE Base Runtime package, so can be relied on being there by any application that is Powered By KDE.

If you have not done so already, please read the [http://websvn.kde.org/trunk/KDE/kdebase/workspace/plasma/design/plasmoids "plasmoid" design document] first.

== What Is A Simplified JavaScript Plasmoid? ==

This document describes the native Plasma API available to Simplified JavaScript Plasmoids. What makes them "Simplified" is that they do not have access to the entire C++ API in the Plasma, KDE and Qt libraries (let alone things lower in the API stack). This helps ensure that these Plasmoids are more likely to work properly between releases as changes in underlying API don't affect them as well as allowing Plasma to offer stronger security guarantees around them.

To denote that this Plasmoid is a Simplified JavaScript widget, ensure that in the metadata.desktop file there is this line:

X-Plasma-API=javascript

What follows is a description of the runtime environment available to a Simplified JavaScript Plasmoid.

== QtScript ==

The Simplified JavaScript API is powered by Qt's QtScript system which provides access to a full featured ECMA Script interpreter. If it works in ECMA Script, it will work in a Simplified JavaScript Plasmoid. As an interesting implementation note, QtScript uses the high performance ECMA Script interpreter from WebKit and shares this code with QtWebKit.

On top of the ECMA Script language, QtScript provides Qt integration features. Probably the most useful one in this context is the use of signals and slots which is Qt's callback mechanism. Signals may be emitted in QtScript by calling the signal method in question, a signal can be connected to a slot by using the connect() method (and disconnected with disconnect()) and any function defined in the Plasmoid may be used as a slot. For example: <code javascript="javascript">
function onClick()
{
print("We got clicked!")
}

function onFirstClick()
{
print("First click!")
button.clicked.disconnect(onFirstClick)
}

button = new PushButton
button.clicked.connect(onClick)
button.clicked.connect(onFirstClick)
button.clicked()
</code> This will print out:

<code>
We got clicked!
First click!
</code>

on the console when the Plasmoid starts, and the "We got clicked!" again whenever the button is clicked by the user.

The object that emitted the signal that caused a slot to be called can be retrieved using the ''QObject'' '''sender''' read-only property of the global '''plasmoid''' object.

== Events (API v2) ==

Starting in API v2, it is possible register functions as event handlers. To register an event handler, use:

* '''addEventListener(String event, Function listener)'''

The event parameter is the name of the event (see list at end of section for known events) and the handler parameter is the function that will be called whenever the event occurs. Event names are not case sensitive. An event object will be passed into the handler, and the type and behavior of that object is event specific.

Any number of event handlers may be added to a given event, and one handler may be registered to any number of events. The order of execution of event handlers is not guaranteed.

To remove an event handler, use:

* '''removeEventListener(String event, Function listener)'''

The function passed in will no longer be called as a result of the event occurring. Any currently pending calls to the listener are still made, however.

If an event handler is registered using addEventListener, then any callback in the global plasmoid object that may be related to the same event will be suppressed. For instance, if an event handler is registered using addEventListener for the paintInterface event, then plasmoid.paintInterface will not be called.

=== Input Events (API v2) ===

Following are the input events which are recognized on the Plasmoid along with the type of event object passed in to registered event listeners:

* HoverEnter: HoverEvent Object
* HoverLeave: HoverEvent Object
* HoverMove: HoverEvent Object
* KeyPress: KeyEvent Object
* KeyRelease: KeyEvent Object
* MouseDoubleClick: MouseEvent Object
* MouseMove: MouseEvent Object
* MousePress: MouseEvent Object
* MouseRelease: MouseEvent Object
* Wheel: WheelEvent Object

Example:

<code javascript>
// anonymous function as a listener on KeyPress
plasmoid.addEventListener('KeyPress', function(a) { print(a.key) })

function output()
{
print('Hover Event!')
}

function hovered(event)
{
plasmoid.busy = true
plasmoid.removeEventListener('HoverEnter', output)
}

function unhovered(event)
{
plasmoid.busy = false
}

plasmoid.addEventListener('HoverEnter', hovered)
plasmoid.addEventListener('HoverLeave', unhovered)
plasmoid.addEventListener('HoverEnter', output)
plasmoid.addEventListener('HoverLeave', output)
</code>

==== HoverEvent (API v2) ====

==== KeyEvent (API v2) ====

==== MouseEvent (API v2) ====

==== WheelEvent (API v2) ====

=== Addon Events (API v3) ===

The following two events are used in conjuction with Addons. See the Addons section for more information on Addons.

* addonCreated: Object addOn
* newAddonsAvailable

== The Global plasmoid Object ==

There is a global object available to the Plasmoid called, appropriately, "plasmoid". It has a number of useful properties (some of which are read only, but many of which are read/write), functions, constant values and callbacks. Each are enumerated below.

=== Callbacks ===

See the section on Events above.

There are some events that are generated by Plasma for the Plasmoid. These can often be caught by providing a function assigned to a specific name in the plasmoid object. For instance, to get notified of form factor changes, one would provide a formFactorChanged method as follows: <code javascript="javascript">
plasmoid.formFactorChanged = function() {

print("the form factor has changed to: " + plasmoid.formFactor())

}
</code>

The following callbacks are used to notify the Plasmoid of changes in its running environment:

* '''configChanged()'''
* '''currentActivityChanged()'''
* '''formFactorChanged()'''
* '''immutabilityChanged()'''
* '''locationChanged()'''
* '''sizeChanged()'''

Other callbacks include:
* '''dataUpdated(String source, Map[String, Any] data)''': used to pass in DataEngine updates
* '''activate()''': called when the widget is activated by the user, e.g. by a keyboard shortcut. Useful for setting the focus on a specific input widget, for instance. (API v2)
* '''initExtenderItem(Extender extender)''': Called when an Extender should be set up. (API v2)
* '''popupEvent(boolean shown)''': called on PopupApplets when the popup is shown or hidden. (API v2)

In API v2, all of these callbacks can also be used as events. So, for instance, instead of implementing plasmoid.popupEvent, one could also write:

<code javascript>plasmoid.addEventListener('popupEvent', function(shown) { print('shown? ' + shown) } )</code>

This would also suppress any calls to plasmoid.popupEvent.

Further documentation on these callbacks can be found in the relevant sections below.

=== Environment ===

A set of read-only properties (and in most cases notification functions) that tell the Plasmoid about its current environment:

* '''apiVersion''': the integer version of the Simplified JavaScript API in the current execution environment; can be used to change behaviour or usage of functions depending on the version number.

* '''formFactor''': one of Planar (e.g. on a desktop or in an application main view), Horizontal, Vertical or MediaCenter. When the form factor changes, the plasmoid.formFactorChanged function, if defined in the Plasmoid, is called.

* '''size''': the size of the Plasmoid, expressed in QSizeF (explained below). when it changes, plasmoid.sizeChanged() will be called.

* '''location''': one of Floating (no specific location), Desktop (on the application's main view are), FullScreen, LeftEdge, RightEdge, TopEdge or ButtomEdge. When the location changes, the plasmoid.locationChanged function, if defined in the Plasmoid, is called.

* '''immutable''': this property is set to true when the Plasmoid is set to not be movable or otherwise changeable, and false otherwise. Configuration is still usually allowed in this state. When the immutability changes, the plasmoid.immutabilityChanged function, if defined in the Plasmoid, is called.

* '''currentActivity''': the current contextual activity name. When the current activity changes, the plasmoid.currentActivityChanged function, if defined in the Plasmoid, is called.

* '''shouldConserveResources''': true if the plasmoid should not be doing anything that would create too much draw on power, e.g. when on a device with low battery power it may be a good idea not to run a computationally expensive but optional animation

* '''userConfiguring''': true if the user configuration interface is currently being displayed.

=== Properties ===
A set of read/write properties that allow the Plasmoid to set various visual or functional properties:

* ''AspectRatioMode'' '''aspectRatioMode''': defines how to treat the aspect ratio of a Plasmoid when resizing it. See the [[#AspectRatioMode|AspectRatioMode]] documentation for values and their meaning.

* ''BackgroundHints'' '''backgroundHints''': defines how the background of the widget is rendered. See the [[#BackgroundHints|BackgroundHints]] documentation for values and their meaning.

* ''boolean'' '''busy''': set to true when the Plasmoid is currently processing or waiting for data and the user interface should be blocked while doing so; will generally show a full-Plasmoid animated overlay to denote business

=== Geometry ===

Read Only Properties:

* ''QRectF'' '''rect''': the current rect of the Plasmoid; note that the top left may be not be the origin point (0,0)

Functions:

* '''resize(width, height)'''
* '''setMinimumSize(width, height)'''
* '''setPreferredSize(width, height)'''
* '''setBackgroundHints(background)''' - use '''NoBackground''' as value if you want to remove the default plasmoid background box.
* '''popupIcon(QIcon("some icon"))''' - set icon to show when the plasmoid is added to the taskbar. NOTE if the plasmoid is made in QML, you MUST specify a default size for the main Item. This size will be used for the plasmoid when added to the taskbar

=== Painting and Layout ===

To paint directly on to the canvas, a widget may implement the paintInterface function in the plasmoid object:
<code javascript>
plasmoid.paintInterface = function(painter) { /* painting code goes here*/ }
</code>
See the Painting section below for information about helpful classes and functions that can be used when implementing a paintInterface function.

Read/Write Properties:

* ''Layout'' '''layout''': the QGraphicsLayout associated with the Plasmoid for laying out top level items; this property is read-write, though the property is not usually set as one can simply do "new LinearLayout" (or one of the other layout classes provided) and it will be automatically associated with the Plasmoid.

Functions:

* '''update()''': triggers a full repaint of the Plasmoid.
* '''update(QRectF rect)''' triggers a repaint of the rect area of the Plasmoid.
* '''failedToLaunch(bool failed[, string reason])''' sets the launch status of the Plasmoid; if set to true, the script will stop executing and the reason message, if any, will be displayed to the user.

=== Access To Packaged Files ===

Functions:

* ''string'' '''file(string type[, string fileName])''': returns the path to a file in the Plasmoid package of the given type, optionally with a file name to match, e.g. <code javascript>var path = plasmoid.file("mainscript")</code> or <code javascript>var pm = new QPixmap(plasmoid.file("images", "mypixmap.png"))</code>

* ''bool'' '''include(string filename)''': attempts to include the script defined from the package's code directory

=== Configuration Data ===
Configuration values can be defined using [[Development/Tutorials/Using_KConfig_XT|KConfig XT]] XML files in the {{path|contents/config/}} directory of the Plasmoid's package. The default file that is looked for and used is {{path|contents/config/main.xml}}.

==== Accessing Configuration Data ====
Read-write properties:
* ''String'' '''activeConfig''': The current active configuration description. For instance, setting it to "foo" would cause the Plasmoid to try and reference the {{path|contents/config/foo.xml}} KConfigXT file. Setting this to an empty string will switch to the main.xml file.

Functions:
* ''any'' '''readConfig(String key)''': reads the value from the configuration data for the given key as defined by the currently active configuration.

* '''writeConfig(String key, any value) ''': writes a value to the configuration store under the given key

==== User Customization ====

User customization can be offered by providing a Qt Designer file called {{path|contents/ui/config.ui}} in the Plasmoid's package.

Callbacks:
* '''configChanged()''': callback function called when the configuration is changed external to the Plasmoid, e.g. when the user changes settings in a configuration dialog.

=== Context menu ===

It's possible to add some items to the popup menu of the Plasmoid.

Functions:
* '''setAction(name, text, icon, shortcut)''': adds an item to the context menu with the given text and icon; you need to define '''plasmoid.action_<name>''' function, where <name> is the first argument for setAction call, and this function will be called each time user clicks the item

* '''removeAction(name)''': removes the item

== Global Enumerations ==
In the global namespace are a set of useful enumerations that can be used with various classes in the Simplified Javascript Plasmoid API. These include:

=== AspectRatioMode ===
* '''IgnoreAspectRatio''': The Plasmoid can be freely resized
* '''KeepAspectRatio''': The Plasmoid keeps a fixed aspect ratio
* '''Square: The Plasmoid is always a square
* '''ConstrainedSquare''': The Plasmoid is no wider (in horizontal formfactors) or no higher (in vertical ones) than a square
* '''FixedSize''': The Plasmoid cannot be resized

=== FormFactor ===
* '''Planar''': The Plasmoid lives in a plane and has two degrees of freedom to grow. Optimize for desktop, laptop or tablet usage: a high resolution screen 1-3 feet distant from the viewer.
* '''MediaCenter''': As with Plasmoid the applet lives in a but the interface should be optimized for medium-to-high resolution screens that 5-15 feet distant from the viewer. Sometimes referred to as a "ten foot interface".
* '''Horizontal''': The Plasmoid is constrained vertically, but can expand horizontally.
* '''Vertical''': The Plasmoid is constrained horizontally, but can expand vertically.

=== Location ===
* '''Floating''': Free floating. Neither geometry or z-ordering is described precisely by this value.
* '''Desktop''': On the planar desktop layer, extending across the full screen from edge to edge
* '''FullScreen'''
* '''TopEdge'''
* '''BottomEdge'''
* '''LeftEdge'''
* '''RightEdge'''

=== AnimationDirection ===
* '''AnimationForward'''
* '''AnimationBackward'''

=== BackgroundHints ===
* '''NoBackground'''
* '''StandardBackground'''
* '''TranslucentBackground'''
* '''DefaultBackground'''

=== QtAlignment ===
* QtAlignLeft
* QtAlignRight
* QtAlignHCenter
* QtAlignJustify
* QtAlignTop
* QtAlignBottom
* QtAlignVCenter

If you need to align something in the center (both horizontally and vertically) you can sum the constans.

=== QtAnchorPoint ===
* QtAnchorLeft
* QtAnchorRight
* QtAnchorBottom
* QtAnchorTop
* QtAnchorHorizontalCenter
* QtAnchorVerticalCenter

=== QtCorner ===
* QtTopLeftCorner
* QtTopRightCorner
* QtBottomLeftCorner
* QtBottomRightCorner

=== QtMouseButton ===
* QtNoButton
* QtLeftButton
* QtRightButton
* QtMidButton
* QtXButton1
* QtXButton2

=== QtOrientation ===
* QtHorizontal
* QtVertical

=== QtScrollBarPolicy ===
* QtScrollBarAsNeeded
* QtScrollBarAlwaysOff
* QtScrollBarAlwaysOn

=== QtSizePolicy ===
* QSizePolicyFixed
* QSizePolicyMinimum
* QSizePolicyMaximum
* QSizePolicyPreferred
* QSizePolicyExpanding
* QSizePolicyMinimumExpanding
* QSizePolicyIgnored

=== Theme Colors (API v3) ===
* TextColor
* HighlightColor
* BackgroundColor
* ButtonTextColor
* ButtonBackgroundColor
* LinkColor
* VisitedLinkColor

=== Status ===
* UnknownStatus The status is unknown
* PassiveStatus The Item is passive
* ActiveStatus The Item is active
* NeedsAttentionStatus The Item needs attention
* AcceptingInputStatus The Item is accepting input

== User Interface Elements ==

=== Plasma Widgets ===

The Plasma framework provides a set of standard user interface elements such as pushbuttons and checkboxes for use in Plasmoids, and these are available from the Simplified Javascript API as well. These elements follow the Plasma style and other conventions so that widgets blend well both visually and functionally with other Plasma elements.

Note that some UI elements have functions that are synonymous with a read-write property. In those cases, the function can serve as a slot and be connected to signals for easy setting of the property.

=== DataEngine-Aware UI Elements ===
Some of the UI elements are able to accept data directly from DataEngines. These widgets will have a dataUpdated function and can be passed into the DataEngine::connectSource method successfully.

DataEngine-aware UI elements include:

* Label
* TextEdit
* Meter

=== Common Properties ===

By default, all of the Plasma user interface elements have the following properties:

* ''String'' '''objectName'''
* ''number'' '''opacity'''
* ''boolean'' '''enabled'''
* ''boolean'' '''visible'''
* ''QPointF'' '''pos'''
* ''number'' '''x'''
* ''number'' '''y'''
* ''number'' '''z'''
* ''number'' '''rotation'''
* ''number'' '''scale'''
* ''QPointF'' '''transformOriginPoint'''
* ''QPalette'' '''palette'''
* ''QFont'' '''font'''
* ''QSizeF'' '''size'''
* ''QtFocusPolicy'' '''focusPolicy'''
* ''QRectF'' '''geometry'''

=== Common Signals ===

* '''opacityChanged()'''
* '''visibleChanged()'''
* '''enabledChanged()'''
* '''xChanged()'''
* '''yChanged()'''
* '''zChanged()'''
* '''rotationChanged()'''
* '''scaleChanged() '''

=== UI Element Gallery ===

==== CSS Styleable UI Elements ====

Most UI Elements are able to have their appearance adjust using a CSS stylesheet. All of these elements have the following read/write property:

*''String'' '''styleSheet''': A CSS stylesheet describing visual properties to apply to the widget; see [http://doc.trolltech.com/4.5/stylesheet.html the Qt Documentation for more information]

===== CheckBox =====
Read-write properties:
* ''String'' '''text'''
* ''String'' '''image'''
* ''boolean'' '''checked'''
* '''toggled(bool)'''

===== ComboBox =====
Read-only properties:
* ''number'' '''count''': (API v 3) the number of items in the combobox

Read-write properties:
* ''String'' '''text''': the text of the currently selected item in the combobox
* ''number'' currentIndex: (API v 3) the index of the current item

Funtions:
* '''clear()'''

Signals:
* '''activated(String)'''
* '''textChanged(String)'''
* '''currentIndexChanged(number)'''

===== Frame =====
Read-write properties:
* ''Shadow'' '''frameShadow'''
* ''String'' '''text'''
* ''String'' '''image'''

Enumerations:
* '''Shadow'''
* '''Plain'''
* '''Raised'''
* '''Sunken'''

===== GroupBox =====
Read-write properties:
* ''String'' '''text'''

===== Label =====
Read-write properties:
* ''String'' '''text'''
* ''String'' '''image'''
* ''number'' '''alignment''' (see [[#QtAlignment]] for the valid values)
* ''boolean'' '''hasScaledContents'''
* ''boolean'' '''textIsSelectable''' (since 4.4.1)
* ''boolean'' '''wordWrap''' (API v2)

Functions:
* '''dataUpdated(String, Data)'''

Signals:
* '''linkActivated(String)''': emitted when a link is clicked; includes the URL of link that is clicked; this is only available when textIsSelectable
* '''linkHovered(String)''': emitted when a link is hovered

===== LineEdit =====
Read-write properties:
* ''String'' '''text'''
* ''boolean'' '''clearButtonShown'''

Signals:
* '''editingFinished()'''
* '''returnPressed()'''
* '''textEdited(String)'''
* '''textChanged(String)'''

===== PushButton =====
Read-write properties:
* ''String'' '''text'''
* ''String'' '''image'''
* ''QAction'' '''action'''
* ''QIcon'' '''icon'''
* ''boolean'' '''checkable'''
* ''boolean'' '''checked'''
* ''boolean'' '''down'''

Signals:
* '''pressed()'''
* '''released()'''
* '''clicked()'''
* '''toggled(bool)'''

===== RadioButton =====
Read-write properties:
* ''String'' '''text'''
* ''String'' '''image'''
* ''boolean'' '''checked'''

Signals:
* '''toggled(bool)'''

===== ScrollWidget =====
Read-write properties:
* ''QGraphicsWidget'' '''widget'''
* ''number'' '''horizontalScrollBarPolicy'''
* ''number'' '''verticalScrollBarPolicy'''
* ''QPointF'' '''scrollPosition'''
* ''QSizeF'' '''contentsSize'''
* ''QRectF'' '''viewportGeometry'''

Functions:
* '''ensureRectVisible(QRectF)'''
* '''ensureItemVisible(QGraphicsItem)'''
* '''registerAsDragHandle(QGraphicsWidget)'''
* '''unregisterAsDragHandle(QGraphicsWidget)'''

===== ScrollBar =====
Read-write properties:
* ''number'' '''singleStep'''
* ''number'' '''pageStep'''
* ''number'' '''value'''
* ''number'' '''minimum'''
* ''number'' '''maximum'''
* ''QtOrientation'' '''setOrientation'''

Functions:
* '''setValue(number)'''
* '''setOrientation(QtOrientation)'''

Signals:
* '''valueChanged(number)'''

===== Slider =====
Read-write properties:
* ''number'' '''maximum'''
* ''number'' '''minimum'''
* ''number'' '''value'''
* ''number'' '''orientation'''

Signals:
* '''sliderMoved(number)'''
* '''valueChanged(number)'''

Functions:
* '''setMaximum(number)'''
* '''setMinimum(number)'''
* '''setRange(number, number)'''
* '''setValue(number)'''
* '''setOrientation(QtOrientation)'''

===== SpinBox =====
Read-write properties:
* ''number'' '''maximum'''
* ''number'' '''minimum'''
* ''number'' '''value'''

Functins:
* '''setMaximum(number)'''
* '''setMinimum(number)'''
* '''setRange(number, number)'''
* '''setValue(number)'''

Signals:
* '''sliderMoved(number)'''
* '''valueChanged(number)'''
* '''editingFinished()'''

===== TabBar =====
Read-write properties:
* ''number'' '''currentIndex'''
* ''number'' '''count'''
* ''boolean'' '''tabBarShown'''

Functions:
* '''setCurrentIndex(number)'''
* '''insertTab(number, QIcon,String,QGraphicsLayoutItem)'''
* '''insertTab(number, QIcon,String)'''
* '''insertTab(number, String,QGraphicsLayoutItem)'''
* '''insertTab(number, String)'''
* '''addTab(QIcon,String,QGraphicsLayoutItem)'''
* '''addTab(QIcon,String)'''
* '''addTab(String,QGraphicsLayoutItem)'''
* '''addTab(String)'''
* '''removeTab(number)'''
* '''takeTab(number)'''
* '''tabAt(number)'''
* '''setTabText(number, String)'''
* '''tabText(number)'''
* '''setTabIcon(number, QIcon)'''
* '''tabIcon(number)'''

Signals:
* '''currentChanged(number)'''

===== TextEdit =====
Read-write properties:
* ''String'' '''text'''
* ''boolean'' '''readOnly'''

Functions:
* '''dataUpdated(String, Data)'''

Signals:
* '''textChanged()'''

===== ToolButton =====
:Read-write properties:

* ''''QAction'' '''action''': the action associated with this '''ToolButton'''
* ''''boolean'' '''autoRaise''': whether or not the ToolButton should raise automatically when the user interacts with it'''
* ''''String'' '''image''': path to an icon or image (e.g. in the widget's Package) to show on the ToolButton
* ''''String'' '''text''': the text shown on the ToolButton

API v2 adds:
* ''''boolean'' '''down''': whether or not the ToolButton is in the down position (since protocol version 2)

:Signals:
* '''clicked()'''
* '''pressed()'''
* '''released()'''

===== TreeView =====
Read-write properties:
* ''QAbstractModel'' '''model'''

===== VideoWidget =====
Read-writeproperties:
* ''String'' '''url'''
* ''number'' '''currentTime'''
* ''number'' '''totalTime'''
* ''number'' '''remainingTime'''
* ''Controls'' '''usedControls'''
* ''boolean'' '''controlsVisible'''

Functions:
* '''play()'''
* '''pause()'''
* '''stop()'''
* '''seek(number)'''

Signals:
* '''tick(number)'''
* '''aboutToFinish()'''
* '''nextRequested()'''
* '''previousRequested()'''

Enumerations:
* Controls
** NoControls
** Play
** Pause
** Stop
** PlayPause
** Previous
** Next
** Progress
** Volume
** OpenFile
** DefaultControls

==== Other UI Elements ====

===== BusyWidget =====
Read-write properties:
* ''boolean'' '''running'''
* ''String'' '''label'''

Signals:
* '''clicked()'''

===== FlashingLabel =====
Read-write properties:
* ''boolean'' '''autohide'''
* ''QColor'' '''color'''
* ''number'' '''duration'''

Functins:
* '''kill()'''
* '''fadeIn()'''
* '''fadeOut()'''
* '''flash(String, number, QTextOption)'''
* '''flash(String ,number)'''
* '''flash(String)'''
* '''flash(QPixmap, number, QtAlignment)'''
* '''flash(QPixmap, number)'''
* '''flash(QPixmap)'''

===== GraphicsWidget (API v3) =====
This is just a plain element with no painting or other features. It is useful primarily as a place holder, especially to contain layouts for other elements.

===== IconWidget =====
Read-only properties:
* ''QSizeF'' '''iconSize''' - the actual size of the icon given the size of the IconWidget, space reserved (if any) for text displayed, etc.

Read-write properties:
* ''String'' '''text'''
* ''String'' '''infoText'''
* ''QIcon'' '''icon'''
* ''QColor'' '''textBackgroundColor'''
* ''String'' '''svg'''
* ''QAction'' '''action'''
* ''QtOrientation'' '''orientation'''
* ''number'' '''numDisplayLines'''

Functions:
* '''setPressed(boolean)'''
* '''setUnpressed()'''
* '''setIcon(String)'''

Signals:
* '''pressed(bool)'''
* '''clicked()'''
* '''doubleClicked()'''
* '''activated()'''
* '''changed()'''

===== ItemBackground =====
Read-write properties:
* ''QRectF'' '''target'''
* ''QGraphicsItem'' '''targetItem'''

Signals:
* '''appearanceChanged()'''
* '''animationStep(qreal)'''
* '''targetReached(QRectF)'''
* '''targetItemReached(QGraphicsItem)'''

===== Meter =====
Read-write properties:
* ''number'' '''minimum'''
* ''number'' '''maximum'''
* ''number'' '''value'''
* ''String'' '''svg'''
* ''MeterType'' '''meterType'''

Functions:
* '''dataUpdated(String, Data)'''

Enumerations:
* '''MeterType'''
** BarMeterHorizontal
** BarMeterVertical
** AnalogMeter

===== Separator =====
Read-write properties:
* ''QtOrientation'' '''orientation'''

===== SignalPlotter =====
Read-write properties:
* ''String'' '''title'''
* ''String'' '''unit'''
* ''boolean'' '''useAutoRange'''
* ''number'' '''horizontalScale'''
* ''boolean'' '''showVerticalLines'''
* ''QColor'' '''verticalLinesColor'''
* ''number'' '''verticalLinesDistance'''
* ''boolean'' '''verticalLinesScroll'''
* ''boolean'' '''showHorizontalLines'''
* ''QColor'' '''horizontalLinesColor'''
* ''QColor'' '''fontColor'''
* ''number'' '''horizontalLinesCount'''
* ''boolean'' '''showLabels'''
* ''boolean'' '''showTopBar'''
* ''QColor'' '''backgroundColor'''
* ''String'' '''svgBackground'''
* ''boolean'' '''thinFrame'''
* ''boolean'' '''stackPlots'''

===== SvgWidget =====
Read-write properties:
* ''Svg'' '''svg'''
* ''String'' '''elementID'''

Signals:
* '''clicked(QtMouseButton)'''

===== WebView =====
Read-only properties:
* ''QSizeF'' '''contentsSize'''
* ''QRectF'' '''viewportGeometry'''

Read-write properties:
* ''Url'' '''url'''
* ''String'' '''html'''
* ''boolean'' '''dragToScroll'''
* ''QPointF'' '''scrollPosition'''

Signals:
* '''loadProgress(number)'''
* '''loadFinished(bool)'''

=== Layouts ===

==== LinearLayout ====
* ''number'' '''spacing'''
* ''QtOrientation'' '''orientation''' (''QtVertical'' or ''QtHorizontal'')
* ''function'' '''removeAt'''
* ''function'' '''addStretch'''
* ''function'' '''setStretchFactor'''
* ''function'' '''setAlignment'''
* ''function'' '''insertStretch'''
* ''function'' '''setItemSpacing'''
* ''function'' '''setContentsMargins'''
* ''function'' '''addItem'''
* ''function'' '''removeItem'''
* ''function'' '''insertItem'''
* ''function'' '''toString'''
* ''function'' '''activate''' (API v3)

==== AnchorLayout ====
* ''number'' '''horizontalSpacing'''
* ''number'' '''verticalSpacing'''
* ''function'' '''setSpacing'''
* ''function'' '''removeAt'''
* ''function'' '''addAnchor'''
* ''function'' '''anchor'''
* ''function'' '''addAnchors'''
* ''function'' '''addCornerAnchors'''
* ''function'' '''toString'''
* ''function'' '''activate''' (API v3)

==== GridLayout ====
* ''number '''horizontalSpacing'''
* ''number '''verticalSpacing'''
* ''function'' '''rowSpacing'''
* ''function'' '''setRowSpacing'''
* ''function'' '''columnSpacing'''
* ''function'' '''setColumnSpacing'''
* ''function'' '''rowMinimumHeight'''
* ''function'' '''setRowMinimumHeight'''
* ''function'' '''rowPreferredHeight'''
* ''function'' '''setRowPreferredHeight'''
* ''function'' '''rowMaximumHeight'''
* ''function'' '''setRowMaximumHeight'''
* ''function'' '''rowFixedHeight'''
* ''function'' '''setRowFixedHeight'''
* ''function'' '''columnMinimumWidth'''
* ''function'' '''setColumnMinimumWidth'''
* ''function'' '''columnPreferredWidth'''
* ''function'' '''setColumnPreferredWidth'''
* ''function'' '''columnMaximumWidth'''
* ''function'' '''setColumnMaximumWidth'''
* ''function'' '''columnFixedWidth'''
* ''function'' '''setColumnFixedWidth'''
* ''function'' '''remoteAt'''
* ''function'' '''setAlignment'''
* ''function'' '''setSpacing'''
* ''function'' '''setContentsMargins'''
* ''function'' '''addItem'''
* ''function'' '''toString'''
* ''function'' '''activate''' (API v3)

=== Undocumented Properties and Functions ===

There are a handful of other undocumented properties and functions available to UI elements. These are not supported or guaranteed to exist in future versions however, and as such should not be used or relied upon.

== Animations ==

=== Creating Animation Objects ===
An Animation object can be retrieved by calling the ''Animation'' '''animation(string type)''' function. The ''string'' corresponds to the type of animation, which are listed below.

New Animation objects are associated with (and therefore will animate) the Plasmoid by default. By setting the widgetToAnimate property, however, it can be assigned to animate any QGraphicsWidget desired (e.g. Plasma widgets such as push buttons, sliders, etc) .

=== Enumerations ===
All Animation objects have the following enumerations:

==== MovementDirection ====
* '''MoveUp'''
* '''MoveUpRight'''
* '''MoveRight'''
* '''MoveDownRight'''
* '''MoveDown'''
* '''MoveDownLeft'''
* '''MoveLeft'''
* '''MoveUpLeft'''

==== Reference ====
The reference point, relative to the target widget, for the animation.
* '''Center'''
* '''Up'''
* '''Down'''
* '''Left'''
* '''Right'''

==== State ====
* '''Paused'''
* '''Running'''
* '''Stopped'''

=== Common API ===
With the exception of Pause and Property animations, all animations support the following read/write properties:

* ''AnimationDirection'' '''direction''': the direction the animation should play: AnimationForward or AnimationBackward
* ''int'' '''duration''': length of the animation in ms.
* ''EasingCurveType'' '''easingCurveType''': The easing curve to use in the animation
* ''QGraphicsWidget'' '''targetWidget''': the QGraphicsWidget (e.g. a Plasma::Widget) that this animation should operate on

=== Animation Groups ===
Animations may be put into groups for convenient sequential or parallel running. Sequential groups, where the animations run one after the other, are handled by the '''AnimationGroup''' class. Parallel aniations, where the animations run simultaneously, are handled the '''ParallelAnimationGroup''' class.

Animations are added to a group by calling '''add(Animation)''' on the group object. Groups may also be added to other groups.

=== Custom Animations ===
Custom animation types can be defined using Javascript files that are included as part of the Plasmoid's package in the {{path|contents/animations/}} directory. To learn how to create such animations and access them from your Plasmoid, visit the [[Development/Tutorials/Plasma/JavaScript/Animations|Javascript Animations tutorial]].

=== Standard Animation Types ===
Below is a list of all current standard animation types and their particular read/write properties:

==== Fade ====
* ''number'' '''startOpacity''': the opacity, between 0 and 1, that the target widget starts at when the animation begins
* ''number'' '''targetOpacity''': the opacity, between 0 and 1, that the target widget will be at the end of the animation

==== Geometry ====
* ''QRectF'' '''startGeometry''': the geometry that the target widget should start with
* ''QRectF'' '''targetGeometry''': the geometry the target widget will have at the end of the animation

==== Grow ====
* ''number'' '''factor''': the factor by which the target widget will grow to by the end of the animation

==== Pause ====
* ''number'' '''duration''': the number of milliseconds to pause for

==== Property ====
Animates an object (must be a QObject internally, which includes all Plasma Widgets) by manipulating one of its properties. Property animations have the following read/write properties:

* ''any'' '''startValue'''
* ''any'' '''endValue'''
* ''ByteArray'' '''propertyName'''
* ''QObject'' '''targetObject'''
* ''number'' '''duration'''
* ''EasingCurve'' '''easingCurve'''

==== Pulser ====
* ''number'' '''targetScale''': the maximum scale of the pulse-shadow item, relative to the target widget

==== Rotate ====
* ''QtAxis'' '''axis''': the axis along which to rotate the item
* ''Reference'' '''reference''': the reference point around which to rotate the target widget
* ''number'' '''angle''': the number of degrees to rotate the item

==== RotateStacked ====
* ''MovementDirection'' '''movementDirection''': the direction to rotate the widgets in the stack around
* ''QGraphicsLayoutItem'' '''layout'''
* ''Reference'' '''reference''': the reference point around which to rotate the target widget
* ''QGraphicsWidget'' '''backingWidget''': the widget in the "back" to rotate to the front of the target widget

==== Slide ====
* ''MovementDirection'' '''movementDirection''': the direction to slide the widget
* ''number'' '''distance''': the distance to slide the widget

==== Zoom ====
* ''number'' '''zoom''': the factor by which to zoom the target widget

=== QEasingCurve ===
Used to set the progress shape of Animation objects, this class has the following read-only properties:

* ''string'' '''toString'''
* ''number'' '''valueForProgress(number progress)''': returns effective progress for the easing curve at progress. While progress must be between 0 and 1, the returned effective progress can be outside those bounds.

as well as the following read/write property:

* ''EasingCurveType'' '''type''': the shape of this easing curve

and the following enumeration:

* '''EasingCurveType'''
** Linear
** InQuad
** OutQuad
** InOutQuad
** OutInQuad
** InCubic
** OutCubic
** InOutCubic
** OutInCubic
** InQuart
** OutQuart
** InOutQuart
** OutInQuart
** InQuint
** OutQuint
** InOutQuint
** OutInQuint
** InSize
** OutSine
** InOutSine
** OutInSine
** InExpo
** OutExpo
** InOutExpo
** OutInExpo
** InCirc
** OutCirc
** InOutCirc
** InOutCirc
** OutInCirc
** InElastic
** OutElastic
** InOutElastic
** OutInElastic
** InBack
** OutBack
** InOutBack
** OutInBack
** InBounc
** OutBounce
** InOutBounce
** OutInBounce
** InCurve
** OutCurve
** SineCurve
** CosineCurve

== Painting ==

See the "[[Development/Tutorials/Plasma/JavaScript/API#Painting_and_Layout|Painting and Layout]]" section, part of the Global Plasmoid object chapter, for information on using these classes within a widget.

=== Pixmaps ===

The QPixmap object allows widgets to use pixmaps for painting. Widgets may include pixmaps in various common formats (PNG, JPEG, GIF, etc.) in the contents/images/ directory of the Plasmoid package and load them by passing the name of the file into the pixmap constructor:
<code javascript>
var pixmap = new QPixmap("myimage.png")
</code>
In addition to being used as a file load, some objects return or take pixmaps and the QPixmap object facilitates that as well.

Read-only properties:
* ''boolean'' '''null''': true if the pixmap is empty
* ''QRectF'' '''rect''': the rect of the pixmap

Functions:
* ''QPixmap'' '''scaled(number width, number height);;: returns a scaled version of the pixmap with width and height dimensions.

=== Icons ===

(Since 4.4.1)

The QIcon object provides simple access to icons. They can be constructed using a String or a QPixmap, with the String version either loading a file from disk if given an absolute path (useful for loading icons from the Plasmoid's package) or from the desktop icon theme if given just a name (e.g. "file-open").

Read-only properties:
* ''boolean'' '''null''': true if the icon is empty

Functions:
* '''addPixmap(QPixmap)''': adds another pixmap to this icon
* '''addFile(String)''': adds another file to this icon

=== SVG Images ===

Plasma makes heavy usage of SVG images. More information on this industry standard scalable vector format can be found here:

:http://www.w3.org/Graphics/SVG/

Free and Open Source Software tools for creating SVGs include Inkscape and Karbon13. Widgets may include their own SVG files in the contents/images/ directory or may use SVG images that are part of the standard Plasma Desktop Theme as documented here:

:http://techbase.kde.org/Projects/Plasma/Theme

Two classes are provide: Svg and FrameSvg. Svg allows loading and painting entire SVG documents or individual elements in an SVG document. FrameSvg extends Svg with methods to paint bordered frames from specially crafted SVG documents (see the Plasma Desktop Theme documentation for more information on this).

====Svg====
Constructors:
*'''Svg(string fileName)'''': fileName can be a file in the desktop theme or the plasmoid package

Read-only properties:
*''QSizeF'' '''size''': the current size of the svg

Read-write properties:
* ''boolean'' '''multipleImages''': whether or not the svg contains multiple separate images
* ''string'' '''imagePath''': the file path, including name of the svg
* ''boolean'' '''usingRenderingCache'': whether or not to cache rendered pixmaps; improves performance (at the cost of some disk and memory usage) for SVG data that is repeatedly rendered

Functions:
* ''QSizeF'' elementSize(String svgElemen)'''
* ''QRectF'' elementRect(String svgElemen)'''
* ''boolean'' '''hasElement(String svgElement)'''
* '''elementAtPoint(QPoint pos)'''
* ''boolean'' '''isValid()'''
* ''QPixmap'' '''pixmap(String svgElement)''': a pixmap of the element in the svg rendered to the current size
* ''QPixmap'' '''pixmap()''': a pixmap of the entire svg rendered to the current size
* '''paint(QPainter painter, QPointF point)'''
* '''paint(QPainter painter, QPointF point, String svgElement)'''
* '''paint(QPainter painter, number x, number y)'''
* '''paint(QPainter painter, number x, number y, String svgElement)'''
* '''paint(QPainter painter, QRectF destination)'''
* '''paint(QPainter painter, QRectF destination, String svgElement)'''
* '''paint(QPainter painter, number y, number width, number height)'''
* '''paint(QPainter painter, number x, number y, number width, number height, QString svgElement)'''
* '''resize(number width, number height)
* '''resize(QSizeF size)'''
* '''resize()''': resizes the SVG to the document size defined in the SVG itself

Signals:
* '''repaintNeeded()''': emitted when the SVG is in need of a repaint, such as when the theme changes and the SVG has reloaded its data

====FrameSvg====
Constructors:
* '''FrameSvg(String fileName)''': fileName can be a file in the desktop theme or the plasmoid package

Read-only properties:
* ''boolean'' '''multipleImages''': whether or not the svg contains multiple separate images

Functions:
* '''setEnabledBorders(EnabledBorders borders)''': sets which borders are enabled when painting
* ''EnabledBorders'' '''enabledBorders()''': the borders which are enabled when painting
* '''resizeFrame(QSizeF size)''': resizes the frame to size
* ''QSizeF'' '''frameSize()''': the size of the current frame
* ''number'' '''marginSize(MarginEdge margin)''': the size of the margin for a given edge
* '''getMargins(number left, number top, number right, number bottom)''': stores the margin values in the variables passed in
* ''QRectF'' '''contentsRect()''': the rect containing the contents, e.g. the size of the SVG minus the space required by the enabled borders
* '''setElementPrefix(Location)''': sets the frame element for the given location if it exists
* '''setElementPrefix(String prefix)''': sets the element prefix
* ''boolean'' '''hasElementPrefix(String prefix)''': returns true if the SVG contains a frame with the given prefix
* ''boolean'' '''hasElementPrefix(Location location)''': true if the SVG contains a frame element for the given location
* '''prefix()'''
* '''mask()'''
* '''setCacheAllRenderedFrames(bool)'''
* '''cacheAllRenderedFrames()'''
* ''QPixmap'' '''framePixmap()''': a pixmap containing the current frame at the current size
* '''paintFrame(QPainter painter)'''
* '''paintFrame(QPainter painter, QPointF target)'''
* '''paintFrame(QPainter painter, QRectF target)'''
* '''paintFrame(QPainter painter, QRectF target, QRectF source)'''

Enumerations
* '''EnabledBorder'''
** NoBorder
** TopBorder
** BottomBorder
** LeftBorder
** RightBorder
** AllBorders

=== Painting on the Canvas ===

==== QColor ====

*Constructors:
** QColor
** QColor(string colorName)
** QColor(number red, number green, number blue, number alpha)

Functions:
* '''setThemeColor(ThemeColor color)''': sets the color to the appropriate ThemeColor

Read/write properties:
* ''number'' '''red'''
* ''number'' '''green'''
* ''number'' '''blue'''
* ''number'' '''alpha'''
* ''boolean'' '''valid'''

==== QFont ====

*Constructors:
**QFont
**QFont(string fontName)
**QFont(string fontName, number pointSize)
**QFont(string fontName, number pointSize, number weight)
**QFont(string fontName, number pointSize, number weight, boolean italic)
*string key
*string lastResortFamily
*string lastResortFont
*string defaultFamily
*boolean exactMatch
*string toString
*boolean bold
*string family
*boolean fixedPitch
*undefined fromString
*boolean italic
*boolean kerning
*boolean overline
*number pixelSize
*number pointSize
*number pointSizeF
*boolean strikeOut
*number stretch
*boolean underline
*number weight
*function isCopyOf
*function resolve

====QPainter ====
* Constructors
** QPainter
** QPainter(object paintDevice): used to start a painter on a specific QWidget; rarely if ever needed in a JavaScript Plasmoid
* object background
* number backgroundMode
* object brush
* undefined setBrush
* object brushOrigin
* undefined clipping
* object clipPath
* object clipRegion
* number compositionMode
* object font
* number layoutDirection
* number opacity
* object pen
* number renderHints
* undefined transform
* object viewport
* boolean viewTransformEnabled
* object window
* object worldMatrix
* object worldTransform
* boolean worldMatrixEnabled
* object combinedMatrix
* object combinedTransform
* boolean active
* function begin
* function end
* function boundingRect
* function drawChord
* function drawConvexPolygon
* function drawArc
* function drawEllipse
* function drawImage
* function drawLine
* function drawLines
* function drawPath
* function drawPicture
* function drawPie
* function drawPixmap
* function drawPoint
* function drawPoints
* function drawPolygon
* function drawPolyline
* function drawRect
* function drawRects
* function drawRoundRect
* function drawText
* function drawTiledPixmap
* function eraseRect
* function fillPath
* function fillRect
* function resetMatrix
* function resetTransform
* function restore
* function rotate
* function save
* function scale
* function setClipRect
* function setRenderHint
* function shear
* function strokePath
* function testRenderHint
* function toString
* function translate

==== QPen ====
*Constructors:
**QPen
* object brush
* object color
* number capStyle
* number joinStyle
* number style
* number dashOffset
* number miterLimit
* number width
* boolean solid
* number red
* number green
* number blue
* number alpha
* boolean valid

==== QRectF ====
Read-only properties:
* ''boolean'' '''empty''': true if the rectangle's width or height is less than, or equal to, 0; an empty rectangle is also invalid
* ''boolean'' '''null''': true if the rectangle has both the width and the height set to 0; a null rectangle is also empty and not valid
* ''boolean'' '''valid''': true if the rectangle has a width > 0 and height 0.

Read-write properties:
* ''number'' '''left'''
* ''number'' '''top'''
* ''number'' '''bottom'''
* ''number'' '''right'''
* ''number'' '''height'''
* ''number'' '''width'''
* ''number'' '''x'''
* ''number'' '''y'''

Constructors:
* '''QRectF'''
* '''QRectF(number x, number y, number width, number height)''': Sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.

Functions:
* '''adjust(number dx1, number dy1, number dx2, number dy2)''': adds dx1, dy1, dx2 and dy2 respectively to the existing coordinates of the rectangle
* ''QRectF'' '''adjusted(number dx1, number dy1, number dx2, number dy2)''': returns a new QRectF with dx1, dy1, dx2 and dy2 added respectively to the existing coordinates of the rectangle
* '''translate(number dx, number dy)''': translates the rect by dx, dy
* '''setCoords(number x1, number y1, number x2, number y2)''': sets the coordinates of the rectangle's top-left corner to (x1, y1), and the coordinates of its bottom-right corner to (x2, y2).
* '''setRect(number x, number y, number width, number height)''': sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.
* ''boolean'' '''contains(number x, number y)''': returns true if the rect contains the point (x, y)
* '''moveBottom(number delta)'': moves the bottom by delta pixels
* '''moveLeft(number delta)''': moves the left by delta pixels
* '''moveRight(number delta)''': moves the right by delta pixels
* '''moveTo(number x, number y)''': moves the top left of the rect to point (x, y)
* '''moveTop(number delta)''': moves the top by delta pixels

==== QSizeF ====

*Constructors:
**QSizeF
**QSizeF(number width, number height)
*number height
*number width

==== QPoint ====

Constructors:
* '''QPoint'''
* '''QPoint(number x, number y)'''

Read-only properties:
* ''bool'' '''null'''
* ''number'' '''manhattanLength '''

Read-write propertie:
* ''number'' '''x '''
* ''number'' '''y'''

== Accessing Sources of Data ==

See the [[Development/Tutorials/Plasma/JavaScript/DataEngine|JavaScript Plasmoid DataEngine tutorials]]

=== Global Functions to Access DataEngines and Services ===
* dataEngine(string name): returns a DataEngine object
* service(string dataEngineName, string sourceName): returns a ServiceObject, see also DataEngine::serviceForSource

=== DataEngine ===
Read-only properties:
* ''Array[String]'' '''sources'''
* ''boolean'' '''valid'''
* ''String'' '''icon'''
* ''String'' '''name'''

Signals:
* '''sourceAdded(String sourceName)'''
* '''sourceRemoved(String sourceName)'''

Functions:
* '''serviceForSource(String sourceName)'''
* '''connectSource(String sourceName, Object connectTo[, number interval[, IntervalAlignment alignment] ])''': if the object passed in as the object to connect to is the plasmoid object, then the plasmoid.dataUpdated(String source, Map[String, Any] data) callback will be called if it exists
* '''connectAllSources(Object connectTo[, number interval[, IntervalAlignment alignment] ])''': if the object passed in as the object to connect to is the plasmoid object, then the plasmoid.dataUpdated(String source, Map[String, Any] data) callback will be called if it exists
* '''disconnectSource(String sourceName, Object connectedTo)''': if the object passed in as the object to connect to is the plasmoid object, then the plasmoid.dataUpdated(String source, Map[String, Any] data) callback will be called if it exists
* '''Data query(String sourceName)'''

The following functions are only of interest to DataEngine reimplementations (e.g. JavaScript DataEngines):

* '''scheduleSourcesUpdated()'''
* '''removeSource(String)'''
* '''updateAllSources()'''
* '''forceImmediateUpdateOfAllVisualizations()'''
* '''DataContainer containerForSource(String)'''

=== Service ===
* function finished(Plasma::ServiceJob*)
* function operationsChanged()
* function serviceReady(Plasma::Service*)
* function setDestination(QString)
* function destination()
* function operationNames()
* function operationDescription(QString)
* function startOperationCall(KConfigGroup,QObject*)
* function startOperationCall(KConfigGroup)
* function isOperationEnabled(QString)
* function name()
* function associateWidget(QWidget*,QString)
* function disassociateWidget(QWidget*)
* function associateWidget(QGraphicsWidget*,QString)
* function disassociateWidget(QGraphicsWidget*)
* function parametersFromDescription(KConfigGroup)

== Other Functions and Classes ==
=== Print and Debug ===
* '''print(string message)''': prints message to console
* '''debug(string message)''': print message to console if it is running in a KDE debug build

=== GraphicsItem ===
This class represents an item on the canvas. Support is only provided so that GraphicsItem objects returned or taken by other objects work. There is no meaningful API provided directly in the JavaScript runtime for these objects and they should not need to be used directly.

=== QSizePolicy ===
The QSizePolicy class is a layout attribute describing horizontal and vertical resizing policy. This can be set on any graphics widget that you have using the enums provided for this (QtSizePolicy ), for example:

button = new PushButton();
button.sizePolicy = QSizePolicy(QSizePolicyMaximum, QSizePolicyFixed);

This is useful when your widgets are being laid out by a layout (specially the anchor layout).

* ''QtSizePolicy '' '''horizontalPolicy''': The horizontal component of the size policy.
* ''QtSizePolicy '' '''verticalPolicy''': The vertical component of the size policy.
* ''number'' '''horizontalStretch''': The horizontal stretch factor of the size policy.
* ''number'' '''verticalStretch''': The vertical stretch factor of the size policy.

=== IOJob ===
This object is returned by input/output access for asynchronous file and data access (see the section on Extensions for documentation on getUrl). It is used by connecting Javascript functions in your code to the relevant signals.

Functions:
* '''kill()'''
* '''suspend()'''
* '''resume()'''

Signals:
* '''data(IOJob job, ByteArray data)''': emitted whenever data arrives. If data is empty (data.length == 0) then the transmission has completed.
* '''dataReq(IOJob job, ByteArray data)''': when sending data, this signal is emitted when data is requested; add the data to be sent ot the data member, or leave it empty to signal that the process is complete and there is no more data to send
* '''finished(IOJob job)''': emitted when the transmission has completed
* '''suspended(IOJob job)''': emitted when the job has been suspeneded
* '''resumed(IOJob job)'''
* '''canceled(IOJob job)'''
* '''connected(IOJob job)'''
* '''redirection(IOJob job, Url to)'''
* '''permanentRedirection(IOJob job, Url from, Url to)'''
* '''mimetype(IOJob job, String mimetype)'''

=== QTimer ===
Read-write properties:
* ''boolean'' '''active''': true if active, false if not
* ''boolean'' '''singleShot''': true if the timer will fire once when started, false if it will fire repeatedly until stopped
* ''boolean'' '''interval''': the interval in milliseconds that the timer will trigger

Functions:
* '''start(int msec)''': starts the timer with msec as the interval
* '''start()''': starts the timer with the default interval
* '''stop()''': stops the timer

Signals:
* '''timeout()''': this signal is emitted whenever the timer interval is reached

=== Url ===
Represents a local or remote address. To create a new Url (or assign to an existing one), use the following syntax:

<code javascript>var url = new Url("http://kde.org")</code>

Read-only properties:
* ''string'' '''toString''': the URL as a String object

Read-write properties (each representing a portion of the full URL):
* ''string'' '''protocol'''
* ''string'' '''host'''
* ''string'' '''path'''
* ''string'' '''user'''
* ''string'' '''password'''

=== ByteArray ===
This class provides an array of bytes. This is often used by data centric objects, such as the Job classes returned by getUrl.

Read-only properties:
* ''number'' '''length''': the size of the array (number of bytes)

Functions:
* '''chop(number numBytes)''': chops numBytes from the end of the array
* ''bool'' '''equals(ByteArray other)'''
* ''ByteArray '''left(number len)''': return len bytes from the left of the array
* ''ByteArray '''mid(number pos, number len)''': returns an array of bytes starting a post and length len (if len is -1, it returns all remaining bytes)
* ''ByteArray '''remove(number pos, number len)''': removes len bytes starting at index pos from the array and returns it
* ''ByteArray '''right(number len)''': returns len bytes from the right of the array
* ''ByteArray '''simplified()''': returns a byte array that has whitespace removed from the start and the end, and which has each sequence of internal whitespace replaced with a single space
* ''ByteArray '''toBase64()''': returns the array encoded in base64
* ''ByteArray '''toLower()''': returns a lowercased copy of the array
* ''ByteArray '''toUpper()''': returns an uppercased copy of the array
* ''ByteArray '''trimmed()''': returns a copy of the array with whitespace remove from the start and end
* truncate(number pos): truncates the array at index pos
* ''String'' '''toLatin1String()''': returns a Latin1-ized string based on the array
* ''String'' '''toUtf8()''': (API v3) returns a string from the contents of the array using a Utf8 conversation
* ''String'' '''valueOf()''': returns the raw data in the array as a string

== Addons (API V3) ==
Plasmoids may also have plugins of their own, also written in Javascript, and which are shipped separately to the Plasmoid. These are referred to as "Addons" and are packaged similarly to a Plasmoid. For more information on creating Javascript Addons, visit the [[/JavascriptAddons|Javascript Addons tutorial]].

It is possible to list, load and be notified of new Addons having been installed for your Plasmoid.

* ''Array[AddonInformation]'' '''listAddons(string type)''': an array of available addons of the provided type. The type name maps to the X-KDE-PluginInfo-Category entry in the Addon's metadata.desktop file.
* ''boolean'' '''loadAddon(String type, String id)''': load the addon with the given id and type, return true on success. In order to be notified when the addon is successfully created, add an event listener to the "addCreated" event.

The following are the Addon events which are recognized by the Plasmoid along with the type of event objects (if any) that are passed to registered event listeners that are registered with addEventListener:

* addonCreated: Object addOn
* newAddonsAvaiable

=== AddonInformation (API V3) ===

The AddonInformation object contains the following read-only properties:

* ''String'' '''id''': the id of the Addon. Can be used with loadAddon
* ''String'' '''name''': a string suitable for showing the user, such as in a configuration dialog

== Extensions ==
An API extension is a security controlled set of functions and objects that are loaded on demand. These extensions are requested by the widget by listing the required and the optional extensions (if any) it wants loaded in its metadata.desktop file. This way, even prior to the widget being loaded, Plasma can know what it will want.

Required extensions are requested using the X-Plasma-RequiredExtensions key, and optional extensions with the X-Plasma-OptionalExtensions. For example:

<code ini>
X-Plasma-RequiredExtensions=FileDialog,MyCustomQScriptExtension
X-Plasma-OptionalExtensions=LaunchApp,HTTP
</code>

The Simplified Javascript Engine then decides if the widget will actually get that extension or not. Failure to load a required extension will result in script execution being aborted.

Each of the built-in extensions provided are described below.

=== FileDialog ===

Provides access to open and save dialog classes: OpenFileDialog and SaveFileDialog. Both are non-modal and run asynchronously, so the signals must be used. Other than the name difference (and resulting UI variance) the API for each is identical:

* Constructors
** '''OpenFileDialog'''
** '''SaveFileDialog'''
* Properties
** Read Only
*** ''array(Url)'' '''urls''': the selected file, as a Url object
*** ''Url'' '''baseUrl''', the current path (minus filename) as a Url
*** ''string '''file''': the selected file, as a string
*** ''array(string)'' '''files''': selected files (plural), as an array of strings
** Read/Write
*** ''Url'' '''url''': the current Url, can be read from when the user is done or assigned before to set the starting path
*** ''string'' '''filter''': a string representing the mimetype filter; e.g. "*.cpp|C++ Source Files\n*.h|Header files" or "*.cpp" or "*.cpp|*h"
*** ''boolean'' '''localOnly''': true to show only local files, false if network locations are Ok as well
*** ''boolean'' '''directoriesOnly''': true to only allow selection of a directory (not a file)
*** ''boolean'' '''existingOnly''': true if only existing files/directories may be selected
* Functions
** '''show()''': when called, the dialog will be shown to the user
* Signals
** '''accepted(FileDialogProxy)'''': emitted when the file dialog has been successfully accepted by the user with one or more files/directories.
** '''finished(FileDialogProxy)''': emitted when the file dialog closes, included when cancelled/closed without being accepted

=== LocalIO ===
This extension allows access to local files.

Functions:
* ''IOJob'' '''getUrl(Url url)''': attempts to fetch the file using an IOJob
* ''IOJob'' '''getUrl(String url)''': attempts to fetch the file using an IOJob
* ''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
** music
** video
** downloads
** pictures
** autostart
** desktop (should be considered deprecated for Plasma workspaces)

If a second string is passed in, it is considered a request for a specific path and the following types are recognized:
** apps - Applications menu (.desktop files).
** autostart - Autostart directories (both XDG and kde-specific)
** cache - Cached information (e.g. favicons, web-pages)
** cgi - CGIs to run from kdehelp.
** config - Configuration files.
** data - Where applications store data.
** emoticons - Emoticons themes
** exe - Executables in $prefix/bin. findExe() for a function that takes $PATH into account.
** html - HTML documentation.
** icon - Icons, see KIconLoader.
** kcfg - KConfigXT config files.
** lib - Libraries.
** locale - Translation files for KLocale.
** mime - Mime types defined by KDE-specific .desktop files.
** module - Module (dynamically loaded library).
** qtplugins - Qt plugins (dynamically loaded objects for Qt)
** services - Services.
** servicetypes - Service types.
** sound - Application sounds.
** templates - Templates for the "Create new file" functionality.
** wallpaper - Wallpapers.
** tmp - Temporary files (specific for both current host and current user)
** socket - UNIX Sockets (specific for both current host and current user)
** xdgconf-menu - Freedesktop.org standard location for menu layout (.menu) files.
** xdgdata-apps - Freedesktop.org standard location for application desktop files.
** xdgdata-dirs - Freedesktop.org standard location for menu descriptions (.directory files).
** xdgdata-mime - Freedesktop.org standard location for MIME type definitions.
** xdgdata-icon - Freedesktop.org standard location for icons.
** xdgdata-pixmap - Gnome-compatibility location for pixmaps.

The second parameter should be a specific resource to find the path to. An example might be userDataPath("data", "plasma-desktop").

=== NetworkIO ===
This extensions allows access to network addresses.

Functions:
* ''IOJob'' '''getUrl(Url url)''': attempts to fetch the file using an IOJob
* ''IOJob'' '''getUrl(String url)''': attempts to fetch the file using an IOJob

=== HTTP ===
This extension allows access to data and files via http and https.

Functions:
* ''IOJob'' '''getUrl(Url url)''': attempts to fetch the file using an IOJob
* ''IOJob'' '''getUrl(String url)''': attempts to fetch the file using an IOJob
* ''bool'' '''openUrl([string|Url] url)''': (API v4) Opens the url in the default application (or asks the user if there is no default application for the file). The url parameter may be either a string or a Url. Returns true on success, false on failure.

=== LaunchApp ===

Adds methods to the global plasmoid object that allow launching applications, running commands and opening files and urls.

* ''bool'' '''runApplication(string application[, array files])''' Runs an application by name (can reference an installed .desktop file as well as an executable in the user's $PATH) with an optional array of files. The file array may contain either Urls or strings. Returns true on success, false on failure.
* ''bool'' '''runCommand(string exe[, array args])''' Runs the executable with the given arguments. Returns true on success, false on failure.
* ''bool'' '''openUrl([string|Url] url)''': Opens the url in the default application (or asks the user if there is no default application for the file). The url parameter may be either a string or a Url. Returns true on success, false on failure.
* ''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.
* ''String'' '''applicationPath(String name)''': (scripting version >= 4) returns the full local path to a given application or .desktop file if it exists.

KDE System Administration/PlasmaDesktopScripting

2011-05-27T07:53:20Z

Aseigo: /* Locating Applications and Paths */

== ECMA Script Interaction With Plasma Shells ==

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.

== Examples ==

A set of examples can be found [https://projects.kde.org/projects/kde/kdeexamples/repository/revisions/master/show/plasma/javascript/plasma-shell-scripting 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.

== 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|For security reasons, scripts located in the user's home directory will '''not''' be run during this phase.}}

* '''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|For security reasons, scripts located in the user's home directory will '''not''' be run during this phase.}}

* '''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 <code bash>qdbus org.kde.plasma-desktop /MainApplication showInteractiveConsole</code>

{{note|This method is not available for plasma-netbook.}}

: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
<code bash>qdbus org.kde.plasma-desktop /MainApplication loadScriptInInteractiveConsole /path/to/file</code>

== Templates ==

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:

* metadata.desktop: a .desktop file describing the template
* contents/layout.js: a Javascript file containing the actual script

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:

<code ini>
[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
</code>

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.

=== Examples of Usage ===

==== Creating panels ====
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.

==== Automating tasks ====
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:

<code javascript>
var template = loadTemplate('org.kde.plasma-desktop.findWidgets')
template.findWidgets('systemtray')
</code>

==== Activity templates ====
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:

<code ini>
[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
</code>

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:
* $desktop
* $autostart
* $documents
* $music
* $video
* $downloads
* $pictures

They all expand into the path toward the user corresponding default folder.

== 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|API compatibility is guaranteed from version to version starting with KDE Software Compilation v4.4.0.}}

=== 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. 0.3
* ''String'' '''platformVersion''': the version of the KDE Platform, e.g. 0.3
* ''number'' '''scriptingVersion''': the version of the scripting API; e.g. in KDE SC 4.5 this is 2

=== 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
* ''Array[String]'' '''knownActivityTypes''': (scripting version >= 2) 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:
* ''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.
* ''Array[Activity]'' '''activities()''': returns an array of all activities that currently exist

=== 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
* ''Array[String]'' '''knownPanelTypes''': (scripting version >= 2) 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.

Functions:
* ''Panel'' '''panelById(int id)''': returns an object representing the Panel that matches the given id
* ''Array[Panels]'' '''panels()''': returns an array of all panels that currently exist

=== Activities and Panels ===
Activity and Panel objects, once 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
* ''Array[String]'' '''configKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current configuration group
* ''Array[String]'' '''configGroups''': (scriptingVersion >= 2) a list of all the groups in the current configuration group
* ''Array[String]'' '''globalConfigKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current global configuration group
* ''Array[String]'' '''globalConfigGroups''': (scriptingVersion >= 2) a list of all the groups in the current global configuration group

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
* ''String'' '''wallpaperPlugin''': (scriptingVersion >= 2) the wallpaper plugin to use with the Activity
* ''String'' '''wallpaperMode''': (scriptingVersion >= 2) the wallpaper plugin mode to use with the Activity
* ''Array[String]'' '''currentConfigGroup''': (scriptingVersion >= 2) 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
* ''String'' '''version''': (scriptingVersion >= 2) the version of the Activity or Panel

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
* '''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
* '''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
* '''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
* ''Array[String]'' '''currentGlobalConfigGroup''': (scriptingVersion >= 2) the current global configuration group path, with each entry in the array representing a sub-group, similar to currentConfigGroup. However, global configuration is shared by all instances of panels and activities of the same type.
* ''Array[Widget]'' '''widgets([String type])''': (scriptingVersion >= 2) returns all the widgets in the Panel or Activity. If the optional type is specified, only widgets matching that type will be returned.

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 list of all installed widget types can be retrieved the following read-only property:

* ''Array[String]'' '''knownWidgetTypes''' (scripting version >= 2)

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
* ''Array[String]'' '''globalConfigKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current global configuration group
* ''Array[String]'' '''globalConfigGroups''': (scriptingVersion >= 2) a list of all the groups in the current global configuration group
* ''String'' '''version''': (scriptingVersion >= 2) the version of the Activity or Panel

as well as the following read-write properties:

* ''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
* ''Array[String]'' '''currentGlobalConfigGroup''': (scriptingVersion >= 2) the current global configuration group path, with each entry in the array representing a sub-group, similar to currentConfigGroup. However, global configuration is shared by all instances of widgets of the same type.
* ''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
* ''number'' '''index''': the layout index of the widget; in a Panel this corresponds to the order the widget appears in. Changing the value of the index will change the position of the widget in Panels and may do so in some Activities as well.

and the following 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
* '''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
* '''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
* '''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:
* ''QRectF'' '''screenGeometry(number screen)''': returns a rect object representing the geometry of a screen

=== Wallpaper Plugins ===

* ''Array[String => Array[String]]'' '''knownWallpaperPlugins()''': (scripting version >= 4) returns a list of all installed wallpaper plugins. They 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 ===
* ''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.
* ''String'' '''applicationPath(String name)''': (scripting version >= 4) returns the full local path to a given application or .desktop file if it exists.
* ''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
** music
** video
** downloads
** pictures
** autostart
** desktop (should be considered deprecated for Plasma workspaces)

If a second string is passed in, it is considered a request for a specific path and the following types are recognized:
** apps - Applications menu (.desktop files).
** autostart - Autostart directories (both XDG and kde-specific)
** cache - Cached information (e.g. favicons, web-pages)
** cgi - CGIs to run from kdehelp.
** config - Configuration files.
** data - Where applications store data.
** emoticons - Emoticons themes
** exe - Executables in $prefix/bin. findExe() for a function that takes $PATH into account.
** html - HTML documentation.
** icon - Icons, see KIconLoader.
** kcfg - KConfigXT config files.
** lib - Libraries.
** locale - Translation files for KLocale.
** mime - Mime types defined by KDE-specific .desktop files.
** module - Module (dynamically loaded library).
** qtplugins - Qt plugins (dynamically loaded objects for Qt)
** services - Services.
** servicetypes - Service types.
** sound - Application sounds.
** templates - Templates for the "Create new file" functionality.
** wallpaper - Wallpapers.
** tmp - Temporary files (specific for both current host and current user)
** socket - UNIX Sockets (specific for both current host and current user)
** xdgconf-menu - Freedesktop.org standard location for menu layout (.menu) files.
** xdgdata-apps - Freedesktop.org standard location for application desktop files.
** xdgdata-dirs - Freedesktop.org standard location for menu descriptions (.directory files).
** xdgdata-mime - Freedesktop.org standard location for MIME type definitions.
** xdgdata-icon - Freedesktop.org standard location for icons.
** xdgdata-pixmap - Gnome-compatibility location for pixmaps.

The second parameter should be a specific resource to find the path to. An example might be userDataPath("data", "plasma-desktop").

=== Misc. Global Properties and Functions ===
Read-write properties:
* ''boolean'' '''locked''': whether the desktop shell and widgets are locked or not (settable)
* ''string'' '''theme''': (scripting version >= 3) the name of the desktop theme to use for the interface, e.g. default, Air, Oxygen, etc.

Read-only properties:
* ''boolean'' '''hasBattery''': whether or not the system has the ability to run on battery power, e.g. a laptop or mobile device
* ''boolean'' '''multihead''': (scripting version >= 3) true if the system is running with multiple screens in a "Xaphod" multiple display server configuration
* ''int'' '''multiheadScreen''': (scripting version >= 3) if multihead is true, contains the (real) screen id of the current screen

Functions:
* '''sleep(number ms)''': sleeps the script for the specified number of millseconds

=== QRectF ===
A rectangle class is also provided for use with Widget, Panel and screen geometry properties and functions.

Read-only properites:
* ''boolean'' '''empty''': true if the rectangle's width or height is less than, or equal to, 0; an empty rectangle is also invalid
* ''boolean'' '''null''': true if the rectangle has both the width and the height set to 0; a null rectangle is also empty and not valid
* ''boolean'' '''valid''': true if the rectangle has a width > 0 and height 0.

Read-write properties:
* ''number'' '''left'''
* ''number'' '''top'''
* ''number'' '''bottom'''
* ''number'' '''right'''
* ''number'' '''height'''
* ''number'' '''width'''
* ''number'' '''x'''
* ''number'' '''y'''

Constructors:
* '''QRectF'''
* '''QRectF(number x, number y, number width, number height)''': Sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.

Functions:
* '''adjust(number dx1, number dy1, number dx2, number dy2)''': adds dx1, dy1, dx2 and dy2 respectively to the existing coordinates of the rectangle
* ''QRectF'' '''adjusted(number dx1, number dy1, number dx2, number dy2)''': returns a new QRectF with dx1, dy1, dx2 and dy2 added respectively to the existing coordinates of the rectangle
* '''translate(number dx, number dy)''': translates the rect by dx, dy
* '''setCoords(number x1, number y1, number x2, number y2)''': sets the coordinates of the rectangle's top-left corner to (x1, y1), and the coordinates of its bottom-right corner to (x2, y2).
* '''setRect(number x, number y, number width, number height)''': sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.
* ''boolean'' '''contains(number x, number y)''': returns true if the rect contains the point (x, y)
* '''moveBottom(number delta)'': moves the bottom by delta pixels
* '''moveLeft(number delta)''': moves the left by delta pixels
* '''moveRight(number delta)''': moves the right by delta pixels
* '''moveTo(number x, number y)''': moves the top left of the rect to point (x, y)
* '''moveTop(number delta)''': moves the top by delta pixels

== Configuration Keys ==
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'''.

=== Common configuration keys ===
Here are some keys that can be used with all widgets:

* '''Share''' (true/false): Whether or not the widget is to be announces throughout the network (Share tab)

=== Common time and date keys ===
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.
* '''announceInterval''' (number ≥ 0): Interval in minutes that the time is read out loud
* '''calendarType''' (local/coptic/ethopian/gregorian/gregorian-proleptic/hebrew/hijri/indian-national/jalali/japanese/julian/minguo/thai): Calendar system to be used, defaults to local
* '''defaultTimezone''' (Local/…): Time zone to be used
* '''displayHolidays''' (true/false): Whether holidays are to be displayed
* '''holidayRegions''' (tbd): tbd
* '''holidayRegionaDaysOff''' (tbd): tbd
* '''timeZones''' (Europe/Andorra,…): Comma-separated list of timezones to be used (e. g. Europe/Andorra,Indian/Antananarivo,Asia/Aqtau)

=== Analog clock (clock) ===
* '''showSecondHand''' (true/false): self-explanatory
* '''showTimezoneString''' (true/false): self-explanatory

=== Battery status (battery) ===
* '''showBatteryString''' (true/false): Whether or not battery status is shown as overlay for the battery icon (if in systemtray or panel)
* '''showMultipleBatteries''' (true/false): Whether or not battery status is shown for each battery separately

=== Digital clock (digital-clock) ===
* '''plainClockColor''' (rrr,ggg,bbb): Color set for clock font (e. g. 192,0,0 - to be used with useCustomColor=true!)
* '''plainClockDrawShadow''' (true/false): Whether a shadow is to bed drawn (defaults to true)
* '''plainClockShadowColor''' (rrr,ggg,bbb): Color set for clock shadow (e. g. 64,97,128 - to be used with useCustomShadowColor=true!)
* '''plainClockFont''' (tbd): Font to be used for clock (e. g. Serif,12,-1,5,75,0,0,0,0,0)
* '''showDate''' (true/false): self-explanatory
* '''showDay''' (true/false): self-explanatory
* '''showSeconds''' (true/false): self-explanatory
* '''showTimezone''' (true/false): self-explanatory
* '''showYear''' (true/false): self-explanatory
* '''useCustomColor''' (true/false): Whether or not a custom color is to be used (use with plainClockColor=rrr,ggg,bbb!)
* '''useCustomShadowColor''' (true/false): Whether or not a custom shadow color is to be used (use with plainClockShadowColor=rrr,ggg,bbb!)

=== Folderview (folderview) ===
* '''alignToGrid''' (true/false): self-explanatory
* '''customIconSize''' (16/22/24/32/48/…): Use custom icon size for files/folders (use only default/common icon sizes, powers of 2)
* '''customLabel''': Use custom title rather than default path or place name
* '''drawShadows''' (true/false): Whether or not file labels are to draw shadows
* '''filter''' (0/1/2): Defines whether a filter is to be used or not (0 = No filter, 1 = Show only matching files, 2 = Hide matching files)
* '''filterFiles''': Wildcard filter to filter file names
* '''mimeFilter''': Comma-separated list of mimetypes to be filtered (shown/hidden depends on filter-setting)
* '''iconsLocked''' (true/false): Whether or not icons can be moved
* '''numTextLines''' (number > 0): Amount of lines a file name can have before it is truncated
* '''url''': Folder URL to be displayed (e. g. desktop:/// or file:///home/yourusername)
* '''sortColumn''' (-1/0/1/2/3/4/5): The way files and folders are sorted (-1 = No sorting, 0 = By name, 1 = By size, 2 = By type, 3 = By date)
* '''sortDirsFirst''' (true/false): Whether or not folders are displayed before files (defaults to true)
* '''textColor''' (rrr,ggg,bbb): Color the icon labels will have

=== Kickoff menu (launcher) ===
* '''SwitchTabsOnHover''' (true/false): self-explanatory
* '''ShowAppsByName''' (true/false): Apps are sorted by name rather than by description

=== Pager (pager) ===
* '''displayedText''' (0/1/2): Text to be shown on individual virtual desktops (0 = Workspace number, 1 = Workspace title, 2 = None)
* '''ShowWindowIcons''' (true/false): Whether or not the application icon is to be shown on each individual window
* '''currentDesktopSelected''' (0/1/2): Defines what should happen if the user clicks on the virtual desktop that is currently active (0 = Nothing, 1 = Show Workspace, i. e. minimize windows, 2 = Show Dashboard)
* '''rows''' (number > 0): Amount of rows the pager should have. (Note: ''This is a global option, so you need to use '''writeGlobalConfig''' instead'')

=== Notifications (notifications) ===
{{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}}
* '''AutoHidePopup''' (true/false): Whether or not popups are to be hidden automatiaclly
* '''ShowJobs''' (true/false): Whether or not jobs are to be shown (e. g. file transfer progress)
* '''ShowNotifications''' (true/false): Whether or not notifications are to be shown

=== Removable media notifier (notifier) ===
* '''ShowDevices''' (0/1/2): Defines what kind of devices are to be shown (0 = Removable media only, 1 = Non-removable media only, 2 = All)
{{note|Auto-mount settings and device actions are not stored in this Plasmoid’s settings.}}

=== Taskbar (tasks) ===
* '''groupingStrategy''' (0/1/2): Defines how taskbar entries are to be grouped (0 = Never, 1 = Manually, 2 = By Program Name)
* '''groupWhenFull''' (true/false): Only group when taskbar is full (to be used with groupingStrategy=2 only!)
* '''highlightWindows''' (true/false): Highlight a window if your mouse cursor is hovering its taskbar entry (requires Desktop Compositing and “Highlight windows” effect enabled to work)
* '''maxRows''' (number > 0): Amount of rows taskbar entries can take
* '''forceRows''' (true/false): Force row setting for taskbar entries
* '''showOnlyCurrentActivity''' (true/false): Show only windows from current activity
* '''showOnlyCurrentDesktop''' (true/false): Show only windows from current virtual desktop
* '''showOnlyCurrentScreen''' (true/false): Show only windows from current screen (multi monitor setup)
* '''showTooltip''' (true/false): Whether or not tooltips are to be shown
* '''sortingStrategy''' (0/1/2/3): How taskbar entries are to be sorted (0 = Never, 1 = Manually, 2 = Alphabetically, 3 = By Desktop)

=== System Tray ===
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.

==== Generic System Tray configuration keys ====
* '''DefaultAppletAdded''' (true/false): Remembers whether the default plasmoids (networkmanagement, device manager, notifications) have already been added(??)
* '''ShowApplicationStatus''' (true/false): Show system tray icons of applications that belong to the group “Applications”
* '''ShowCommunications''' (true/false): Show system tray icons of applications that belong to the group “Applications” (i. e. Messenger, IRC chat)
* '''ShowHardware''' (true/false): Show system tray icons of applications that belong to the group “Hardware” (i. e. volume control, printer applet)
* '''ShowSystemServices''' (true/false): Show system tray icons of applications that belong to the group “System Services” (i. e. Nepomuk Indexing Agent)
* '''ShowUnknown''' (true/false): Show system tray icons that do not belong into one of the categories mentioned above (or that do not use KDE’s system tray protocol and thus do not provide such information)
* '''alwaysShown''': Comma-separated list of widgets and entries that are to be shown all the time (e. g. KMix,notifier)
* '''hidden''': Comma-separated list of widgets and entries that are to be hidden all the time (e. g. Nepomuk Indexing Agent,Klipper,kmail)
{{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}}

==== 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.
<code bash>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(?)</code>

Now you can “create” the plasmoid by adding a “plugin” configuration entry
<code bash>systray.writeConfig("plugin","notifier") // This will add a Device Notifier Plasmoid</code>
You can modify the plasmoid’s configuration by using writeConfig.
<code bash>systray.writeConfig("property","value")</code>
To change back to the top configuration level and thus edit the systemtray plasmoid itself pass an empty array to currentConfigGroup.

==== Edit existing widgets in systemtray ====

==== Remove a widget from systemtray ====

To remove a widget, simply delete the corresponding configuration group.

KDE System Administration/PlasmaDesktopScripting

2011-05-27T07:52:14Z

Aseigo: /* Remove a widget from systemtray = */

== ECMA Script Interaction With Plasma Shells ==

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.

== Examples ==

A set of examples can be found [https://projects.kde.org/projects/kde/kdeexamples/repository/revisions/master/show/plasma/javascript/plasma-shell-scripting 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.

== 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|For security reasons, scripts located in the user's home directory will '''not''' be run during this phase.}}

* '''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|For security reasons, scripts located in the user's home directory will '''not''' be run during this phase.}}

* '''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 <code bash>qdbus org.kde.plasma-desktop /MainApplication showInteractiveConsole</code>

{{note|This method is not available for plasma-netbook.}}

: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
<code bash>qdbus org.kde.plasma-desktop /MainApplication loadScriptInInteractiveConsole /path/to/file</code>

== Templates ==

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:

* metadata.desktop: a .desktop file describing the template
* contents/layout.js: a Javascript file containing the actual script

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:

<code ini>
[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
</code>

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.

=== Examples of Usage ===

==== Creating panels ====
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.

==== Automating tasks ====
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:

<code javascript>
var template = loadTemplate('org.kde.plasma-desktop.findWidgets')
template.findWidgets('systemtray')
</code>

==== Activity templates ====
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:

<code ini>
[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
</code>

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:
* $desktop
* $autostart
* $documents
* $music
* $video
* $downloads
* $pictures

They all expand into the path toward the user corresponding default folder.

== 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|API compatibility is guaranteed from version to version starting with KDE Software Compilation v4.4.0.}}

=== 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. 0.3
* ''String'' '''platformVersion''': the version of the KDE Platform, e.g. 0.3
* ''number'' '''scriptingVersion''': the version of the scripting API; e.g. in KDE SC 4.5 this is 2

=== 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
* ''Array[String]'' '''knownActivityTypes''': (scripting version >= 2) 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:
* ''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.
* ''Array[Activity]'' '''activities()''': returns an array of all activities that currently exist

=== 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
* ''Array[String]'' '''knownPanelTypes''': (scripting version >= 2) 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.

Functions:
* ''Panel'' '''panelById(int id)''': returns an object representing the Panel that matches the given id
* ''Array[Panels]'' '''panels()''': returns an array of all panels that currently exist

=== Activities and Panels ===
Activity and Panel objects, once 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
* ''Array[String]'' '''configKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current configuration group
* ''Array[String]'' '''configGroups''': (scriptingVersion >= 2) a list of all the groups in the current configuration group
* ''Array[String]'' '''globalConfigKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current global configuration group
* ''Array[String]'' '''globalConfigGroups''': (scriptingVersion >= 2) a list of all the groups in the current global configuration group

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
* ''String'' '''wallpaperPlugin''': (scriptingVersion >= 2) the wallpaper plugin to use with the Activity
* ''String'' '''wallpaperMode''': (scriptingVersion >= 2) the wallpaper plugin mode to use with the Activity
* ''Array[String]'' '''currentConfigGroup''': (scriptingVersion >= 2) 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
* ''String'' '''version''': (scriptingVersion >= 2) the version of the Activity or Panel

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
* '''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
* '''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
* '''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
* ''Array[String]'' '''currentGlobalConfigGroup''': (scriptingVersion >= 2) the current global configuration group path, with each entry in the array representing a sub-group, similar to currentConfigGroup. However, global configuration is shared by all instances of panels and activities of the same type.
* ''Array[Widget]'' '''widgets([String type])''': (scriptingVersion >= 2) returns all the widgets in the Panel or Activity. If the optional type is specified, only widgets matching that type will be returned.

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 list of all installed widget types can be retrieved the following read-only property:

* ''Array[String]'' '''knownWidgetTypes''' (scripting version >= 2)

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
* ''Array[String]'' '''globalConfigKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current global configuration group
* ''Array[String]'' '''globalConfigGroups''': (scriptingVersion >= 2) a list of all the groups in the current global configuration group
* ''String'' '''version''': (scriptingVersion >= 2) the version of the Activity or Panel

as well as the following read-write properties:

* ''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
* ''Array[String]'' '''currentGlobalConfigGroup''': (scriptingVersion >= 2) the current global configuration group path, with each entry in the array representing a sub-group, similar to currentConfigGroup. However, global configuration is shared by all instances of widgets of the same type.
* ''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
* ''number'' '''index''': the layout index of the widget; in a Panel this corresponds to the order the widget appears in. Changing the value of the index will change the position of the widget in Panels and may do so in some Activities as well.

and the following 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
* '''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
* '''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
* '''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:
* ''QRectF'' '''screenGeometry(number screen)''': returns a rect object representing the geometry of a screen

=== Wallpaper Plugins ===

* ''Array[String => Array[String]]'' '''knownWallpaperPlugins()''': (scripting version >= 4) returns a list of all installed wallpaper plugins. They 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 ===
* ''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 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'' '''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
** music
** video
** downloads
** pictures
** autostart
** desktop (should be considered deprecated for Plasma workspaces)

If a second string is passed in, it is considered a request for a specific path and the following types are recognized:
** apps - Applications menu (.desktop files).
** autostart - Autostart directories (both XDG and kde-specific)
** cache - Cached information (e.g. favicons, web-pages)
** cgi - CGIs to run from kdehelp.
** config - Configuration files.
** data - Where applications store data.
** emoticons - Emoticons themes
** exe - Executables in $prefix/bin. findExe() for a function that takes $PATH into account.
** html - HTML documentation.
** icon - Icons, see KIconLoader.
** kcfg - KConfigXT config files.
** lib - Libraries.
** locale - Translation files for KLocale.
** mime - Mime types defined by KDE-specific .desktop files.
** module - Module (dynamically loaded library).
** qtplugins - Qt plugins (dynamically loaded objects for Qt)
** services - Services.
** servicetypes - Service types.
** sound - Application sounds.
** templates - Templates for the "Create new file" functionality.
** wallpaper - Wallpapers.
** tmp - Temporary files (specific for both current host and current user)
** socket - UNIX Sockets (specific for both current host and current user)
** xdgconf-menu - Freedesktop.org standard location for menu layout (.menu) files.
** xdgdata-apps - Freedesktop.org standard location for application desktop files.
** xdgdata-dirs - Freedesktop.org standard location for menu descriptions (.directory files).
** xdgdata-mime - Freedesktop.org standard location for MIME type definitions.
** xdgdata-icon - Freedesktop.org standard location for icons.
** xdgdata-pixmap - Gnome-compatibility location for pixmaps.

The second parameter should be a specific resource to find the path to. An example might be userDataPath("data", "plasma-desktop").

=== Misc. Global Properties and Functions ===
Read-write properties:
* ''boolean'' '''locked''': whether the desktop shell and widgets are locked or not (settable)
* ''string'' '''theme''': (scripting version >= 3) the name of the desktop theme to use for the interface, e.g. default, Air, Oxygen, etc.

Read-only properties:
* ''boolean'' '''hasBattery''': whether or not the system has the ability to run on battery power, e.g. a laptop or mobile device
* ''boolean'' '''multihead''': (scripting version >= 3) true if the system is running with multiple screens in a "Xaphod" multiple display server configuration
* ''int'' '''multiheadScreen''': (scripting version >= 3) if multihead is true, contains the (real) screen id of the current screen

Functions:
* '''sleep(number ms)''': sleeps the script for the specified number of millseconds

=== QRectF ===
A rectangle class is also provided for use with Widget, Panel and screen geometry properties and functions.

Read-only properites:
* ''boolean'' '''empty''': true if the rectangle's width or height is less than, or equal to, 0; an empty rectangle is also invalid
* ''boolean'' '''null''': true if the rectangle has both the width and the height set to 0; a null rectangle is also empty and not valid
* ''boolean'' '''valid''': true if the rectangle has a width > 0 and height 0.

Read-write properties:
* ''number'' '''left'''
* ''number'' '''top'''
* ''number'' '''bottom'''
* ''number'' '''right'''
* ''number'' '''height'''
* ''number'' '''width'''
* ''number'' '''x'''
* ''number'' '''y'''

Constructors:
* '''QRectF'''
* '''QRectF(number x, number y, number width, number height)''': Sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.

Functions:
* '''adjust(number dx1, number dy1, number dx2, number dy2)''': adds dx1, dy1, dx2 and dy2 respectively to the existing coordinates of the rectangle
* ''QRectF'' '''adjusted(number dx1, number dy1, number dx2, number dy2)''': returns a new QRectF with dx1, dy1, dx2 and dy2 added respectively to the existing coordinates of the rectangle
* '''translate(number dx, number dy)''': translates the rect by dx, dy
* '''setCoords(number x1, number y1, number x2, number y2)''': sets the coordinates of the rectangle's top-left corner to (x1, y1), and the coordinates of its bottom-right corner to (x2, y2).
* '''setRect(number x, number y, number width, number height)''': sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.
* ''boolean'' '''contains(number x, number y)''': returns true if the rect contains the point (x, y)
* '''moveBottom(number delta)'': moves the bottom by delta pixels
* '''moveLeft(number delta)''': moves the left by delta pixels
* '''moveRight(number delta)''': moves the right by delta pixels
* '''moveTo(number x, number y)''': moves the top left of the rect to point (x, y)
* '''moveTop(number delta)''': moves the top by delta pixels

== Configuration Keys ==
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'''.

=== Common configuration keys ===
Here are some keys that can be used with all widgets:

* '''Share''' (true/false): Whether or not the widget is to be announces throughout the network (Share tab)

=== Common time and date keys ===
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.
* '''announceInterval''' (number ≥ 0): Interval in minutes that the time is read out loud
* '''calendarType''' (local/coptic/ethopian/gregorian/gregorian-proleptic/hebrew/hijri/indian-national/jalali/japanese/julian/minguo/thai): Calendar system to be used, defaults to local
* '''defaultTimezone''' (Local/…): Time zone to be used
* '''displayHolidays''' (true/false): Whether holidays are to be displayed
* '''holidayRegions''' (tbd): tbd
* '''holidayRegionaDaysOff''' (tbd): tbd
* '''timeZones''' (Europe/Andorra,…): Comma-separated list of timezones to be used (e. g. Europe/Andorra,Indian/Antananarivo,Asia/Aqtau)

=== Analog clock (clock) ===
* '''showSecondHand''' (true/false): self-explanatory
* '''showTimezoneString''' (true/false): self-explanatory

=== Battery status (battery) ===
* '''showBatteryString''' (true/false): Whether or not battery status is shown as overlay for the battery icon (if in systemtray or panel)
* '''showMultipleBatteries''' (true/false): Whether or not battery status is shown for each battery separately

=== Digital clock (digital-clock) ===
* '''plainClockColor''' (rrr,ggg,bbb): Color set for clock font (e. g. 192,0,0 - to be used with useCustomColor=true!)
* '''plainClockDrawShadow''' (true/false): Whether a shadow is to bed drawn (defaults to true)
* '''plainClockShadowColor''' (rrr,ggg,bbb): Color set for clock shadow (e. g. 64,97,128 - to be used with useCustomShadowColor=true!)
* '''plainClockFont''' (tbd): Font to be used for clock (e. g. Serif,12,-1,5,75,0,0,0,0,0)
* '''showDate''' (true/false): self-explanatory
* '''showDay''' (true/false): self-explanatory
* '''showSeconds''' (true/false): self-explanatory
* '''showTimezone''' (true/false): self-explanatory
* '''showYear''' (true/false): self-explanatory
* '''useCustomColor''' (true/false): Whether or not a custom color is to be used (use with plainClockColor=rrr,ggg,bbb!)
* '''useCustomShadowColor''' (true/false): Whether or not a custom shadow color is to be used (use with plainClockShadowColor=rrr,ggg,bbb!)

=== Folderview (folderview) ===
* '''alignToGrid''' (true/false): self-explanatory
* '''customIconSize''' (16/22/24/32/48/…): Use custom icon size for files/folders (use only default/common icon sizes, powers of 2)
* '''customLabel''': Use custom title rather than default path or place name
* '''drawShadows''' (true/false): Whether or not file labels are to draw shadows
* '''filter''' (0/1/2): Defines whether a filter is to be used or not (0 = No filter, 1 = Show only matching files, 2 = Hide matching files)
* '''filterFiles''': Wildcard filter to filter file names
* '''mimeFilter''': Comma-separated list of mimetypes to be filtered (shown/hidden depends on filter-setting)
* '''iconsLocked''' (true/false): Whether or not icons can be moved
* '''numTextLines''' (number > 0): Amount of lines a file name can have before it is truncated
* '''url''': Folder URL to be displayed (e. g. desktop:/// or file:///home/yourusername)
* '''sortColumn''' (-1/0/1/2/3/4/5): The way files and folders are sorted (-1 = No sorting, 0 = By name, 1 = By size, 2 = By type, 3 = By date)
* '''sortDirsFirst''' (true/false): Whether or not folders are displayed before files (defaults to true)
* '''textColor''' (rrr,ggg,bbb): Color the icon labels will have

=== Kickoff menu (launcher) ===
* '''SwitchTabsOnHover''' (true/false): self-explanatory
* '''ShowAppsByName''' (true/false): Apps are sorted by name rather than by description

=== Pager (pager) ===
* '''displayedText''' (0/1/2): Text to be shown on individual virtual desktops (0 = Workspace number, 1 = Workspace title, 2 = None)
* '''ShowWindowIcons''' (true/false): Whether or not the application icon is to be shown on each individual window
* '''currentDesktopSelected''' (0/1/2): Defines what should happen if the user clicks on the virtual desktop that is currently active (0 = Nothing, 1 = Show Workspace, i. e. minimize windows, 2 = Show Dashboard)
* '''rows''' (number > 0): Amount of rows the pager should have. (Note: ''This is a global option, so you need to use '''writeGlobalConfig''' instead'')

=== Notifications (notifications) ===
{{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}}
* '''AutoHidePopup''' (true/false): Whether or not popups are to be hidden automatiaclly
* '''ShowJobs''' (true/false): Whether or not jobs are to be shown (e. g. file transfer progress)
* '''ShowNotifications''' (true/false): Whether or not notifications are to be shown

=== Removable media notifier (notifier) ===
* '''ShowDevices''' (0/1/2): Defines what kind of devices are to be shown (0 = Removable media only, 1 = Non-removable media only, 2 = All)
{{note|Auto-mount settings and device actions are not stored in this Plasmoid’s settings.}}

=== Taskbar (tasks) ===
* '''groupingStrategy''' (0/1/2): Defines how taskbar entries are to be grouped (0 = Never, 1 = Manually, 2 = By Program Name)
* '''groupWhenFull''' (true/false): Only group when taskbar is full (to be used with groupingStrategy=2 only!)
* '''highlightWindows''' (true/false): Highlight a window if your mouse cursor is hovering its taskbar entry (requires Desktop Compositing and “Highlight windows” effect enabled to work)
* '''maxRows''' (number > 0): Amount of rows taskbar entries can take
* '''forceRows''' (true/false): Force row setting for taskbar entries
* '''showOnlyCurrentActivity''' (true/false): Show only windows from current activity
* '''showOnlyCurrentDesktop''' (true/false): Show only windows from current virtual desktop
* '''showOnlyCurrentScreen''' (true/false): Show only windows from current screen (multi monitor setup)
* '''showTooltip''' (true/false): Whether or not tooltips are to be shown
* '''sortingStrategy''' (0/1/2/3): How taskbar entries are to be sorted (0 = Never, 1 = Manually, 2 = Alphabetically, 3 = By Desktop)

=== System Tray ===
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.

==== Generic System Tray configuration keys ====
* '''DefaultAppletAdded''' (true/false): Remembers whether the default plasmoids (networkmanagement, device manager, notifications) have already been added(??)
* '''ShowApplicationStatus''' (true/false): Show system tray icons of applications that belong to the group “Applications”
* '''ShowCommunications''' (true/false): Show system tray icons of applications that belong to the group “Applications” (i. e. Messenger, IRC chat)
* '''ShowHardware''' (true/false): Show system tray icons of applications that belong to the group “Hardware” (i. e. volume control, printer applet)
* '''ShowSystemServices''' (true/false): Show system tray icons of applications that belong to the group “System Services” (i. e. Nepomuk Indexing Agent)
* '''ShowUnknown''' (true/false): Show system tray icons that do not belong into one of the categories mentioned above (or that do not use KDE’s system tray protocol and thus do not provide such information)
* '''alwaysShown''': Comma-separated list of widgets and entries that are to be shown all the time (e. g. KMix,notifier)
* '''hidden''': Comma-separated list of widgets and entries that are to be hidden all the time (e. g. Nepomuk Indexing Agent,Klipper,kmail)
{{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}}

==== 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.
<code bash>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(?)</code>

Now you can “create” the plasmoid by adding a “plugin” configuration entry
<code bash>systray.writeConfig("plugin","notifier") // This will add a Device Notifier Plasmoid</code>
You can modify the plasmoid’s configuration by using writeConfig.
<code bash>systray.writeConfig("property","value")</code>
To change back to the top configuration level and thus edit the systemtray plasmoid itself pass an empty array to currentConfigGroup.

==== Edit existing widgets in systemtray ====

==== Remove a widget from systemtray ====

To remove a widget, simply delete the corresponding configuration group.

Development/Tutorials/Git/Feature Development Workflow

2011-05-19T08:52:29Z

Aseigo: /* Requirements */

{{warning|This page refers to a draft policy which is still to be agreed and implemented. Please take it as a reference for a work in progress project. }}

These tutorials are aimed to get people started with KDE's policy for merging and integrating changes into the repositories.

Such policies vary depending on the developer's role inside the project. Please follow the tutorial which best suits your role and profile

* [[Development/Tutorials/Git/Feature_Development_Workflow/Simple_Branch_Development|Casual Developer]] - follow this tutorial if you simply wish to contribute features or fixes OR you are a developer without specific knowledge of git. Difficulty level: easy
* [[Development/Tutorials/Git/Feature_Development_Workflow/Branch_Development_With_Merge|Core Developer with git knowledge]] - follow this tutorial if you are a developer which contributes frequently AND you have a more-than-average knowledge of git. Difficulty level: manageable
* Repository Maintainer - follow this tutorial if you are a repository maintainer or if you want to apply for becoming one. Difficulty level: relevant

Also, for your knowledge, you should check out these specific articles:

* [[Development/Tutorials/Git/Feature_Development_Workflow/Which_repository_should_I_use|Which repository should I use?]]
* [[Development/Tutorials/Git/Feature_Development_Workflow/Rationale_and_Explanation_of_Workflow|Rationale and explanation of workflow]]
* [[Development/Tutorials/Git/Feature_Development_Workflow/Rebase_vs_Merge|Rebase vs. merging: why and how]]
* [[Development/Tutorials/Git/Feature_Development_Workflow/Staging_Phase_Explained|The staging phase explained]]
* Merge strategies to and from integration
* [[Development/Tutorials/Git/Feature_Development_Workflow/Branches_and_Commit_policies|Branches and commit policies]]

Some KDE Components have adopted an integration-staging-origin policy for pushing features into KDE's repositories. This document is designed to get developers started with this workflow and understand the steps involved.

===Repositories and projects complying with this policy===
The following repositories/projects follow these guidelines. Any project not mentioned here is unaffected by what described

* kde-workspace
* kde-runtime
* kdelibs (plasma only)

===Requirements===
The requirements of the KDE community that this workflow aims to meet include the following items. The final workflow may not meet all of the requirements with 100% perfection and there may be some need for compromise on some points as we develop the workflow further. However, these are points of value to the KDE community which need to be addressed by the proposed git workflow:

* low barrier of entry (easily learnable, easily practiced,) for developers with little to no git knowledge / mastery
* master being in a continuously stable state
* the ability to do integration in a branch other than master
* ease of bug fixing, particularly making applying the same fix to stable and integration branches clear and simple
* no interruption to feature development, even during freezes in preparation of Software Compilation releases
* a single workflow applied across all participants in the Software Compilation and, hopefully, even wider across projects hosted in KDE's git installation to keep the barrier to participation low
* as clean a history in the repo as possible
* works with existing "Best Practices" in KDE such as commit mailing lists and other communication aids as development happens (not just post-merge)

===Rationale===
This approach is meant to implement proper quality evaluation into the main repositories, still allowing developers to work on anything they want, and providing a sane merging strategy which does not require any specific knowledge from the developer's side.

This is achieved by using two separate repositories. One is ''origin'', the official project repository, where just maintainers are allowed to push, apart from special cases. The other is ''integration'', where work in progress happens, and everyone can create branches and work on that.

There are two separate figures: developers and maintainers. Developers are people who want to work on features on a specific repositories, maintainers are the gatekeepers for those repositories. Please note the purpose of the maintainer is purely organizational: no special power over technical decision is given to maintainers.

A developer would provide his code into a remote branch in ''integration'': as soon as this code is ready and reviewed, the maintainer would take care of merging into ''integration/master'' first, prepare for staging in ''integration/staging'', and finally merge into master when needed.

===Setting up the development environment===
In the following steps, we will assume your system is set up as shown in the [http://community.kde.org/Sysadmin/GitKdeOrgManual git.kde.org user manual], especially regarding [http://community.kde.org/Sysadmin/GitKdeOrgManual#Let_Git_rewrite_URL_prefixes automatic URL rewriting for KDE repositories] enabled.

In the following tutorial, we'll refer to kdelibs as the main target, but this applies to any other repository using this policy.

====Cloning the repository and adding integration====
To clone the repository, issue

git clone kde:kdelibs

This will create a kdelibs directory containing the whole repository. You now need to add a separate remote for handling ''integration''. A remote is a repository URL, and your local clone can contain multiple repositories to track different branches. To add kdelibs' ''integration'' repository, issue inside kdelibs' clone:

git remote add integration kde:clones/kdelibs/dafre/kdelibs-integration

Now, fetch from integration to retrieve the changes:

git fetch integration

{{note|When working with multiple remotes, you can issue ''git fetch --all'' to update all the remotes tracked by your local copy }}

====Creating branches====
You now need to get your branches set up, in particular ''integration/master''. In this example, we are creating a new branch named ''integration-master'' which would serve for this purpose in particular:

git checkout -b integration-master integration/master

This command creates a local branch set to track a remote one. This branch should be the branch you'll be basing your work upon: origin/master is not meant for development!

{{note|Advanced users might want to use ''integration'' as their origin }}

====Using integration vs. using your own clone====
It is ''strongly'' advised to push your work to integration, but under some circumstances (your work is extremely big in size, you do not have a KDE Development account, etc.), it is allowed to push your branches to a separate personal clone. All work should end up into integration for being reviewed anyway.

===Developing a new feature===
We'll now walk through the process needed to develop a new feature. We'll suppose you want to add a button which says "hello" to a specific part of code.

====Creating a new branch====
First thing to do is creating a new branch on which to base your work on. This branch must be based upon ''integration/master''. To make sure this happens, start by issuing

git checkout integration-master

Now create your branch. Give it a self-explainatory name: try to keep branches as atomic as possible, and possibly split big changes throughout multiple branches divided as per topic. In our case, we want to name our branch ''add-hello-button''. To do that, we do:

git checkout -b add-hello-button

That will create our personal branch which is going to contain our work. Push your branch to integration by issuing

git push integration add-hello-button

====Getting the branch reviewed====
Once you are done with your changes, you are ready to get your branch reviewed. This involves three easy steps:

=====Rebase your branch onto integration/master=====
It is important to have your branch rebased to be ready for review. Rebasing puts your commits on top of anything else of the branch you are rebasing on, including the changes from that branch. You of course want to rebase onto ''integration/master''. To do that, issue

git rebase integration/master

Be sure to fetch before doing that. At this stage, conflicts might occur: be sure to fix them and commit/push the result. You will be required to force push at this stage.

{{warning|Rebasing must be done at this stage only: please avoid rebasing before getting reviewed or after getting reviewed if not strictly necessary }}

=====Push your changes to integration=====
If you have a KDE developer account, simply

git push integration add-hello-button

from within your ''add-hello-button'' branch. If you do not have one, please have your mentor push your branch for you.

=====Submit the branch for review=====
Use Reviewboard for getting your branch reviewed. You can read [http://techbase.kde.org/Development/Review_Board KDE Reviewboard+Git tutorial] for getting started.

====Getting the branch approved====
After your branch has been reviewed and marked as "Ship it!" at least by one of the maintainers of the code you are adding features to, your branch is ready for integration and staging. Your reviewer will inform one of the repository's maintainers of that.

Your work is done at this stage: the maintainer will integrate and stage your branch for you, and will merge it into ''origin'' according to the project's merging policy. You will be CCMailed upon every separate step your branch will take on its way to ''origin/master''

Development/Tutorials/Git/Feature Development Workflow

2011-05-19T07:12:35Z

Aseigo: /* Rationale */

{{warning|This page refers to a draft policy which is still to be agreed and implemented. Please take it as a reference for a work in progress project. }}

These tutorials are aimed to get people started with KDE's policy for merging and integrating changes into the repositories.

Such policies vary depending on the developer's role inside the project. Please follow the tutorial which best suits your role and profile

* [[Development/Tutorials/Git/Feature_Development_Workflow/Simple_Branch_Development|Casual Developer]] - follow this tutorial if you simply wish to contribute features or fixes OR you are a developer without specific knowledge of git. Difficulty level: easy
* [[Development/Tutorials/Git/Feature_Development_Workflow/Branch_Development_With_Merge|Core Developer with git knowledge]] - follow this tutorial if you are a developer which contributes frequently AND you have a more-than-average knowledge of git. Difficulty level: manageable
* Repository Maintainer - follow this tutorial if you are a repository maintainer or if you want to apply for becoming one. Difficulty level: relevant

Also, for your knowledge, you should check out these specific articles:

* [[Development/Tutorials/Git/Feature_Development_Workflow/Which_repository_should_I_use|Which repository should I use?]]
* [[Development/Tutorials/Git/Feature_Development_Workflow/Rationale_and_Explanation_of_Workflow|Rationale and explanation of workflow]]
* [[Development/Tutorials/Git/Feature_Development_Workflow/Rebase_vs_Merge|Rebase vs. merging: why and how]]
* [[Development/Tutorials/Git/Feature_Development_Workflow/Staging_Phase_Explained|The staging phase explained]]
* Merge strategies to and from integration
* [[Development/Tutorials/Git/Feature_Development_Workflow/Branches_and_Commit_policies|Branches and commit policies]]

Some KDE Components have adopted an integration-staging-origin policy for pushing features into KDE's repositories. This document is designed to get developers started with this workflow and understand the steps involved.

===Repositories and projects complying with this policy===
The following repositories/projects follow these guidelines. Any project not mentioned here is unaffected by what described

* kde-workspace
* kde-runtime
* kdelibs (plasma only)

===Requirements===
The requirements of the KDE community that this workflow aims to meet include:

* master being in a continuously stable state
* the ability to do integration in a branch other than master
* ease of bug fixing, particularly making applying the same fix to stable and integration branches clear and simple
* no interruption to feature development, even during freezes in preparation of Software Compilation releases
* a single workflow applied across all participants in the Software Compilation and, hopefully, even wider across projects hosted in KDE's git installation to keep the barrier to participation low

===Rationale===
This approach is meant to implement proper quality evaluation into the main repositories, still allowing developers to work on anything they want, and providing a sane merging strategy which does not require any specific knowledge from the developer's side.

This is achieved by using two separate repositories. One is ''origin'', the official project repository, where just maintainers are allowed to push, apart from special cases. The other is ''integration'', where work in progress happens, and everyone can create branches and work on that.

There are two separate figures: developers and maintainers. Developers are people who want to work on features on a specific repositories, maintainers are the gatekeepers for those repositories. Please note the purpose of the maintainer is purely organizational: no special power over technical decision is given to maintainers.

A developer would provide his code into a remote branch in ''integration'': as soon as this code is ready and reviewed, the maintainer would take care of merging into ''integration/master'' first, prepare for staging in ''integration/staging'', and finally merge into master when needed.

===Setting up the development environment===
In the following steps, we will assume your system is set up as shown in the [http://community.kde.org/Sysadmin/GitKdeOrgManual git.kde.org user manual], especially regarding [http://community.kde.org/Sysadmin/GitKdeOrgManual#Let_Git_rewrite_URL_prefixes automatic URL rewriting for KDE repositories] enabled.

In the following tutorial, we'll refer to kdelibs as the main target, but this applies to any other repository using this policy.

====Cloning the repository and adding integration====
To clone the repository, issue

git clone kde:kdelibs

This will create a kdelibs directory containing the whole repository. You now need to add a separate remote for handling ''integration''. A remote is a repository URL, and your local clone can contain multiple repositories to track different branches. To add kdelibs' ''integration'' repository, issue inside kdelibs' clone:

git remote add integration kde:clones/kdelibs/dafre/kdelibs-integration

Now, fetch from integration to retrieve the changes:

git fetch integration

{{note|When working with multiple remotes, you can issue ''git fetch --all'' to update all the remotes tracked by your local copy }}

====Creating branches====
You now need to get your branches set up, in particular ''integration/master''. In this example, we are creating a new branch named ''integration-master'' which would serve for this purpose in particular:

git checkout -b integration-master integration/master

This command creates a local branch set to track a remote one. This branch should be the branch you'll be basing your work upon: origin/master is not meant for development!

{{note|Advanced users might want to use ''integration'' as their origin }}

====Using integration vs. using your own clone====
It is ''strongly'' advised to push your work to integration, but under some circumstances (your work is extremely big in size, you do not have a KDE Development account, etc.), it is allowed to push your branches to a separate personal clone. All work should end up into integration for being reviewed anyway.

===Developing a new feature===
We'll now walk through the process needed to develop a new feature. We'll suppose you want to add a button which says "hello" to a specific part of code.

====Creating a new branch====
First thing to do is creating a new branch on which to base your work on. This branch must be based upon ''integration/master''. To make sure this happens, start by issuing

git checkout integration-master

Now create your branch. Give it a self-explainatory name: try to keep branches as atomic as possible, and possibly split big changes throughout multiple branches divided as per topic. In our case, we want to name our branch ''add-hello-button''. To do that, we do:

git checkout -b add-hello-button

That will create our personal branch which is going to contain our work. Push your branch to integration by issuing

git push integration add-hello-button

====Getting the branch reviewed====
Once you are done with your changes, you are ready to get your branch reviewed. This involves three easy steps:

=====Rebase your branch onto integration/master=====
It is important to have your branch rebased to be ready for review. Rebasing puts your commits on top of anything else of the branch you are rebasing on, including the changes from that branch. You of course want to rebase onto ''integration/master''. To do that, issue

git rebase integration/master

Be sure to fetch before doing that. At this stage, conflicts might occur: be sure to fix them and commit/push the result. You will be required to force push at this stage.

{{warning|Rebasing must be done at this stage only: please avoid rebasing before getting reviewed or after getting reviewed if not strictly necessary }}

=====Push your changes to integration=====
If you have a KDE developer account, simply

git push integration add-hello-button

from within your ''add-hello-button'' branch. If you do not have one, please have your mentor push your branch for you.

=====Submit the branch for review=====
Use Reviewboard for getting your branch reviewed. You can read [http://techbase.kde.org/Development/Review_Board KDE Reviewboard+Git tutorial] for getting started.

====Getting the branch approved====
After your branch has been reviewed and marked as "Ship it!" at least by one of the maintainers of the code you are adding features to, your branch is ready for integration and staging. Your reviewer will inform one of the repository's maintainers of that.

Your work is done at this stage: the maintainer will integrate and stage your branch for you, and will merge it into ''origin'' according to the project's merging policy. You will be CCMailed upon every separate step your branch will take on its way to ''origin/master''

KDE System Administration/PlasmaDesktopScripting

2011-05-05T15:08:36Z

Aseigo:

== ECMA Script Interaction With Plasma Shells ==

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.

== Examples ==

A set of examples can be found [https://projects.kde.org/projects/kde/kdeexamples/repository/revisions/master/show/plasma/javascript/plasma-shell-scripting 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.

== 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|For security reasons, scripts located in the user's home directory will '''not''' be run during this phase.}}

* '''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|For security reasons, scripts located in the user's home directory will '''not''' be run during this phase.}}

* '''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 <code bash>qdbus org.kde.plasma-desktop /MainApplication showInteractiveConsole</code>

{{note|This method is not available for plasma-netbook.}}

: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
<code bash>qdbus org.kde.plasma-desktop /MainApplication loadScriptInInteractiveConsole /path/to/file</code>

== Templates ==

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:

* metadata.desktop: a .desktop file describing the template
* contents/layout.js: a Javascript file containing the actual script

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:

<code ini>
[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
</code>

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.

=== Examples of Usage ===

==== Creating panels ====
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.

==== Automating tasks ====
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:

<code javascript>
var template = loadTemplate('org.kde.plasma-desktop.findWidgets')
template.findWidgets('systemtray')
</code>

==== Activity templates ====
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:

<code ini>
[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
</code>

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:
* $desktop
* $autostart
* $documents
* $music
* $video
* $downloads
* $pictures

They all expand into the path toward the user corresponding default folder.

== 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|API compatibility is guaranteed from version to version starting with KDE Software Compilation v4.4.0.}}

=== 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. 0.3
* ''String'' '''platformVersion''': the version of the KDE Platform, e.g. 0.3
* ''number'' '''scriptingVersion''': the version of the scripting API; e.g. in KDE SC 4.5 this is 2

=== 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
* ''Array[String]'' '''knownActivityTypes''': (scripting version >= 2) 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:
* ''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.
* ''Array[Activity]'' '''activities()''': returns an array of all activities that currently exist

=== 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
* ''Array[String]'' '''knownPanelTypes''': (scripting version >= 2) 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.

Functions:
* ''Panel'' '''panelById(int id)''': returns an object representing the Panel that matches the given id
* ''Array[Panels]'' '''panels()''': returns an array of all panels that currently exist

=== Activities and Panels ===
Activity and Panel objects, once 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
* ''Array[String]'' '''configKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current configuration group
* ''Array[String]'' '''configGroups''': (scriptingVersion >= 2) a list of all the groups in the current configuration group
* ''Array[String]'' '''globalConfigKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current global configuration group
* ''Array[String]'' '''globalConfigGroups''': (scriptingVersion >= 2) a list of all the groups in the current global configuration group

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
* ''String'' '''wallpaperPlugin''': (scriptingVersion >= 2) the wallpaper plugin to use with the Activity
* ''String'' '''wallpaperMode''': (scriptingVersion >= 2) the wallpaper plugin mode to use with the Activity
* ''Array[String]'' '''currentConfigGroup''': (scriptingVersion >= 2) 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
* ''String'' '''version''': (scriptingVersion >= 2) the version of the Activity or Panel

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
* '''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
* '''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
* '''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
* ''Array[String]'' '''currentGlobalConfigGroup''': (scriptingVersion >= 2) the current global configuration group path, with each entry in the array representing a sub-group, similar to currentConfigGroup. However, global configuration is shared by all instances of panels and activities of the same type.
* ''Array[Widget]'' '''widgets([String type])''': (scriptingVersion >= 2) returns all the widgets in the Panel or Activity. If the optional type is specified, only widgets matching that type will be returned.

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 list of all installed widget types can be retrieved the following read-only property:

* ''Array[String]'' '''knownWidgetTypes''' (scripting version >= 2)

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
* ''Array[String]'' '''globalConfigKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current global configuration group
* ''Array[String]'' '''globalConfigGroups''': (scriptingVersion >= 2) a list of all the groups in the current global configuration group
* ''String'' '''version''': (scriptingVersion >= 2) the version of the Activity or Panel

as well as the following read-write properties:

* ''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
* ''Array[String]'' '''currentGlobalConfigGroup''': (scriptingVersion >= 2) the current global configuration group path, with each entry in the array representing a sub-group, similar to currentConfigGroup. However, global configuration is shared by all instances of widgets of the same type.
* ''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
* ''number'' '''index''': the layout index of the widget; in a Panel this corresponds to the order the widget appears in. Changing the value of the index will change the position of the widget in Panels and may do so in some Activities as well.

and the following 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
* '''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
* '''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
* '''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:
* ''QRectF'' '''screenGeometry(number screen)''': returns a rect object representing the geometry of a screen

=== Wallpaper Plugins ===

* ''Array[String => Array[String]]'' '''knownWallpaperPlugins()''': (scripting version >= 4) returns a list of all installed wallpaper plugins. They 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 ===
* ''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 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'' '''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
** music
** video
** downloads
** pictures
** autostart
** desktop (should be considered deprecated for Plasma workspaces)

If a second string is passed in, it is considered a request for a specific path and the following types are recognized:
** apps - Applications menu (.desktop files).
** autostart - Autostart directories (both XDG and kde-specific)
** cache - Cached information (e.g. favicons, web-pages)
** cgi - CGIs to run from kdehelp.
** config - Configuration files.
** data - Where applications store data.
** emoticons - Emoticons themes
** exe - Executables in $prefix/bin. findExe() for a function that takes $PATH into account.
** html - HTML documentation.
** icon - Icons, see KIconLoader.
** kcfg - KConfigXT config files.
** lib - Libraries.
** locale - Translation files for KLocale.
** mime - Mime types defined by KDE-specific .desktop files.
** module - Module (dynamically loaded library).
** qtplugins - Qt plugins (dynamically loaded objects for Qt)
** services - Services.
** servicetypes - Service types.
** sound - Application sounds.
** templates - Templates for the "Create new file" functionality.
** wallpaper - Wallpapers.
** tmp - Temporary files (specific for both current host and current user)
** socket - UNIX Sockets (specific for both current host and current user)
** xdgconf-menu - Freedesktop.org standard location for menu layout (.menu) files.
** xdgdata-apps - Freedesktop.org standard location for application desktop files.
** xdgdata-dirs - Freedesktop.org standard location for menu descriptions (.directory files).
** xdgdata-mime - Freedesktop.org standard location for MIME type definitions.
** xdgdata-icon - Freedesktop.org standard location for icons.
** xdgdata-pixmap - Gnome-compatibility location for pixmaps.

The second parameter should be a specific resource to find the path to. An example might be userDataPath("data", "plasma-desktop").

=== Misc. Global Properties and Functions ===
Read-write properties:
* ''boolean'' '''locked''': whether the desktop shell and widgets are locked or not (settable)
* ''string'' '''theme''': (scripting version >= 3) the name of the desktop theme to use for the interface, e.g. default, Air, Oxygen, etc.

Read-only properties:
* ''boolean'' '''hasBattery''': whether or not the system has the ability to run on battery power, e.g. a laptop or mobile device
* ''boolean'' '''multihead''': (scripting version >= 3) true if the system is running with multiple screens in a "Xaphod" multiple display server configuration
* ''int'' '''multiheadScreen''': (scripting version >= 3) if multihead is true, contains the (real) screen id of the current screen

Functions:
* '''sleep(number ms)''': sleeps the script for the specified number of millseconds

=== QRectF ===
A rectangle class is also provided for use with Widget, Panel and screen geometry properties and functions.

Read-only properites:
* ''boolean'' '''empty''': true if the rectangle's width or height is less than, or equal to, 0; an empty rectangle is also invalid
* ''boolean'' '''null''': true if the rectangle has both the width and the height set to 0; a null rectangle is also empty and not valid
* ''boolean'' '''valid''': true if the rectangle has a width > 0 and height 0.

Read-write properties:
* ''number'' '''left'''
* ''number'' '''top'''
* ''number'' '''bottom'''
* ''number'' '''right'''
* ''number'' '''height'''
* ''number'' '''width'''
* ''number'' '''x'''
* ''number'' '''y'''

Constructors:
* '''QRectF'''
* '''QRectF(number x, number y, number width, number height)''': Sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.

Functions:
* '''adjust(number dx1, number dy1, number dx2, number dy2)''': adds dx1, dy1, dx2 and dy2 respectively to the existing coordinates of the rectangle
* ''QRectF'' '''adjusted(number dx1, number dy1, number dx2, number dy2)''': returns a new QRectF with dx1, dy1, dx2 and dy2 added respectively to the existing coordinates of the rectangle
* '''translate(number dx, number dy)''': translates the rect by dx, dy
* '''setCoords(number x1, number y1, number x2, number y2)''': sets the coordinates of the rectangle's top-left corner to (x1, y1), and the coordinates of its bottom-right corner to (x2, y2).
* '''setRect(number x, number y, number width, number height)''': sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.
* ''boolean'' '''contains(number x, number y)''': returns true if the rect contains the point (x, y)
* '''moveBottom(number delta)'': moves the bottom by delta pixels
* '''moveLeft(number delta)''': moves the left by delta pixels
* '''moveRight(number delta)''': moves the right by delta pixels
* '''moveTo(number x, number y)''': moves the top left of the rect to point (x, y)
* '''moveTop(number delta)''': moves the top by delta pixels

== Configuration Keys ==
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'''.

=== Common configuration keys ===
Here are some keys that can be used with all widgets:

* '''Share''' (true/false): Whether or not the widget is to be announces throughout the network (Share tab)

=== Digital clock (digital-clock) ===
* '''announceInterval''' (number ≥ 0): Interval in minutes that the time is read out loud
* '''calendarType''' (local/coptic/ethopian/gregorian/gregorian-proleptic/hebrew/hijri/indian-national/jalali/japanese/julian/minguo/thai): Calendar system to be used, defaults to local
* '''defaultTimezone''' (Local/…): Time zone to be used
* '''displayHolidays''' (true/false): Whether holidays are to be displayed
* '''holidayRegions''' (tbd): tbd
* '''holidayRegionaDaysOff''' (tbd): tbd
* '''plainClockColor''' (rrr,ggg,bbb): Color set for clock font (e. g. 192,0,0 - to be used with useCustomColor=true!)
* '''plainClockDrawShadow''' (true/false): Whether a shadow is to bed drawn (defaults to true)
* '''plainClockShadowColor''' (rrr,ggg,bbb): Color set for clock shadow (e. g. 64,97,128 - to be used with useCustomShadowColor=true!)
* '''plainClockFont''' (tbd): Font to be used for clock (e. g. Serif,12,-1,5,75,0,0,0,0,0)
* '''showDate''' (true/false): self-explanatory
* '''showDay''' (true/false): self-explanatory
* '''showSeconds''' (true/false): self-explanatory
* '''showTimezone''' (true/false): self-explanatory
* '''showYear''' (true/false): self-explanatory
* '''timeZones''' (Europe/Andorra,…): Comma-separated list of timezones to be used (e. g. Europe/Andorra,Indian/Antananarivo,Asia/Aqtau)
* '''useCustomColor''' (true/false): Whether or not a custom color is to be used (use with plainClockColor=rrr,ggg,bbb!)
* '''useCustomShadowColor''' (true/false): Whether or not a custom shadow color is to be used (use with plainClockShadowColor=rrr,ggg,bbb!)

=== Folderview (folderview) ===
* '''alignToGrid''' (true/false): self-explanatory
* '''customIconSize''' (16/22/24/32/48/…): Use custom icon size for files/folders (use only default/common icon sizes, powers of 2)
* '''customLabel''': Use custom title rather than default path or place name
* '''drawShadows''' (true/false): Whether or not file labels are to draw shadows
* '''filter''' (0/1/2): Defines whether a filter is to be used or not (0 = No filter, 1 = Show only matching files, 2 = Hide matching files)
* '''filterFiles''': Wildcard filter to filter file names
* '''mimeFilter''': Comma-separated list of mimetypes to be filtered (shown/hidden depends on filter-setting)
* '''iconsLocked''' (true/false): Whether or not icons can be moved
* '''numTextLines''' (number > 0): Amount of lines a file name can have before it is truncated
* '''url''': Folder URL to be displayed (e. g. desktop:/// or file:///home/yourusername)
* '''sortColumn''' (-1/0/1/2/3/4/5): The way files and folders are sorted (-1 = No sorting, 0 = By name, 1 = By size, 2 = By type, 3 = By date)
* '''sortDirsFirst''' (true/false): Whether or not folders are displayed before files (defaults to true)
* '''textColor''' (rrr,ggg,bbb): Color the icon labels will have

=== Kickoff menu (launcher) ===
* '''SwitchTabsOnHover''' (true/false): self-explanatory
* '''ShowAppsByName''' (true/false): Apps are sorted by name rather than by description

=== Taskbar (tasks) ===
* '''groupingStrategy''' (0/1/2): Defines how taskbar entries are to be grouped (0 = Never, 1 = Manually, 2 = By Program Name)
* '''groupWhenFull''' (true/false): Only group when taskbar is full (to be used with groupingStrategy=2 only!)
* '''highlightWindows''' (true/false): Highlight a window if your mouse cursor is hovering its taskbar entry (requires Desktop Compositing and “Highlight windows” effect enabled to work)
* '''maxRows''' (number > 0): Amount of rows taskbar entries can take
* '''forceRows''' (true/false): Force row setting for taskbar entries
* '''showOnlyCurrentActivity''' (true/false): Show only windows from current activity
* '''showOnlyCurrentDesktop''' (true/false): Show only windows from current virtual desktop
* '''showOnlyCurrentScreen''' (true/false): Show only windows from current screen (multi monitor setup)
* '''showTooltip''' (true/false): Whether or not tooltips are to be shown
* '''sortingStrategy''' (0/1/2/3): How taskbar entries are to be sorted (0 = Never, 1 = Manually, 2 = Alphabetically, 3 = By Desktop)

=== System Tray ===
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.

==== Generic Systemtray configuration keys ====
* '''DefaultAppletAdded''' (true/false): Remembers whether the default plasmoids (networkmanagement, device manager, notifications) have already been added(??)
* '''ShowApplicationStatus''' (true/false): Show system tray icons of applications that belong to the group “Applications”
* '''ShowCommunications''' (true/false): Show system tray icons of applications that belong to the group “Applications” (i. e. Messenger, IRC chat)
* '''ShowHardware''' (true/false): Show system tray icons of applications that belong to the group “Hardware” (i. e. volume control, printer applet)
* '''ShowSystemServices''' (true/false): Show system tray icons of applications that belong to the group “System Services” (i. e. Nepomuk Indexing Agent)
* '''ShowUnknown''' (true/false): Show system tray icons that do not belong into one of the categories mentioned above (or that do not use KDE’s system tray protocol and thus do not provide such information)
* '''alwaysShown''': Comma-separated list of widgets and entries that are to be shown all the time (e. g. KMix,notifier)
* '''hidden''': Comma-separated list of widgets and entries that are to be hidden all the time (e. g. Nepomuk Indexing Agent,Klipper,kmail)

==== 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.
<code bash>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(?)</code>

Now you can “create” the plasmoid by adding a “plugin” configuration entry
<code bash>systray.writeConfig("plugin","notifier") // This will add a Device Notifier Plasmoid</code>
You can modify the plasmoid’s configuration by using writeConfig.
<code bash>systray.writeConfig("property","value")</code>
To change back to the top configuration level and thus edit the systemtray plasmoid itself pass an empty array to currentConfigGroup.

==== Edit existing widgets in systemtray ====

==== Remove a widget from systemtray =====

KDE System Administration/PlasmaDesktopScripting

2011-04-28T12:00:02Z

Aseigo: /* Activity templates */

== ECMA Script Interaction With Plasma Shells ==

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.

== Examples ==

A set of examples can be found [https://projects.kde.org/projects/kde/kdeexamples/repository/revisions/master/show/plasma/javascript/plasma-shell-scripting 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.

== 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|For security reasons, scripts located in the user's home directory will '''not''' be run during this phase.}}

* '''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|For security reasons, scripts located in the user's home directory will '''not''' be run during this phase.}}

* '''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 <code bash>qdbus org.kde.plasma-desktop /MainApplication showInteractiveConsole</code>

{{note|This method is not available for plasma-netbook.}}

: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
<code bash>qdbus org.kde.plasma-desktop /MainApplication loadScriptInInteractiveConsole /path/to/file</code>

== Templates ==

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:

* metadata.desktop: a .desktop file describing the template
* contents/layout.js: a Javascript file containing the actual script

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:

<code ini>
[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
</code>

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.

=== Examples of Usage ===

==== Creating panels ====
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.

==== Automating tasks ====
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:

<code javascript>
var template = loadTemplate('org.kde.plasma-desktop.findWidgets')
template.findWidgets('systemtray')
</code>

==== Activity templates ====
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:

<code ini>
[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
</code>

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:
* $desktop
* $autostart
* $documents
* $music
* $video
* $downloads
* $pictures

They all expand into the path toward the user corresponding default folder.

== 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|API compatibility is guaranteed from version to version starting with KDE Software Compilation v4.4.0.}}

=== 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. 0.3
* ''String'' '''platformVersion''': the version of the KDE Platform, e.g. 0.3
* ''number'' '''scriptingVersion''': the version of the scripting API; e.g. in KDE SC 4.5 this is 2

=== 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
* ''Array[String]'' '''knownActivityTypes''': (scripting version >= 2) 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:
* ''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.
* ''Array[Activity]'' '''activities()''': returns an array of all activities that currently exist

=== 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
* ''Array[String]'' '''knownPanelTypes''': (scripting version >= 2) 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.

Functions:
* ''Panel'' '''panelById(int id)''': returns an object representing the Panel that matches the given id
* ''Array[Panels]'' '''panels()''': returns an array of all panels that currently exist

=== Activities and Panels ===
Activity and Panel objects, once 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
* ''Array[String]'' '''configKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current configuration group
* ''Array[String]'' '''configGroups''': (scriptingVersion >= 2) a list of all the groups in the current configuration group
* ''Array[String]'' '''globalConfigKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current global configuration group
* ''Array[String]'' '''globalConfigGroups''': (scriptingVersion >= 2) a list of all the groups in the current global configuration group

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
* ''String'' '''wallpaperPlugin''': (scriptingVersion >= 2) the wallpaper plugin to use with the Activity
* ''String'' '''wallpaperMode''': (scriptingVersion >= 2) the wallpaper plugin mode to use with the Activity
* ''Array[String]'' '''currentConfigGroup''': (scriptingVersion >= 2) 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
* ''String'' '''version''': (scriptingVersion >= 2) the version of the Activity or Panel

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
* '''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
* '''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
* '''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
* ''Array[String]'' '''currentGlobalConfigGroup''': (scriptingVersion >= 2) the current global configuration group path, with each entry in the array representing a sub-group, similar to currentConfigGroup. However, global configuration is shared by all instances of panels and activities of the same type.
* ''Array[Widget]'' '''widgets([String type])''': (scriptingVersion >= 2) returns all the widgets in the Panel or Activity. If the optional type is specified, only widgets matching that type will be returned.

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 list of all installed widget types can be retrieved the following read-only property:

* ''Array[String]'' '''knownWidgetTypes''' (scripting version >= 2)

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
* ''Array[String]'' '''globalConfigKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current global configuration group
* ''Array[String]'' '''globalConfigGroups''': (scriptingVersion >= 2) a list of all the groups in the current global configuration group
* ''String'' '''version''': (scriptingVersion >= 2) the version of the Activity or Panel

as well as the following read-write properties:

* ''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
* ''Array[String]'' '''currentGlobalConfigGroup''': (scriptingVersion >= 2) the current global configuration group path, with each entry in the array representing a sub-group, similar to currentConfigGroup. However, global configuration is shared by all instances of widgets of the same type.
* ''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
* ''number'' '''index''': the layout index of the widget; in a Panel this corresponds to the order the widget appears in. Changing the value of the index will change the position of the widget in Panels and may do so in some Activities as well.

and the following 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
* '''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
* '''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
* '''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:
* ''QRectF'' '''screenGeometry(number screen)''': returns a rect object representing the geometry of a screen

=== Wallpaper Plugins ===

* ''Array[String => Array[String]]'' '''knownWallpaperPlugins()''': (scripting version >= 4) returns a list of all installed wallpaper plugins. They 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 ===
* ''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 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'' '''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
** music
** video
** downloads
** pictures
** autostart
** desktop (should be considered deprecated for Plasma workspaces)

If a second string is passed in, it is considered a request for a specific path and the following types are recognized:
** apps - Applications menu (.desktop files).
** autostart - Autostart directories (both XDG and kde-specific)
** cache - Cached information (e.g. favicons, web-pages)
** cgi - CGIs to run from kdehelp.
** config - Configuration files.
** data - Where applications store data.
** emoticons - Emoticons themes
** exe - Executables in $prefix/bin. findExe() for a function that takes $PATH into account.
** html - HTML documentation.
** icon - Icons, see KIconLoader.
** kcfg - KConfigXT config files.
** lib - Libraries.
** locale - Translation files for KLocale.
** mime - Mime types defined by KDE-specific .desktop files.
** module - Module (dynamically loaded library).
** qtplugins - Qt plugins (dynamically loaded objects for Qt)
** services - Services.
** servicetypes - Service types.
** sound - Application sounds.
** templates - Templates for the "Create new file" functionality.
** wallpaper - Wallpapers.
** tmp - Temporary files (specific for both current host and current user)
** socket - UNIX Sockets (specific for both current host and current user)
** xdgconf-menu - Freedesktop.org standard location for menu layout (.menu) files.
** xdgdata-apps - Freedesktop.org standard location for application desktop files.
** xdgdata-dirs - Freedesktop.org standard location for menu descriptions (.directory files).
** xdgdata-mime - Freedesktop.org standard location for MIME type definitions.
** xdgdata-icon - Freedesktop.org standard location for icons.
** xdgdata-pixmap - Gnome-compatibility location for pixmaps.

The second parameter should be a specific resource to find the path to. An example might be userDataPath("data", "plasma-desktop").

=== Misc. Global Properties and Functions ===
Read-write properties:
* ''boolean'' '''locked''': whether the desktop shell and widgets are locked or not (settable)
* ''string'' '''theme''': (scripting version >= 3) the name of the desktop theme to use for the interface, e.g. default, Air, Oxygen, etc.

Read-only properties:
* ''boolean'' '''hasBattery''': whether or not the system has the ability to run on battery power, e.g. a laptop or mobile device
* ''boolean'' '''multihead''': (scripting version >= 3) true if the system is running with multiple screens in a "Xaphod" multiple display server configuration
* ''int'' '''multiheadScreen''': (scripting version >= 3) if multihead is true, contains the (real) screen id of the current screen

Functions:
* '''sleep(number ms)''': sleeps the script for the specified number of millseconds

=== QRectF ===
A rectangle class is also provided for use with Widget, Panel and screen geometry properties and functions.

Read-only properites:
* ''boolean'' '''empty''': true if the rectangle's width or height is less than, or equal to, 0; an empty rectangle is also invalid
* ''boolean'' '''null''': true if the rectangle has both the width and the height set to 0; a null rectangle is also empty and not valid
* ''boolean'' '''valid''': true if the rectangle has a width > 0 and height 0.

Read-write properties:
* ''number'' '''left'''
* ''number'' '''top'''
* ''number'' '''bottom'''
* ''number'' '''right'''
* ''number'' '''height'''
* ''number'' '''width'''
* ''number'' '''x'''
* ''number'' '''y'''

Constructors:
* '''QRectF'''
* '''QRectF(number x, number y, number width, number height)''': Sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.

Functions:
* '''adjust(number dx1, number dy1, number dx2, number dy2)''': adds dx1, dy1, dx2 and dy2 respectively to the existing coordinates of the rectangle
* ''QRectF'' '''adjusted(number dx1, number dy1, number dx2, number dy2)''': returns a new QRectF with dx1, dy1, dx2 and dy2 added respectively to the existing coordinates of the rectangle
* '''translate(number dx, number dy)''': translates the rect by dx, dy
* '''setCoords(number x1, number y1, number x2, number y2)''': sets the coordinates of the rectangle's top-left corner to (x1, y1), and the coordinates of its bottom-right corner to (x2, y2).
* '''setRect(number x, number y, number width, number height)''': sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.
* ''boolean'' '''contains(number x, number y)''': returns true if the rect contains the point (x, y)
* '''moveBottom(number delta)'': moves the bottom by delta pixels
* '''moveLeft(number delta)''': moves the left by delta pixels
* '''moveRight(number delta)''': moves the right by delta pixels
* '''moveTo(number x, number y)''': moves the top left of the rect to point (x, y)
* '''moveTop(number delta)''': moves the top by delta pixels

KDE System Administration/PlasmaDesktopScripting

2011-04-28T11:59:34Z

Aseigo: /* Activity templates */

== ECMA Script Interaction With Plasma Shells ==

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.

== Examples ==

A set of examples can be found [https://projects.kde.org/projects/kde/kdeexamples/repository/revisions/master/show/plasma/javascript/plasma-shell-scripting 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.

== 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|For security reasons, scripts located in the user's home directory will '''not''' be run during this phase.}}

* '''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|For security reasons, scripts located in the user's home directory will '''not''' be run during this phase.}}

* '''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 <code bash>qdbus org.kde.plasma-desktop /MainApplication showInteractiveConsole</code>

{{note|This method is not available for plasma-netbook.}}

: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
<code bash>qdbus org.kde.plasma-desktop /MainApplication loadScriptInInteractiveConsole /path/to/file</code>

== Templates ==

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:

* metadata.desktop: a .desktop file describing the template
* contents/layout.js: a Javascript file containing the actual script

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:

<code ini>
[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
</code>

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.

=== Examples of Usage ===

==== Creating panels ====
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.

==== Automating tasks ====
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:

<code javascript>
var template = loadTemplate('org.kde.plasma-desktop.findWidgets')
template.findWidgets('systemtray')
</code>

==== Activity templates ====
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:

<code ini>
[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
</code>

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 startups 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:
* $desktop
* $autostart
* $documents
* $music
* $video
* $downloads
* $pictures

They all expand into the path toward the user corresponding default folder.

== 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|API compatibility is guaranteed from version to version starting with KDE Software Compilation v4.4.0.}}

=== 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. 0.3
* ''String'' '''platformVersion''': the version of the KDE Platform, e.g. 0.3
* ''number'' '''scriptingVersion''': the version of the scripting API; e.g. in KDE SC 4.5 this is 2

=== 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
* ''Array[String]'' '''knownActivityTypes''': (scripting version >= 2) 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:
* ''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.
* ''Array[Activity]'' '''activities()''': returns an array of all activities that currently exist

=== 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
* ''Array[String]'' '''knownPanelTypes''': (scripting version >= 2) 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.

Functions:
* ''Panel'' '''panelById(int id)''': returns an object representing the Panel that matches the given id
* ''Array[Panels]'' '''panels()''': returns an array of all panels that currently exist

=== Activities and Panels ===
Activity and Panel objects, once 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
* ''Array[String]'' '''configKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current configuration group
* ''Array[String]'' '''configGroups''': (scriptingVersion >= 2) a list of all the groups in the current configuration group
* ''Array[String]'' '''globalConfigKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current global configuration group
* ''Array[String]'' '''globalConfigGroups''': (scriptingVersion >= 2) a list of all the groups in the current global configuration group

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
* ''String'' '''wallpaperPlugin''': (scriptingVersion >= 2) the wallpaper plugin to use with the Activity
* ''String'' '''wallpaperMode''': (scriptingVersion >= 2) the wallpaper plugin mode to use with the Activity
* ''Array[String]'' '''currentConfigGroup''': (scriptingVersion >= 2) 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
* ''String'' '''version''': (scriptingVersion >= 2) the version of the Activity or Panel

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
* '''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
* '''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
* '''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
* ''Array[String]'' '''currentGlobalConfigGroup''': (scriptingVersion >= 2) the current global configuration group path, with each entry in the array representing a sub-group, similar to currentConfigGroup. However, global configuration is shared by all instances of panels and activities of the same type.
* ''Array[Widget]'' '''widgets([String type])''': (scriptingVersion >= 2) returns all the widgets in the Panel or Activity. If the optional type is specified, only widgets matching that type will be returned.

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 list of all installed widget types can be retrieved the following read-only property:

* ''Array[String]'' '''knownWidgetTypes''' (scripting version >= 2)

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
* ''Array[String]'' '''globalConfigKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current global configuration group
* ''Array[String]'' '''globalConfigGroups''': (scriptingVersion >= 2) a list of all the groups in the current global configuration group
* ''String'' '''version''': (scriptingVersion >= 2) the version of the Activity or Panel

as well as the following read-write properties:

* ''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
* ''Array[String]'' '''currentGlobalConfigGroup''': (scriptingVersion >= 2) the current global configuration group path, with each entry in the array representing a sub-group, similar to currentConfigGroup. However, global configuration is shared by all instances of widgets of the same type.
* ''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
* ''number'' '''index''': the layout index of the widget; in a Panel this corresponds to the order the widget appears in. Changing the value of the index will change the position of the widget in Panels and may do so in some Activities as well.

and the following 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
* '''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
* '''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
* '''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:
* ''QRectF'' '''screenGeometry(number screen)''': returns a rect object representing the geometry of a screen

=== Wallpaper Plugins ===

* ''Array[String => Array[String]]'' '''knownWallpaperPlugins()''': (scripting version >= 4) returns a list of all installed wallpaper plugins. They 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 ===
* ''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 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'' '''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
** music
** video
** downloads
** pictures
** autostart
** desktop (should be considered deprecated for Plasma workspaces)

If a second string is passed in, it is considered a request for a specific path and the following types are recognized:
** apps - Applications menu (.desktop files).
** autostart - Autostart directories (both XDG and kde-specific)
** cache - Cached information (e.g. favicons, web-pages)
** cgi - CGIs to run from kdehelp.
** config - Configuration files.
** data - Where applications store data.
** emoticons - Emoticons themes
** exe - Executables in $prefix/bin. findExe() for a function that takes $PATH into account.
** html - HTML documentation.
** icon - Icons, see KIconLoader.
** kcfg - KConfigXT config files.
** lib - Libraries.
** locale - Translation files for KLocale.
** mime - Mime types defined by KDE-specific .desktop files.
** module - Module (dynamically loaded library).
** qtplugins - Qt plugins (dynamically loaded objects for Qt)
** services - Services.
** servicetypes - Service types.
** sound - Application sounds.
** templates - Templates for the "Create new file" functionality.
** wallpaper - Wallpapers.
** tmp - Temporary files (specific for both current host and current user)
** socket - UNIX Sockets (specific for both current host and current user)
** xdgconf-menu - Freedesktop.org standard location for menu layout (.menu) files.
** xdgdata-apps - Freedesktop.org standard location for application desktop files.
** xdgdata-dirs - Freedesktop.org standard location for menu descriptions (.directory files).
** xdgdata-mime - Freedesktop.org standard location for MIME type definitions.
** xdgdata-icon - Freedesktop.org standard location for icons.
** xdgdata-pixmap - Gnome-compatibility location for pixmaps.

The second parameter should be a specific resource to find the path to. An example might be userDataPath("data", "plasma-desktop").

=== Misc. Global Properties and Functions ===
Read-write properties:
* ''boolean'' '''locked''': whether the desktop shell and widgets are locked or not (settable)
* ''string'' '''theme''': (scripting version >= 3) the name of the desktop theme to use for the interface, e.g. default, Air, Oxygen, etc.

Read-only properties:
* ''boolean'' '''hasBattery''': whether or not the system has the ability to run on battery power, e.g. a laptop or mobile device
* ''boolean'' '''multihead''': (scripting version >= 3) true if the system is running with multiple screens in a "Xaphod" multiple display server configuration
* ''int'' '''multiheadScreen''': (scripting version >= 3) if multihead is true, contains the (real) screen id of the current screen

Functions:
* '''sleep(number ms)''': sleeps the script for the specified number of millseconds

=== QRectF ===
A rectangle class is also provided for use with Widget, Panel and screen geometry properties and functions.

Read-only properites:
* ''boolean'' '''empty''': true if the rectangle's width or height is less than, or equal to, 0; an empty rectangle is also invalid
* ''boolean'' '''null''': true if the rectangle has both the width and the height set to 0; a null rectangle is also empty and not valid
* ''boolean'' '''valid''': true if the rectangle has a width > 0 and height 0.

Read-write properties:
* ''number'' '''left'''
* ''number'' '''top'''
* ''number'' '''bottom'''
* ''number'' '''right'''
* ''number'' '''height'''
* ''number'' '''width'''
* ''number'' '''x'''
* ''number'' '''y'''

Constructors:
* '''QRectF'''
* '''QRectF(number x, number y, number width, number height)''': Sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.

Functions:
* '''adjust(number dx1, number dy1, number dx2, number dy2)''': adds dx1, dy1, dx2 and dy2 respectively to the existing coordinates of the rectangle
* ''QRectF'' '''adjusted(number dx1, number dy1, number dx2, number dy2)''': returns a new QRectF with dx1, dy1, dx2 and dy2 added respectively to the existing coordinates of the rectangle
* '''translate(number dx, number dy)''': translates the rect by dx, dy
* '''setCoords(number x1, number y1, number x2, number y2)''': sets the coordinates of the rectangle's top-left corner to (x1, y1), and the coordinates of its bottom-right corner to (x2, y2).
* '''setRect(number x, number y, number width, number height)''': sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.
* ''boolean'' '''contains(number x, number y)''': returns true if the rect contains the point (x, y)
* '''moveBottom(number delta)'': moves the bottom by delta pixels
* '''moveLeft(number delta)''': moves the left by delta pixels
* '''moveRight(number delta)''': moves the right by delta pixels
* '''moveTo(number x, number y)''': moves the top left of the rect to point (x, y)
* '''moveTop(number delta)''': moves the top by delta pixels

Development/Tutorials/Git/Feature Development Workflow/Simple Branch Development

2011-04-27T18:30:50Z

Aseigo: /* The Recipe */

{{warning|This page refers to a draft policy which is still to be agreed and implemented. Please take it as a reference for a work in progress project. }}

This tutorial can help casual developers as well as developers with a limited knowledge of git to get started quickly. It covers the entire work flow, from developing in branches to getting them merged and integrated for the next release.

This tutorial does not require any git-specific knowledge.

Before you start, you are strongly advised to read the following documents:

* [[Development/Tutorials/Git/Feature_Development_Workflow/Repository_Roles|Which repository should I use?]]

===Repositories and projects complying with this policy===
The following repositories/projects follow these guidelines. Any project not mentioned here is unaffected by what described

* kde-workspace
* kde-runtime
* kdelibs (plasma only)

===Rationale===
The approach described in this document helps us implement proper quality evaluation for code that ends up in the main repositories while still allowing developers to work on anything they want. It provides a sane merging strategy which does not require any special git knowledge from the contributing developer's side.

To learn more about the rationale behind this approach, please read [[Development/Tutorials/Git/Feature_Development_Workflow/Rationale|the Rationale article]].

===Setting up the development environment===
The following steps assume your system is set up as shown in the [http://community.kde.org/Sysadmin/GitKdeOrgManual git.kde.org user manual], especially regarding [http://community.kde.org/Sysadmin/GitKdeOrgManual#Let_Git_rewrite_URL_prefixes automatic URL rewriting for KDE repositories] enabled.

In the following tutorial, we'll refer to kdelibs as the main target, but this applies to any other repository using this policy.

====Cloning the repository and adding integration====

=====The Recipe=====
<code lang="bash">git clone kde:kdelibs
git remote add integration kde:clones/kdelibs/dafre/kdelibs-integration
git fetch integration</code>

=====The Explanation=====

To clone the repository, issue

<code lang="bash">git clone kde:kdelibs</code>

This will create a kdelibs directory containing the whole repository. You now need to add a separate remote for handling ''integration''. A remote is a repository URL, and your local clone can contain multiple repositories to track different branches. To add kdelibs' ''integration'' repository, issue inside kdelibs' clone:

<code lang="bash">git remote add integration kde:clones/kdelibs/dafre/kdelibs-integration</code>

Now, fetch from integration to retrieve the changes:

<code lang="bash">git fetch integration</code>

{{note|When working with multiple remotes, you can issue ''git fetch --all'' to update all the remotes tracked by your local copy }}

====Creating branches====
You now need to get your branches set up, in particular ''integration/master''. In this example, we are creating a new branch named ''integration-master'' which would serve for this purpose in particular:

git checkout -b integration-master integration/master

This command creates a local branch set to track a remote one. This branch should be the branch you'll be basing your work upon: origin/master is not meant for development!

====Using integration vs. using your own clone====
It is ''strongly'' advised to push your work to integration, but under some circumstances (your work is extremely big in size, you do not have a KDE Development account, etc.), it is allowed to push your branches to a separate personal clone. All work should end up into integration for being reviewed anyway.

===Developing a new feature===
We'll now walk through the process needed to develop a new feature. We'll suppose you want to add a button which says "hello" to a specific part of code.

====Creating a new branch====
First thing to do is creating a new branch on which to base your work on. This branch must be based upon ''integration/master''. To make sure this happens, start by issuing

git checkout integration-master

Now create your branch. Give it a self-exeplainatory name: try to keep branches as atomic as possible, and possibly split big changes throughout multiple branches divided as per topic. In our case, we want to name our branch ''add-hello-button''. To do that, we do:

git checkout -b add-hello-button

That will create our personal branch which is going to contain our work. Push your branch to integration by issuing

git push integration add-hello-button

====Synchronizing the branch with master====
When you create a branch (like you did), you are not receiving incremental updates from other people working in the repository (so in the ''master'' branch). This is usually not an issue, and instead an advantage: you can work on your code without being affected by other changes.

However, there are some cases in which ''synchronizing'' your code with what's been going on with master is required. Git gives you two ways for doing that: merging or rebasing. Both have upsides and downsides, and both come at a cost.

For this reason, you are ''strongly'' invited to avoid merging or rebasing on top of master while developing your feature whenever possible. Although, if you need to, you are supposed to merge your branch with master, and not to rebase it. What you need to do is the following:

git fetch --all
git merge integration/master

This command merges your work with the very latest code from ''integration/master''. This process comes with a cost: your branch will not be a candidate for a clean rebase, and each merge makes the history more complex.

Again, this means that you should try to avoid this process if possible, and if you ''absolutely'' need to do that, you should try and keep the number of merges you'll do in your branch as low as possible. More than 3 merges start to create a very cluttered history.

To learn more about merging, rebasing, and what this implies to your branch and to our merge strategy, you are invited to read [[Development/Tutorials/Git/Feature_Development_Workflow/Rebase_vs_Merge|Rebasing vs. merging: why and how]]

====Getting the branch reviewed====
Once you are done with your changes, you are ready to get your branch reviewed. In the review process, the project's core developers will evaluate your code's quality, and will help you in making it perfect before it gets integrated. Here's how to do it.

=====Push your changes to integration=====
If you have a KDE developer account, simply

git push integration add-hello-button

from within your ''add-hello-button'' branch.

If you do not have a KDE Developer account, please get in touch with the core developer who is mentoring you, or with one of the repository's maintainers to get your changes pushed into ''integration''.

=====Submit the branch for review=====
Use Reviewboard for getting your branch reviewed. You can read [[Development/Review_Board|KDE Reviewboard+Git tutorial]] for getting started and understanding the steps involved.

It is '''critical''' that you specify in the review request whether your branch has ever been merged with master or not.

=====Modifying the branch=====
Everytime you update your review request with new code, please remember to push changes to ''integration'' with your new code. That will help developers in reviewing and maintainers in handling your request.

====Getting your branch integrated====
Once your review request has been marked as "Ship it!", your job is done. The maintainers will take care of merging the branch into ''integration/master'', stage it for release, and make it reach ''origin'' in the end.

It is '''critical''' at this point to have your branch ''frozen''. You should not commit anything else to your branch and you should consider it dead. Maintainers will take over its commits and will delete it when merging occurs.

If you are curious to find out what happens to your commit after your code is accepted, read [[Development/Tutorials/Git/Feature_Development_Workflow/Merge_Strategies|Merge strategies to and from integration]]

Development/Tutorials/Git/Feature Development Workflow/Simple Branch Development

2011-04-27T18:30:40Z

Aseigo: /* Cloning the repository and adding integration */

Development/Tutorials/Git/Feature Development Workflow/Simple Branch Development

2011-04-27T18:27:53Z

Aseigo: /* Setting up the development environment */

{{warning|This page refers to a draft policy which is still to be agreed and implemented. Please take it as a reference for a work in progress project. }}

This tutorial can help casual developers as well as developers with a limited knowledge of git to get started quickly. It covers the entire work flow, from developing in branches to getting them merged and integrated for the next release.

This tutorial does not require any git-specific knowledge.

Before you start, you are strongly advised to read the following documents:

* [[Development/Tutorials/Git/Feature_Development_Workflow/Repository_Roles|Which repository should I use?]]

===Repositories and projects complying with this policy===
The following repositories/projects follow these guidelines. Any project not mentioned here is unaffected by what described

* kde-workspace
* kde-runtime
* kdelibs (plasma only)

===Rationale===
The approach described in this document helps us implement proper quality evaluation for code that ends up in the main repositories while still allowing developers to work on anything they want. It provides a sane merging strategy which does not require any special git knowledge from the contributing developer's side.

To learn more about the rationale behind this approach, please read [[Development/Tutorials/Git/Feature_Development_Workflow/Rationale|the Rationale article]].

===Setting up the development environment===
The following steps assume your system is set up as shown in the [http://community.kde.org/Sysadmin/GitKdeOrgManual git.kde.org user manual], especially regarding [http://community.kde.org/Sysadmin/GitKdeOrgManual#Let_Git_rewrite_URL_prefixes automatic URL rewriting for KDE repositories] enabled.

In the following tutorial, we'll refer to kdelibs as the main target, but this applies to any other repository using this policy.

====Cloning the repository and adding integration====
To clone the repository, issue

git clone kde:kdelibs

This will create a kdelibs directory containing the whole repository. You now need to add a separate remote for handling ''integration''. A remote is a repository URL, and your local clone can contain multiple repositories to track different branches. To add kdelibs' ''integration'' repository, issue inside kdelibs' clone:

git remote add integration kde:clones/kdelibs/dafre/kdelibs-integration

Now, fetch from integration to retrieve the changes:

git fetch integration

{{note|When working with multiple remotes, you can issue ''git fetch --all'' to update all the remotes tracked by your local copy }}

====Creating branches====
You now need to get your branches set up, in particular ''integration/master''. In this example, we are creating a new branch named ''integration-master'' which would serve for this purpose in particular:

git checkout -b integration-master integration/master

This command creates a local branch set to track a remote one. This branch should be the branch you'll be basing your work upon: origin/master is not meant for development!

====Using integration vs. using your own clone====
It is ''strongly'' advised to push your work to integration, but under some circumstances (your work is extremely big in size, you do not have a KDE Development account, etc.), it is allowed to push your branches to a separate personal clone. All work should end up into integration for being reviewed anyway.

===Developing a new feature===
We'll now walk through the process needed to develop a new feature. We'll suppose you want to add a button which says "hello" to a specific part of code.

====Creating a new branch====
First thing to do is creating a new branch on which to base your work on. This branch must be based upon ''integration/master''. To make sure this happens, start by issuing

git checkout integration-master

Now create your branch. Give it a self-exeplainatory name: try to keep branches as atomic as possible, and possibly split big changes throughout multiple branches divided as per topic. In our case, we want to name our branch ''add-hello-button''. To do that, we do:

git checkout -b add-hello-button

That will create our personal branch which is going to contain our work. Push your branch to integration by issuing

git push integration add-hello-button

====Synchronizing the branch with master====
When you create a branch (like you did), you are not receiving incremental updates from other people working in the repository (so in the ''master'' branch). This is usually not an issue, and instead an advantage: you can work on your code without being affected by other changes.

However, there are some cases in which ''synchronizing'' your code with what's been going on with master is required. Git gives you two ways for doing that: merging or rebasing. Both have upsides and downsides, and both come at a cost.

For this reason, you are ''strongly'' invited to avoid merging or rebasing on top of master while developing your feature whenever possible. Although, if you need to, you are supposed to merge your branch with master, and not to rebase it. What you need to do is the following:

git fetch --all
git merge integration/master

This command merges your work with the very latest code from ''integration/master''. This process comes with a cost: your branch will not be a candidate for a clean rebase, and each merge makes the history more complex.

Again, this means that you should try to avoid this process if possible, and if you ''absolutely'' need to do that, you should try and keep the number of merges you'll do in your branch as low as possible. More than 3 merges start to create a very cluttered history.

To learn more about merging, rebasing, and what this implies to your branch and to our merge strategy, you are invited to read [[Development/Tutorials/Git/Feature_Development_Workflow/Rebase_vs_Merge|Rebasing vs. merging: why and how]]

====Getting the branch reviewed====
Once you are done with your changes, you are ready to get your branch reviewed. In the review process, the project's core developers will evaluate your code's quality, and will help you in making it perfect before it gets integrated. Here's how to do it.

=====Push your changes to integration=====
If you have a KDE developer account, simply

git push integration add-hello-button

from within your ''add-hello-button'' branch.

If you do not have a KDE Developer account, please get in touch with the core developer who is mentoring you, or with one of the repository's maintainers to get your changes pushed into ''integration''.

=====Submit the branch for review=====
Use Reviewboard for getting your branch reviewed. You can read [[Development/Review_Board|KDE Reviewboard+Git tutorial]] for getting started and understanding the steps involved.

It is '''critical''' that you specify in the review request whether your branch has ever been merged with master or not.

=====Modifying the branch=====
Everytime you update your review request with new code, please remember to push changes to ''integration'' with your new code. That will help developers in reviewing and maintainers in handling your request.

====Getting your branch integrated====
Once your review request has been marked as "Ship it!", your job is done. The maintainers will take care of merging the branch into ''integration/master'', stage it for release, and make it reach ''origin'' in the end.

It is '''critical''' at this point to have your branch ''frozen''. You should not commit anything else to your branch and you should consider it dead. Maintainers will take over its commits and will delete it when merging occurs.

If you are curious to find out what happens to your commit after your code is accepted, read [[Development/Tutorials/Git/Feature_Development_Workflow/Merge_Strategies|Merge strategies to and from integration]]

Development/Tutorials/Git/Feature Development Workflow/Simple Branch Development

2011-04-27T18:26:17Z

Aseigo: /* Rationale */

{{warning|This page refers to a draft policy which is still to be agreed and implemented. Please take it as a reference for a work in progress project. }}

This tutorial can help casual developers as well as developers with a limited knowledge of git to get started quickly. It covers the entire work flow, from developing in branches to getting them merged and integrated for the next release.

This tutorial does not require any git-specific knowledge.

Before you start, you are strongly advised to read the following documents:

* [[Development/Tutorials/Git/Feature_Development_Workflow/Repository_Roles|Which repository should I use?]]

===Repositories and projects complying with this policy===
The following repositories/projects follow these guidelines. Any project not mentioned here is unaffected by what described

* kde-workspace
* kde-runtime
* kdelibs (plasma only)

===Rationale===
The approach described in this document helps us implement proper quality evaluation for code that ends up in the main repositories while still allowing developers to work on anything they want. It provides a sane merging strategy which does not require any special git knowledge from the contributing developer's side.

To learn more about the rationale behind this approach, please read [[Development/Tutorials/Git/Feature_Development_Workflow/Rationale|the Rationale article]].

===Setting up the development environment===
In the following steps, we will assume your system is set up as shown in the [http://community.kde.org/Sysadmin/GitKdeOrgManual git.kde.org user manual], especially regarding [http://community.kde.org/Sysadmin/GitKdeOrgManual#Let_Git_rewrite_URL_prefixes automatic URL rewriting for KDE repositories] enabled.

In the following tutorial, we'll refer to kdelibs as the main target, but this applies to any other repository using this policy.

====Cloning the repository and adding integration====
To clone the repository, issue

git clone kde:kdelibs

This will create a kdelibs directory containing the whole repository. You now need to add a separate remote for handling ''integration''. A remote is a repository URL, and your local clone can contain multiple repositories to track different branches. To add kdelibs' ''integration'' repository, issue inside kdelibs' clone:

git remote add integration kde:clones/kdelibs/dafre/kdelibs-integration

Now, fetch from integration to retrieve the changes:

git fetch integration

{{note|When working with multiple remotes, you can issue ''git fetch --all'' to update all the remotes tracked by your local copy }}

====Creating branches====
You now need to get your branches set up, in particular ''integration/master''. In this example, we are creating a new branch named ''integration-master'' which would serve for this purpose in particular:

git checkout -b integration-master integration/master

This command creates a local branch set to track a remote one. This branch should be the branch you'll be basing your work upon: origin/master is not meant for development!

====Using integration vs. using your own clone====
It is ''strongly'' advised to push your work to integration, but under some circumstances (your work is extremely big in size, you do not have a KDE Development account, etc.), it is allowed to push your branches to a separate personal clone. All work should end up into integration for being reviewed anyway.

===Developing a new feature===
We'll now walk through the process needed to develop a new feature. We'll suppose you want to add a button which says "hello" to a specific part of code.

====Creating a new branch====
First thing to do is creating a new branch on which to base your work on. This branch must be based upon ''integration/master''. To make sure this happens, start by issuing

git checkout integration-master

Now create your branch. Give it a self-exeplainatory name: try to keep branches as atomic as possible, and possibly split big changes throughout multiple branches divided as per topic. In our case, we want to name our branch ''add-hello-button''. To do that, we do:

git checkout -b add-hello-button

That will create our personal branch which is going to contain our work. Push your branch to integration by issuing

git push integration add-hello-button

====Synchronizing the branch with master====
When you create a branch (like you did), you are not receiving incremental updates from other people working in the repository (so in the ''master'' branch). This is usually not an issue, and instead an advantage: you can work on your code without being affected by other changes.

However, there are some cases in which ''synchronizing'' your code with what's been going on with master is required. Git gives you two ways for doing that: merging or rebasing. Both have upsides and downsides, and both come at a cost.

For this reason, you are ''strongly'' invited to avoid merging or rebasing on top of master while developing your feature whenever possible. Although, if you need to, you are supposed to merge your branch with master, and not to rebase it. What you need to do is the following:

git fetch --all
git merge integration/master

This command merges your work with the very latest code from ''integration/master''. This process comes with a cost: your branch will not be a candidate for a clean rebase, and each merge makes the history more complex.

Again, this means that you should try to avoid this process if possible, and if you ''absolutely'' need to do that, you should try and keep the number of merges you'll do in your branch as low as possible. More than 3 merges start to create a very cluttered history.

To learn more about merging, rebasing, and what this implies to your branch and to our merge strategy, you are invited to read [[Development/Tutorials/Git/Feature_Development_Workflow/Rebase_vs_Merge|Rebasing vs. merging: why and how]]

====Getting the branch reviewed====
Once you are done with your changes, you are ready to get your branch reviewed. In the review process, the project's core developers will evaluate your code's quality, and will help you in making it perfect before it gets integrated. Here's how to do it.

=====Push your changes to integration=====
If you have a KDE developer account, simply

git push integration add-hello-button

from within your ''add-hello-button'' branch.

If you do not have a KDE Developer account, please get in touch with the core developer who is mentoring you, or with one of the repository's maintainers to get your changes pushed into ''integration''.

=====Submit the branch for review=====
Use Reviewboard for getting your branch reviewed. You can read [[Development/Review_Board|KDE Reviewboard+Git tutorial]] for getting started and understanding the steps involved.

It is '''critical''' that you specify in the review request whether your branch has ever been merged with master or not.

=====Modifying the branch=====
Everytime you update your review request with new code, please remember to push changes to ''integration'' with your new code. That will help developers in reviewing and maintainers in handling your request.

====Getting your branch integrated====
Once your review request has been marked as "Ship it!", your job is done. The maintainers will take care of merging the branch into ''integration/master'', stage it for release, and make it reach ''origin'' in the end.

It is '''critical''' at this point to have your branch ''frozen''. You should not commit anything else to your branch and you should consider it dead. Maintainers will take over its commits and will delete it when merging occurs.

If you are curious to find out what happens to your commit after your code is accepted, read [[Development/Tutorials/Git/Feature_Development_Workflow/Merge_Strategies|Merge strategies to and from integration]]

Development/Tutorials/Git/Feature Development Workflow/Simple Branch Development

2011-04-27T18:22:43Z

Aseigo:

{{warning|This page refers to a draft policy which is still to be agreed and implemented. Please take it as a reference for a work in progress project. }}

This tutorial can help casual developers as well as developers with a limited knowledge of git to get started quickly. It covers the entire work flow, from developing in branches to getting them merged and integrated for the next release.

This tutorial does not require any git-specific knowledge.

Before you start, you are strongly advised to read the following documents:

* [[Development/Tutorials/Git/Feature_Development_Workflow/Repository_Roles|Which repository should I use?]]

===Repositories and projects complying with this policy===
The following repositories/projects follow these guidelines. Any project not mentioned here is unaffected by what described

* kde-workspace
* kde-runtime
* kdelibs (plasma only)

===Rationale===
This approach is meant to implement proper quality evaluation into the main repositories, still allowing developers to work on anything they want, and providing a sane merging strategy which does not require any specific knowledge from the developer's side.

To learn more about the rationale behind this approach, please read [[Development/Tutorials/Git/Feature_Development_Workflow/Rationale|the Rationale article]].

===Setting up the development environment===
In the following steps, we will assume your system is set up as shown in the [http://community.kde.org/Sysadmin/GitKdeOrgManual git.kde.org user manual], especially regarding [http://community.kde.org/Sysadmin/GitKdeOrgManual#Let_Git_rewrite_URL_prefixes automatic URL rewriting for KDE repositories] enabled.

In the following tutorial, we'll refer to kdelibs as the main target, but this applies to any other repository using this policy.

====Cloning the repository and adding integration====
To clone the repository, issue

git clone kde:kdelibs

This will create a kdelibs directory containing the whole repository. You now need to add a separate remote for handling ''integration''. A remote is a repository URL, and your local clone can contain multiple repositories to track different branches. To add kdelibs' ''integration'' repository, issue inside kdelibs' clone:

git remote add integration kde:clones/kdelibs/dafre/kdelibs-integration

Now, fetch from integration to retrieve the changes:

git fetch integration

{{note|When working with multiple remotes, you can issue ''git fetch --all'' to update all the remotes tracked by your local copy }}

====Creating branches====
You now need to get your branches set up, in particular ''integration/master''. In this example, we are creating a new branch named ''integration-master'' which would serve for this purpose in particular:

git checkout -b integration-master integration/master

This command creates a local branch set to track a remote one. This branch should be the branch you'll be basing your work upon: origin/master is not meant for development!

====Using integration vs. using your own clone====
It is ''strongly'' advised to push your work to integration, but under some circumstances (your work is extremely big in size, you do not have a KDE Development account, etc.), it is allowed to push your branches to a separate personal clone. All work should end up into integration for being reviewed anyway.

===Developing a new feature===
We'll now walk through the process needed to develop a new feature. We'll suppose you want to add a button which says "hello" to a specific part of code.

====Creating a new branch====
First thing to do is creating a new branch on which to base your work on. This branch must be based upon ''integration/master''. To make sure this happens, start by issuing

git checkout integration-master

Now create your branch. Give it a self-exeplainatory name: try to keep branches as atomic as possible, and possibly split big changes throughout multiple branches divided as per topic. In our case, we want to name our branch ''add-hello-button''. To do that, we do:

git checkout -b add-hello-button

That will create our personal branch which is going to contain our work. Push your branch to integration by issuing

git push integration add-hello-button

====Synchronizing the branch with master====
When you create a branch (like you did), you are not receiving incremental updates from other people working in the repository (so in the ''master'' branch). This is usually not an issue, and instead an advantage: you can work on your code without being affected by other changes.

However, there are some cases in which ''synchronizing'' your code with what's been going on with master is required. Git gives you two ways for doing that: merging or rebasing. Both have upsides and downsides, and both come at a cost.

For this reason, you are ''strongly'' invited to avoid merging or rebasing on top of master while developing your feature whenever possible. Although, if you need to, you are supposed to merge your branch with master, and not to rebase it. What you need to do is the following:

git fetch --all
git merge integration/master

This command merges your work with the very latest code from ''integration/master''. This process comes with a cost: your branch will not be a candidate for a clean rebase, and each merge makes the history more complex.

Again, this means that you should try to avoid this process if possible, and if you ''absolutely'' need to do that, you should try and keep the number of merges you'll do in your branch as low as possible. More than 3 merges start to create a very cluttered history.

To learn more about merging, rebasing, and what this implies to your branch and to our merge strategy, you are invited to read [[Development/Tutorials/Git/Feature_Development_Workflow/Rebase_vs_Merge|Rebasing vs. merging: why and how]]

====Getting the branch reviewed====
Once you are done with your changes, you are ready to get your branch reviewed. In the review process, the project's core developers will evaluate your code's quality, and will help you in making it perfect before it gets integrated. Here's how to do it.

=====Push your changes to integration=====
If you have a KDE developer account, simply

git push integration add-hello-button

from within your ''add-hello-button'' branch.

If you do not have a KDE Developer account, please get in touch with the core developer who is mentoring you, or with one of the repository's maintainers to get your changes pushed into ''integration''.

=====Submit the branch for review=====
Use Reviewboard for getting your branch reviewed. You can read [[Development/Review_Board|KDE Reviewboard+Git tutorial]] for getting started and understanding the steps involved.

It is '''critical''' that you specify in the review request whether your branch has ever been merged with master or not.

=====Modifying the branch=====
Everytime you update your review request with new code, please remember to push changes to ''integration'' with your new code. That will help developers in reviewing and maintainers in handling your request.

====Getting your branch integrated====
Once your review request has been marked as "Ship it!", your job is done. The maintainers will take care of merging the branch into ''integration/master'', stage it for release, and make it reach ''origin'' in the end.

It is '''critical''' at this point to have your branch ''frozen''. You should not commit anything else to your branch and you should consider it dead. Maintainers will take over its commits and will delete it when merging occurs.

If you are curious to find out what happens to your commit after your code is accepted, read [[Development/Tutorials/Git/Feature_Development_Workflow/Merge_Strategies|Merge strategies to and from integration]]