Introduction to the Plasmoid QML Declarative API

This document provides an overview/reference of the Declarative QML API for Plasmoids. It isn't a full binding to all of Qt or KDE's libraries, but a focused set of bindings designed to make writing Plasmoids fast and easy, while remaining powerful.

The API in this documentation covers the API of the Plasma specific QML components, so only the Declarative part of the API.

The QML ScriptEngine is based upon the Plasma JavaScript engine, making the API of the JavaScript part identical to the one of the JavaScript plasmoids engine.
To see the api of the global Plasmoid object, see the JavaScript API documentation.
(TODO: the JavaScript api page should probably be copied and stripped down the imperative bits not present there, it would make it harder to update tough)
The most important API for using graphical widgets is the Plasma QtComponents API

What Is a Declarative Plasmoid?

To denote that this Plasmoid is a Declarative widget, ensure that in the metadata.desktop file there is this line:

X-Plasma-API=declarativeappletscript

What follows is a description of the Plasma declarative classes instantiable from QML.

fetching data from the plasmoid package

If you have a file in your plasmoid package under contents, let's say an image, you can access it with the plasmapackage url protocol:

Image {
source:"plasmapackage:/images/foo.png"}

The above code will load in the Image component the file foo.png located in contents/images of your plasmoid package.

import"plasmapackage:/code/foo.js"as Foo

Similarly, the above code will import a javascript file from the folder contents/code of your plasmoid package.

Properties exported from the main QML item

The root qml item can export some properties to influence its behavior:

property Component compactRepresentation: if the plasmoid is a popupapplet, the component in compactRepresentation will be used instead of the icon and will always be collapsed, regardless if it's in a panel or not.

Main Plasma QML Classes

Data Engines

While it's possible to fetch data from a Plasma DataEngine in the same way as the JavaScript API, it is preferrable to use the following declarative classes:

DataSource

DataSource is a receiver for a dataEngine and can be declared inside QML:

Properties

bool valid (read only): true when the DataSource is successfully connected to a data engine

