* ''ItemStatus'' '''status''': See [http://api.kde.org/4.10-api/kdelibs-apidocs/plasma/html/namespacePlasma.html#a4d967711130487b1070311626ad285cb ItemStatus documentation] for values and their meaning. The plasmoid.statusChanged signal is emitted when the status changes.

* ''ItemStatus'' '''status''': See [http://api.kde.org/4.10-api/kdelibs-apidocs/plasma/html/namespacePlasma.html#a4d967711130487b1070311626ad285cb ItemStatus documentation] for values and their meaning. The plasmoid.statusChanged signal is emitted when the status changes.

−

−

=== PopupApplet specific ===

−

* '''popupIcon''': it will be used instead of the applet content when the applet is in a panel

−

<syntaxhighlight lang="ini">

−

plasmoid.popupIcon = "foo-icon";

−

</syntaxhighlight>

−

−

* ''Object'' '''popupIconToolTip''': it contains the icon, mainText and subtext for the tooltip the applet will have when collapsed in an icon, properties:

−

** ''variant'' '''image''': the icon, it may be an icon name, an image path.

−

** ''String'' '''mainText''': the tooltip title

−

** ''String'' '''subText''': the tooltip descriptive subtext

−

−

<syntaxhighlight lang="javascript">

−

var data = new Object

−

data["image"] = "konqueror"

−

data["mainText"] = "ToolTip title"

−

data["subText"] = "ToolTip descriptive sub text"

−

plasmoid.popupIconToolTip = data

−

</syntaxhighlight>

−

−

* ''bool'' '''passivePopup''': if true when the popup is opened other windows can gain focus and the popup won't close

−

−

* ''bool'' '''popupShowing''': true when the popupapplet is iconified and its popup is open

=== Containment specific ===

=== Containment specific ===

Line 109:

Line 86:

* ''int'' '''screen''': Number of the screen this containment is in

* ''int'' '''screen''': Number of the screen this containment is in

* ''string'' '''activityName''': The name of the activity this containment belongs to.

* ''string'' '''activityName''': The name of the activity this containment belongs to.

−

* ''string'' '''activityId''': The id of the activity this containment belongs to.

−

−

* ''ToolBox'' '''toolBox()''': The toolbox of the Containment. The ToolBox is rendered as a separate item on the scene and provides access to the following properties:

−

** ''Array(QAction)'' '''actions''': A list of actions provided by the Containment.

−

== Events ==

== Events ==

Line 129:

Line 101:

The events delivered to declarative applets are:

The events delivered to declarative applets are:

−

* '''popupEvent(boolean shown)''': called on PopupApplets when the popup is shown or hidden

* '''activate()''': called when the widget is activated by the user, e.g. by a keyboard shortcut. Useful for setting the focus on a specific input widget, for instance.

−

* '''initExtenderItem(Extender extender)''': called when an Extender should be set up.

−

= Main Plasma QML Classes =

= Main Plasma QML Classes =

Line 242:

Line 210:

=== Service ===

=== 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.

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:

+

This following example is a simplified version from the Media Controller QML widget in the kde-workspace git repository:

<syntaxhighlight lang="javascript">

<syntaxhighlight lang="javascript">

−

var service = dataSource.serviceForSource(activeSource)

+

var service = mpris2Source.serviceForSource(activeSource);

−

var operation = service.operationDescription("seek")

+

var operation = service.operationDescription("Play");

−

operation.seconds = 10

+

service.startOperationCall(operation);

−

+

−

var job = service.startOperationCall(operation)

+

</syntaxhighlight>

</syntaxhighlight>

−

Here dataSource is the id of a DataSource object, and activeSource is a source contained in one of its '''connectedSources'''.

+

Here mpris2Source 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.

+

The service provides an operation called "Play", that executes the operation for "Play" when service.startOperationCall(operation) is called.

=== ServiceJob ===

=== ServiceJob ===

Line 305:

Line 271:

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

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 ===

=== SortFilterModel ===

Line 337:

Line 301:

}

}

</syntaxhighlight>

</syntaxhighlight>

−

−

== 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:

−

−

<syntaxhighlight lang="ini">

−

ServiceTypes=Plasma/PopupApplet

−

</syntaxhighlight>

−

−

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

−

−

<syntaxhighlight lang="javascript">

−

plasmoid.popupIcon = "konqueror"

−

</syntaxhighlight>

−

−

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

* 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 '''iconSizes'''. it is an Object, that has the following properties:

Theme is also used to control icon sizes, with the property '''iconSizes'''. it is an Object, that has the following properties:

Line 582:

Line 529:

* String '''subText'''

* String '''subText'''

* String '''image''': freedesktop compliant icon name as image of the tooltip

* String '''image''': freedesktop compliant icon name as image of the tooltip

−

−

== Containments ==

−

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 ===

−

The AppletContainer class provides access to the geometry and status of Plasmoids in this Containment.

