See also Plasma Packages

[edit] 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 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 seperated 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
    • 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 scripting language the plasmoid is written in
• Description of the Plasmoid giving the user a nice overview of the Plasmoid capabilities

Optionally these fields can be added:

• 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=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

[edit] Packager

When a Plasmagik package is installed via the Plasma Packager, it will store the package in $APPDATA/plasma/packages 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 (provided by Plasmagik?) as well as a class for browsing the contents of a package, getting information on it and pulling out files on demand.

A D-Bus interface also needs to be provided, probably registered at org.kde.plasma /Plasmagik.

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.

TODO: Plasmagik should be able to automatically put code, images, etc... into their directory. Feature to be implemented later.

TODO:

• Localisation
• Write a metadata.xml to be shown as example (later)