int interval: interval of polling of the dataengine, if 0 (default value, so no need to specify if you don't need it) no polling will be executed

string engine: the plugin name of the dataengine to load, e.g. "nowplaying", etc.

Array(string) connectedSources: all the sources of the dataengine we are connected to (and whose data will appear in the data property)

Array(string) sources (read only): all the sources available from the dataengine

variant map data (read only): It's the most important property, it's a map of all the data available from the dataengine: its structure will be as follows:

each key of the map will be a source name, in connectedSources

each value will be a variant hash, so an hash with strings as keys and any variant as value

example: dataSource.data["Local"]["Time"] indicates the Time key of the dataengine source called "Local"

string sourceFilter it's a regular expression. If the DataSource is connected to more than one source, only inserts data from sources matching this filter expression in the model. If we want to have a source watch all sources beginning with say "name:", the required regexp would be sourceFilter: "name:.*"

Signals

It has the following signals:

Note that javascript/qml applies the 'on' prefix to signals. So the actual signal name in C++ which is e.g. newData(...) becomes onNewData(...).

onNewData(String sourceName, Plasma::DataEngine::Data data)

onSourceAdded(String source)

onSourceRemoved(String source)

onSourceConnected(String source)

onSourceDisconnected(String source)

onIntervalChanged()

onEngineChanged()

onDataChanged()

onConnectedSourcesChanged()

onSourcesChanged()

Methods

It has the following methods:

StringList keysForSource(String source): lists all the keys corresponding to a certain source: for instance in the "time" dataengine, for the "Local" source, keys will be:

"Timezone Continent"

"Offset"

"Timezone"

"Time"

"Date"

"Timezone City"

Service serviceForSource(String source): returns a Plasma service that corresponds a given source: see the section about services for how to use it.

void connectSource(String source): adds to connectedSources the new source

Service

Due to their imperative nature, Plasma Services are not instantiated as QML classes, but rather created out of a DataSource with the method serviceForSource and used in the JavaScript portions of the QML files.
This following example is a simplified version from the Now Playing QML widget in the kdeexamples git repository:

Here dataSource is the id of a DataSource object, and activeSource is a source contained in one of its connectedSources.
The service provides an operation called "seek", with a parameter called "seconds", that can be written on it as a property of a JavaScript object.

ServiceJob

It is necessary to monitor the result of a Service operation, it's possible to connect to the finished signal provided by the job return paramenter of the startOperationCall service method.
The finished signal has the same job as parameter, from which is possible to check the variant result property, to check the result.

DataModel

Some data engines return as their data something that can be interpreted as a list of items, rather than simple key/value pairs.
QML provides some item views such as ListView, GridView and Repeater.
The DataModel QML object can provide, based on a DataSource a model suitable for those QML item views.

It has the following properties:

DataSource dataSource: the id of an existing (and connected) DataSource

String sourceFilter: it's a regular expression. If the DataSource is connected to more than one source, only inserts data from sources matching this filter expression in the model. To, for example, have a source watch all sources beginning with say "name:", the required regexp would be sourceFilter: "name:.*"

String keyRoleFilter: it's a regular expression. Only data with keys that match this filter expression will be inserted in the model

In the example, microblogSource is the id of a DataSource, and inserts in the model only entries that have a number as the key name (matched with [\\d]*, in this case tweets ids)

Each item in the model will have the form of a variant hash: all the keys of the hash will be registered as model role names, in the example, "title" is a role of the model containing a string (also reachable with model["title"]).

A special reserved role will always be present: "DataEngineSource": it will contain the name of the data engine source that gave origin to this item. Therefore, if you want merely the string of the current source that the model is at...do model["DataEngineSource"].

SortFilterModel

SortFilterModel is a proxy model for easy sorting and/or filtering of the items in a DataModel (or any other QAbstractItemModel subclass that has been registered in QML with setContextProperty from a C++ application)
Properties:

model sourceModel

String filterRegExp

String filterRole

String sortRole

Qt::SortOrder sortOrder

int count (read only)

Popup Applet

So you want your QML applet to be a popup applet, like the device notifier (an icon in the panel shows and expands the applet)?

Why, that's easy.

To change your plasmoid from being a regular boring one, in your metadata.desktop, simply change this following line:

ServiceTypes=Plasma/Applet

To:

ServiceTypes=Plasma/Applet,Plasma/PopupApplet

Then in the main QML item's Component.onCompleted, do:

plasmoid.popupIcon="konqueror"

If you want to use other elements instead of an icon when collapsed in a panel, use the compactRepresentation property in the root Item.

Plasma Themes

Theme

This class instantiable from QML provides access to the Plasma Theme colors and other facilities such as fonts.
From KDE 4.8 a Theme instance is always present given the org.kde.plasma.core plugin was imported, is not necessary to create it by hand.
It has the following properties:

Svg

String imagePath can be anything in the desktoptheme/ folder. For more information on what is available, see Plasma Theme Elements

bool usingRenderingCache

Methods:

QPixmap pixmap(QString elementID)

void resize(qreal width, qreal height)

void resize(): resets the image to its default dimension

QSize elementSize(QString elementId)

QRectF elementRect(QString elementId)

bool hasElement(QString elementId)

bool isValid(): true if valid svg file

FrameSvg

Declaring a FrameSvg element instantiates a Plasma FrameSvg instance. This class doesn't draw anything. For drawing, FrameSvgItem is used.
This is to be used when you need informations about the framesvg, such as hasElementPrefix().

Properties:

All properties from Svg

EnabledBorders enabledBorders: flag combination of:

NoBorder

TopBorder

BottomBorder

LeftBorder

RightBorder

Methods:

All methods from Svg

void setImagePath(QString path)

void resizeFrame(QSize size)

QSize frameSize()

qreal marginSize(Plasma::MarginEdge edge)

void getMargins(qreal left, qreal top, qreal right, qreal bottom): parameters are output, they get set with the margins from the FrameSvg

QRectF contentsRect(): the rectangle of the center element, taking the margins into account.