View source for KWin/KConfigXT Effects

= KConfigXT for KWin Effects =

== Motivation ==
To port the configuration of an Effect to KConfigXT no programming skills are required, though can be helpful. The task is to move the configuration from being hard coded values in the source code into an XML definition from which source code get's generated. This improves the maintenance of the source code and makes it more difficult to have errors caused by typos. Furthermore the business logic to update and track the user interface can be managed automatically limiting the risk of errors there.

Last but not least it allows to move the configuration interfaces in future to new technologies like QML.

== Performing a Port ==
Best first read the [http://techbase.kde.org/Development/Tutorials/Using_KConfig_XT tutorial on KConfigXT], then pick an effect of those listed below. The source code for the effects can be found [https://projects.kde.org/projects/kde/kde-workspace/repository/revisions/master/show/kwin/effects here], each effect is in an own sub directory. Locate the file effectname_config.cpp, that's the most important one to look at. In there you find some code starting with '''void EffectNameConfig::load()''', there you find many readEntry() lines. Each readEntry contains the name of the config option, the default value and the data type. Each of these config options becomes an entry in the kcfg file.

Now start creating the kcfg file. As a name use '''effectname.kcfg'''. For the name attribute of "kcfgfile" use ''kwinrc''. The kcfg file should have exactly one group. The name of this you can find in the source code in a method call ''EffectsHandler::effectConfig("Foo")'' which gets appended to a ''Effect-'', e.g. ''Effect-Foo''. This should be enough to define the complete kcfg file for the effect.

The next step is to update the ui file in the same directory. Best do that in Qt designer and for each widget update the object name to be '''kcfg_ConfigOption''' as explained in the tutorial.

Now all that is needed is defining the kcfgc file:
<pre>
File=foo.kcfg
ClassName=FooConfig
NameSpace=KWin
Singleton=true
Mutators=true
</pre>

If you have some developer experience, please also update the CMakeLists.txt and the source code of the effect and the configuration. Though this is no requirement.

A complete example for such a port can be found in [https://git.reviewboard.kde.org/r/106310/ Review Request for Translucency Effect].

== Publish the Result ==
Best is to upload a Review Request on [https://git.reviewboard.kde.org Review Board] for group KWin. Alternative is to send your changes to KWin's mailing list. Bonus for being a git format-patched diff as that allows that the change in the repository will be addressed to the correct author.

== Effects ==

{| cellspacing="0" cellpadding="5" border="1" style="border: 1px solid gray; border-collapse: collapse; text-align: left; width: 100%;" class="sortable"
|- style="background: rgb(236, 236, 236) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous; white-space: nowrap;"

! Status
! Effect
! Review Board
! Claimed By

{{FeatureProjectInProgress |Blur|-|moraru69@yahoo.com|lilianmoraru}}
{{FeatureProjectInProgress |CoverSwitch|[https://git.reviewboard.kde.org/r/106396/ 106396]|dariocambie@gmail.com|dcambie}}
{{FeatureProjectInProgress |Cube|-|francesco.cecconi@gmail.com|cecconi}}
{{FeatureProjectInProgress |Dashboard|[https://git.reviewboard.kde.org/r/106390/ 106390]|andrea@archlinux.org|ascarpino}}
{{FeatureProjectInProgress |DesktopGrid|-|moraru69@yahoo.com|lilianmoraru}}
{{FeatureProjectInProgress |DimInactive|-|jsardid@gmail.com}}
{{FeatureProjectTodo |FlipSwitch|-|-}}
{{FeatureProjectInProgress |Glide|[https://git.reviewboard.kde.org/r/106392/ 106392]|dariocambie@gmail.com|dcambie}}
{{FeatureProjectTodo |Invert|-|-}}
{{FeatureProjectInProgress |Login|[https://git.reviewboard.kde.org/r/106387/ 106387]|andrea@archlinux.org|ascarpino}}
{{FeatureProjectTodo |LookingGlass|-|-}}
{{FeatureProjectInProgress |MagicLamp|-|andrea@archlinux.org|ascarpino}}
{{FeatureProjectTodo |Magnifier|-|-}}
{{FeatureProjectTodo |MouseMark|-|-}}
{{FeatureProjectTodo |PresentWindows|-|-}}
{{FeatureProjectInProgress |Resize|-|happy5214@gmail.com|alexanderjones}}
{{FeatureProjectTodo |ShowFPS|-|-}}
{{FeatureProjectTodo |ThumbnailAside|-|-}}
{{FeatureProjectTodo |Trackmouse|-|-}}
{{FeatureProjectInProgress|Translucency|[https://git.reviewboard.kde.org/r/106310/ 106310]|mgraesslin@kde.org|Martin Gräßlin}}
{{FeatureProjectTodo |WindowGeometry|-|-}}
{{FeatureProjectInProgress |WobblyWindows|[https://git.reviewboard.kde.org/r/106389/ 106389]|friesoft@gmail.com|friesoft}}
{{FeatureProjectTodo |Zoom|-|-}}
|}