Development/Tutorials/Plasma/JavaScript/ConfigDialog

Once you have created your plasmoid, you will need to do the following to add a Config dialog:

• Add a ui/config.ui file. You can use qtdesigner or edit the XML file if you are an advanced developer.
• Add an event listener function to the "ConfigChanged" event.
• Create an XML config file into your config directory. The default is config/main.xml. See [1] for more information.

The config.ui File

You'll need this tips before creating the configuration dialog's user interface:

• qtdesigner is a good tool for editing this files without typing XML. Like a WYSIWYG editor.
• You don't have to add an "accept", "apply" nor a "cancel" button, those will be added automatically.
• Any configuration entry's name must have a "kcfg_" prefix.

Entries can be of type boolean, string, integer, etc.

The Event Listener Function

Typically, is correct to create a new javascript file called "code/config.js" and then is imported using the import command.

This JS file should have all the functions necessary to manage the configuration of your plasmoid and knows what to do when one of these events happen:

• is the first time the app starts (so default configurations is used)
• the users changes the configuration by clicking "Accept" or "Apply" button.

And it should have a function that is called when the the configurations is changed (by one of the two event stated). Let's call that function configChanged().

Finally, you have to tell to the plasmoid object that the configChanged() function is the one it have to call when one event need to change the configuration. For that, you can add this QML component into your main QML file:

    Component.onCompleted: {
        plasmoid.addEventListener('ConfigChanged', Config.changed)
    }

The Component.onCompleted is a QML signal that is called as soon as the QML objects are loaded, and is used for "startups" scripts (see Component documentation).

See plasmoid object's callbacks for the addEventListener() function.

The XML Config Values File

This file will have the default values and its entry names for the configuration. You may like to see the [2] page for more information about these files.

Remember that for each "kcfg_" objects names at the ui/config.ui file should match the entry names of this config values files (without the prefix).

Example

At the ui/config.ui file I defined the following:

• Just a QLineEdit object. Its objectName property is setted to kcfg_textconfig.

At the ui/main.qml I have the following:

import QtQuick 1.1
import org.kde.plasma.components 0.1 as PComp
import '../code/Config.js' as Config

Item {

    ...

    PComp.Label {
            id: resp
            text: i18n("")
    }
    Component.onCompleted: {
        plasmoid.addEventListener('ConfigChanged', Config.configChanged)
    }
}

At the code/Config.js I defined the following:

function configChanged(){
    // Not necessary, main.xml is the default if no activeConfig is setted:
    plasmoid.activeConfig = "main"; 
    resp.text = "Config changed to...";
    var text = plasmoid.readConfig("configtext");
    resp.text = resp.text + text;
}

At the config/main.xml I wrote the following:

<?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="configtext" type="String">
      <label>This is a label.</label>
      <default>hi world</default>
    </entry>
  </group>

</kcfg>

Useful Links

• API Plasmoid Object, Configuration Data section
• KConfig_XT for the config/main.xml file.
• plasmoid Object's Callbacks
• The Qt4 QML Component Documentation (external link to the Qt documentation web page).
• Mozilla's Javascript Wiki Page
• JS The Getting Started and the Plasma JS API