< PlasmaRevision as of 16:50, 25 August 2015 by Sebas (talk | contribs)(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff) The Ultimate Guide to Plasma Development Contents 1 Introduction 1.1 Is this guide for you? 1.2 Apps, Widgets and Plasmoids? 2 An app in 5 easy steps 2.1 Download an example 2.2 Adjust the plasmoid's metadata 2.3 Edit the QML code 2.4 Installing the plasmoid 2.5 Running it 3 Requirements Analysis & Design= 4 Software Stack 5 Getting Started 6 Developing a Plasmoid 6.1 Creating the empty package 6.1.1 filesystem structure 6.1.2 metadata.desktop 188.8.131.52 Choosing a Category 6.1.3 installation 6.2 Starting the Code 6.2.1 main.qml stuffz 6.2.2 Plasma API 7 Development Environment Setup 8 Tools 9 Display and Rendering 10 Supporting Multiple Devices 11 Workspace Integration 12 Translations 13 Distribution Introduction This guide explains the basic steps to build a fully integrated application. This guide is targeted at developers with basic knowledge of QML. It guides through the complete process of developing an application from scratch. Plasma allows to write applications that work well on different form factors or devices. Plasma is built to adapt to different input methods (mouse, touch, keyboard, etc.) screen sizes and to be resolution-independent. Most of the information in this guide is applicable to all form factors. Topics that may differ for different form factors are indicated as such. A well-architectured Plasma application will be able to offer different user interface per form factor. For desktops, a landscape layout with quite a lot of space for display and interaction can be used, while the same underlying components in a different, portrait-oriented layout can be used to present the user interface on a phone. A tablet user interface may use either, or combine the components in yet another fashion to make the best use of available screen real estate. In general, Plasma widgets such as buttons and other controls, work well on touch, mouse and with keyboard input, but can be switched at application start or runtime, transparently to the application using it. Is this guide for you? Plasma makes extensive use of QtQuick and QML to write the user interface and business logic of your application. Basic understanding of QtQuick is necessary, though Plasma is also a great environment to learn by doing it. This guide targets developers that are familiar with common programming paradigms, but do not have special knowledge of the Plasma APIs, libraries and mechanisms to solve certain problems. Many things can be implemented without knowing or being able to write C++ code. Plasma provides high-level APIs to solve a great number of tasks and provide common functionality such as retrieving data, displaying information as well as widgets for common interaction patterns and themes and artwork to make your app beautiful and consistent. In some cases, or in more complex apps, you may extend the functionality by writing a C++ plugin (or "import"). This allows to access custom functionality in your system, leverage an existing library, or move logic into a type-safe language that is easier to test (using unit tests, for example) or performs better. Apps, Widgets and Plasmoids? Plasma offers user interfaces for applications as well as workspaces (the environment you run your app in, the desktop, or phone user interface offering a launcher, task switcher, settings, for example). The workspace can be extended using Plasma Widgets, or in more technical terms, plasmoids. A plasmoid is a package containing metadata, images, configuration defaults and the QML files that make up the UI. Most of Plasma Desktop's functionality is offered using plasmoids. The application launcher in the bottom-left corner is a plasmoid, the task manager in the panel which allows you to switch between running applications is a plasmoid, many of the widgets in the notification area on both, Plasma Mobile and Plasma Desktop are plasmoids. You can also put Plasmoids on your desktop, the analog clock widgets and the "post-it" notes plasmoids are popular examples. Apps are loaded from packages as well. The main difference, aside from the layout probably being different, is that instead of loading the QML code inside a panel, or widget on the desktop, the application is loaded into its own window. (There are certain API features which may only make sense in the workspace, but those are usually implementation details that can be ignored where they don't make sense.) An app or a plasmoid would typically load the main layout for the window, popup or widget from a QML file, and then use imports to load additional libraries or make APIs available from within the applications QML code. An app in 5 easy steps Creating a simple application in Plasma is very easy. Download an exampletemplate Adjust the package metadata Edit the QML code Install the plasmoid Run it to try it out Download an example You can create your own plasmoid from a simple example, shipped with the plasma-framework source code from git: git clone git://anongit.kde.org/plasma-framework Then copy a basic example, which is going to be your new plasmoid. Let's call it "myplasmoid": cp -R plasma-framework/examples/developerguide/basic myplasmoid Adjust the plasmoid's metadata Open myplasmoid/metadata.desktop with your favorite text editor (mine is "Kate"): kate myplasmoid/metadata.desktop and change the Name and Comment fields. These will identify your Plasmoid in the widget chooser, be the default window name, Name=My Plasmoid Comment=Plasma Hacker 101 You can also pick a nice icon here. Use for example the "cuttlefish" tool to pick a nice one. Now change the line containing the "X-KDE-PluginInfo-Name" key to a different plugin id: X-KDE-PluginInfo-Name=org.example.myplasmoid The plugin name is used to identify the plugin on the system, make sure you pick a unique plugin name. It's advised to use a reverse domain name pattern. The plugin name will also be used in the installation path. Edit the QML code In order to change the template and write your own code, open its main QML file and hack away. kate myplasmoid/contents/ui/main.qml Play around with it a bit, try to change something, add a few new things, make yourself comfortable with it. For simple, first testing, you can also just skip this step for now and get back to actually hacking the application later on. Installing the plasmoid To install a plasmoid, you can use the "kpackagetool5" program: kpackagetool5 -i myplasmoid This will install the plasmoid locally in your home directory, into ~/.local/share/kpackage/genericqml/org.example.myplasmoid on my system -- your installation path may vary. To update an already-installed package on your system, use kpackagetool5 -u myplasmoid to remove it, use kpackagetool5 -r myplasmoid Running it You can now start your brand-new app using kpackagelauncherqml: kpackagelauncherqml -a org.example.myplasmoid And a window will show up with your application. Requirements Analysis & Design= Software Stack - QML / QtQuick: ui primitives, app logic, rendering, states - imports - Plasma libs - underlying frameworks - runtime environment - kpackage Getting Started Developing a Plasmoid Creating the empty package filesystem structure metadata.desktop - system integration (systray, alternatives, mimetypes, arguments, formfactors) Choosing a Category The following are acceptable known entries for plasmoids and applets. If your applet does not fall within one of the following categories, leave the category field empty (it will be automatically categorized under "Miscellaneous" for the time being) and contact the Plasma development team to have a suitable category added to the list (at which point you may then use that category). Accessibility tools that help those with special needs or disabilities use their computer Application Launchers application starters and file openers. Astronomy anything to do with the night sky or other celestial bodies. Date and Time clocks, calendars, scheduling, etc Development Tools tools and utilities to aid software developers Education teaching and educational aides Environment and Weather add-ons that display information regarding the weather or other environmentally related data Examples samples that are not meant for production systems File System anything that operates on files or the file system as it's primary purpose, such as file watchers or directory listings. Simply using a file as storage does not qualify the add-on for this category. Fun and Games for games and amusements Graphics for add-ons where displaying images, photos or graphical eye candy is the primary purpose Language add-ons whose primary purpose is language related, such as dictionaries and translators. Mapping geography and geographic data add-ons Multimedia music and video. Online Services add-ons that provide an interface to online services such as social networking or blogging sites. If there is another more appropriate category for the add-on given the topic (e.g. mapping if the applet's purpose is to show maps), even if the data is retrieved from the Internet prefer that other category over this one. System Information display and interaction with information about the computer such as network activity, hardware health, memory usage, etc Utilities Useful tools like calculators Windows and Tasks managers for application windows and/or tasks, such as taskbars installation - cmake - plasmapkg2 Starting the Code main.qml stuffz - Layouts - plasmoid object - fullRepresentation vs. popup Plasma API + links to API documentation! - PlasmaCore - PlasmaComponents - PlasmaExtras - kdeclarative's useful stuff: kcmOpen? more useful imports - general guidelines: units, iconSizes, Development Environment Setup Tools - editor - commandline - plasmapkg2 - plasmoidviewer - plasmathemething - cuttlefish - Display and Rendering - theming - image display - dpi - ColorScope - Wayland vs. X11 Supporting Multiple Devices - touch friendliness - layout considerations - formfactor support (X-KDE-FormFactors) - touch-specific overrides Workspace Integration - system tray - plasmoid status - dbus autoload Translations - i18n() & friends - making sure i18n is set up & how to x-test Distribution - plasmoid package - appstream metadata - kdeapps online installation - distros - upstreaming code Retrieved from "https://community.kde.org/index.php?title=Plasma/DeveloperGuide&oldid=44026" Content is available under Creative Commons License SA 4.0 unless otherwise noted.