Make sure the names of the .desktop files in CMakeLists.txt are correct, since incorrect names lead to problems finding and loading your package, or even to conflicts between different modules. In case of doubt check active-settings --list for already installed modules.

+

After you installed the plugin (or changed its metadata) you'll need to run "kbuildsycoca4" in order to update the plugin metainformation cache.

+

== KConfig Bindings ==

== KConfig Bindings ==

== Extending your Settings Module with with C++ ==

== Extending your Settings Module with with C++ ==

Revision as of 17:22, 30 December 2011

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

Contents

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:

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:

Creating Your Own Settings Module

Simple, QML-only Module

Writing a basic ActiveSettings configuration module is as simple as creating a Plasma Package, using the X-KDE-ServiceTypes "Active/SettingsModule". The service type registers your package as settings module, so active-settings will find (and list) it, and so it can be loaded using the SettingsItem QML binding. A simple active settings package will look like this:

The metadata.desktop file holds the plugin information, which script to load from the plugin initially, and a bunch of metadata, just like normal Plasma Packages. A simple metadata.desktop file will look like this:

The interesting bits, specific to active-settings are the plugin name, the package name and the mainscript. The plugin name is used to find the package, and will translates to the "module" property of SettingsItem.
Web.qml points to a normal Item { [...] } in a file, normal rules apply here.

The CMakeLists.txt file takes care of proper installation and will be needed in order to install and package your settings module. It looks like this:

Make sure the names of the .desktop files in CMakeLists.txt are correct, since incorrect names lead to problems finding and loading your package, or even to conflicts between different modules. In case of doubt check active-settings --list for already installed modules.
After you installed the plugin (or changed its metadata) you'll need to run "kbuildsycoca4" in order to update the plugin metainformation cache.