Development/Tutorials/Plasma4/QML/API

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 bassed 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 paged should probably be copied and stripped down the imperative bits not present there, it would make harder to update tough)

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.

Data engines

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

DataSource

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

DataSource {
    id: dataSource
    engine: "time"
    connectedSources: ["Local"]
    interval: 500
}

It has the following 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 no polling will be executed
• string engine: the plugin name of the dataengine to load
• 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"

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
• void disconnectSource(String source): removes that source from connectedSources

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:

 var service = dataSource.serviceForSource(activeSource)
 var operation = service.operationDescription("seek")
 operation.seconds = 10

 var job = service.startOperationCall(operation)

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

If 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
• String keyRoleFilter: it's a regular expression. Only data with keys that match this filter expression will be inserted in the model
• int count (read only): how many items are in the model

Example:

ListView {
  model: PlasmaCore.DataModel {
       dataSource: microblogSource
       keyRoleFilter: "[\\d]*"
   }
   delegate: Text {
       text: title
   }
}

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"]).

Plasma Themes

Theme

This class instantiable from QML provides access to the Plasma Theme colors and other facilities such as fonts. It has the following properties:

• String themeName (read only)
• QFont font (read only)
• bool windowTranslucentEnabled (read only)
• Url homepage (read only)
• bool useGlobalSettings (read only)
• QString wallpaperPath (read only)
• color textColor (read only)
• color highlightColor (read only)
• color backgroundColor (read only)
• color buttonTextColor (read only)
• color buttonBackgroundColor (read only)
• color linkColor (read only)
• color visitedLinkColor (read only)
• color visitedLinkColor (read only)
• color buttonHoverColor (read only)
• color buttonFocusColor (read only)
• color viewTextColor (read only)
• color viewBackgroundColo (read only)r
• color viewHoverColor (read only)
• color viewFocusColor (read only)
• String styleSheet (read only)