Writing a plasma applet in QML is very easy, in fact, with KDE 4.6 and Qt 4.7 it just works.

+

Writing a Plasma applet in QML is very easy, in fact, with Workspaces 4.6 and Qt 4.7 it just works.

== QML Basics ==

== QML Basics ==

−

It is recommended that you have read through the [http://doc.qt.nokia.com/4.7/qtquick.html Qt QML Tutorials], as there are quite a few and they are explained thoroughly. There is also a list of all [http://doc.qt.nokia.com/4.7/qdeclarativeelements.html standard QML elements].

+

It is recommended that you have read through the [http://qt-project.org/doc/qt-4.8/qtquick.html Qt QML Tutorials], as there are quite a few and they are explained thoroughly. There is also a list of all [http://qt-project.org/doc/qt-4.8/qdeclarativeelements.html standard QML elements].

−

Essentially, most of the content is the same. The exceptions to be noted are how data is gathered...since we use Data Engines, it is a bit different. Text color and font should be made to use PlasmaCore.Theme.

+

Essentially, most of the content is the same. The exceptions to be noted are how data is gathered... since we use Data Engines, it is a bit different. Text color and font should be made to use PlasmaCore.Theme.

−

See the [https://projects.kde.org/projects/kde/kdeexamples/repository KDE Examples] repository for more KDE-related helpful resources. Also of use (which use QML and Plasma) are: [https://projects.kde.org/projects/playground/base/plasma-mobile/repository Plasma Mobile], [https://projects.kde.org/projects/playground/base/declarative-plasmoids/repository Declarative Plasmoids (playground)], for WIP ports of C++ originals

+

See the [https://projects.kde.org/projects/kde/kdeexamples/repository KDE Examples] repository for more KDE-related helpful resources. Also of use (which use QML and Plasma) are: [https://projects.kde.org/projects/playground/base/plasma-mobile/repository Plasma Mobile], [https://projects.kde.org/projects/playground/base/declarative-plasmoids/repository Declarative Plasmoids (playground)], for WIP ports of C++ originals.

=== Root Item ===

=== Root Item ===

Line 18:

Line 18:

==== Row and Column ====

==== Row and Column ====

+

Coloums and Rows are very easy way to grouping items and is very simular to the "normal layout management" with [http://doc.qt.digia.com/stable/qhboxlayout.html QHBoxLayout] and [http://doc.qt.digia.com/stable/qvboxlayout.html QVBoxLayout]. In QML these are named:

+

* Column arranges its children in a column

+

* Row arranges its children in a row

+

* Grid arranges its children in a grid

+

* Flow arranges its children like words on a page

+

+

They have a special property '''spacing'''(int) to define the distance in pixels between two children.

+

+

For furture help please look at [http://qt-project.org/doc/qt-4.8/qml-positioners.html Using QML Positioner and Repeater Items from qt-project.org]

+

+

Some example:

+

<syntaxhighlight lang="javascript">

+

import QtQuick 1.0

+

import org.kde.plasma.core 0.1 as PlasmaCore

+

+

Item {

+

Column{

+

spacing: 10

+

Row {

+

spacing: 5

+

Text{text: 'Local'}

+

Text {

+

id: local

+

text: "XX:XX:XX"

+

}

+

}

+

Row {

+

spacing: 5

+

Text{text: 'UTC'}

+

Text {

+

id: utc

+

text: "XX:XX:XX"

+

}

+

}

+

}

+

}

+

</syntaxhighlight>

==== Anchors ====

==== Anchors ====

−

Anchor layouts offer a nice way of grouping UI elements nicely together. The idea is that you connect edges or corners of one element to the edge or corner of another widget.

+

Anchor layouts offer a nice way of grouping UI elements nicely together. The idea is that you connect edges or corners of one element to the edge or corner of another widget. Available anchors are:

+

* left

+

* horizontalCenter

+

* right

+

* top

+

* verticalCenter

+

* baseline, and bottom.

+

+

Some examples:

Some examples:

<syntaxhighlight lang="javascript">

<syntaxhighlight lang="javascript">

Line 53:

Line 98:

}

}

</syntaxhighlight>

</syntaxhighlight>

+

+

Keep in mind, that you can only use elements that are a parent or a sibling.

+

+

Here a WRONG example ('first'' and ''second'' are no siblings):

+

+

<syntaxhighlight lang="javascript">

+

Text {

+

id: first

+

text: i18n("1st line")

+

}

+

Item{

+

id: breakIt

+

Text {

+

id: second

+

text: i18n("2nd line")

+

anchors {

+

top: first.bottom;

+

}

+

}

+

}

+

</syntaxhighlight>

+

Plasmoidviewer will show you the following explanation:

+

+

file:///XXXX/contents/ui/main.qml:69:9: QML Text: Cannot anchor to an item that isn't a parent or sibling.

+

+

+

More examples you will find on the [http://qt-project.org/doc/qt-4.8/qml-anchor-layout.html Anchor-based Layout in QML from the qt-project.org].

=== Buttons ===

=== Buttons ===

Line 61:

Line 133:

== Package Structure ==

== Package Structure ==

−

You create a .desktop file and the .qml file. They have to be in the usual plasma package structure:

+

You create a .desktop file and the .qml file. They have to be in the usual Plasma package structure:

Essentially, most of the content is the same. The exceptions to be noted are how data is gathered... since we use Data Engines, it is a bit different. Text color and font should be made to use PlasmaCore.Theme.

The root item can be anything that inherits QGraphicsItem. For example, in this case it is QGraphicsWidget which is a plasmoid. It can also simply be an Item. I also noticed that PathView does not respond to mouse inputs automatically (so flicking doesn't work). Probably because events are being intercepted. So take note, it'll have to be e.g. an Item, for that case.

Where the -I is the path to the plasma plugin for qml. Try to look for the path of
/usr/lib/kde4/imports/org/kde/plasma/graphicswidgets/libgraphicswidgetsbindingsplugin.so
and use everything up to org of that path.

Hovewer it's strongly discouraged to use qmlviewer to develop plasmoids, because some features won't be available there, like the following:

In order to have a better integration with the KDE platform and to reach an higher degree of expressivity, the stock features of QML have been expanded with the following features, that strictly follow the Plasmoid JavaScript API:

if the root object of the plasmoid has the properties minimumWidth and minimumHeight, they will be used as the minimum size for the plasmoid. If they will change during the plasmoid execution, the plasmoid minimum size will be updated accordingly.

Every QML plasmoid will have an object called plasmoid, that will give access to the configuration, the formfactor, immutability and so on. It offers the same api as the object with the same name in the Javascript API.

To use standard plasma widgets (e.g. Plasma::LineEdit, etc.), you simply add an import line for them.
All properties, signals and slots from ordinary Plasma widgets are available there.
These widgets are provided as a transition tool, intended to be replaced by the Plasma version of QtComponents, which is currently in development by a gsoc. (note that the Plasma QtComponents have nothing to do with the QtExtraComponents module described above)