RFC: Merge branch new_kcm_code into HEAD

[Frans Englich]

Hello all,

The "KCM technologies" were originally invented for KControl only, but has 
since then slowly grown towards being generic: modules in 
configuration dialogs, for example. That concept -- modules are atomic units 
which goes anywhere -- should now be lived up to fully, and the classic KDE 
integration pushed one step further.

--- Detailed Description ---

Previously, the KCModuleProxy class(in kutils) was a lightweight helper class, 
while KControl and kcmshell implemented their own powerfull classes. Now, 
because of the KCM technology being generic, the flexibility only KControl 
had, is useful on a wider basis. Since these two sets of classes tried to do 
the same thing more or less, but did it in different ways, it led to trouble 
and duplication. 

KCModuleProxy is now the one and only wrapper class, and takes care of all 
interals(with steady help from KCModuleLoader). These are the advantages this 
refactoring, combined with extensions, brings:

* Root modules can be loaded anywhere: Be it kcmshell, configuration dialogs 
or any other place. K3b can now integrate its "Setup 2" module into its 
ordinary configuration dialog, for example.

* Module uniqueness is ensured everywhere. If a module is loaded in an 
application, and then tried to be loaded anywhere else, the loading is 
aborted, the user informed, and the module is automatically loaded when it is 
unloaded in the other application. IIRC, a Kontact crash fixed by this.

* Delayed module loading have in some cases been improved(performance).

* An improved error reporting API by Matthias Kretz and I, which makes coding 
easier, and also results in a better user interface.

* Usability/GUI improvements, especially surrounding root mode

* Currently, a common problem with modules/configuration dialogs is they 
expand outside the viewing area of smaller screens. This is a cause of faulty 
designed dialogs, since they violate the HIG.[1] In either case, the new 
proxy class workarounds this in a bearable way by wrapping modules in a 
QScrollView(see BR #72112, #89940). If a configuration dialog have scrollbars 
after merging, it's because it violates the HIG(the new code only hack around 
it). If that's the case, it is an excellent time to find out what options 
that can be removed by selecting good defaults, clever coding, and conscious 
user targeting.


--- New Features ---

One new feature is Conditional Module Loading(CML, buzz buzz), which allows 
modules to themselves probe, and report back, whether they should be shown. 
For example, on my system(in my KControl) the Joystick module doesn't show up 
because I don't have a joystick connected. This is implemented in 
the various helper classes, and is hence available everywhere.

Practically, it is achieved by a boolean desktop file directive which tells 
whether the module should be tested, and (eventually) a boolean test 
function, similar to create_, whose return value tells if the module should 
be loaded. 

CML will help keep the module count lower and the modules relevant, but it is 
also a great way to mess up an interface. All relevant modules support CML(in 
HEAD), except the laptop modules which fundamentally requires a refactoring, 
although changes have happened lately.

Another new feature is the utility class KCModuleContainer, which is common 
code centralized, as well as a mechanism for organizing modules. But again, 
also a formidable way to create havoc when not used properly. As constructor 
arguments it takes a list of module names, which it then creates a module of, 
which has a tab widget containing the specified modules. 

KCModuleContainer is a KCModule which wraps real modules -- it's a 
"meta-module". It does this in a complete way: What's This text is handled, 
icons on tabs, efficient saving, etc. KCModuleContainer is as generic as 
KCModuleProxy; it can mix root modules with regulars, its test function tests 
the contained modules, etc. 

It is accompanied by a macro which takes care of everything, such as library 
declaration. For example, this creates the "Peripherals/Display" module with 
library name "display":
KCMODULECONTAINER("randr, xinerama, power, kgamma", display);

--

The features and other advantages are supported in all module wrappers, such 
as kcmshell, KCMultiDialog, and KCModuleContainer -- except KControl. E.g, 
modules won't be conditionally loaded in current KControl even if the modules 
support it. In fact, none of the changes affects KControl. kcmshell is 
backwards compatible(behavior wise, for example).

KControl with its 5500 LOC is a sinking ship, and no matter what needs to be 
replaced in KDE 4 to properly adapt to the changes which have happened over 
time. KDE 4 will be the release where these features and advantages are 
widely used. 

I want the code merged to ease maintenance, have the code available for 
distributors and 3rd parties, and the bugs/fixes it brings to KCMultiDialog. 

All in all, have the lines of code count dropped by a couple of thousands(when 
including an replacement of the current KControl), and that should rise 
further as code is upgraded. Writing KControl prototypes should also be 
simpler, easier, and allowing to focus on other issues. For example, I have a 
KControl, feature complete, in 400 LOC. 

The branch is simply a refactoring which makes functionality widely available, 
combined with extensions.


--- Code condition & future changes ---

The majority of code haven't been touched for months, and it feels 
reasonably stable. As usual, it's difficult to do proper testing, so I 
wouldn't be surprised if regressions pops up. Some of the things KCModuleProxy 
does is neither exactly straight forward; while a large goal with the branch 
was to simplify and compact code, it still looks complex, although I wonder 
if the code by its nature can be done simple in a snap..

An API cleanup is of course needed(KDE 4). Many modules needs fresh ups to 
take advantage of the API changes in KCModule(among other things), but it 
would be wise to wait with that until KDE 4 is in development.

--- Concerns for Merging ---

* Touched code is all KCM classes in kdelibs/kutils which have either been 
extended or adapted to the new code, and a more or less new kcmshell in 
kdelibs/kcmshell(disentangled from KControl). 

* The code uses kdesu for loading root modules, and it currently resides in 
kdebase. Moving it is no technical problem(AFAICT) and would probably be 
helpful in other cases. This was discussed on kde-core-devel a long time ago 
and agreed upon was sensible, but I had to go offline and the move was never 
done. (And no, kdelibs is not only for libraries.) 

* Security implications: From that perspective the situation is not changed 
AFAICT; kdesu and the root modules are what is of concern. Those are the one 
to audit, and eventually the KCModuleProxy class(which sits inbetween).

* Binary Compatibility: The interfaces are heavily extended, so a watchful 
eye on BC is necessary. _AFAICT_ BC haven't been broken. 
I've attached a diff of kcmoduleproxy.h against HEAD, in case anyone wants to 
review. If I were you, I would review.

I am interested in objections for merging the new_kcm_code branch and moving 
kdesu. Questions and suggestions are also appreciated.


		Frans


1.
http://usability.kde.org/hig/current/windows-size.php
-------------- next part --------------
A non-text attachment was scrubbed...
Name: kcmoduleproxy.h.diff
Type: text/x-diff
Size: 10056 bytes
Desc: not available
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20041126/688a3331/attachment.diff>