Plasma/Package: Difference between revisions

From KDE Community Wiki
(→‎Plasma Package Format: update to new syntaxhighlighter)
m (moved)
Tag: Replaced
 
(One intermediate revision by one other user not shown)
Line 1: Line 1:
<b>See also [http://aseigo.blogspot.com/2008/03/plasma-packages.html Plasma Packages]</b>
This was moved to https://develop.kde.org/docs/plasma/
 
== 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)
** {{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
 
In the root of the package, an XML format file called {{path|metadata.xml}} which gives a detailed description of the plasmoid.
 
{{path|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 {{path|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:
 
<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>
 
== Packager ==
 
When a Plasma package is installed via the Plasma Packager, it will store the package in {{path|$APPDATA/plasma/$PACKAGE_TYPE_ROOT}} then read {{path|metadata.xml}} and create a <tt>.desktop</tt> 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.

Latest revision as of 12:52, 2 May 2023