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

    From KDE TechBase
    (Created page with " ==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 mak...")
     
    (→‎Find and try out existing Plasmoids: add example for plasmoidviewer)
    (19 intermediate revisions by 6 users not shown)
    Line 1: Line 1:
    ==Abstract==
    ==Abstract==
    This tutorial needs KDE Frameworks 5 / Plasma 2 to build.
    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 .
    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 .


    Line 9: Line 7:
    You create a .desktop file and the .qml file. They have to be in the usual Plasma 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/metadata.desktop
    * plasmoid_plasma2/contents/ui/main.qml
    * plasmoid/contents/ui/main.qml


    Your directory structure should now be as follows:
    Your directory structure should now be as follows:
    Line 16: Line 14:
    <syntaxhighlight lang="bash">
    <syntaxhighlight lang="bash">
    myproject/CMakeLists.txt
    myproject/CMakeLists.txt
    myproject/package/
    myproject/plasmoid/
    myproject/package/metadata.desktop
    myproject/plasmoid/metadata.desktop
    myproject/package/contents/
    myproject/plasmoid/contents/
    myproject/package/contents/ui/
    myproject/plasmoid/contents/ui/
    myproject/package/contents/ui/main.qml
    myproject/plasmoid/contents/ui/main.qml
    </syntaxhighlight>
    </syntaxhighlight>


    Line 27: Line 25:
    Every Plasmoid needs a .desktop file to tell plasma how it should be started and what name it carries.  
    Every Plasmoid needs a .desktop file to tell plasma how it should be started and what name it carries.  


    '''plasma2-applet-tutorial.desktop'''
    '''metadata.desktop'''
    <syntaxhighlight lang="ini">
    <syntaxhighlight lang="ini">
    [Desktop Entry]
    [Desktop Entry]
    Encoding=UTF-8
    Encoding=UTF-8
    Name=Tutorial
    Name=Tutorial
    Comment=Tutoial on getting started with plasma2 plasmoids .
    Comment=Tutoial on getting started with Plasma 5 plasmoids .
    Type=Service
    Type=Service
    X-KDE-ParentApp=
    X-KDE-ParentApp=
    X-Plasma-DefaultSize=200,200
    X-KDE-PluginInfo-Author=Heena
    X-KDE-PluginInfo-Author=Heena
    Line 44: Line 41:
    X-KDE-ServiceTypes=Plasma/Applet
    X-KDE-ServiceTypes=Plasma/Applet
    X-Plasma-API=declarativeappletscript
    X-Plasma-API=declarativeappletscript
    X-Plasma-DefaultSize=
    X-Plasma-MainScript=ui/main.qml
    X-Plasma-MainScript=ui/main.qml
    X-Plasma-RemoteLocation=
    X-Plasma-RemoteLocation=
    Line 58: Line 54:


    PlasmaComponents.Label {
    PlasmaComponents.Label {
         text: "Hello world in plasma2 ";
         text: "Hello world in Plasma 5 ";
    }
    }
    </syntaxhighlight>
    </syntaxhighlight>
    Line 70: Line 66:
       
       
    For more details on CMake please read [[Development/Tutorials/CMake]]
    For more details on CMake please read [[Development/Tutorials/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 ==
    == 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.
    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">
    <syntaxhighlight lang="javascript">
    import QtQuick 2.0
    import QtQuick 2.0
    import QtQuick.Layouts 1.1
    import org.kde.plasma.components 2.0 as PlasmaComponents
    import org.kde.plasma.components 2.0 as PlasmaComponents


    PlasmaComponents.Label {
    PlasmaComponents.Label {
         property int minimumWidth : formFactor == PlasmaCore.Types.Horizontal ? height : 1
         Layout.minimumWidth : formFactor == PlasmaCore.Types.Horizontal ? height : 1
         property int minimumHeight : formFactor == PlasmaCore.Types.Vertical ? width  : 1
         Layout. minimumHeight : formFactor == PlasmaCore.Types.Vertical ? width  : 1
         text: "Hello world in plasma2 ";
         text: "Hello world in plasma5 ";
    }
    }
    </syntaxhighlight>
    </syntaxhighlight>
    Line 88: Line 106:
    == Localization ==
    == Localization ==
    It is possible to localize strings with the usual i18n(), i18nc(), i18np() global functions.
    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">
    plasmapkg2 --install plasmoid_plasma5
    </syntaxhighlight>


    == Testing the Applet ==
    == Testing the Applet ==
    Line 93: Line 125:


    and run kbuildsycoca5 (so that KDE apps will know about the new desktop files).
    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 :
    In order to test your Applet you can load the Plasma 5 plasmoid in plasma-shell as shown :
    <syntaxhighlight lang="bash">
    <syntaxhighlight lang="bash">
    kbuildsycoca5 #Needed once to let KDE know there is a new plugin
    kbuildsycoca5 #Needed once to let KDE know there is a new plugin
    Line 103: Line 135:
    == Wow that was fun! ==
    == Wow that was fun! ==
    Congrats! you just  made your first qml 2.0 Plasmoid.
    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 KDE4 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</nowiki>}}
    [[File:Plasmoidviewer.png]]
    The "FormFactors" and "Location" button help to see how the plasmoid behaves in different situations.

    Revision as of 15:52, 4 March 2015

    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 need is to put

      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

    Just you need to put

      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 KDE4 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.