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

    From KDE TechBase
    (→‎Building it all, the CMakeLists.txt: clarify output file in text)
    Line 61: Line 61:


    === Building it all, the CMakeLists.txt ===
    === Building it all, the CMakeLists.txt ===
    Finally, to put everything together you need to build everything. All you need is to put
    Finally, to put everything together you need to build everything. All you have to do is create a CMakeLists.txt file containing:


    <syntaxhighlight lang="javascript">
    <syntaxhighlight lang="cmake">
      plasma_install_package(tutorial org.kde.tutorial plasma/plasmoids applet)
    plasma_install_package(tutorial org.kde.tutorial plasma/plasmoids applet)
    </syntaxhighlight>
    </syntaxhighlight>
       
       

    Revision as of 10:45, 1 August 2015

    Information
    This page should be merged with Tutorials/Plasma2/*


    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 .

    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
    

    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

    [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=[email protected]
    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.

    main.qml

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

    Building it all, the CMakeLists.txt

    Finally, to put everything together you need to build everything. All you have to do is create a CMakeLists.txt file containing:

    plasma_install_package(tutorial org.kde.tutorial plasma/plasmoids applet)
    

    For more details on CMake please read Development/Tutorials/CMake

    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.

    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 .

    Localization

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


    Install

    Cmake

    You just need to put

      find_package(KF5Plasma)
    

    in your project's top level CMakeLists.txt and

      plasma_install_package(tutorial org.kde.tutorial plasma/plasmoids applet)
    

    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:

    plasmapkg2 --install plasmoid_plasma5
    

    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.

    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

    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

    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.

    plasmoidviewer

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

    plasmoidviewer

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