(→Theme: bolden) |
(→Svg: explain imagepath, rearrange it) |
||
Line 197: | Line 197: | ||
* QSize '''size''' | * QSize '''size''' | ||
* bool '''multipleImages''' | * bool '''multipleImages''' | ||
− | * String '''imagePath''' | + | * String '''imagePath''' can be anything in the '''desktoptheme/''' folder. For more information on what is available, see [http://techbase.kde.org/Projects/Plasma/Theme#Current_Theme_Elements Plasma Theme Elements] |
* bool '''usingRenderingCache''' | * bool '''usingRenderingCache''' | ||
Line 216: | Line 216: | ||
} | } | ||
</syntaxhighlight> | </syntaxhighlight> | ||
− | |||
=== SvgItem === | === SvgItem === |
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)
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.
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 is a receiver for a dataEngine and can be declared inside QML:
import org.kde.plasma.core 0.1 as PlasmaCore
PlasmaCore.DataSource {
id: dataSource
engine: "time"
connectedSources: ["Local"]
interval: 500
}
It has the following properties:
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'(...).
It has the following methods:
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.
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.
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:
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"]).
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"].
Note that view.currentItem holds the item currently selected. However, due to (http://bugreports.qt.nokia.com/browse/QTBUG-16347) this does not work in PathView. A workaround is to make your own.
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:
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, simply change
ServiceTypes=Plasma/Applet
To:
ServiceTypes=Plasma/Applet,Plasma/PopupApplet
Then in the main QML item's Component.onCompleted, do:
NOTE: the below code presently has no affect, yet the icons seems to get retrieved from the desktop file (FIXME - is this needed?).
plasmoid.popupIcon("konqueror")
This class instantiable from QML provides access to the Plasma Theme colors and other facilities such as fonts. It has the following properties:
Declaring a Svg element instantiates a Plasma Svg instance. This class doesn't draw anything. For drawing, SvgItem is used. Properties:
Methods:
Sample Code:
PlasmaCore.Svg {
id: mySvg
imagePath: "widgets/line"
}
It's a graphical element that will actually paint a Svg instance. Properties:
It's a graphical element that paints a Plasma::FrameSvg, so a rectangular image composed by 9 elements contained in a Svg file, useful for things like buttons and frames.
Flags
Properties:
Properties:
Dialog instantiates a Plasma::Dialog, it will be a Plasma themed top level window that can contain any QML component.
Properties:
Methods:
Properties:
Declaring a ToolTip instance makes it possible to use Plasma tooltips with any QML item.
Properties:
TODO