Development/Tutorials/Plasma5/QML2/GettingStarted
Abstract
This tutorial needs KDE Frameworks 5 / Plasma 5 to build. We are going to create a simple plasmoid in this tutorial. To keep things simple, we are going to make have use QML 2.0 and it will use Plasma Components in our tutorial .
Package Structure
You create a .desktop file and the .qml file. They have to be in the usual Plasma package structure:
- plasmoid/metadata.desktop
- plasmoid/contents/ui/main.qml
Your directory structure should now be as follows:
myproject/CMakeLists.txt
myproject/plasmoid/
myproject/plasmoid/metadata.desktop
myproject/plasmoid/contents/
myproject/plasmoid/contents/ui/
myproject/plasmoid/contents/ui/main.qml
The Code
The .desktop file
Every Plasmoid needs a .desktop file to tell plasma how it should be started and what name it carries.
metadata.desktop
[Desktop Entry]
Encoding=UTF-8
Name=Tutorial
Comment=Tutoial on getting started with Plasma 5 plasmoids .
Type=Service
X-KDE-ParentApp=
X-KDE-PluginInfo-Author=Heena
X-KDE-PluginInfo-Email=[email protected]
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-Name=org.kde.tutorial
X-KDE-PluginInfo-Version=2.0
X-KDE-PluginInfo-Website=plasma.kde.org
X-KDE-ServiceTypes=Plasma/Applet
X-Plasma-API=declarativeappletscript
X-Plasma-MainScript=ui/main.qml
X-Plasma-RemoteLocation=
X-KDE-PluginInfo-Category=Windows and Tasks
The most important bits are the X-KDE-Library and X-KDE-PluginInfo-Name, they are the "glue" between your class and plasma, without it, nothing will start. For X-KDE-PluginInfo-Category, refer to the PIG.
main.qml
import QtQuick 2.0
import org.kde.plasma.components 2.0 as PlasmaComponents
PlasmaComponents.Label {
text: "Hello world in Plasma 5 ";
}
Building it all, the CMakeLists.txt
Finally, to put everything together you need to build everything. All you need is to put
plasma_install_package(tutorial org.kde.tutorial plasma/plasmoids applet)
For more details on CMake please read Development/Tutorials/CMake
Representations
The plasmoid can provide two components: compactRepresentation and FullRepresentation
import QtQuick 2.0
import QtQuick.Layouts 1.1
import org.kde.plasma.plasmoid 2.0
import org.kde.plasma.core 2.0 as PlasmaCore
Item {
Plasmoid.compactRepresentation: CompactRepresentation {}
Plasmoid.fullRepresentation: FullRepresentation {}
}
where the files CompactRepresentation.qml and FullRepresentation.qml exist in the plasmoid package. They are both optional: if compactRepresentation is not present, a default one will be created (the plasmoid icon) if fullRepresentation is not defined, the root item will be picked instead. If a fullRepresentaion is defined, the root item will not contain any graphical element (they will be never shown) but is only supposed to contain models and data that must be accessible from both the compact and the full representation.
Minimum size
if the root object of the plasmoid (or the fullRepresentation if present) has the Layout attached property exposed, 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.
import QtQuick 2.0
import QtQuick.Layouts 1.1
import org.kde.plasma.components 2.0 as PlasmaComponents
PlasmaComponents.Label {
Layout.minimumWidth : formFactor == PlasmaCore.Types.Horizontal ? height : 1
Layout. minimumHeight : formFactor == PlasmaCore.Types.Vertical ? width : 1
text: "Hello world in plasma5 ";
}
In the above example, the minimum width will be the height in case the formFactor is Horizontal .Similarly , if the formFactor is Vertical then minimumHeight shall be the width as shown in the above example .
Localization
It is possible to localize strings with the usual i18n(), i18nc(), i18np() global functions.
Install
Cmake
Just you need to put
plasma_install_package(tutorial org.kde.tutorial plasma/plasmoids applet)
in your CMakeLists.txt and you will be fine .
Plasmapkg
You can install your plasmoid, though obviously this is just temporary. CMake, below, is recommended:
plasmapkg2 --install plasmoid_plasma5
Testing the Applet
If your current Development Environment differs from the Test Installation, you have to run cmake with -DCMAKE_INSTALL_PREFIX=$KF5. Then run make. If succesfull the applet can be installed by running sudo make install
and run kbuildsycoca5 (so that KDE apps will know about the new desktop files). In order to test your Applet you can load the Plasma 5 plasmoid in plasma-shell as shown :
kbuildsycoca5 #Needed once to let KDE know there is a new plugin
plasma-shell
You can even find your plasmoid in ~./local5 after you build it . Where applet_name is the value specified into .desktop for the X-KDE-PluginInfo-Name key.
Wow that was fun!
Congrats! you just made your first qml 2.0 Plasmoid.
Find and try out existing Plasmoids
Here you will learn how to find existing installed plasmoid packages and selectively start one from command line.
If you are working from within Plasma you can call
eval $(dbus-launch)
first which will speed things up. But beware that a second DBUS can interfere with your existing Plasma session.
To get a list of installed Plasma packages call
plasmapkg2 --list
The result will look similar to this:
org.kde.desktopcontainment org.kde.milou org.kde.muonnotifier org.kde.panel org.kde.plasma.activitybar org.kde.plasma.analogclock org.kde.plasma.battery org.kde.plasma.calculator org.kde.plasma.calendar org.kde.plasma.clipboard org.kde.plasma.devicenotifier org.kde.plasma.digitalclock org.kde.plasma.fifteenpuzzle org.kde.plasma.folder org.kde.plasma.fuzzyclock org.kde.plasma.icon org.kde.plasma.katesessions org.kde.plasma.kicker org.kde.plasma.kickoff org.kde.plasma.kimpanel org.kde.plasma.lock_logout org.kde.plasma.mediacontroller org.kde.plasma.networkmanagement org.kde.plasma.notes org.kde.plasma.notifications org.kde.plasma.pager org.kde.plasma.panelspacer org.kde.plasma.printmanager org.kde.plasma.showActivityManager org.kde.plasma.showdesktop org.kde.plasma.systemloadviewer org.kde.plasma.systemmonitor.cpu org.kde.plasma.systemmonitor.diskactivity org.kde.plasma.systemmonitor.diskusage org.kde.plasma.systemmonitor.memory org.kde.plasma.systemmonitor.net org.kde.plasma.systemtray org.kde.plasma.taskmanager org.kde.plasma.timer org.kde.plasma.trash org.kde.plasma.webbrowser org.kde.plasma.windowlist
plasmawindowed
Pick one of those lines of your choice and run for example
plasmawindowed org.kde.plasma.kickoff
which will launch the Kickoff Application Launcher in a separate window.
plasmoidviewer
Instead of plasmawindowed you can also use plasmoidviewer (in the plasmate repo).
plasmoidviewer
The "FormFactors" and "Location" button help to see how the plasmoid behaves in different situations.