* more api documentation

* changes to reflect api movement

svn path=/trunk/KDE/kdebase/workspace/plasma/lib/; revision=668671

applet.cpp

@@ -16,8 +16,6 @@
  *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  */
 
-#include "applet.h"
-
 #include <QEvent>
 #include <QList>
 #include <QSize>
@@ -29,7 +27,8 @@
 #include <KService>
 #include <KServiceTypeTrader>
 
-#include "interface.h"
+#include "applet.h"
+#include "dataenginemanager.h"
 
 namespace Plasma
 {
@@ -51,7 +50,7 @@ class Applet::Private
         ~Private()
         {
             foreach ( const QString& engine, loadedEngines ) {
-               Interface::self()->unloadDataEngine( engine );
+               DataEngineManager::self()->unloadDataEngine( engine );
             }
             delete appletDescription;
         }
@@ -126,7 +125,7 @@ bool Applet::loadDataEngine( const QString& name )
         return true;
     }
 
-    if ( Plasma::Interface::self()->loadDataEngine( name ) ) {
+    if ( DataEngineManager::self()->loadDataEngine( name ) ) {
         d->loadedEngines.append( name );
         return true;
     }

applet.h

@@ -141,15 +141,35 @@ class PLASMA_EXPORT Applet : public QObject, public QGraphicsItemGroup
         static Applet* loadApplet(const KPluginInfo* info, uint appletId = 0);
 
     Q_SIGNALS:
+        /**
+         * Emit this signal when your applet needs to take (or lose) keyboard
+         * focus. This ensures that autohiding elements stay unhidden and other
+         * bits of bookkeeping are performed to ensure proper function.
+         *
+         * If you call watchForFocus on your applet, then this is handled for
+         * the applet and it is not necessary to emit the signal directly.
+         *
+         * @param focus true if the applet is taking keyboard focus, false if
+         *        it is giving it up
+         **/
         void requestFocus( bool focus );
 
     protected:
-
+        /**
+         * Returns the name of the applet. This will be the same for all
+         * instances of this applet.
+         **/
         QString globalName() const;
+
+        /**
+         * Returns a name unique to the insane of this applet. Useful for
+         * being able to refer directly to a particular applet. Combines the
+         * global name with the applet id
+         **/
         QString instanceName() const;
 
         /**
-        * Register widgets that can receive keyboard focus with this this method
+        * Register widgets that can receive keyboard focus with this method
         * This call results in an eventFilter being places on the widget.
         * @param widget the widget to watch for keyboard focus
         * @param watch whether to start watching the widget, or to stop doing so
@@ -165,7 +185,9 @@ class PLASMA_EXPORT Applet : public QObject, public QGraphicsItemGroup
         */
         void needsFocus( bool focus );
 
-
+        /**
+         * @internal event filter; used for focus watching
+         **/
         bool eventFilter( QObject *o, QEvent *e );
 
     private:

dataenginemanager.cpp

@@ -25,7 +25,7 @@
 namespace Plasma
 {
 
-    class DataEngineManager::Private
+class DataEngineManager::Private
 {
     public:
         Private()
@@ -35,6 +35,19 @@ namespace Plasma
 
 };
 
+class DataEngineManagerSingleton
+{
+    public:
+        DataEngineManager self;
+};
+
+K_GLOBAL_STATIC(DataEngineManagerSingleton, privateSelf)
+
+DataEngineManager* DataEngineManager::self()
+{
+    return &privateSelf->self;
+}
+
 DataEngineManager::DataEngineManager()
     : d(new Private())
 {
@@ -106,7 +119,7 @@ void DataEngineManager::unloadDataEngine(const QString& name)
     }
 }
 
-QStringList DataEngineManager::knownEngines() const
+QStringList DataEngineManager::knownEngines()
 {
     QStringList engines;
     KService::List offers = KServiceTypeTrader::self()->query("Plasma/DataEngine");

svg.cpp

@@ -18,6 +18,7 @@
 
 #include "svg.h"
 
+#include <QDir>
 #include <QMatrix>
 #include <QPainter>
 #include <QPixmapCache>
@@ -32,10 +33,16 @@ namespace Plasma
 class Svg::Private
 {
     public:
-        Private( const QString& image )
+        Private( const QString& imagePath )
-            : renderer( 0 ),
+            : renderer( 0 )
-              themePath( image )
         {
+            if (QDir::isAbsolutePath(themePath)) {
+                path = imagePath;
+                themed = false;
+            } else {
+                themePath = imagePath;
+                themed = true;
+            }
         }
 
         ~Private()
@@ -55,24 +62,16 @@ class Svg::Private
 
         void findInCache(QPixmap& p, const QString& elementId)
         {
-            if ( path.isNull() ) {
+            createRenderer();
-                path = Plasma::Theme::self()->image( themePath );
-
-                if ( path.isNull() ) {
-                    // bad theme path
-                    return;
-                }
-            }
-
             id = QString::fromLatin1("%3_%2_%1")
-                                    .arg( size.width() )
+                                    .arg(size.width())
-                                    .arg( size.height() )
+                                    .arg(size.height())
-                                    .arg( themePath );
+                                    .arg(path);
             if (!elementId.isEmpty()) {
                 id.append(elementId);
             }
 
-            if ( QPixmapCache::find( id, p ) ) {
+            if (QPixmapCache::find(id, p)) {
                 //kDebug() << "found cached version of " << id << endl;
                 return;
             } else {
@@ -80,14 +79,8 @@ class Svg::Private
             }
 
             // we have to re-render this puppy
-            if (!renderer) {
-                //TODO: connect the renderer's repaintNeeded to the Plasma::Svg signal
-                //      take into consideration for cache, e.g. don't cache if svg is animated
-                renderer = new KSvgRenderer(path);
-            }
-
             QSize s;
-            if ( elementId.isEmpty() ) {
+            if (elementId.isEmpty()) {
                 s = size.toSize();
             } else {
                 s = renderer->boundsOnElement(elementId).size().toSize();
@@ -96,30 +89,48 @@ class Svg::Private
 
             p = QPixmap(s);
             p.fill(Qt::transparent);
-            QPainter renderPainter( &p );
+            QPainter renderPainter(&p);
 
-            if ( elementId.isEmpty() ) {
+            if (elementId.isEmpty()) {
-                renderer->render( &renderPainter );
+                renderer->render(&renderPainter);
             } else {
-                renderer->render( &renderPainter, elementId );
+                renderer->render(&renderPainter, elementId);
             }
             renderPainter.end();
             QPixmapCache::insert( id, p );
         }
 
+        void createRenderer()
+        {
+            if (renderer) {
+                return;
+            }
+
+            if (themed && path.isNull()) {
+                path = Plasma::Theme::self()->image(themePath);
+            }
+
+            //TODO: connect the renderer's repaintNeeded to the Plasma::Svg signal
+            //      take into consideration for cache, e.g. don't cache if svg is animated
+            renderer = new KSvgRenderer(path);
+        }
+
         //TODO: share renderers between Svg objects with identical themePath
         KSvgRenderer* renderer;
         QString themePath;
         QString path;
         QString id;
         QSizeF size;
+        bool themed;
 };
 
 Svg::Svg( const QString& imagePath, QObject* parent )
     : QObject( parent ),
       d( new Private( imagePath ) )
 {
-    connect(Plasma::Theme::self(), SIGNAL(changed()), this, SLOT(themeChanged()));
+    if (d->themed) {
+        connect(Plasma::Theme::self(), SIGNAL(changed()), this, SLOT(themeChanged()));
+    }
 }
 
 Svg::~Svg()
@@ -158,18 +169,13 @@ void Svg::resize( const QSizeF& size )
 
 void Svg::resize()
 {
-    if (!d->renderer) {
+    d->createRenderer();
-        d->renderer = new KSvgRenderer(Plasma::Theme::self()->image(d->themePath));
-    }
     d->size = d->renderer->defaultSize();
 }
 
 QSize Svg::elementSize(const QString& elementId) const
 {
-    if (!d->renderer) {
+    d->createRenderer();
-        d->renderer = new KSvgRenderer(Plasma::Theme::self()->image(d->themePath));
-    }
-
     QSizeF elementSize = d->renderer->boundsOnElement(elementId).size();
     QSizeF naturalSize = d->renderer->defaultSize();
     qreal dx = d->size.width() / naturalSize.width();

svg.h

@@ -35,6 +35,14 @@ class QMatrix;
 namespace Plasma
 {
 
+/**
+ * @brief A theme aware image-centric SVG class
+ *
+ * Plasma::Svg provides a class for rendering SVG images to a QPainter in a
+ * convenient manner. Unless an absolute path to a file is provided, it loads
+ * the SVG document using Plasma::Theme. It also provides a number of internal
+ * optimizations to help lower the cost of painting SVGs, such as caching.
+ **/
 class PLASMA_EXPORT Svg : public QObject
 {
     Q_OBJECT
@@ -49,8 +57,8 @@ class PLASMA_EXPORT Svg : public QObject
          *
          * The size is initialized to be the SVG's native size.
          *
-         * @arg imagePath the image to show, used to load the image from
+         * @arg imagePath the image to show. If a relative path is passed, then
-         * Plasma::Theme
+         * Plasma::Theme is used to load the SVG.
          * @arg parent options QObject to parent this to
          *
          * @related Plasma::Theme