|Getting Data: How to retrieve data from a DataEngine
What is a widget?
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.
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:
- SuperKaramba's karambas
- Enlightenment 17 edje content
- Google Gadgets
- MacOS dashboard widgets (though not all)
These are loaded via host AppletScriptEngine plugins that bridge between the widget itself and Plasma's canvas.
What is a Plasmoid?
The only required part of the structure, in fact, is the contents directory - almost everything will go in this directory. But separating your code into a different directory from application data is a good habit to have.
X-KDE-PluginInfo-Author=<Your name here>
X-KDE-PluginInfo-Email=<Your email here>
This metadata.desktop file list important information needed by Plasma to load the widget, and also information about what the widget is and who created it.
Comment gives a more detailed description of the widget. This is also displayed in the Add Widget dialog, and can be translated in the same way as Name.
Icon gives the name of the icon to associate with this plasmoid. The icon is shown in the Add Widget dialog. It must be the name of an icon that is either distributed with KDE (such as chronometer) or provided by your plasmoid. If you want to provide the icon, you can use Icon=icon.png.
The Type, X-KDE-ServiceTypes, X-Plasma-API and X-Plasma-MainScript fields are required for Plasma to find your plasmoid and know what to do with it. Note that X-Plasma-MainScript is a path relative the contents directory.
X-Plasma-DefaultSize specifies the default size for widget, as width,height. While the units aren't technically pixels, they have the same value as pixels providing you don't do anything like zoom in or out on your desktop.
X-KDE-PluginInfo-Category gives a category for the widget. This is used in the Add Widgets dialog to group and filter widgets. The value must be one of the category names listed at Projects/Plasma/PIG.
X-KDE-PluginInfo-Name is the internal name of the plasmoid (you can think of this as the name of the plasmoid, as opposed to the name of the widget which is given by Name). This is the name you will use as an argument to plasmoidviewer or plasmapkg when you need to provide a plasmoid name rather than a path. It doesn't have to be the same name as the directory containing metadata.desktop.
X-KDE-PluginInfo-Author, X-KDE-PluginInfo-Email, X-KDE-PluginInfo-Version, X-KDE-PluginInfo-Website and X-KDE-PluginInfo-License are informational, and are displayed in the About dialog for the plasmoid (which can be viewed by clicking the information icon next to the corresponding widget in the Add Widgets dialog of plasma).
X-KDE-PluginInfo-EnabledByDefault and X-KDE-PluginInfo-Depends rarely need to be changed from the values given here.
layout = new LinearLayout(plasmoid);
label = new Label();
plasmoid is a global variable that represents your widget. It has some useful methods that we'll come to in later tutorials.
First, we create a layout, because plasmoids don't have a layout by default. This just makes sure that the label is the correct size and in the correct place. Passing plasmoid to the LinearLayout attaches the layout to the widget.
Next we add a label to the layout, and finally we set the label text.
Testing (KDE 4.3+)
This is very convenient for development as you can edit the Plasmoid and test the changes immediately without re-installing the plasmoid over and over again.
plasmapkg -i .
The final argument to plasmapkg is the path to the directory containing metadata.desktop and the contents directory.
You can now add your widget to the desktop using the Add Widgets dialog, or view it by running
If you want to see where your plasmoid has actually been installed you can find out like this:
To uninstall the plasmoid, use plasmapkg again with its -r option:
Note that while the argument to plasmapkg -i is a file or directory, you need to pass the plasmoid name (given by X-KDE-PluginInfo-Name in metadata.desktop) to plasmapkg -r.
On top of the ECMA Script language, QtScript provides Qt integration features. Probably the most useful one in the context of writing Plasmoids is the use of signals and slots which is Qt's callback mechanism. Signals may be emitted in QtScript by calling the signal method in question, a signal can be connected to a slot by using the connect() method (and disconnected with disconnect()) and any function defined in the Plasmoid may be used as a slot. For example:
print("We got clicked!")
button = new PushButton
This will print out:
We got clicked!
on the console when the Plasmoid starts, and the "We got clicked!" again whenever the button is clicked by the user.