From 3d517330189f34fb4835794952ffde07a5ce385b Mon Sep 17 00:00:00 2001 From: "Aaron J. Seigo" Date: Sun, 27 May 2007 08:01:31 +0000 Subject: [PATCH] * more api documentation * changes to reflect api movement svn path=/trunk/KDE/kdebase/workspace/plasma/lib/; revision=668671 --- applet.cpp | 9 +++-- applet.h | 28 ++++++++++++++-- dataenginemanager.cpp | 17 ++++++++-- svg.cpp | 76 +++++++++++++++++++++++-------------------- svg.h | 12 +++++-- 5 files changed, 95 insertions(+), 47 deletions(-) diff --git a/applet.cpp b/applet.cpp index 9a8d3ef2f..ea614e5e5 100644 --- a/applet.cpp +++ b/applet.cpp @@ -16,8 +16,6 @@ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ -#include "applet.h" - #include #include #include @@ -29,7 +27,8 @@ #include #include -#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; } diff --git a/applet.h b/applet.h index 0e7a2f99c..bb0e3330e 100644 --- a/applet.h +++ b/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: diff --git a/dataenginemanager.cpp b/dataenginemanager.cpp index f8544cff4..bb6bc4add 100644 --- a/dataenginemanager.cpp +++ b/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"); diff --git a/svg.cpp b/svg.cpp index c8725dfa0..421d6242c 100644 --- a/svg.cpp +++ b/svg.cpp @@ -18,6 +18,7 @@ #include "svg.h" +#include #include #include #include @@ -32,10 +33,16 @@ namespace Plasma class Svg::Private { public: - Private( const QString& image ) - : renderer( 0 ), - themePath( image ) + Private( const QString& imagePath ) + : renderer( 0 ) { + 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() ) { - path = Plasma::Theme::self()->image( themePath ); - - if ( path.isNull() ) { - // bad theme path - return; - } - } - + createRenderer(); id = QString::fromLatin1("%3_%2_%1") - .arg( size.width() ) - .arg( size.height() ) - .arg( themePath ); + .arg(size.width()) + .arg(size.height()) + .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() ) { - renderer->render( &renderPainter ); + if (elementId.isEmpty()) { + 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->renderer = new KSvgRenderer(Plasma::Theme::self()->image(d->themePath)); - } + d->createRenderer(); d->size = d->renderer->defaultSize(); } QSize Svg::elementSize(const QString& elementId) const { - if (!d->renderer) { - d->renderer = new KSvgRenderer(Plasma::Theme::self()->image(d->themePath)); - } - + d->createRenderer(); QSizeF elementSize = d->renderer->boundsOnElement(elementId).size(); QSizeF naturalSize = d->renderer->defaultSize(); qreal dx = d->size.width() / naturalSize.width(); diff --git a/svg.h b/svg.h index 5f67df0df..5896b6322 100644 --- a/svg.h +++ b/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 - * Plasma::Theme + * @arg imagePath the image to show. If a relative path is passed, then + * Plasma::Theme is used to load the SVG. * @arg parent options QObject to parent this to * * @related Plasma::Theme