Introducing components, how to

[Marco Martin]

Hi all,

there is still some work to do, but the components are almost done in their 
final structure (good for the upoming freeze, ehehe :)

components are imported with:
import org.kde.plasma.components

regardless of the platform we're in.

We have at the moment 37 widgets in the touch profile, 35 in the normal one, 
tried to follow the standard api as much as possible even tough with some 
little deviations (especially where it was too unbearably ugly :p)

As for documentation, of course any help will always be welcome :p


If you are writing an application, just use kdeclarative, and the proper 
import paths will be setted.

to see what component is available, just take a look at the qmldir file in the 
source directory of kde-runtime
kde-runtime/plasma/declarativeimports/plasmacomponents/qml/
or
kde-
runtime/plasma/declarativeimports/plasmacomponents/platformcomponents/touch/

now, two things:
Q: why checking qmldir? 
A: not all files are available, the ones not shown there are private api

Q: what are those two folders?
A: hardware specific components:

the plasma QtComponents are targeted to two things: 
* Plasma Desktop widgets
* Plasma Active widgets and applications

(for desktop applications, we can only wait to see whatever it happens with 
desktop components but is way too early to know ;)

When writing a widget, an application etc, just use 
import org.kde.plasma.components, the proper one is decided by the
kdeclarativerc file, if it has
[Components-platform]
name=touch

for packagers: in plasma active among the default files this kdeclarativerc 
has to be installed

the imports in platformcomponents/touch will override the standard one, 
actually giving a series of touch optimized widgets.

only a few that needed have different implementations, the other ones are 
duplicated by being installed 2 times by cmake

some of the differences:
* Buttons and lineedits don't have mouseover effects
* by default scrollbars behave like scroll decorators on touch
* scrolldecorators are installed only on touch (provided just for 
compatibility, use scrollbar instead, it behaves the right way(tm) ;))
* sectionscroller looks like the iphone addressbook scroller on touch, like a 
scrollbar on desktop
* Window is *not* provided on desktop: in desktop widgets makes really no 
sense
* QueryDialog uses a KDialog on desktop, on touch uses qml items and is in a 
Plasma::Dialog
* the same way, Menu/ContextMenu is a QMenu on desktop, while is a more plasma 
looking thing on touch


this architecture is going to be final once released in 4.8 (at least until 
frameworks5), so "speak now or forever shut up" :p


Cheers,
Marco Martin