Development/Tutorials/Plasma4/JavaScript/CheatSheet

    From KDE TechBase
    The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.
    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);