|
|
| (2 intermediate revisions by 2 users 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:
| |
| | |
| <code 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
| |
| </code>
| |
| | |
| == 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.
| |
