Development/Tutorials/Plasma4/JavaScript/DataEngineAPI

Introduction to the DataEngine JavaScript API

DataEngines are a key concept in Plasma. They are objects which serve to deliver some kind of data to one or more Plasma applets or plasmoids. Separating the part of the code that supplies the data from the part which displays the data, means that one DataEngine can be reused by many applets, regardless of which language the DataEngine or applet is written in.

DataEngines provide a standardized interface to various resources. Applets may be written for different uses, with different devices in mind, manage the presentation with for example JavaScript, C++ or HTML and still use the same dataEngine to supply the raw data. On the other hand, plasmoids can use the same API to access different kinds of data.

Plasma supports out of the box many different DataEngines, which deliver all kinds of varied information about things like the state of the machine, e.g. CPU usage, memory usage, position of the mouse pointer and Internet access. It is also possible to write new dataEngines. Some of the existing dataEngines include rss-feedreader, microblogging engine and weather service report.

Useful tool for anyone working with dataEngines is

plasmaengineexplorer

You can use it to inspect which engines are currently available in your system to supply data and what data are they providing.

DataEngines work in one-directional one-to-many relationship. One dataEngine may provide same raw data to many plasmoids all at the same (for example the same time engine could power both clock and timezone applets) but plasmoids cannot send information to dataEngines - they only provide information. In some situations it might be useful to provide some data (for example login credentials to web service) for the interaction. For that purpose there is another plasma technology, Services.

This document describes the API any dataEngine exposes to plasmoids written in JavaScript.

QtScript

Warning

This section needs improvements: Please help us to

cleanup confusing sections and fix sections which contain a todo

The example used is from the Plasmoids, and isn't relevant to DataEngines as it uses PushButton, etc. A new example should be written that uses the DataEngine API

The Simplified JavaScript API is powered by Qt's QtScript system which provides access to a full featured ECMA Script interpreter. If it works in ECMA Script, it will work in a Simplified JavaScript Plasmoid. As an interesting implementation note, QtScript uses the high performance ECMA Script interpreter from WebKit and shares this code with QtWebKit.

On top of the ECMA Script language, QtScript provides Qt integration features. Probably the most useful one in this context 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:

function onClick()
{
    print("We got clicked!")
}

function onFirstClick()
{
    print("First click!")
    button.clicked.disconnect(onFirstClick)
}

button = new PushButton
button.clicked.connect(onClick)
button.clicked.connect(onFirstClick)
button.clicked()

This will print out:

We got clicked!
First click!

on the console when the Plasmoid starts, and the "We got clicked!" again whenever the button is clicked by the user.

The object that emitted the signal that caused a slot to be called can be retrieved using the QObject sender read-only property of the global plasmoid object.

Addons

Warning

This section needs improvements: Please help us to

cleanup confusing sections and fix sections which contain a todo

This section can be copy and pasted from the Plasmoid API page

Extensions

Warning

This section needs improvements: Please help us to

cleanup confusing sections and fix sections which contain a todo

This section can be copy and pasted from the Plasmoid API page