Development/Tutorials/Plasma4/QML/ActiveSettings

This tutorial teaches you how you can load Active settings modules into your app, and create your own modules.

Introduction

Active Settings is an app, much like Plasma Desktop's kcmshell that shows and loads configuration modules. These configuration modules are plugins providing a QML package and an optional C++-plugin which exports custom-written configuration objects as QObject to the declarative environment.

You can query available modules using the --list argument to active-settings:

$ active-settings --list
org.kde.active.settings.web             Settings for history, caching, etc.
org.kde.active.settings.configtest      Test Module for the Config Bindings
org.kde.active.settings.time            Settings for timezone and date display

You can load an individual module by supplying its plugin name as argument to active-settings:

active-settings org.kde.active.settings.time

will open the active-settings app and load the "Time and Date" module on startup.

Architecture

The Active Settings app consists of a number of parts, an Active App, which loads a QML package providing the chrome for active-settings, a set of Declarative components which encapsulate loading settings modules and a set of settings modules, which provide the UI and backend code for a specific settings domain (i.e. Time and Date, Browser settings, etc.).

Integrating a Settings Module into an App

In order to integrate a settings module "inline" into your app, you can use the SettingsItem component, which comes with the ActiveSettings declarative plugin. SettingsItem provides a PageStack (from PlasmaComponents) with a bit of additional API, the module property. Creating an Item with a settings module is as easy as:

import org.kde.active.settings 0.1 as ActiveSettings
[...]
ActiveSettings.SettingsItem {
    id: webSettingsItem
    module: "org.kde.active.settings.time"
    anchors { ... }
}

In order to speed up loading your app, you will want to lazy-load the settings module. This is very easy by using the PageStack features that SettingsItem encapsulates:

import org.kde.active.settings 0.1 as ActiveSettings
[...]
ActiveSettings.SettingsItem {
    id: settingsItem
    initialPage: someOtherItem
    anchors { [...] }
}

PlasmaComponents.Button {
    // This button toggles the settings item and someOtherPage
    [...]
    onClicked: {
        if (settingsItem.module != "org.kde.active.settings.web") {
            settingsItem.module = "org.kde.active.settings.web"
        } else {
            // Switching back...
            settingsItem.replace(someOtherItem);
        }
    }
}

Item {
    id: someOtherItem
    /* this guy is shown before any module is loaded */
}