Development/Tutorials/Plasma4/JavaScript/CheatSheet

JavaScript Plasmoid Cheat Sheet

Tutorial Series	JavaScript Plasmoids
Previous	Now Playing: Advanced DataEngine Usage Example
What's Next	n/a
Further Reading	JavaScript Plasmoid API reference

Basics

Everything but the metadata.desktop file goes in a directory named contents
X-Plasma-MainScript in the metadata.desktop file should point to the main script, relative to the contents directory
X-Plasma-DefaultSize in the metadata.desktop file specifies the default widget size in width,height format (eg: 200,100)
plasmoidviewer is an immensely useful tool
To connect to a signal use object.signalName.connect(function() {});
Enumeration values can be used like

if (plasmoid.formFactor() == Vertical) {

   layout.setOrientation(QtVertical);

} else {

   layout.setOrientation(QtHorizontal);

}

The plasmoid variable contains all the main plasmoid functionality and represents the main plasmoid widget, and corresponds to the Applet class in C++
The startupArguments variable contains any arguments that were passed to the plasmoid when it was started (such as when the plasmoid is registered as a handler for a mimetype)
The loadui function can be used to load a Qt UI file. Beware that a relative path is relative to plasma's working directory (in 4.2 at least), and so may not do what you want.
The print function prints debug output
There are several ccontructor methods:
- PlasmaSvg(file, parent) constructs a Plasma::Svg. The second argument is optional.
- PlasmaFrameSvg(file, parent) constructs a Plasma:FrameSvg. The second argument is optional.
- QPainter()
- QGraphicsItem()
- QTimer()
- QFont()
- QRectF()
- QSizeF()
- QPoint()
- LinearLayout() constructs a QGraphicsLinearLayout
- Url() constructs a KUrl
Plus constructors for all the Plasma widgets (eg: IconWidget()).

The Name and Comment fields in the metadata.desktop file can be translated like Name[nl]=Hallo JavaScript
plasmoid.i18n() takes a string (in English) as the first argument, and substitutes in the following arguments to replace %1, %2, %3 etc. Eg: plasmoid.i18n("The file is called %1", fileName);
plasmoid.i18nc() works just the same, but has an extra argument at the start that provides some context for translators. Eg: plasmoid.i18nc("Player name - score", "%1 - %2", playerName, score);
plasmoid.i18np() is for cases where plural forms might be important. Eg: plasmoid.i18np("One image in album %2", "%1 images in album %2", imageCount, albumName);
plasmoid.i18ncp() is a combination of the previous two. Eg: plasmoid.i18ncp("Personal file", "One file", "%1 files", numFiles);

Add a dataUpdate method to plasmoid to receive updates: plasmoid.dataUpdate = function(name, data) { /* ... */ } - data contains an object mapping keys to values
plasmoid.dataEngine("engine name").connectSource("source name", plasmoid, 500); updates every half second
plasmoid.dataEngine("engine name").connectSource("source name", plasmoid); updates when new data is available
plasmaengineexplorer is your friend

Prior to KDE 4.4, DO NOT use plasmoid.dataEngine("engine name").serviceForSource("source name") - you will get a dummy service back. Instead, use plasmoid.service("engine name", "source name")