Plasma/Package

From KDE Community Wiki
Revision as of 23:42, 2 July 2011 by Nalvarez (talk | contribs) (→‎Plasma Package Format: update to new syntaxhighlighter)

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.