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

    From KDE TechBase
    (→‎Find and try out existing Plasmoids: add example for plasmoidviewer)
    (make this code work without warnings (hopefully correctly!))
    (32 intermediate revisions by 11 users not shown)
    Line 9: Line 9:
    * plasmoid/metadata.desktop
    * plasmoid/metadata.desktop
    * plasmoid/contents/ui/main.qml
    * plasmoid/contents/ui/main.qml
    (where "plasmoid" should be replaced with the name of your package)


    Your directory structure should now be as follows:
    Your directory structure should now be as follows:
    Line 30: Line 32:
    Encoding=UTF-8
    Encoding=UTF-8
    Name=Tutorial
    Name=Tutorial
    Comment=Tutoial on getting started with Plasma 5 plasmoids .
    Comment=Tutorial on getting started with Plasma 5 plasmoids.
    Type=Service
    Type=Service
    X-KDE-Library=plasma_applet_tutorial
    X-KDE-ParentApp=
    X-KDE-ParentApp=
    X-KDE-PluginInfo-Author=Heena
    X-KDE-PluginInfo-Author=Heena
    Line 46: Line 50:
    </syntaxhighlight>
    </syntaxhighlight>


    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 [[Projects/Plasma/PIG | PIG]].
    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> ===
    ===  <tt>main.qml</tt> ===
    Line 58: Line 68:
    </syntaxhighlight>
    </syntaxhighlight>


    === Building it all, the CMakeLists.txt ===
    === CMakeLists.txt ===
    Finally, to put everything together you need to build everything. All you need is to put
    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} ${ECM_KDE_MODULE_DIR} ${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 lang="javascript">
      plasma_install_package(tutorial org.kde.tutorial plasma/plasmoids applet)
    </syntaxhighlight>
    </syntaxhighlight>
       
       
    For more details on CMake please read [[Development/Tutorials/CMake]]
    For more details on CMake please read [[Guidelines_and_HOWTOs/CMake]]


    == Representations ==
    == Representations ==
    Line 93: Line 118:
    import QtQuick.Layouts 1.1
    import QtQuick.Layouts 1.1
    import org.kde.plasma.components 2.0 as PlasmaComponents
    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 {
    PlasmaComponents.Label {
         Layout.minimumWidth : formFactor == PlasmaCore.Types.Horizontal ? height : 1
         Layout.minimumWidth : plasmoid.formFactor == PlasmaCore.Types.Horizontal ? height : 1
         Layout. minimumHeight : formFactor == PlasmaCore.Types.Vertical ? width  : 1
         Layout.minimumHeight : plasmoid.formFactor == PlasmaCore.Types.Vertical ? width  : 1
         text: "Hello world in plasma5 ";
         text: "Hello world in plasma5";
    }
    }
    </syntaxhighlight>
    </syntaxhighlight>
    Line 108: Line 134:




    ==Install==
    ==Install and Test==
    ===Cmake===
    Since this plasmoid contains no native (compiled) code you can directly try and execute it using
    Just you need to put
    <syntaxhighlight lang="bash">
    <syntaxhighlight lang="javascript">
    qmlscene main.qml
      plasma_install_package(tutorial org.kde.tutorial plasma/plasmoids applet)
    </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>
    </syntaxhighlight>
    in your CMakeLists.txt and you will be fine .
     
    ===Plasmapkg===
    To remove the plasmoid, use the Plasma Package Manager:
    You can install your plasmoid, though obviously this is just temporary. CMake, below, is recommended:
     
    <syntaxhighlight lang="bash">
    <syntaxhighlight lang="bash">
    plasmapkg2 --install plasmoid_plasma5
    kpackagetool5 -t Plasma/Applet --remove org.kde.tutorial
    </syntaxhighlight>
    </syntaxhighlight>


    == Testing the Applet ==
    == 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
     
    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 takes again the path (full or relative) to the directory containing the metadata.desktop file of your Plasmoid.
     
    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).
    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 :
    In order to test your Applet you can load the Plasma 5 plasmoid in plasmashell 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
    plasma-shell
    plasmashell
    </syntaxhighlight>
    </syntaxhighlight>
    You can even find your plasmoid in ~./local5 after you build it .
    You can even find your plasmoid in ~./local5 after you build it .
    Line 139: Line 197:
    Here you will learn how to find existing installed plasmoid packages and selectively start one from command line.
    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
    If you are working from within Plasma you can call
    {{Input|1=<nowiki>eval $(dbus-launch)</nowiki>}}
    {{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.
    first which will speed things up. But beware that a second DBUS can interfere with your existing Plasma session.
    Line 199: Line 257:
    === plasmoidviewer ===
    === plasmoidviewer ===


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


    {{Input|1=<nowiki>plasmoidviewer</nowiki>}}
    {{Input|1=<nowiki>plasmoidviewer --applet org.kde.plasma.kickoff</nowiki>}}


    [[File:Plasmoidviewer.png]]
    [[File:Plasmoidviewer.png]]


    The "FormFactors" and "Location" button help to see how the plasmoid behaves in different situations.
    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.

    Revision as of 22:06, 20 October 2017

    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

    (where "plasmoid" should be replaced with the name of your package)

    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=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-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:-

    • 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 PIG.


    These are the "glue" between your class and plasma, without it, nothing will start.

    main.qml

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

    CMakeLists.txt

    This CMakeLists.txt file describes where your plasmoid will be installed.

    # 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} ${ECM_KDE_MODULE_DIR} ${CMAKE_MODULE_PATH})
    
    # Locate plasma_install_package macro.
    find_package(KF5Plasma REQUIRED)
    
    # Add installatation target ("make install").
    plasma_install_package(plasmoid org.kde.tutorial)
    

    For more details on CMake please read Guidelines_and_HOWTOs/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
    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";
    }
    

    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

    qmlscene main.qml
    

    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:

    kpackagetool5 -t Plasma/Applet --install plasmoid
    

    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:

    kpackagetool5 -t Plasma/Applet --upgrade plasmoid
    

    To remove the plasmoid, use the Plasma Package Manager:

    kpackagetool5 -t Plasma/Applet --remove org.kde.tutorial
    

    Testing the Applet

    You can test your Plasmoid without installing it with the plasmoidviewer tool:

    plasmoidviewer --applet package

    The --applet parameter takes again the path (full or relative) to the directory containing the metadata.desktop file of your Plasmoid.

    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 :

    kbuildsycoca5 #Needed once to let KDE know there is a new plugin
    plasmashell
    

    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 --applet org.kde.plasma.kickoff

    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.