documentation++

src/scriptengines/qml/plasmoid/appletinterface.h

@@ -51,24 +51,91 @@ class AppletInterface : public QQuickItem
     Q_OBJECT
 
     /**
-     * The QML root object defined in the applet main.qml
+     * The QML root object defined in the applet main.qml will be direct child of an AppletInterface instance
+     */
+
+    /**
+     * Version of the QML2 script engine
+     */
+    Q_PROPERTY(int apiVersion READ apiVersion CONSTANT)
+
+    /**
+     * User friendly title for the plasmoid: it's the localized applet name by default
      */
     Q_PROPERTY(QString title READ title WRITE setTitle NOTIFY titleChanged)
+
     //TODO: writable icon
+    /**
+     * Icon to represent the plasmoid
+     */
     Q_PROPERTY(QString icon READ icon CONSTANT)
+
+    /**
+     * Applet id: is unique in the whole Plasma session and will never change across restarts
+     */
     Q_PROPERTY(uint id READ id CONSTANT)
+
+    /**
+     * FormFactor for the plasmoid
+     */
     Q_PROPERTY(Plasma::Types::FormFactor formFactor READ formFactor NOTIFY formFactorChanged)
+
+    /**
+     * Location for the plasmoid
+     */
     Q_PROPERTY(Plasma::Types::Location location READ location NOTIFY locationChanged)
+
+    /**
+     * Current activity name the plasmoid is in
+     */
     Q_PROPERTY(QString currentActivity READ currentActivity NOTIFY contextChanged)
+
+    /**
+     * Configuration object: each config key will be a writable property of this object. property bindings work.
+     */
     Q_PROPERTY(QObject* configuration READ configuration CONSTANT)
+
+    /**
+     * FIXME-API: do we still want this?
+     * current active configuration
+     */
     Q_PROPERTY(QString activeConfig WRITE setActiveConfig READ activeConfig)
+
+    /**
+     * When true the plasmoid is busy. The containment may graphically indicate that drawing for instance a spinner busy widget over it
+     */
     Q_PROPERTY(bool busy WRITE setBusy READ isBusy NOTIFY busyChanged)
+
+    /**
+     * True when the applet is showing its full representation. either as the main only view, or in a popup.
+     * Setting it will open or close the popup if the plasmoid is iconified, however it won't have effect if the applet is open
+     */
     Q_PROPERTY(bool expanded WRITE setExpanded READ isExpanded NOTIFY expandedChanged)
+
+    /**
+     * How the applet wants its background to be drawn. The containment may chose to ignore this hint.
+     */
     Q_PROPERTY(Plasma::Types::BackgroundHints backgroundHints WRITE setBackgroundHints READ backgroundHints NOTIFY backgroundHintsChanged)
+
+    /**
+     * The immutability state of the Corona. the plasmoid implementation should avoid allowing "dangerous" modifications from the user when in an immutable mode
+     */
     Q_PROPERTY(bool immutable READ immutable NOTIFY immutableChanged)
+
+    /**
+     * True when the user is configuring, for instance when the configuration dialog is open.
+     */
     Q_PROPERTY(bool userConfiguring READ userConfiguring NOTIFY userConfiguringChanged)
-    Q_PROPERTY(int apiVersion READ apiVersion CONSTANT)
+
+    /**
+     * Status of the plasmoid: useful to instruct the shell if this plasmoid is requesting attention, if is accepting input, or if is in an idle, inactive state
+     */
     Q_PROPERTY(Plasma::Types::ItemStatus status READ status WRITE setStatus NOTIFY statusChanged)
+
+    /**
+     * Sets the associated application of this plasmoid, if the plasmoid is representing the "compact" view for some application or for some document type. 
+     * TODO: a way to set associated application urls.
+     */
     Q_PROPERTY(QString associatedApplication WRITE setAssociatedApplication READ associatedApplication)
 
     // TODO: This was moved up from ContainmentInterface because it is required by the
@@ -77,15 +144,23 @@ class AppletInterface : public QQuickItem
     // would be preferrable if found.
     Q_PROPERTY(int screen READ screen NOTIFY screenChanged)
 
-    //Size hints Note that the containments may chose to not respect them.
+    //Size hints. Note that the containments may chose to not respect them.
     Q_PROPERTY(qreal minimumWidth READ minimumWidth NOTIFY minimumWidthChanged)
     Q_PROPERTY(qreal minimumHeight READ minimumHeight NOTIFY minimumHeightChanged)
     Q_PROPERTY(qreal maximumWidth READ maximumWidth NOTIFY maximumWidthChanged)
     Q_PROPERTY(qreal maximumHeight READ maximumHeight NOTIFY maximumHeightChanged)
-    //implicitWidth/height is already there
+    //FIXME?implicitWidth/height is already there
     Q_PROPERTY(qreal implicitWidth READ implicitWidth NOTIFY implicitWidthChanged)
     Q_PROPERTY(qreal implicitHeight READ implicitHeight NOTIFY implicitHeightChanged)
+
+    /**
+     * If the plasmoid is in a linear layout, such as a panel, it indicates to take as much horizontal space as possible
+     */
     Q_PROPERTY(bool fillWidth READ fillWidth NOTIFY fillWidthChanged)
+
+    /**
+     * If the plasmoid is in a linear layout, such as a panel, it indicates to take as much vertical space as possible
+     */
     Q_PROPERTY(bool fillHeight READ fillHeight NOTIFY fillHeightChanged)
 
 public:
@@ -95,6 +170,10 @@ public:
 //API not intended for the QML part
     QmlObject *qmlObject();
 
+    QList<QAction*> contextualActions() const;
+
+    inline Plasma::Applet *applet() const { return m_appletScriptEngine->applet(); }
+
 //QML API-------------------------------------------------------------------
 
     Q_INVOKABLE void setConfigurationRequired(bool needsConfiguring, const QString &reason = QString());
@@ -116,10 +195,7 @@ public:
 
     Q_INVOKABLE void debug(const QString &msg);
 
-    QList<QAction*> contextualActions() const;
-
-    inline Plasma::Applet *applet() const { return m_appletScriptEngine->applet(); }
-
+    //FIXME-API: remove?
     Q_INVOKABLE QString downloadPath(const QString &file);
     Q_INVOKABLE QStringList downloadedFiles() const;