Plasma/Package

See also Plasma Packages

Plasma Package Format

This document describes the Plasmoid Package Format. It uses the Plasma::Package implementation in libplasma as a basis.

A Plasmoid is packed in one zip compressed file that contains all the necessary files to run the plasmoid. It is best to give it a .plasmoid extension. It can also pick icons from the icon theme running in KDE as well as SVGs from the Plasma Theme.

The files in a Plasmoid package can be code, images, layout or plasmoid-specific data files.

To keep those files separated each filetype is stored in a subdirectory.

• $PlasmoidName-$PlasmoidVersion/ (root)
  • 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

In the root of the package, an XML format file called metadata.xml which gives a detailed description of the plasmoid.

metadata.desktop contains the following mandatory fields:

• Name of the Plasmoid
• Author
• A version number for the Plasmoid
• Icon (YES/NO/$iconName).
  • If YES (uppercase), it should pick icon.png.
  • If it's $iconName, it should pick the icon from the user KDE theme.
  • If it's NO (uppercase), the plasmoid won't have 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:

[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=[email protected]
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

Packager

When a Plasma package is installed via the Plasma Packager, it will store the package in $APPDATA/plasma/$PACKAGE_TYPE_ROOT then read metadata.xml and create a .desktop file which it will install into the services directory. In this way, Plasma can use KTrader to find all Plasmoids whether they are written in C++ or an interpreted language.

A user interface needs to be created for browsing through packages for installation as well as a class for browsing the contents of a package, getting information on it and pulling out files on demand.

Another nice thing to be done would be a small command-line app to quickly create plasmoids with arbitrary metadata information, just for testing purposes.