Difference between revisions of "Development/Tutorials/Plasma5/QML2/GettingStarted"

Jump to: navigation, search
(Find and try out existing Plasmoids: add example for plasmoidviewer)
 
(18 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
 
 
==Abstract==
 
==Abstract==
This tutorial needs KDE Frameworks 5 / Plasma 2 to build.
+
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 .
 
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 .
  
Line 9: Line 7:
 
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:
  
* plasmoid_plasma2/metadata.desktop
+
* plasmoid/metadata.desktop
* plasmoid_plasma2/contents/ui/main.qml
+
* plasmoid/contents/ui/main.qml
  
 
Your directory structure should now be as follows:
 
Your directory structure should now be as follows:
Line 16: Line 14:
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
 
myproject/CMakeLists.txt
 
myproject/CMakeLists.txt
myproject/package/
+
myproject/plasmoid/
myproject/package/metadata.desktop
+
myproject/plasmoid/metadata.desktop
myproject/package/contents/
+
myproject/plasmoid/contents/
myproject/package/contents/ui/
+
myproject/plasmoid/contents/ui/
myproject/package/contents/ui/main.qml
+
myproject/plasmoid/contents/ui/main.qml
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 27: Line 25:
 
Every Plasmoid needs a .desktop file to tell plasma how it should be started and what name it carries.  
 
Every Plasmoid needs a .desktop file to tell plasma how it should be started and what name it carries.  
  
'''plasma2-applet-tutorial.desktop'''
+
'''metadata.desktop'''
 
<syntaxhighlight lang="ini">
 
<syntaxhighlight lang="ini">
 
[Desktop Entry]
 
[Desktop Entry]
 
Encoding=UTF-8
 
Encoding=UTF-8
 
Name=Tutorial
 
Name=Tutorial
Comment=Tutoial on getting started with plasma2 plasmoids .
+
Comment=Tutoial on getting started with Plasma 5 plasmoids .
 
Type=Service
 
Type=Service
 
X-KDE-ParentApp=
 
X-KDE-ParentApp=
X-Plasma-DefaultSize=200,200
 
 
X-KDE-PluginInfo-Author=Heena
 
X-KDE-PluginInfo-Author=Heena
 
X-KDE-PluginInfo-Email=heena393@gmail.com
 
X-KDE-PluginInfo-Email=heena393@gmail.com
Line 44: Line 41:
 
X-KDE-ServiceTypes=Plasma/Applet
 
X-KDE-ServiceTypes=Plasma/Applet
 
X-Plasma-API=declarativeappletscript
 
X-Plasma-API=declarativeappletscript
X-Plasma-DefaultSize=
 
 
X-Plasma-MainScript=ui/main.qml
 
X-Plasma-MainScript=ui/main.qml
 
X-Plasma-RemoteLocation=
 
X-Plasma-RemoteLocation=
Line 58: Line 54:
  
 
PlasmaComponents.Label {
 
PlasmaComponents.Label {
     text: "Hello world in plasma2 ";
+
     text: "Hello world in Plasma 5 ";
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 70: Line 66:
 
   
 
   
 
For more details on CMake please read [[Development/Tutorials/CMake]]
 
For more details on CMake please read [[Development/Tutorials/CMake]]
 +
 +
== Representations ==
 +
 +
The plasmoid can provide two components: compactRepresentation and FullRepresentation
 +
<syntaxhighlight lang="javascript">
 +
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 {}
 +
}
 +
 +
</syntaxhighlight>
 +
 +
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 ==
 
== Minimum size ==
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.
+
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.
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
 
import QtQuick 2.0
 
import QtQuick 2.0
 +
import QtQuick.Layouts 1.1
 
import org.kde.plasma.components 2.0 as PlasmaComponents
 
import org.kde.plasma.components 2.0 as PlasmaComponents
 +
  
 
PlasmaComponents.Label {
 
PlasmaComponents.Label {
     property int minimumWidth : formFactor == PlasmaCore.Types.Horizontal ? height : 1
+
     Layout.minimumWidth : formFactor == PlasmaCore.Types.Horizontal ? height : 1
     property int minimumHeight : formFactor == PlasmaCore.Types.Vertical ? width  : 1
+
     Layout. minimumHeight : formFactor == PlasmaCore.Types.Vertical ? width  : 1
     text: "Hello world in plasma2 ";
+
     text: "Hello world in plasma5 ";
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 100: Line 118:
 
You can install your plasmoid, though obviously this is just temporary. CMake, below, is recommended:
 
You can install your plasmoid, though obviously this is just temporary. CMake, below, is recommended:
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
plasmapkg --install plasmoid-qml
+
plasmapkg2 --install plasmoid_plasma5
 
</syntaxhighlight>
 
</syntaxhighlight>
 
  
 
== Testing the Applet ==
 
== Testing the Applet ==
Line 108: Line 125:
  
 
and run kbuildsycoca5 (so that KDE apps will know about the new desktop files).
 
and run kbuildsycoca5 (so that KDE apps will know about the new desktop files).
In order to test your Applet you can load the plasma2 plasmoid in plasma-shell as shown :
+
In order to test your Applet you can load the Plasma 5 plasmoid in plasma-shell as shown :
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
 
kbuildsycoca5 #Needed once to let KDE know there is a new plugin
 
kbuildsycoca5 #Needed once to let KDE know there is a new plugin
Line 118: Line 135:
 
== Wow that was fun! ==
 
== Wow that was fun! ==
 
Congrats! you just  made your first qml 2.0 Plasmoid.
 
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 KDE4 you can call
 +
{{Input|1=<nowiki>eval $(dbus-launch)</nowiki>}}
 +
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
 +
{{Input|1=<nowiki>plasmapkg2 --list</nowiki>}}
 +
 +
The result will look similar to this:
 +
{{Output|1=<nowiki>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</nowiki>}}
 +
 +
=== plasmawindowed ===
 +
 +
Pick one of those lines of your choice and run for example
 +
{{Input|1=<nowiki>plasmawindowed org.kde.plasma.kickoff</nowiki>}}
 +
 +
which will launch the Kickoff Application Launcher in a separate window.
 +
 +
=== plasmoidviewer ===
 +
 +
Instead of plasmawindowed you can also use plasmoidviewer (in the plasmate repo).
 +
 +
{{Input|1=<nowiki>plasmoidviewer</nowiki>}}
 +
 +
[[File:Plasmoidviewer.png]]
 +
 +
The "FormFactors" and "Location" button help to see how the plasmoid behaves in different situations.

Latest revision as of 15:52, 4 March 2015

Contents

[edit] 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 .

[edit] 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

[edit] The Code

[edit] 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=heena393@gmail.com
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.

[edit] main.qml

import QtQuick 2.0
import org.kde.plasma.components 2.0 as PlasmaComponents
 
PlasmaComponents.Label {
    text: "Hello world in Plasma 5 ";
}

[edit] 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

[edit] 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.

[edit] 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 .

[edit] Localization

It is possible to localize strings with the usual i18n(), i18nc(), i18np() global functions.


[edit] Install

[edit] 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 .

[edit] Plasmapkg

You can install your plasmoid, though obviously this is just temporary. CMake, below, is recommended:

plasmapkg2 --install plasmoid_plasma5

[edit] 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.

[edit] Wow that was fun!

Congrats! you just made your first qml 2.0 Plasmoid.

[edit] 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 KDE4 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

[edit] 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.

[edit] plasmoidviewer

Instead of plasmawindowed you can also use plasmoidviewer (in the plasmate repo).

plasmoidviewer

Plasmoidviewer.png

The "FormFactors" and "Location" button help to see how the plasmoid behaves in different situations.


This page was last modified on 4 March 2015, at 15:52. This page has been accessed 6,623 times. Content is available under Creative Commons License SA 3.0 as well as the GNU Free Documentation License 1.2.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal