Warning, /plasma/plasma-desktop/design/plasmoids is written in an unsupported language. File is not indexed.
0001 Plasmoids 0002 ========= 0003 0004 What is a widget? 0005 ================ 0006 In the context of Plasma, a "widget" is a single, self-contained graphical object on the canvas. They can be added and removed individually, configured separately from other widgets, etc. These "mini applications" are sometimes referred to in other widget platforms as "applets", "apps", "gadgets", "karambas", "desklets". We chose the word "widget" for Plasma as it is used by other some other existing systems. 0007 0008 The API of a widget is defined by the host "ScriptEngine", with the exception of native Plasma widgets written in C++ which allows plugins in loadable libraries which use the API of the Plasma library directly. Currently Plasma supports both such "native" widgets written in C++, ones written in various dynamic languages (Plasmoids) as well as: 0009 0010 * SuperKaramba's karambas 0011 * Enlightenment 17 edje content 0012 * MacOS dashboard widgets (though not all) 0013 0014 These are loaded via host AppletScriptEngine plugins that bridge between the widget itself and Plasma's canvas. 0015 0016 What is a Plasmoid? 0017 ================== 0018 A Plasmoid is a widget that can be loaded into Plasma that uses the native Plasma API and comes packaged in a single archive file that includes the code, metadata, images, configuration definitions, etc. Plasmoids may be currently written in the following languages / APIs: 0019 0020 * HTML/JavaScript widgets (essentially "web pages for Plasma"): they are limited to a small subset of the Plasma library API and DataEngines 0021 * Simplified JavaScript: these are written in JavaScript but use a managed set of API from the Plasma library and elsewhere; these are the most likely to be widely portable between Plasma instances and are the most securable. 0022 * Full JavaScript: a work in progress, this provides full access to the Plasma, KDE and Qt APIs 0023 * Ruby: full access to the Plasma, KDE, Qt and other Ruby APIs are provided 0024 * Python: full access to the Plasma, KDE, Qt and other Python APIs are provided 0025 0026 There are tutorials for the various APIs available here: https://techbase.kde.org/Development/Tutorials/Plasma 0027 0028 The Plasmoid Package 0029 ==================== 0030 A Plasmoid package is a single archive file compressed using the zip compression algorithm. By convention they have a .plasmoid suffix. 0031 0032 The layout of a Plasmoid package is as follows, starting with the root (/) being the top of the zip archive: 0033 0034 metadata.desktop: a .desktop file (INI format) following the standard KPluginInfo layout. See more about this file below. 0035 contents/ 0036 code/ -> where all the scripts are kept 0037 main -> by default, the name of the script to start the Plasmoid from 0038 config/ -> KConfigXT and INI files describing configuration variables 0039 main.xml -> main config file, KConfigXT xml 0040 default-configrc -> default configuration, INI file 0041 configui/ -> Qt Designer files describing configuration dialog pages 0042 config.ui -> main configuration UI 0043 images/ -> image files of various formats 0044 translations/ -> po files for individual translations; each translation should appear in subdirectories named after the language code 0045 ui/ -> user interface description files, usually Qt Designer 0046 0047 The Metadata File 0048 ================= 0049 The metadata.desktop file contains information about the widget that is critical to proper function. This file is a standard "INI format" file with one group in it called [Desktop Entry]. A typical such file appears below: 0050 0051 [Desktop Entry] 0052 Name=JavaScript Animations 0053 Comment=An example showing how animations can be used from JavaScript 0054 Icon=plasma 0055 Type=Service 0056 X-KDE-ServiceTypes=Plasma/Applet 0057 X-KDE-PluginInfo-Author=Aaron Seigo 0058 X-KDE-PluginInfo-Category=Examples 0059 X-KDE-PluginInfo-Email=plasma-devel@kde.org 0060 X-KDE-PluginInfo-EnabledByDefault=true 0061 X-KDE-PluginInfo-License=BSD 0062 X-KDE-PluginInfo-Name=javascript-animations-example 0063 X-KDE-PluginInfo-Version=0.1 0064 X-KDE-PluginInfo-Website=https://www.kde.org/plasma-desktop 0065 X-Plasma-API=javascript 0066 0067 The icon can either refer to a file in the root of the package by the same name, or a standard icon theme icon name. 0068 0069 Important fields include: 0070 0071 * X-KDE-PluginInfo-Name= what the widget will be referred to internally and MUST be unique; as such a "reverse domain name" approach is a good idea, e.g. "org.foo.somewidget". 0072 * X-Plasma-API entry defines which language and API the widget is written for and dictates which ScriptEngine will be loaded for it. 0073 0074 Useful optional fields include: 0075 * X-Plasma-MainScript= path relative to the contents/ dir of the package; used to override the default of "contents/code/main" 0076 0077 Installing and Replacing 0078 ======================== 0079 Plasmoid packages can be installed and removed from the Add Widgets interfaces of various Plasma applications, such as plasma desktop, or directly using the kpackagetool5 binary. See the output of `kpackagetool5 --help` for more information on using that utility. 0080