QML and Plasma -> progress()

[Marco Martin]

Hi all,
the status of an AppletScript for writing plasmoids in pure QML is progressing 
rather well, i thought to write a detailed status report/documentation before 
significative design problems go too far in the implementation, be patient, is 
really long, but it can be used as a basis for a future documentation.

* It is now possible to have packages that specify a main qml file, just like 
js plasmoids.

* Plasma widgets are binded in the QML language, with the Plasma.* prefix
* QGraphicsLayouts are binded in plasma bindings themselves, it is not going 
to be in Qt sadly (but QGraphicsWidget subclasses are starting to work pretty 
well with anchors/positioners as well)
* Plasma::Svg and FrameSvg are implemented as QDeclarativeItem subclasses 
binded as Svg and FrameSvg. in the future plasma widgets are going to be 
reimplemented in QML probably, those will be the classes for theming

To use QML in Plasma there are 2 ways:
* Plasma::QMLWidget -> i a qgraphicswidget that loads a qml file in it, and 
keeps the context/engine/etc, it shortens an otherwise long and repetitive 
task of loding qml files with eventiual parse error management, to be used in 
c++ plasmoids, where complex logic is needed.
* QML AppletScript: to write applets completely in QML, (uses a QMLWidget 
internally)
* only pure qml applets will have access to the "plasmoid" object? (or, the 
plasmoid object could be registered from QMLWidget, only when it is actually 
descendent of an Applet, but it would have to be in libplasma, instead of in 
workspace/runtime)

* Package: as in js bindings the package name resolution is accessible from 
plasmoid.file()

* Theme: defining a Plasma.Theme{} element in qml will obtain an object with 
the Plasma colors as properties  -> should be an object always registered to 
the root context instead? maybe by QMLWidget itself so it is always 
accessible?

* DataEngine: a Plasma.DataSource{} object can be defined in QML, this 
connects to a single dataengine source, das the source, dataengine and 
interval properties. its Data property is a QDeclarativePropertyMap, that maps 
perfectly DataEngine::Data (but is a qobject, so it can notify all properties 
that change) to access the time  of the tiime dataengine one can do: 
dataSource.data.time .
    This can be used from both qml plasmoids or outside. I'm not completely 
sure it's the right approach, alternatively in the dataUpdated of the 
AppletScript QDeclarativePropertyMaps named as something like 
dataengine+source could be assigned to the root context, connections would be 
done in the oncomplete{} slot of qml items. uhm... in the end i think i'll 
leave the DataSource approach.

* Service: still to be defined, if Plasma.DataSource is the right way to go, 
it could have a service() method that would essentially call serviceForSource, 
then bindings for kconfig would be needed, but this part is still fggy to me.

* Something else forgotten?


Here is the status of the support to Applet properties and methods:

== Methods that the ql applets should be able to reimplement: ==

* paintInterface -> no, no access to qpainters here (and was quickly becoming 
deprecated anyways)

* constraintsEvent -> formfactor, location, immutable and currentActivity 
become notifying properties -> property binding

* dataUpdated: DataSource qml item: alternative is to set a 
QDeclarativePropertyMap on dataupdated -> but would be good to use it also in 
c++ plasmoids

* configChanged() -> qml applet reimplements configChanged() function in root 
Item

* popupEvent() -> qml applet reimplements popupEvent() function in the root 
Item

== Plasmoid functions/properties ==

Unique "plasmoid" oject registered in the root context
shamelessy copied from the js bindings has the following stuff:

--properties (AppletInterface):

* aspectRatioMode
* formFactor NORIFY formFactorChanged()
* location NOTIFY locationChanged()
* currentActivity NOTIFY contextChanged()
* shouldConserveResources
* activeConfig
* busy
* backgroundHints
* immutable NOTIFY immutableChanged()
* userConfiguring
* apiVersion CONSTANT
* rect
* size

--properties (PopupAplletInterface):

* popupIcon -> needs QIcon bindings for QML
* passivePopup
* popupWidget -> is it useful there?

Should all properties that are not CONSTANT have a NOTIFY signal? that is 
needed for qml property binding.

--methods (AppletInterface):

* void setFailedToLaunch(bool failed, const QString &reason = QString())
* void setConfigurationRequired(bool needsConfiguring, const QString &reason = 
QString())
* void setAction(const QString &name, const QString &text,
                 const QString &icon = QString(), const QString &shortcut = 
QString());
* void removeAction(const QString &name);
* void resize(qreal w, qreal h);
* void setMinimumSize(qreal w, qreal h);
* void setPreferredSize(qreal w, qreal h);
* QVariant readConfig(const QString &entry) const;
* void writeConfig(const QString &entry, const QVariant &value);
* QString file(const QString &fileType);   ->  qml already can read files only 
from subdirectories of the main script, i still prefer package even tough 
could package return paths unreadable from QML?
* QString file(const QString &fileType, const QString &filePath);
* QObject *findChild(const QString &name) const   ->   useless?
* Plasma::Extender *extender() const;   ->  won't be possible to do much with 
extenders: to set extenderitems in QML should be possible to have qml items 
out of the root object i think (and only a single root is possible)

--methods (PopupAppletInterface slots):
* void setPopupIconByName(const QString &name);
* void togglePopup();
* void hidePopup();
* void showPopup();

Cheers,
Marco Martin