−

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'' '''minimumHeight''': The minimum height of the applet

−

* ''int'' '''maximumWidth''': The maximum width of the applet

−

* ''int'' '''maximumHeight''': The maximum height of the applet

−

* ''int'' '''preferredWidth''': The preferred height of the applet

−

* ''int'' '''preferredHeight''': The preferred height of the applet

−

* ''enum'' '''status''': The status of the applet, one in the enum

−

** '''UnknownStatus''': The status is unknown

−

** '''PassiveStatus''': The applet is passive

−

** '''ActiveStatus''': The applet is active

−

** '''NeedsAttentionStatus''': The applet asks for attention

−

** '''AcceptingInputStatus''': The applet is accepting input

−

−

−

They can be imported in your code with:

−

<syntaxhighlight lang="javascript">

−

import org.kde.plasma.containments 2.0 as PlasmaContainments

−

</syntaxhighlight>

−

−

−

AppletContainer is only available for Plasma/Containment packages, and only if they are loaded as containment. AppletContainer is new in 4.10.

−

−

=== 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 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:

−

* ''Array(QAction)'' '''actions''': A list of actions provided by the Containment. These actions' most interesting properties are:

Introduction to the Plasmoid QML 2 Declarative API

This document provides an overview/reference of the Declarative QML 2 API for Plasmoids. It isn't a full binding to all of Qt 5.2 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.

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"asFoo

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

Properties exported from the main QML 2 item

The root qml 2.0 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.

Environment

A set of read-only properties (and in most cases notification functions) that tell the Plasmoid about its current environment:

FormFactorformFactor: See the FormFactor documentation for values and their meaning. When the form factor changes, the plasmoid.formFactorChanged signal is emitted.

Locationlocation: See the Location documentation for values and their meaning. When the location changes, the plasmoid.locationChanged signal is emitted.

booleanimmutable: this property is set to true when the Plasmoid is set to not be movable or otherwise changeable, and false otherwise. Configuration is still usually allowed in this state. When the immutability changes, the plasmoid.immutableChanged signal is emitted.

stringcurrentActivity: the current contextual activity name. When the current activity changes, the plasmoid.contextChanged signal is emitted.

booleanuserConfiguring: true if the user configuration interface is currently being displayed.

Properties

A set of read/write properties that allow the Plasmoid to set various visual or functional properties:

AspectRatioModeaspectRatioMode: defines how to treat the aspect ratio of a Plasmoid when resizing it. See the AspectRatioMode documentation for values and their meaning.

For eg :

plasmoid.aspectRatioMode=IgnoreAspectRatio;

BackgroundHintsbackgroundHints: defines how the background of the widget is rendered. See the BackgroundHints documentation for values and their meaning.

For eg :

plasmoid.backgroundHints=0;

booleanbusy: set to true when the Plasmoid is currently processing or waiting for data and the user interface should be blocked while doing so; will generally show a full-Plasmoid animated overlay to denote business

SizePolicyhorizontalSizePolicy: behaviour of the plasmoid in an horizontal layout such as a panel. See the JavaScript API documentation for more information.

SizePolicyverticalSizePolicy: behaviour of the plasmoid in a vertical layout such as a panel.

ItemStatusstatus: See ItemStatus documentation for values and their meaning. The plasmoid.statusChanged signal is emitted when the status changes.

Containment specific

Array(Object)applets: List of all applets in the containment

booldrawWallpaper: Enable/disable the wallpaper painting by the containment

enumcontainmentType: one of

DesktopContainment: A desktop containment

PanelContainment: A desktop panel

CustomContainment: A containment that is neither a desktop nor a panel but something application specific

CustomPanelContainment: A customized desktop panel

intscreen: Number of the screen this containment is in

stringactivityName: The name of the activity this containment belongs to.

Events

Note that many of the events of the JavaScript API are signals in the declarative API (eg: formFactorChanged). These should be connected to in the usual way, for example:

plasmoid.formFactorChanged.connect(function(){...});

However, some notifications are still delivered by events, which should be connected to using addEventListener:

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 Media Controller QML widget in the kde-workspace git repository:

Here mpris2Source is the id of a DataSource object, and activeSource is a source contained in one of its connectedSources.
The service provides an operation called "Play", that executes the operation for "Play" when service.startOperationCall(operation) is called.

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 a list of items as their DataSources; for example the hotplug DataEngine lists all devices currently plugged in and the microblog engine lists all tweets/dents visible to a given account. QML provides some item views such as ListView, GridView and Repeater. Using a DataSource, the DataModel QML object can provide a suitable model 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. If you need all data inserted in the mode, you must explicitly request it using the regular expression ".*"

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:

Plasma Themes

Theme

This class instantiable from QML provides access to the Plasma Theme colors and other facilities such as fonts.
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. Make sure to strip the final extension from this string, so you should for example use "dialogs/background" to get the standard background.

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.