Plasma/PortingQMLPlasmoids

Most API the QML plasmoids will use hasn't been changed between Plasma1 and Plasma2, however there are some significant differences in some areas that will need to be considered when porting a plasmoid.

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.