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

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