|
|
| (8 intermediate revisions by 5 users not shown) |
| Line 1: |
Line 1: |
| {{Note|1=This is very much a work in progress. I only have so much free time each day. Keep checking back.}}
| | This has been moved to https://develop.kde.org/docs/plasma/widget/ |
| | |
| ==Welcome!==
| |
| This tutorial will take you through the process of creating a simple "Hello World"-style plasmoid. It is written primarily in QML2 and intended for the Plasma 5.10+ desktop. There will also be a bit of Javascript mixed in, and it will be called out when used. An explanation of the various plasmoid testing and installation tools will be covered as well.
| |
| | |
| ===Tools and Prerequisites===
| |
| | |
| You're going to need a text editor, preferably one that can highlight QML syntax. The [https://atom.io/ Atom] editor is free and has a QML syntax plugin. The ultimate in Qt/QML development is Qt Creator, which is the integrated development environment (IDE) that ships with the Qt framework, which powers the entire Plasma interface. It's overkill for our purposes, so it's recommended you stick with a fairly basic text editor for now.
| |
| | |
| You '''will not''' have to spend hours downloading and compiling source code in order to develop plasmoids. Everything you'll need is probably already included in your KDE-based distribution.
| |
| | |
| ===File Structure===
| |
| | |
| The plasmoid system relies on a common file structure, so open up a terminal and create the following directories. The example shows the highest level as <code>~/projects</code>, but feel free to create an empty folder anywhere in your personal workspace. That root directory will be omitted during the rest of the tutorial - it's just a convenient place for you to store your code.
| |
| | |
| {{Input|1=<nowiki>
| |
| ~/projects/
| |
| hellomoid/
| |
| hellomoid/plasmoid/
| |
| hellomoid/plasmoid/contents/
| |
| hellomoid/plasmoid/contents/ui
| |
| </nowiki>}}
| |
| | |
| There are also two important configuration files. First off is '''CMakeLists.txt''', which defines some of the underlying dependencies to turn your plasmoid source code into a runnable program.
| |
| | |
| Create a new file in your editor and use the following template:
| |
| | |
| {{input|1=<nowiki>
| |
| # set minimum CMake version (req'd for CMake 3.0 or later)
| |
| cmake_minimum_required(VERSION 2.8.12)
| |
| | |
| # use Extra CMake Modules (ECM) for common functionality
| |
| find_package(ECM REQUIRED NO_MODULE)
| |
| # needed by find_package(KF5Plasma) below.
| |
| set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH} ${ECM_KDE_MODULE_DIR} ${CMAKE_MODULE_PATH})
| |
| | |
| # Locate plasma_install_package macro
| |
| find_package(KF5Plasma REQUIRED)
| |
| | |
| # Add installation target ("make install")
| |
| plasma_install_package(plasmoid.org.kde.hellomoid)
| |
| </nowiki>}}
| |
| | |
| Save this file as <code>hellomoid/CMakeLists.txt</code>. At least for the sake of this tutorial, you probably won't need to touch it again. So just create it and file it away.
| |
| | |
| Next up is '''metadata.desktop''', which contains many more configurable options. We'll start with the template, then explain which options are safe to change while keeping your plasmoid running.
| |
| | |
| {{input|1=<nowiki>
| |
| [Desktop Entry]
| |
| Encoding=UTF-8
| |
| Name=Hellomoid
| |
| Comment=Hello World example plasmoid
| |
| Icon=face-cool
| |
| Type=Service
| |
| | |
| X-KDE-ParentApp=
| |
| X-KDE-PluginInfo-Author=Your Name
| |
| | |
| X-KDE-PluginInfo-License=GPL
| |
| X-KDE-PluginInfo-Name=org.kde.hellomoid
| |
| X-KDE-PluginInfo-Version=1.0
| |
| X-KDE-PluginInfo-Website=plasma.kde.org
| |
| X-KDE-ServiceTypes=Plasma/Applet
| |
| X-KDE-PluginInfo-Category=Windows and Tasks
| |
| | |
| X-Plasma-API=declarativeappletscript
| |
| X-Plasma-MainScript=ui/main.qml
| |
| X-Plasma-RemoteLocation=
| |
| </nowiki>}}
| |
| | |
| Feel free to change the PluginInfo-Author and PluginInfo-Email definitions with your own information. Go ahead and change the Comment line if you'd like a different tag line for your example. Please don't change the Name or PluginIn-Name fields. The rest of the tutorial depends on these remaining the same as the example.
| |
| | |
| Save this file as <code>hellomoid/plasmoid/metadata.desktop</code>
| |
| | |
| ==Your First QML Code==
| |
| We're done with the boilerplate setup for now. It's time to start creating something interesting. Back in the metadata.desktop file, we defined the property '''X-Plasma-MainScript''' and set the value to '''ui/main.qml'''. It's time to create that file.
| |
| | |
| {{Input|1=<nowiki>
| |
| import QtQuick 2.0
| |
| import org.kde.plasma.plasmoid 2.0
| |
| import org.kde.plasma.core 2.0 as PlasmaCore
| |
| | |
| Item {
| |
| PlasmaCore.IconItem {
| |
| source: "face-smile"
| |
| width: parent.width
| |
| height: parent.width
| |
| }
| |
| }
| |
| </nowiki>}}
| |
| | |
| Save this file as <code>hellomoid/plasmoid/contents/ui/main.qml</code>. It does three simple things:
| |
| * imports the libraries necessary for the plasmoid to function
| |
| * defines an '''IconItem''', which, naturally, displays an icon
| |
| * sets the source and size for the icon
| |
| | |
| You're probably eager to see your plasmoid in action, even though it doesn't do much right now. To preview your plasmoid, we use the '''plasmoidviewer''' tool.
| |
| | |
| From your terminal prompt, enter the following command:
| |
| | |
| <code>plasmoidviewer --applet ~/projects/hellomoid/plasmoid/</code>
| |
| | |
| You should be rewarded with a window like this:
| |
