(add import) |
(typo--) |
||
(7 intermediate revisions by 4 users not shown) | |||
Line 78: | Line 78: | ||
It has the following 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'''(...). | + | 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) | + | * '''onNewData'''(String sourceName, Plasma::DataEngine::Data data) the local vairables are named to '''sourceName''' and '''data''' |
* '''onSourceAdded'''(String source) | * '''onSourceAdded'''(String source) | ||
* '''onSourceRemoved'''(String source) | * '''onSourceRemoved'''(String source) | ||
Line 90: | Line 90: | ||
* '''onConnectedSourcesChanged'''() | * '''onConnectedSourcesChanged'''() | ||
* '''onSourcesChanged'''() | * '''onSourcesChanged'''() | ||
+ | |||
+ | You normaly wants to use '''onNewData''' (that is the aquivalent to '''dataUpdated''' in other languages). Here is sample with the time dataengine: | ||
+ | |||
+ | <syntaxhighlight lang="javascript"> | ||
+ | import QtQuick 1.0 | ||
+ | import org.kde.plasma.core 0.1 as PlasmaCore | ||
+ | |||
+ | Item { | ||
+ | PlasmaCore.DataSource { | ||
+ | id: dataSource | ||
+ | engine: "time" | ||
+ | connectedSources: ["Local","UTC"] | ||
+ | interval: 500 | ||
+ | |||
+ | onNewData:{ | ||
+ | if(sourceName== "Local"){ | ||
+ | local.text = data.Time | ||
+ | } | ||
+ | else if(sourceName== "UTC"){ | ||
+ | label_utc.text = data.Timezone | ||
+ | } | ||
+ | } | ||
+ | |||
+ | } | ||
+ | Grid{ | ||
+ | columns: 2 | ||
+ | spacing: 5 | ||
+ | Text{text: dataSource.data.Local.Timezone} | ||
+ | Text { | ||
+ | id: local | ||
+ | text: "XX:XX:XX" | ||
+ | } | ||
+ | Text{id: label_utc; text: "XXXX"} | ||
+ | Text { | ||
+ | id: utc | ||
+ | text: dataSource.data.UTC.Time | ||
+ | } | ||
+ | } | ||
+ | } | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | You see two different approches to get to the data: | ||
+ | |||
+ | * One is to act on ''onNewData'' | ||
+ | * Use the ''data'' parameter from dataSource | ||
==== Methods ==== | ==== Methods ==== | ||
Line 148: | Line 193: | ||
* DataSource '''dataSource''': the id of an existing (and connected) DataSource | * 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 '''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 | + | * String '''keyRoleFilter''': it's a regular expression. Only data with keys that match this filter expression will be inserted in the model. If you need all data inserted in the mode, you must explicitly request it using the regular expression ".*" |
* int '''count''' (read only): how many items are in the model | * int '''count''' (read only): how many items are in the model | ||
Line 271: | Line 316: | ||
* real '''wordSpacing''' (read only) | * real '''wordSpacing''' (read only) | ||
* size '''mSize''' the size, width and height of an uppercase "M" in this font (read only) | * size '''mSize''' the size, width and height of an uppercase "M" in this font (read only) | ||
+ | |||
+ | Theme is also used to control icon sizes, with the property '''iconSize'''. it is an Object, that has the following properties: | ||
+ | * int '''desktop''': size of icons suited for the workspace | ||
+ | * int '''toolbar''': icons to be put in a ToolBar component | ||
+ | * int '''small''': smallest size for still "readable" icons | ||
+ | * int '''dialog''': icons to be put in popup dialogs | ||
=== Svg === | === Svg === | ||
Line 442: | Line 493: | ||
== Containments == | == Containments == | ||
− | A Plasma Containment manages the position and manipulation of Plasmoids. | + | A Plasma Containment manages the position and manipulation of Plasmoids. The declarative containment is responsible for layout of applets and can provide custom applet handles. The containment should listen to the plasmoid.immutability property. In order to lay out applets in your containment, you can use the AppletContainer class to access geometry information of applets. |
+ | Actions such as configure and close are available through plasmoid.actions. | ||
+ | You can access the plasmoid global property from containments in the same way as from declarative and javascript plasmoids. If the plasmoid is a Containment, you can get a list of actions for it. If you want to provide background rendering in your Containment yourself, read the applet.backgroundHints property and after that set applet.backgroundHints to 0 to tell the Applet that is should not render the background. | ||
+ | |||
=== AppletContainer === | === AppletContainer === | ||
The AppletContainer class provides access to the geometry and status of Plasmoids in this Containment. | The AppletContainer class provides access to the geometry and status of Plasmoids in this Containment. | ||
Properties: | Properties: | ||
+ | * ''Item'' '''applet''': The applet item, this property allows you to track destruction of the actual applet and update your layout. | ||
+ | ** ''int'' '''backgroundHints''': Should the Applet be rendered on top of a background frame? 0 for no background, 1 for default background, 2 for translucent background | ||
* ''int'' '''minimumWidth''': The minimum width of the applet | * ''int'' '''minimumWidth''': The minimum width of the applet | ||
* ''int'' '''minimumHeight''': The minimum height of the applet | * ''int'' '''minimumHeight''': The minimum height of the applet | ||
Line 468: | Line 524: | ||
AppletContainer is only available for Plasma/Containment packages, and only if they are loaded as containment. AppletContainer is new in 4.10. | AppletContainer is only available for Plasma/Containment packages, and only if they are loaded as containment. AppletContainer is new in 4.10. | ||
− | == ToolBox == | + | === ToolBox === |
The ToolBox is only available through the plasmoid object, through plasmoid.toolBox(). The ToolBox is rendered as a separate item on top of the scene covering the entire containment. It is loaded from the "org.kde.toolbox" Plasma Package, if the package is not found, no ToolBox will be loaded. | The ToolBox is only available through the plasmoid object, through plasmoid.toolBox(). The ToolBox is rendered as a separate item on top of the scene covering the entire containment. It is loaded from the "org.kde.toolbox" Plasma Package, if the package is not found, no ToolBox will be loaded. | ||
The ToolBox provides a listmodel of actions that can be rendered using Repeaters or ListViews. The ''actions'' list property contains actions from the Corona and Containments. Examples for these actions are showing the add widget or activities interface, lock and unlock. The actions in the list change dynamically whenever the widgets are locked or unlocked. | The ToolBox provides a listmodel of actions that can be rendered using Repeaters or ListViews. The ''actions'' list property contains actions from the Corona and Containments. Examples for these actions are showing the add widget or activities interface, lock and unlock. The actions in the list change dynamically whenever the widgets are locked or unlocked. | ||
Line 477: | Line 533: | ||
** ''QIcon'' '''icon''': The icon belonging to this action. | ** ''QIcon'' '''icon''': The icon belonging to this action. | ||
** ''String'' '''text''': The icon belonging to this action. | ** ''String'' '''text''': The icon belonging to this action. | ||
− | ** | + | ** '''trigger()''': Call trigger from your action delegate to trigger the action. |
<syntaxhighlight lang="javascript"> | <syntaxhighlight lang="javascript"> | ||
import org.kde.plasma.containments 0.1 as PlasmaContainments | import org.kde.plasma.containments 0.1 as PlasmaContainments | ||
− | </ | + | </syntaxhighlight> |
+ | |||
ToolBox is only available for Containments and new in 4.10. | ToolBox is only available for Containments and new in 4.10. | ||
Line 527: | Line 584: | ||
* QPixmapItem.Tile: the image is duplicated horizontally and vertically | * QPixmapItem.Tile: the image is duplicated horizontally and vertically | ||
* QPixmapItem.TileVertically: the image is stretched horizontally and tiled vertically | * QPixmapItem.TileVertically: the image is stretched horizontally and tiled vertically | ||
− | * QPixmapItem.TileHorizontally : | + | * QPixmapItem.TileHorizontally : the image is stretched vertically and tiled horizontally |
QImageItem defines the same values, you just need to replace QPixmapItem with QImageItem. | QImageItem defines the same values, you just need to replace QPixmapItem with QImageItem. |
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
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.
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.
The root qml item can export some properties to influence its behavior:
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 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(...).
You normaly wants to use onNewData (that is the aquivalent to dataUpdated in other languages). Here is sample with the time dataengine:
import QtQuick 1.0
import org.kde.plasma.core 0.1 as PlasmaCore
Item {
PlasmaCore.DataSource {
id: dataSource
engine: "time"
connectedSources: ["Local","UTC"]
interval: 500
onNewData:{
if(sourceName== "Local"){
local.text = data.Time
}
else if(sourceName== "UTC"){
label_utc.text = data.Timezone
}
}
}
Grid{
columns: 2
spacing: 5
Text{text: dataSource.data.Local.Timezone}
Text {
id: local
text: "XX:XX:XX"
}
Text{id: label_utc; text: "XXXX"}
Text {
id: utc
text: dataSource.data.UTC.Time
}
}
}
You see two different approches to get to the data:
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.
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.
var service = messagesDataSource.serviceForSource(src)
var operation = "auth";
function result(job) {
statusItem.authorizationStatus = job.result;
print("ServiceJob result: " + job.result + " op: " + job.operationName);
}
var operation = service.operationDescription(operation);
operation.user = userName;
operation.password = password;
var serviceJob = service.startOperationCall(operation);
serviceJob.finished.connect(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:
This is an example from the feed widget:
model: PlasmaCore.SortFilterModel {
id: postTitleFilter
filterRole: "title"
sortRole: "time"
sortOrder: "DescendingOrder"
filterRegExp: toolbarFrame.searchQuery
sourceModel: PlasmaCore.SortFilterModel {
id: feedCategoryFilter
filterRole: "feed_url"
sourceModel: PlasmaCore.DataModel {
dataSource: feedSource
keyRoleFilter: "items"
}
}
}
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.
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:
Each Font element has the following properties:
Theme is also used to control icon sizes, with the property iconSize. it is an Object, that 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:
"dialogs/background"
to get the standard background.Methods:
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:
Methods:
Sample Code:
PlasmaCore.FrameSvg {
id: myFrameSvg
imagePath: "widgets/button"
prefix: "pressed"
}
It's a graphical element that will actually paint a Svg instance. Properties:
Sample Code:
PlasmaCore.SvgItem {
id: mySvgItem
anchors {
top: parent.top
left: parent.left
}
width: 300
height: 3
svg: mySvg
elementId: "horizontal-line"
}
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:
Sample Code:
PlasmaCore.FrameSvgItem {
id: myFrameSvgItem
anchors.fill: parent
imagePath: "translucent/dialogs/background"
}
Dialog instantiates a Plasma::Dialog, it will be a Plasma themed top level window that can contain any QML component.
Properties:
import QtQuick 1.1
import org.kde.plasma.core 0.1 as PlasmaCore
Item {
PlasmaCore.Dialog {
visible: true
mainItem: Item {
width: 500
height: 500
Text {
anchors.centerIn: parent
color: "red"
text: qsTr("text")
}
}
}
}
Methods:
Properties:
Declaring a ToolTip instance makes it possible to use Plasma tooltips with any QML item.
Properties:
A Plasma Containment manages the position and manipulation of Plasmoids. The declarative containment is responsible for layout of applets and can provide custom applet handles. The containment should listen to the plasmoid.immutability property. In order to lay out applets in your containment, you can use the AppletContainer class to access geometry information of applets. Actions such as configure and close are available through plasmoid.actions. You can access the plasmoid global property from containments in the same way as from declarative and javascript plasmoids. If the plasmoid is a Containment, you can get a list of actions for it. If you want to provide background rendering in your Containment yourself, read the applet.backgroundHints property and after that set applet.backgroundHints to 0 to tell the Applet that is should not render the background.
The AppletContainer class provides access to the geometry and status of Plasmoids in this Containment. Properties:
They can be imported in your code with:
import org.kde.plasma.containments 0.1 as PlasmaContainments
AppletContainer is only available for Plasma/Containment packages, and only if they are loaded as containment. AppletContainer is new in 4.10.
The ToolBox is only available through the plasmoid object, through plasmoid.toolBox(). The ToolBox is rendered as a separate item on top of the scene covering the entire containment. It is loaded from the "org.kde.toolbox" Plasma Package, if the package is not found, no ToolBox will be loaded. The ToolBox provides a listmodel of actions that can be rendered using Repeaters or ListViews. The actions list property contains actions from the Corona and Containments. Examples for these actions are showing the add widget or activities interface, lock and unlock. The actions in the list change dynamically whenever the widgets are locked or unlocked. Actions such as lock screen and leave can be implemented using the powermanagement dataengine's services for these functions.
ToolBox provides access to the following properties:
import org.kde.plasma.containments 0.1 as PlasmaContainments
ToolBox is only available for Containments and new in 4.10.
Plasma components documentation online at api.kde.org
The QtExtraComponents make some very convenient Qt classes usable from within QML.
They can be imported in your code with:
import org.kde.qtextracomponents 0.1
This one wraps around a QPixmap class and allows you to send a QPixmap directly to QPixmapItem.
Properties:
This one wraps around a QImage class and allows you to send a QImage directly to QImageItem.
Properties:
Both QPixmapItem and QImageItem expose a FillMode enum. This enum defines how the image is going to be used to fill the item.
For QPixmapItem, possible values are:
QImageItem defines the same values, you just need to replace QPixmapItem with QImageItem.
This one wraps around a QPixmap class and allows you to send a QIcon directly to QIconItem.
Properties: