alecs/plasma-framework
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

a basic plugin skeleton

Browse Source 
this is based off the wallpaper plugin. lots of copy&paste happened. the
dataengine code is still in there, just in case some plugin wants it
someday...

svn path=/trunk/KDE/kdelibs/; revision=1012635
This commit is contained in:
Chani Armitage 2009-08-17 22:30:29 +00:00
parent c67decb4d9
commit 9d452dc2ea
7 changed files with 547 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
CMakeLists.txt
View File

@ -59,6 +59,7 @@ set(plasma_LIB_SRCS
configloader.cpp
containment.cpp
context.cpp
contextaction.cpp
corona.cpp
datacontainer.cpp
dataengine.cpp
@ -202,6 +203,7 @@ set(plasma_LIB_INCLUDES
configloader.h
containment.h
context.h
contextaction.h
corona.h
datacontainer.h
dataengine.h
@ -287,6 +289,7 @@ install(FILES
servicetypes/plasma-applet.desktop
servicetypes/plasma-applet-popupapplet.desktop
servicetypes/plasma-containment.desktop
servicetypes/plasma-contextaction.desktop
servicetypes/plasma-dataengine.desktop
servicetypes/plasma-packagestructure.desktop
servicetypes/plasma-runner.desktop

213
contextaction.cpp Normal file
View File

@ -0,0 +1,213 @@
/*
* Copyright 2008 by Aaron Seigo <aseigo@kde.org>
* Copyright 2008 by Petri Damsten <damu@iki.fi>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU Library General Public License as
* published by the Free Software Foundation; either version 2, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details
*
* You should have received a copy of the GNU Library General Public
* License along with this program; if not, write to the
* Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
#include "contextaction.h"
#include <kdebug.h>
#include <kglobal.h>
#include <kservicetypetrader.h>
#include <kstandarddirs.h>
#include <version.h>
#include "plasma/private/dataengineconsumer_p.h"
#include "plasma/private/packages_p.h"
#include "plasma/private/contextaction_p.h"
namespace Plasma
{
PackageStructure::Ptr ContextActionPrivate::s_packageStructure(0);
ContextAction::ContextAction(QObject * parentObject)
: d(new ContextActionPrivate(KService::serviceByStorageId(QString()), this))
{
setParent(parentObject);
}
ContextAction::ContextAction(QObject *parentObject, const QVariantList &args)
: d(new ContextActionPrivate(KService::serviceByStorageId(args.count() > 0 ?
args[0].toString() : QString()), this))
{
// now remove first item since those are managed by Wallpaper and subclasses shouldn't
// need to worry about them. yes, it violates the constness of this var, but it lets us add
// or remove items later while applets can just pretend that their args always start at 0
QVariantList &mutableArgs = const_cast<QVariantList &>(args);
if (!mutableArgs.isEmpty()) {
mutableArgs.removeFirst();
}
setParent(parentObject);
}
ContextAction::~ContextAction()
{
delete d;
}
KPluginInfo::List ContextAction::listContextActionInfo()
{
QString constraint;
KService::List offers = KServiceTypeTrader::self()->query("Plasma/ContextAction", constraint);
return KPluginInfo::fromServices(offers);
}
ContextAction *ContextAction::load(const QString &contextActionName, const QVariantList &args)
{
if (contextActionName.isEmpty()) {
return 0;
}
QString constraint = QString("[X-KDE-PluginInfo-Name] == '%1'").arg(contextActionName);
KService::List offers = KServiceTypeTrader::self()->query("Plasma/ContextAction", constraint);
if (offers.isEmpty()) {
kDebug() << "offers is empty for " << contextActionName;
return 0;
}
KService::Ptr offer = offers.first();
KPluginLoader plugin(*offer);
if (!Plasma::isPluginVersionCompatible(plugin.pluginVersion())) {
return 0;
}
QVariantList allArgs;
allArgs << offer->storageId() << args;
QString error;
ContextAction *contextAction = offer->createInstance<Plasma::ContextAction>(0, allArgs, &error);
if (!contextAction) {
kDebug() << "Couldn't load contextAction \"" << contextActionName << "\"! reason given: " << error;
}
return contextAction;
}
ContextAction *ContextAction::load(const KPluginInfo &info, const QVariantList &args)
{
if (!info.isValid()) {
return 0;
}
return load(info.pluginName(), args);
}
PackageStructure::Ptr ContextAction::packageStructure()
{
if (!ContextActionPrivate::s_packageStructure) {
ContextActionPrivate::s_packageStructure = new ContextActionPackage();
}
return ContextActionPrivate::s_packageStructure;
}
QString ContextAction::name() const
{
if (!d->contextActionDescription.isValid()) {
return i18n("Unknown ContextAction");
}
return d->contextActionDescription.name();
}
QString ContextAction::icon() const
{
if (!d->contextActionDescription.isValid()) {
return QString();
}
return d->contextActionDescription.icon();
}
QString ContextAction::pluginName() const
{
if (!d->contextActionDescription.isValid()) {
return QString();
}
return d->contextActionDescription.pluginName();
}
bool ContextAction::isInitialized() const
{
return d->initialized;
}
void ContextAction::restore(const KConfigGroup &config)
{
init(config);
d->initialized = true;
}
void ContextAction::init(const KConfigGroup &config)
{
Q_UNUSED(config);
}
void ContextAction::save(KConfigGroup &config)
{
Q_UNUSED(config);
}
QWidget *ContextAction::createConfigurationInterface(QWidget *parent)
{
Q_UNUSED(parent);
return 0;
}
void ContextAction::contextEvent(QGraphicsSceneMouseEvent *event)
{
Q_UNUSED(event)
}
void ContextAction::wheelEvent(QGraphicsSceneWheelEvent *event)
{
Q_UNUSED(event)
}
DataEngine *ContextAction::dataEngine(const QString &name) const
{
return d->dataEngine(name);
}
bool ContextAction::configurationRequired() const
{
return d->needsConfig;
}
void ContextAction::setConfigurationRequired(bool needsConfig, const QString &reason)
{
//TODO: implement something for reason. first, we need to decide where/how
// to communicate it to the user
Q_UNUSED(reason)
if (d->needsConfig == needsConfig) {
return;
}
d->needsConfig = needsConfig;
emit configurationRequired(needsConfig);
}
} // Plasma namespace
#include "contextaction.moc"

259
contextaction.h Normal file
View File

@ -0,0 +1,259 @@
/*
* Copyright 2008 by Aaron Seigo <aseigo@kde.org>
* Copyright 2008 by Petri Damsten <damu@iki.fi>
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU Library General Public License as
* published by the Free Software Foundation; either version 2, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details
*
* You should have received a copy of the GNU Library General Public
* License along with this program; if not, write to the
* Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
#ifndef PLASMA_CONTEXTACTION_H
#define PLASMA_CONTEXTACTION_H
#include <kplugininfo.h>
#include <plasma/plasma.h>
#include <plasma/packagestructure.h>
#include <plasma/version.h>
namespace Plasma
{
class DataEngine;
class ContextActionPrivate;
/**
* @class ContextAction plasma/contextaction.h <Plasma/ContextAction>
*
* @short The base ContextAction class
*
* "ContextActions" are components that provide an action (usually displaying a contextmenu) in
* response to an event with a position (usually a mouse event).
*
* ContextAction plugins are registered using .desktop files. These files should be
* named using the following naming scheme:
*
* plasma-contextaction-\<pluginname\>.desktop
*
*/
class PLASMA_EXPORT ContextAction : public QObject
{
Q_OBJECT
Q_PROPERTY(QString name READ name)
Q_PROPERTY(QString pluginName READ pluginName)
Q_PROPERTY(QString icon READ icon)
public:
/**
* Default constructor for an empty or null contextaction
*/
explicit ContextAction(QObject * parent = 0);
~ContextAction();
/**
* Returns a list of all known contextactions.
*
* @return list of contextactions
**/
static KPluginInfo::List listContextActionInfo();
/**
* Attempts to load a contextaction
*
* Returns a pointer to the contextaction if successful.
* The caller takes responsibility for the contextaction, including
* deleting it when no longer needed.
*
* @param name the plugin name, as returned by KPluginInfo::pluginName()
* @param args to send the contextaction extra arguments
* @return a pointer to the loaded contextaction, or 0 on load failure
**/
static ContextAction *load(const QString &name, const QVariantList &args = QVariantList());
/**
* Attempts to load a contextaction
*
* Returns a pointer to the contextaction if successful.
* The caller takes responsibility for the contextaction, including
* deleting it when no longer needed.
*
* @param info KPluginInfo object for the desired contextaction
* @param args to send the contextaction extra arguments
* @return a pointer to the loaded contextaction, or 0 on load failure
**/
static ContextAction *load(const KPluginInfo &info, const QVariantList &args = QVariantList());
/**
* Returns the Package specialization for contextactions.
*/
static PackageStructure::Ptr packageStructure();
/**
* Returns the user-visible name for the contextaction, as specified in the
* .desktop file.
*
* @return the user-visible name for the contextaction.
**/
QString name() const;
/**
* Returns the plugin name for the contextaction
*/
QString pluginName() const;
/**
* Returns the icon related to this contextaction
**/
QString icon() const;
/**
* @return true if initialized (usually by calling restore), false otherwise
*/
bool isInitialized() const;
/**
* This method should be called once the wallpaper is loaded or mode is changed.
* @param config Config group to load settings
* @see init
**/
void restore(const KConfigGroup &config);
/**
* This method is called when settings need to be saved.
* @param config Config group to save settings
**/
virtual void save(KConfigGroup &config);
/**
* Returns the widget used in the configuration dialog.
* Add the configuration interface of the contextaction to this widget.
* To signal that settings have changed connect to
* settingsChanged(bool modified) in @p parent.
* @code connect(this, SIGNAL(settingsChanged(bool), parent, SLOT(settingsChanged(bool)))
* @endcode
* Emit settingsChanged(true) when the settings are changed and false when the original state is restored.
*/
virtual QWidget *createConfigurationInterface(QWidget *parent);
/**
* Implement this to respond to a mouse button event.
* The user can configure whatever button and modifier they like, so please don't look at
* those parameters.
* @param event the mouse event object
*/
virtual void contextEvent(QGraphicsSceneMouseEvent *event);
/**
* Implement this to respond to a wheel event.
* The user can configure which wheel and whatever modifier they like, so please don't look at
* those parameters.
* @param event the mousewheel event object
*/
virtual void wheelEvent(QGraphicsSceneWheelEvent *event);
/**
* Loads the given DataEngine
*
* Tries to load the data engine given by @p name. Each engine is
* only loaded once, and that instance is re-used on all subsequent
* requests.
*
* If the data engine was not found, an invalid data engine is returned
* (see DataEngine::isValid()).
*
* Note that you should <em>not</em> delete the returned engine.
*
* @param name Name of the data engine to load
* @return pointer to the data engine if it was loaded,
* or an invalid data engine if the requested engine
* could not be loaded
*
*/
Q_INVOKABLE DataEngine *dataEngine(const QString &name) const;
/**
* @return true if the contextaction currently needs to be configured,
* otherwise, false
*/
bool configurationRequired() const;
Q_SIGNALS:
/**
* Emitted when the user wants to configure/change the contextaction.
*/
void configureRequested();
/**
* Emitted when the state of the contextaction requiring configuration
* changes.
*/
void configurationRequired(bool needsConfig);
/**
* Emitted when the configuration of the contextaction needs to be saved
* to disk.
*/
void configNeedsSaving();
protected:
/**
* This constructor is to be used with the plugin loading systems
* found in KPluginInfo and KService. The argument list is expected
* to have one element: the KService service ID for the desktop entry.
*
* @param parent a QObject parent; you probably want to pass in 0
* @param args a list of strings containing one entry: the service id
*/
ContextAction(QObject *parent, const QVariantList &args);
/**
* This method is called once the contextaction is loaded or mode is changed.
*
* The mode can be retrieved using the renderingMode() method.
*
* @param config Config group to load settings
**/
virtual void init(const KConfigGroup &config);
/**
* When the contextaction needs to be configured before being usable, this
* method can be called to denote that action is required
*
* @param needsConfiguring true if the applet needs to be configured,
* or false if it doesn't
* @param reason a translated message for the user explaining that the
* applet needs configuring; this should note what needs
* to be configured
*/
void setConfigurationRequired(bool needsConfiguring, const QString &reason = QString());
private:
friend class ContextActionPackage;
friend class ContextActionPrivate;
ContextActionPrivate *const d;
};
} // Plasma namespace
/**
* Register a contextaction when it is contained in a loadable module
*/
#define K_EXPORT_PLASMA_CONTEXTACTION(libname, classname) \
K_PLUGIN_FACTORY(factory, registerPlugin<classname>();) \
K_EXPORT_PLUGIN(factory("plasma_contextaction_" #libname)) \
K_EXPORT_PLUGIN_VERSION(PLASMA_VERSION)
#endif // multiple inclusion guard

52
private/contextaction_p.h Normal file
View File

@ -0,0 +1,52 @@
/*
* Copyright 2008 by Aaron Seigo <aseigo@kde.org>
* Copyright 2008 by Petri Damsten <damu@iki.fi>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU Library General Public License as
* published by the Free Software Foundation; either version 2, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details
*
* You should have received a copy of the GNU Library General Public
* License along with this program; if not, write to the
* Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
#ifndef PLASMA_CONTEXTACTIONPRIVATE_H
#define PLASMA_CONTEXTACTIONPRIVATE_H
#include "plasma/private/dataengineconsumer_p.h"
namespace Plasma
{
class ContextActionPrivate : public DataEngineConsumer
{
public:
ContextActionPrivate(KService::Ptr service, ContextAction *contextAction) :
q(contextAction),
contextActionDescription(service),
initialized(false),
needsConfig(false)
{
};
static PackageStructure::Ptr s_packageStructure;
ContextAction *q;
KPluginInfo contextActionDescription;
Package *package;
KServiceAction mode;
bool initialized : 1;
bool needsConfig : 1;
};
} // namespace Plasma
#endif

6
private/packages.cpp
View File

@ -305,6 +305,12 @@ void WallpaperPackage::paperDestroyed()
m_paper = 0;
}
ContextActionPackage::ContextActionPackage(QObject *parent)
: Plasma::PackageStructure(parent, QString("ContextAction"))
{
//FIXME how do I do the mimetypes stuff?
}
} // namespace Plasma
#include "packages_p.moc"

10
private/packages_p.h
View File

@ -32,8 +32,6 @@ namespace KNS
namespace Plasma
{
class Wallpaper;
class PlasmoidPackage : public PackageStructure
{
Q_OBJECT
@ -84,6 +82,14 @@ private:
Wallpaper *m_paper;
};
class ContextActionPackage : public PackageStructure
{
Q_OBJECT
public:
explicit ContextActionPackage(QObject *parent = 0);
};
PackageStructure::Ptr defaultPackageStructure(ComponentType type);
} // namespace Plasma

6
servicetypes/plasma-contextaction.desktop Normal file
View File

@ -0,0 +1,6 @@
[Desktop Entry]
Type=ServiceType
X-KDE-ServiceType=Plasma/ContextAction
Comment=Plasma ContextAction