Development/Tutorials/Plasma4/JavaScript/GettingStarted
Abstract
In this tutorial we'll cover creating a very simple plasmoid in QtScript, Qt's ECMAScript implementation, to provide a Plasma widget. ECMAScript may be more familiar to you as JavaScript or JScript, which are Netscape's and Microsoft's implementations of the language, respectively.
Using QtScript doesn't require any external dependecies, since it is part of the Qt libraries. As of KDE 4.3, the Plasma QtScript engine is part of kdebase/runtime, and so can be used in any libplasma-based application, not just the Plasma desktop.
Some terminology: widget refers to what the user will see on their desktop, and plasmoid refers to the package you will create by following this tutorial. The distinction is not very strong, since a plasmoid always shows a widget, and the terms can be used interchangably to a certain extent. Just remember that "widget" is what the user will see.
Project Structure
The first step for any software project is to set up your project's directory on disk. For this tutorial we are going to create a very simple "hello-qtscript" plasmoid. Create a directory on somewhere called hello-qtscript which in turn contains a contents directory which then contains a code directory. This command below will do all this.
mkdir -p hello-qtscript/contents/code
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.
Metadata.desktop
In the hello-qtscript directory create a file called metadata.desktop and open it in your text editor. Copy the following code into metadata.desktop.
[Desktop Entry]
Name=Hello QtScript
Comment=An example QtScript widget
Icon=chronometer
Type=Service
X-KDE-ServiceTypes=Plasma/Applet
X-Plasma-API=javascript
X-Plasma-MainScript=code/main.js
X-Plasma-DefaultSize=200,100
X-KDE-PluginInfo-Author=<Your name here>
X-KDE-PluginInfo-Email=<Your email here>
X-KDE-PluginInfo-Name=hello-qtscript
X-KDE-PluginInfo-Version=1.0
X-KDE-PluginInfo-Website=http://plasma.kde.org/
X-KDE-PluginInfo-Category=Examples
X-KDE-PluginInfo-Depends=
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true
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.
Name gives the name of widget as seen by the user when they go to the Add Widget dialog on the desktop. There can be additional name entries for different languages. For example, you could add a Dutch translation by inserting the line Name[nl]=Hallo QtScript.
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.
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.
Main script
The name of the main script file is given by X-Plasma-MainScript in metadata.desktop, and is relative to the contents directory. In our case, we will need to create the file hello-qtscript/contents/code/main.js. Put the following code in it:
layout = new LinearLayout(plasmoid);
label = new Label();
layout.addItem(label);
label.text = 'Hello QtScript!';
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+)
If you have KDE 4.3 or later, you can now test your plasmoid without installing it by entering the hello-qtscript directory and running plasmoidviewer. Alternatively, call
plasmoidviewer /path/to/hello-qtscript
Note that with KDE 4.2, you will have to install the plasmoid first (see below). After that, you can run plasmoidviewer with the name of the plasmoid given by X-KDE-PluginInfo-Name in metadata.desktop. For example:
plasmoidviewer hello-qtscript
Installing
You can install the plasmoid by running the following command from within the hello-qtscript directory:
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
plasmoidviewer hello-qtscript
Packaging
If you want to share your plasmoid, you'll have to package it. Run the following from within the hello-qtscript directory:
zip -r ../hello-qtscript.zip . &&
mv ../hello-qtscript.zip ../hello-qtscript.plasmoid
You now have a plasmoid package you can share with the world. To install it, either use the "Install new widgets" functionality in the Add Widgets dialog, or go to the directory containing hello-qtscript.plasmoid and run
plasmapkg -i hello-qtscript.plasmoid
To uninstall the plasmoid, use plasmapkg again with its -r option:
plasmapkg -r hello-qtscript
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.