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

    From KDE TechBase
    (6 intermediate revisions by 2 users not shown)
    Line 136: Line 136:
    To Install, Test and Remove your new plasmoid.
    To Install, Test and Remove your new plasmoid.


    ===Plasmapkg===
    ===Kpackagetool5===
    The Plasma Package Manager.
    The Plasma Package Manager.


    You can install your plasmoid, though obviously this is just temporary. CMake, below, is recommended:
    You can install your plasmoid, though obviously this is just temporary. CMake, below, is recommended.


    From the myproject folder defined above, use the Plasma Package Manager:
    <syntaxhighlight lang="bash">
    <syntaxhighlight lang="bash">
    plasmapkg2 --install plasmoid_plasma5
    kpackagetool5 -t Plasma/Applet --install plasmoid
    </syntaxhighlight>
    </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
    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
    Line 149: Line 152:
    * '''Name=Tutorial'''
    * '''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>
     
     
    To remove the plasmoid, use the Plasma Package Manager:
    To remove the plasmoid, use the Plasma Package Manager:


    <syntaxhighlight lang="bash">
    <syntaxhighlight lang="bash">
    plasmapkg2 --remove org.kde.tutorial
    kpackagetool5 -t Plasma/Applet --remove org.kde.tutorial
    </syntaxhighlight>
    </syntaxhighlight>


    == Testing the Applet ==
    == Testing the Applet ==
    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
    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


    Line 234: Line 255:
    === 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 14:16, 16 June 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

    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 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 and Test

    Since this plasmoid contains no native (compiled) code you can directly try and execute it using XXX (!! FixMe !!).

    To Install, Test and Remove your new plasmoid.

    Kpackagetool5

    The Plasma Package Manager.

    You can install your plasmoid, 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.