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
- code/ files containing scripting code
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
[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.