View source for Plasma/PortingQMLPlasmoids

=Porting QML Plasmoids to Plasma 2=
The Plasma Quick APIs have been ported to QtQuick2. This has been done with API compatibility in mind. Usually, it is pretty easy to get your QtQuick2 code running on top of QtQuick2 and Plasma2. [http://qt-project.org/doc/qt-5.0/qtquick/qtquick-porting-qt5.html This document] guides you through the important changes in QtQuick2.

As of today (May 2nd 2013), most of the imports provided by the following modules have been ported:
* org.kde.plasma.core (PlasmaCore)
* org.kde.plasma.components (PlasmaComponents)
* org.kde.plasma.extras (PlasmaExtras)
* org.kde.qtextracomponents (QtExtras)
* org.kde.locale
* org.kde.draganddrop
* org.kde.runnermanager

==API Changes==
The API has been kept compatible to minimize the porting effort to Plasma2. With the following changes, you can get your code running on Plasma2:
* Change import version numbers of all above components to 2.0
* PlasmaCore.Dialog: activateWindow() is gone, use requestActivate() (from QWindow)
* PlasmaCore.Dialog.activeWindow is gone, use Dialog.active (inherited from QWindow)
* PlasmaCore.Dialog.windowFlags is gone, use Dialog.flags (inherited from QWindow)
* PlasmaCore.Theme: mSize now takes a font as argument, theme.mSize(theme.defaultFont)
* PlasmaCore.ToolTip: image property now takes a QString, which is passed as source into an Image item
* QIcon has gone from the API as creatable type, replace QIcon("icon-name") with "icon-name" (PlasmaCore.IconItem.iconSource also understands QIcon)

Backwards compatible API Improvements:
* PlasmaCore.ToolTip can now optionally include Components
* PlasmaCore.MenuItem.icon now accepts icons as QString, as well as QIcon

Please note that the Plasma QtQuick 2 APIs are still subject to change. This document is work in progress.

==Versioning of plugins==
All plugin versions have been upped to 2.0. PlasmaComponents, PlasmaCore, PlasmaExtras, QtExtras, DragAndDrop, RunnerModel, etc. are now at version two. Locale was at 1.0, and is now also at 2.0. Change lines like:
 import org.kde.plasma.components 0.1 as PlasmaComponents
to
 import org.kde.plasma.components 2.0 as PlasmaComponents

==Namespacing of enums==
As we cannot export new types into the global namespace, enums have to be loaded into a namespace. In order to do this, make sure
* you are importing the plugin in question using a namespace (import org.kde.foo 2.0 as MyFoo)
* you change references to enums defined in a class with its full name, i.e. PlasmaCore.Dialog.Closed (not Dialog.Closed)


=Configuration=
Plasma2 doesn't use .ui files anymore. Instead, config pages has to be written in QML.
In order to populate the configuration dialog, put a '''config.qml''' file in the '''config/''' directory of the plasmoid.

==config/config.qml==
The config.qml file '''must''' be an instance of the '''ConfigModel {}''' component, which can only contains '''ConfigCategory {}''' items.

  import org.kde.plasma.configuration 0.1
  ConfigModel {
      ConfigCategory {
           name: "General"
           icon: "plasma"
           source: "configGeneral.qml"
      }
      ConfigCategory {
           name: "Page2"
           icon: "config"
           source: "whatever.qml"
      }
      ...
 }

The ''source'' properties define qml file names that represent the pages of the config categories and will be searched for in the '''ui/''' directory of the Plasma package.

==Mapping from config pages to plasmoid configuration==
TODO

==config/main.xml==
As in Plasma1, the schema for the configuration stays in a KConfigXT '''main.xml''' file under the confg directory, that will define what the allowed config keys are.

 <?xml version="1.0" encoding="UTF-8"?>
 <kcfg xmlns="http://www.kde.org/standards/kcfg/1.0"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.kde.org/standards/kcfg/1.0
       http://www.kde.org/standards/kcfg/1.0/kcfg.xsd" >
   <kcfgfile name=""/>
   <group name="General">
     <entry name="Test" type="String">
       <label>This is a test</label>
       <default>test</default>
     </entry>
   </group>
 </kcfg>

==Reading and writing the configuration from the plasmoid code==
The '''plasmoid''' global object available in the implementation of the QML plasmoid has a new property available: '''plasmoid.configuration'''.

the '''configuration''' object is an Object that has a property for each configuration key in the config file, with the same name.
It is possible to use property bindings for those properties (so the plasmoid implementation  doesn't have to worry about applying configuration values after the user configured something with the config dialog).
If a JavaScript piece assigns a value to one of the properties of ''configuration'', the new value will be written on the configuration on disk.