Development/Tutorials/Plasma4/JavaScript/CheatSheet
JavaScript Plasmoid Cheat Sheet
Tutorial Series | JavaScript Plasmoids |
Previous | System Monitor: How to access systemmonitor data engine |
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);
}
Global variables and functions
- 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 constructor 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()).
Languages
- The Name and Comment fields in the metadata.desktop file can be translated like Name[nl]=Hallo JavaScript
- i18n() takes a string (in English) as the first argument, and substitutes in the following arguments to replace %1, %2, %3 etc. Eg: i18n("The file is called %1", fileName);
- i18nc() works just the same, but has an extra argument at the start that provides some context for translators. Eg: i18nc("Player name - score", "%1 - %2", playerName, score);
- i18np() is for cases where plural forms might be important. Eg: i18np("One image in album %2", "%1 images in album %2", imageCount, albumName);
- i18ncp() is a combination of the previous two. Eg: i18ncp("Personal file", "One file", "%1 files", numFiles);
DataEngines
- 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
Services
- 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")
Notifications
If you want to use the standard notifications in KDE, you can using Services, with the following code:
engine = dataEngine("notifications");
service = engine.serviceForSource("notification");
op = service.operationDescription("createNotification");
op["appName"] = "foo";
op["appIcon"] = "konqueror";
op["summary"] = "this is a summary";
op["body"] = "body of notification";
op["timeout"] = 2000;
service.startOperationCall(op);