Development/Tutorials/Plasma5/QML2/GettingStarted: Difference between revisions

From KDE TechBase
(Not sure if this is correct, but the old link is broken..)
 
(52 intermediate revisions by 17 users not shown)
Line 1: Line 1:
 
This page was moved here: https://develop.kde.org/docs/plasma/widget/
 
==Abstract==
This tutorial needs KDE Frameworks 5 / Plasma 2  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_plasma2/metadata.desktop
* plasmoid_plasma2/contents/ui/main.qml
 
Your directory structure should now be as follows:
 
<syntaxhighlight lang="bash">
myproject/CMakeLists.txt
myproject/plasmoid_plasma2/
myproject/plasmoid_plasma2/metadata.desktop
myproject/plasmoid_plasma2/contents/
myproject/plasmoid_plasma2/contents/ui/
myproject/plasmoid_plasma2/contents/ui/main.qml
</syntaxhighlight>
 
== 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'''
<syntaxhighlight lang="ini">
[Desktop Entry]
Encoding=UTF-8
Name=Tutorial
Comment=Tutoial on getting started with plasma2 plasmoids .
Type=Service
X-KDE-ParentApp=
X-KDE-PluginInfo-Author=Heena
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
</syntaxhighlight>
 
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 [[Projects/Plasma/PIG | PIG]].
 
===  <tt>main.qml</tt> ===
<syntaxhighlight lang="javascript">
import QtQuick 2.0
import org.kde.plasma.components 2.0 as PlasmaComponents
 
PlasmaComponents.Label {
    text: "Hello world in plasma2 ";
}
</syntaxhighlight>
 
=== Building it all, the CMakeLists.txt ===
Finally, to put everything together you need to build everything. All you need is to put
 
<syntaxhighlight lang="javascript">
  plasma_install_package(tutorial org.kde.tutorial plasma/plasmoids applet)
</syntaxhighlight>
For more details on CMake please read [[Development/Tutorials/CMake]]
 
== 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.
<syntaxhighlight lang="javascript">
import QtQuick 2.0
import org.kde.plasma.components 2.0 as PlasmaComponents
 
PlasmaComponents.Label {
    property int minimumWidth : formFactor == PlasmaCore.Types.Horizontal ? height : 1
    property int minimumHeight : formFactor == PlasmaCore.Types.Vertical ? width  : 1
    text: "Hello world in plasma2 ";
}
</syntaxhighlight>
 
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
<syntaxhighlight lang="javascript">
  plasma_install_package(tutorial org.kde.tutorial plasma/plasmoids applet)
</syntaxhighlight>
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:
<syntaxhighlight lang="bash">
plasmapkg --install plasmoid_plasma2
</syntaxhighlight>
 
== 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 plasma2 plasmoid in plasma-shell as shown :
<syntaxhighlight lang="bash">
kbuildsycoca5 #Needed once to let KDE know there is a new plugin
plasma-shell
</syntaxhighlight>
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.

Latest revision as of 08:49, 11 March 2023