summaryrefslogtreecommitdiffstats
path: root/kutils/kplugininfo.h
diff options
context:
space:
mode:
authortoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
committertoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
commitce4a32fe52ef09d8f5ff1dd22c001110902b60a2 (patch)
tree5ac38a06f3dde268dc7927dc155896926aaf7012 /kutils/kplugininfo.h
downloadtdelibs-ce4a32fe52ef09d8f5ff1dd22c001110902b60a2.tar.gz
tdelibs-ce4a32fe52ef09d8f5ff1dd22c001110902b60a2.zip
Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.
BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdelibs@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
Diffstat (limited to 'kutils/kplugininfo.h')
-rw-r--r--kutils/kplugininfo.h319
1 files changed, 319 insertions, 0 deletions
diff --git a/kutils/kplugininfo.h b/kutils/kplugininfo.h
new file mode 100644
index 000000000..32ee5b5a7
--- /dev/null
+++ b/kutils/kplugininfo.h
@@ -0,0 +1,319 @@
+/* This file is part of the KDE project
+ Copyright (C) 2003 Matthias Kretz <kretz@kde.org>
+
+ This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Library General Public
+ License version 2 as published by the Free Software Foundation.
+
+ This library 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
+ Library General Public License for more details.
+
+ You should have received a copy of the GNU Library General Public License
+ along with this library; see the file COPYING.LIB. If not, write to
+ the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ Boston, MA 02110-1301, USA.
+
+*/
+
+#ifndef KPLUGININFO_H
+#define KPLUGININFO_H
+
+#include <qstring.h>
+#include <qmap.h>
+#include <qstringlist.h>
+#include <qvaluelist.h>
+#include <kservice.h>
+
+class KConfigGroup;
+
+/**
+ * @ingroup main
+ * @ingroup plugin
+ * Information about a plugin.
+ *
+ * This holds all the information about a plugin there is. It's used for the
+ * user to decide whether he wants to use this plugin or not.
+ *
+ * @author Matthias Kretz <kretz@kde.org>
+ * @since 3.2
+ */
+class KUTILS_EXPORT KPluginInfo
+{
+ public:
+ typedef QValueList<KPluginInfo*> List;
+
+ /**
+ * Read plugin info from @p filename.
+ *
+ * The file should be of the following form:
+ * \verbatim
+ [Desktop Entry]
+ Name=User Visible Name
+ Comment=Description of what the plugin does
+
+ [X-KDE Plugin Info]
+ Author=Author's Name
+ Email=author@foo.bar
+ PluginName=internalname
+ Version=1.1
+ Website=http://www.plugin.org/
+ Category=playlist
+ Depends=plugin1,plugin3
+ License=GPL
+ EnabledByDefault=true
+ \endverbatim
+ * The first two entries in the "Desktop Entry" group always need to
+ * be present.
+ *
+ * The "X-KDE-PluginInfo" keys you may add further entries which
+ * will be available using property(). The Website,Category,Require
+ * keys are optional.
+ * For EnabledByDefault look at isPluginEnabledByDefault.
+ *
+ * @param filename The filename of the .desktop file.
+ * @param resource If filename is relative, you need to specify a resource type
+ * (e.g. "service", "apps"... KStandardDirs). Otherwise,
+ * resource isn't used.
+ */
+ KPluginInfo( const QString & filename, const char* resource = 0 );
+
+ /**
+ * Read plugin info from a KService object.
+ *
+ * The .desktop file should look like this:
+ * \verbatim
+ [Desktop Entry]
+ Encoding=UTF-8
+ Icon=mypluginicon
+ Type=Service
+ ServiceTypes=KPluginInfo
+
+ X-KDE-PluginInfo-Author=Author's Name
+ X-KDE-PluginInfo-Email=author@foo.bar
+ X-KDE-PluginInfo-Name=internalname
+ X-KDE-PluginInfo-Version=1.1
+ X-KDE-PluginInfo-Website=http://www.plugin.org/
+ X-KDE-PluginInfo-Category=playlist
+ X-KDE-PluginInfo-Depends=plugin1,plugin3
+ X-KDE-PluginInfo-License=GPL
+ X-KDE-PluginInfo-EnabledByDefault=true
+
+ Name=User Visible Name
+ Comment=Description of what the plugin does
+ \endverbatim
+ * In the first three entries the Icon entry is optional.
+ */
+ KPluginInfo( const KService::Ptr service );
+
+//X /**
+//X * Create an empty hidden plugin.
+//X * @internal
+//X */
+//X KPluginInfo();
+
+ virtual ~KPluginInfo();
+
+ /**
+ * @return A list of KPluginInfo objects constructed from a list of
+ * KService objects. If you get a trader offer of the plugins you want
+ * to use you can just pass them to this function.
+ */
+ static KPluginInfo::List fromServices( const KService::List & services, KConfig * config = 0, const QString & group = QString::null );
+
+ /**
+ * @return A list of KPluginInfo objects constructed from a list of
+ * filenames. If you make a lookup using, for example,
+ * KStandardDirs::findAllResources() you pass the list of files to this
+ * function.
+ */
+ static KPluginInfo::List fromFiles( const QStringList & files, KConfig * config = 0, const QString & group = QString::null );
+
+ /**
+ * @return A list of KPluginInfo objects for the KParts plugins of an
+ * instance. You only need the name of the instance not a pointer to the
+ * KInstance object.
+ */
+ static KPluginInfo::List fromKPartsInstanceName( const QString &, KConfig * config = 0, const QString & group = QString::null );
+
+ /**
+ * @return Whether the plugin should be hidden.
+ */
+ bool isHidden() const;
+
+ /**
+ * Set whether the plugin is currently loaded.
+ *
+ * You might need to reimplement this method for special needs.
+ *
+ * @see isPluginEnabled()
+ * @see save()
+ */
+ virtual void setPluginEnabled( bool enabled );
+
+ /**
+ * @return Whether the plugin is currently loaded.
+ *
+ * You might need to reimplement this method for special needs.
+ *
+ * @see setPluginEnabled()
+ * @see load()
+ */
+ virtual bool isPluginEnabled() const;
+
+ /**
+ * @return The default value whether the plugin is enabled or not.
+ * Defaults to the value set in the desktop file, or if that isn't set
+ * to false.
+ */
+ bool isPluginEnabledByDefault() const;
+
+ /**
+ * @return The value associated the the @p key. You can use it if you
+ * want to read custom values. To do this you need to define
+ * your own servicetype and add it to the ServiceTypes keys.
+ *
+ * @see operator[]
+ */
+ QVariant property( const QString & key ) const;
+
+ /**
+ * This is the same as property(). It is provided for convenience.
+ *
+ * @return The value associated with the @p key.
+ *
+ * @see property()
+ */
+ QVariant operator[]( const QString & key ) const;
+
+ /**
+ * @return The user visible name of the plugin.
+ */
+ const QString & name() const;
+
+ /**
+ * @return A comment describing the plugin.
+ */
+ const QString & comment() const;
+
+ /**
+ * @return The iconname for this plugin
+ */
+ const QString & icon() const;
+
+ /**
+ * @return The file containing the information about the plugin.
+ */
+ const QString & specfile() const;
+
+ /**
+ * @return The author of this plugin.
+ */
+ const QString & author() const;
+
+ /**
+ * @return The email address of the author.
+ */
+ const QString & email() const;
+
+ /**
+ * @return The category of this plugin (e.g. playlist/skin).
+ */
+ const QString & category() const;
+
+ /**
+ * @return The internal name of the plugin (for KParts Plugins this is
+ * the same name as set in the .rc file).
+ */
+ const QString & pluginName() const;
+
+ /**
+ * @return The version of the plugin.
+ */
+ const QString & version() const;
+
+ /**
+ * @return The website of the plugin/author.
+ */
+ const QString & website() const;
+
+
+ /**
+ * @return The license of this plugin.
+ */
+ const QString & license() const;
+
+ /**
+ * @return A list of plugins required for this plugin to be enabled. Use
+ * the pluginName in this list.
+ */
+ const QStringList & dependencies() const;
+
+ /**
+ * @return The KService object for this plugin. You might need it if you
+ * want to read custom values. To do this you need to define
+ * your own servicetype and add it to the ServiceTypes keys.
+ * Then you can use the KService::property() method to read your
+ * keys.
+ *
+ * @see property()
+ */
+ KService::Ptr service() const;
+
+ /**
+ * @return A list of Service pointers if the plugin installs one or more
+ * KCModule
+ */
+ const QValueList<KService::Ptr> & kcmServices() const;
+
+ /**
+ * Set the KConfigGroup to use for load()ing and save()ing the
+ * configuration. This will be overridden by the KConfigGroup passed to
+ * save() or load() (if one is passed).
+ */
+ void setConfig( KConfig * config, const QString & group );
+
+ /**
+ * @return If the KPluginInfo object has a KConfig object set return
+ * it, else return 0.
+ */
+ KConfig * config() const;
+
+ /**
+ * @return The groupname used in the KConfig object for load()ing and
+ * save()ing whether the plugin is enabled.
+ */
+ const QString & configgroup() const;
+
+ /**
+ * Save state of the plugin - enabled or not. This function is provided
+ * for reimplementation if you need to save somewhere else.
+ * @param config The KConfigGroup holding the information whether
+ * plugin is enabled.
+ */
+ virtual void save( KConfigGroup * config = 0 );
+
+ /**
+ * Load the state of the plugin - enabled or not. This function is provided
+ * for reimplementation if you need to save somewhere else.
+ * @param config The KConfigGroup holding the information whether
+ * plugin is enabled.
+ */
+ virtual void load( KConfigGroup * config = 0 );
+
+ /**
+ * Restore defaults (enabled or not).
+ */
+ virtual void defaults();
+
+ private:
+ KPluginInfo( const KPluginInfo & );
+ const KPluginInfo & operator=( const KPluginInfo & );
+
+ class KPluginInfoPrivate;
+ KPluginInfoPrivate * d;
+};
+
+// vim: sw=4 sts=4 et tw=80
+#endif // KPLUGININFO_H