plasma/kdecoration/README.md

0001 # KDecoration2
0002
0003 Plugin based library to create window decorations.
0004
0005 ## Introduction
0006
0007 KDecoration2 is a library to create window decorations. These window decorations can be used by
0008 for example an X11 based window manager which re-parents a Client window to a window decoration
0009 frame.
0010
0011 The library consists of two parts:
0012 * Decoration API for implementing a Decoration theme
0013 * Private API to implement the backend part (e.g. from Window Manager side)
0014
0015 ## Providing a Decoration
0016
0017 To provide a custom decoration one needs to create a plugin and provide an own implementation
0018 of KDecoration2::Decoration. For a framework to load and find the plugin it needs to be compiled
0019 with the proper json metadata. An example for such metadata (deco.json):
0020
0021 ```json
0022 {
0023     "KPlugin": {
0024         "Id": "org.kde.myAweseomeDecoration",
0025         "ServiceTypes": [
0026             "org.kde.kdecoration2"
0027         ]
0028     },
0029     "X-KDE-ConfigModule": "kcm_name", /* comes with a configuration module */
0030     "org.kde.kdecoration2": {
0031         "blur": false, /* blur behind not needed */
0032     }
0033 }
0034 ```
0035
0036 To simplify one can use the KPluginFactory macro from the KCoreAddons framework:
0037
0038 ```cpp
0039 K_PLUGIN_FACTORY_WITH_JSON(
0040     MyAwesomeDecorationFactory,
0041     "deco.json",
0042     registerPlugin<MyAwesomeDecoration::Decoration>();
0043 )
0044 ```
0045
0046 The plugin needs to get installed to `${KDE_INSTALL_PLUGINDIR}/org.kde.kdecoration2`.
0047
0048 ## Configuring the Decoration
0049
0050 It is possible to provide a configuration module to tweak some aspects of the decoration. This is done
0051 by creating a plugin that provides such a configuration module.
0052
0053 The `kcmoduleName` specifies the name of the configuration module. It needs to be installed under
0054 `${KDE_INSTALL_PLUGINDIR}/org.kde.kdecoration2.kcm` so that it can be looked up.