Development/Tutorials/Plasma4/QML/GettingStarted: Difference between revisions

    From KDE TechBase
    (bam. crosslink to js 'plasmoid' object api.)
    Line 125: Line 125:
    == Plasmoid object ==
    == Plasmoid object ==
    Every QML plasmoid will have an object called ''plasmoid'', that will give access to the configuration, the formfactor, immutability and so on. It offers the same api as the object with the same name in the Javascript API.
    Every QML plasmoid will have an object called ''plasmoid'', that will give access to the configuration, the formfactor, immutability and so on. It offers the same api as the object with the same name in the Javascript API.
    For specific info on this, see [http://techbase.kde.org/Development/Tutorials/Plasma/JavaScript/API-PlasmoidObject Javascript API-Plasmoid Object]


    == Localization ==
    == Localization ==

    Revision as of 18:30, 24 June 2011

    Abstract

    Writing a plasma applet in QML is very easy, in fact, with KDE 4.6 and Qt 4.7 it just works.

    QML Basics

    It is recommended that you have read through the Qt QML Tutorials, as there are quite a few and they are explained thoroughly. There is also a list of all standard QML elements.

    See the KDE Examples repository for more KDE-related helpful resources.

    Root Item

    The root item can be anything that inherits QGraphicsItem. For example, in this case it is QGraphicsWidget which is a plasmoid. It can also simply be an Item. I also noticed that PathView does not respond to mouse inputs automatically (so flicking doesn't work). Probably because events are being intercepted. So take note, it'll have to be e.g. an Item, for that case.

    Layouts

    Row and Column

    Anchors

    Anchor layouts offer a nice way of grouping UI elements nicely together. The idea is that you connect edges or corners of one element to the edge or corner of another widget. Some examples:

    
    import QtQuick 1.0
    import org.kde.plasma.core 0.1 as PlasmaCore
    
    
    Item {
        width: 200
        heigt: 300
    
    
        Text {
            id: first
            text: i18n("1st line")
            anchors { top: parent.top;
                      left: parent.left;
                      right: parent.right;
            }
        }
        Text {
            id: second
            text: i18n("2nd line")
            anchors { top: first.bottom;
                      left: parent.left;
                      right: parent.right;
                      bottom: parent.bottom;
            }
        }
    }
     
    

    Buttons

    Animations

    Package Structure

    You create a .desktop file and the .qml file. They have to be in the usual plasma package structure.

    plasmoid-qml/metadata.desktop plasmoid-qml/contents/ui/main.qml

    metadata.desktop

    [Desktop Entry] Name=Hello QML Comment=A hello world widget in QML Icon=chronometer

    X-Plasma-API=declarativeappletscript X-Plasma-MainScript=ui/main.qml X-Plasma-DefaultSize=200,100

    X-KDE-PluginInfo-Author=Frederik Gladhorn [email protected] X-KDE-PluginInfo-Website=http://plasma.kde.org/ X-KDE-PluginInfo-Category=Examples X-KDE-PluginInfo-Name=org.kde.hello-qml X-KDE-PluginInfo-Version=0.0

    X-KDE-PluginInfo-Depends= X-KDE-PluginInfo-License=GPL X-KDE-PluginInfo-EnabledByDefault=true X-KDE-ServiceTypes=Plasma/Applet Type=Service

    main.qml

    import QtQuick 1.0

    Text {

       text: "Hello world!";
    

    }

    Installing

    You can install your plasmoid: plasmapkg --install plasmoid-qml

    plasmoidviewer

    You can run it in plasmoidviewer as usual: plasmoidviewer plasmoid-qml

    qmlviewer

    It's possible to use Plasma specific imports in qml files loaded by qmlviewer:

    qmlviewer -I /usr/lib/kde4/imports/ plasmoid-qml/contents/qml/main.qml

    Where the -I is the path to the plasma plugin for qml. Try to look for the path of /usr/lib/kde4/imports/org/kde/plasma/graphicswidgets/libgraphicswidgetsbindingsplugin.so and use everything up to org of that path.

    Hovewer it's strongly discouraged to use qmlviewer to develop plasmoids, because some features won't be available there:

    • localization with i18n()
    • access to the global plasmoid object
    • device specific qml files imported with plasmapackage:// urls
    • bindings for qicons, KJobs, services and KConfig

    Features only available in Plasma widgets

    In order to have a better integration with the KDE platform and to reach an higher degree of expressivity, the stock features of QML have been expanded with the following features, that strictly follow the Plasmoid JavaScript API:

    Plasmoid object

    Every QML plasmoid will have an object called plasmoid, that will give access to the configuration, the formfactor, immutability and so on. It offers the same api as the object with the same name in the Javascript API.

    For specific info on this, see Javascript API-Plasmoid Object

    Localization

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

    Extra types

    Some extra types are available from withing JavaScript, namely

    • KConfigGroup: it's an object with its cnfig keys readable and writable as properties
    • QIcon: can be constructed with QIcon("fdo name") such as QIcon("konqueror")
    • KJob
    • Plasma Service api


    Plasma specific imports

    To use some Plasma specific features is necessary to use some particular QML imports.

    Plasma Core

    org.kde.plasma.core This is the import that lets you access to the most important Plasma Core features.

    DataSource

    Used to connect to a dataengine

    DataModel

    Attaches to a DataSource, makes possible to use a dataengine as a model for a QML ListView, GridView, PathView and so on

    Svg

    Loads a Plasma Svg, it's not the visual item

    SvgItem

    Visual item that paints a Svg

    FrameSvg

    Loads a Plasma FrameSvg, it's not the visual item.

    FrameSvgItem

    Visual item that displays a Plasma FrameSvg

    Extra Qt features

    org.kde.qtextraimports

    • QPixmapItem
    • QImageItem
    • QIconItem

    Plasma Widgets in QML

    To use standard plasma widgets (e.g. Plasma::LineEdit, etc.), you simply add an import line for them. All properties, signals and slots from ordinary Plasma widgets are available there. Those widgets are provided as a transition tool, intended to be replaced by the Plasma version of QtComponents.

    import QtQuick 1.0 import org.kde.plasma.graphicswidgets 0.1 as PlasmaWidgets

    Item {

       width: 64
       height: 64
       PlasmaWidgets.IconWidget {
           id: icon
           Component.onCompleted: setIcon("flag-red")
           anchors.centerIn: parent
       }
    

    }