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

    From KDE TechBase
    Line 16: Line 16:
    <syntaxhighlight lang="bash">
    <syntaxhighlight lang="bash">
    myproject/CMakeLists.txt
    myproject/CMakeLists.txt
    myproject/plasmoid_plasma2/
    myproject/plasmoid/
    myproject/plasmoid_plasma2/metadata.desktop
    myproject/plasmoid/metadata.desktop
    myproject/plasmoid_plasma2/contents/
    myproject/plasmoid/contents/
    myproject/plasmoid_plasma2/contents/ui/
    myproject/plasmoid/contents/ui/
    myproject/plasmoid_plasma2/contents/ui/main.qml
    myproject/plasmoid/contents/ui/main.qml
    </syntaxhighlight>
    </syntaxhighlight>



    Revision as of 11:36, 2 October 2014


    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 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_plasma2/metadata.desktop
    • plasmoid_plasma2/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 plasma2 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 plasma2 ";
    }
    

    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

    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.

    import QtQuick 2.0
    import org.kde.plasma.components 2.0 as PlasmaComponents
    
    PlasmaComponents.Label {
        property int minimumWidth : formFactor == PlasmaCore.Types.Horizontal ? height : 1
        property int minimumHeight : formFactor == PlasmaCore.Types.Vertical ? width  : 1
        text: "Hello world in plasma2 ";
    }
    

    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:

    plasmapkg --install plasmoid_plasma2
    

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