|
|
| (One intermediate revision by one other user not shown) |
| Line 1: |
Line 1: |
| ==Abstract==
| | This page was moved here: https://develop.kde.org/docs/plasma/widget/ |
| 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
| |
| | |
| (where "plasmoid" should be replaced with the name of your package)
| |
| | |
| Your directory structure should now be as follows:
| |
| | |
| <syntaxhighlight lang="bash">
| |
| myproject/CMakeLists.txt
| |
| myproject/plasmoid/
| |
| myproject/plasmoid/metadata.desktop
| |
| myproject/plasmoid/contents/
| |
| myproject/plasmoid/contents/ui/
| |
| myproject/plasmoid/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=Tutorial on getting started with Plasma 5 plasmoids.
| |
| Type=Service
| |
| | |
| X-KDE-Library=plasma_applet_tutorial
| |
| 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-KDE-PluginInfo-Category=Windows and Tasks
| |
| </syntaxhighlight>
| |
| | |
| The most important bits are:-
| |
| | |
| * '''X-KDE-Library''' which specifies which library will provide the configuration dialog. In this example then "plasma_applet_tutorial" assignment is just a place holder.
| |
| * '''X-KDE-PluginInfo-Name''' For '''X-KDE-PluginInfo-Category''', refer to the [[Projects/Plasma/PIG | PIG]].
| |
| | |
| | |
| These are the "glue" between your class and plasma, without it, nothing will start.
| |
| | |
| === <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 Plasma 5 ";
| |
| color: "black";
| |
| }
| |
| </syntaxhighlight>
| |
| | |
| === CMakeLists.txt ===
| |
| This CMakeLists.txt file describes where your plasmoid will be installed.
| |
| | |
| <syntaxhighlight lang="cmake">
| |
| # Set minimum CMake version (required for CMake 3.0 or later)
| |
| cmake_minimum_required(VERSION 2.8.12)
| |
| | |
| # Use Extra CMake Modules (ECM) for common functionality.
| |
| # See http://api.kde.org/ecm/manual/ecm.7.html
| |
| # and http://api.kde.org/ecm/manual/ecm-kde-modules.7.html
| |
| find_package(ECM REQUIRED NO_MODULE)
| |
| # Needed by find_package(KF5Plasma) below.
| |
| set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH} ${CMAKE_MODULE_PATH})
| |
| | |
| # Locate plasma_install_package macro.
| |
| find_package(KF5Plasma REQUIRED)
| |
| | |
| # Add installatation target ("make install").
| |
| plasma_install_package(plasmoid org.kde.tutorial)
| |
| | |
| </syntaxhighlight>
| |
|
| |
| For more details on CMake please read [[Guidelines_and_HOWTOs/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 ==
| |
| 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">
| |
| import QtQuick 2.0
| |
| import QtQuick.Layouts 1.1
| |
| import org.kde.plasma.components 2.0 as PlasmaComponents
| |
| import org.kde.plasma.plasmoid 2.0
| |
| import org.kde.plasma.core 2.0 as PlasmaCore
| |
| | |
| PlasmaComponents.Label {
| |
| Layout.minimumWidth : plasmoid.formFactor == PlasmaCore.Types.Horizontal ? height : 1
| |
| Layout.minimumHeight : plasmoid.formFactor == PlasmaCore.Types.Vertical ? width : 1
| |
| text: "Hello world in plasma5";
| |
| }
| |
| </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 and Test==
| |
| Since this plasmoid contains no native (compiled) code you can directly try and execute it using
| |
| <syntaxhighlight lang="bash">
| |
| qmlscene main.qml
| |
| </syntaxhighlight>
| |
| | |
| ===Kpackagetool5===
| |
| kpackagetool5 is the Plasma Package Manager, which you can use to install, test and remove your new plasmoid.
| |
| | |
| You can install your plasmoid into ~/.local/share/plasma as described in this section, though obviously this is just temporary. CMake, below, is recommended.
| |
| | |
| From the myproject folder defined above, use the Plasma Package Manager:
| |
| <syntaxhighlight lang="bash">
| |
| kpackagetool5 -t Plasma/Applet --install plasmoid
| |
| </syntaxhighlight>
| |
| | |
| You can pass to the --install option of kpackagetool5 the full path of the directory containing the metadata.desktop file or any relative path to it.
| |
| | |
| Notice that your Plasmoid is now available via the +Add Widgets function from the (Right Click Menu) on Plasma Desktop. For clarity of this tutorial, note that the name of your Plasmoid is Tutorial, as defined by the '''Name''' in your .desktop file
| |
| | |
| * '''Name=Tutorial'''
| |
| | |
| After updating your code, to install the new version of your Plasmoid, from the myproject folder defined above, use the Plasma Package Manager:
| |
| <syntaxhighlight lang="bash">
| |
| kpackagetool5 -t Plasma/Applet --upgrade plasmoid
| |
| </syntaxhighlight>
| |
| | |
| To remove the plasmoid, use the Plasma Package Manager:
| |
| | |
| <syntaxhighlight lang="bash">
| |
| kpackagetool5 -t Plasma/Applet --remove org.kde.tutorial
| |
| </syntaxhighlight>
| |
| | |
| == Testing the Applet ==
| |
| | |
| You can test your Plasmoid without installing it with the plasmoidviewer tool:
| |
| | |
| [[File:Plasmoidviewer.png]]
| |
| | |
| {{Input|1=<nowiki>plasmoidviewer --applet package</nowiki>}}
| |
| | |
| The --applet parameter can accept two options:
| |
| * the path (full or relative) to your <code>metadata.desktop</code> file, or
| |
| * the packaged version of your plasmoid, such as <code>org.kde.tutorial</code>, which can usually be found in <code>~/.local/share/plasma/plasmoids/</code>
| |
| Either one will launch your plasmoid in a sample window, as shown above.
| |
| | |
| The "FormFactors" and "Location" buttons help to see how the Plasmoid behaves in different situations.
| |
| | |
| If your current Development Environment differs from the Test Installation, you have to run cmake with -DCMAKE_INSTALL_PREFIX=$KF5. Then run make. If successful 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 plasmashell as shown :
| |
| <syntaxhighlight lang="bash">
| |
| kbuildsycoca5 #Needed once to let KDE know there is a new plugin
| |
| plasmashell
| |
| </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.
| |
| | |
| == 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
| |
| {{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 --applet org.kde.plasma.kickoff</nowiki>}}
| |
| | |
| [[File:Plasmoidviewer.png]]
| |
| | |
| For testing an installed Plasmoid, the --applet parameter takes the X-KDE-PluginInfo-Name of the plasmoid in its .desktop file.
| |
| | |
| The "FormFactors" and "Location" buttons help to see how the Plasmoid behaves in different situations.
| |
