summaryrefslogtreecommitdiffstats
path: root/kutils/kpluginselector.h
diff options
context:
space:
mode:
Diffstat (limited to 'kutils/kpluginselector.h')
-rw-r--r--kutils/kpluginselector.h218
1 files changed, 218 insertions, 0 deletions
diff --git a/kutils/kpluginselector.h b/kutils/kpluginselector.h
new file mode 100644
index 000000000..b21e41b3e
--- /dev/null
+++ b/kutils/kpluginselector.h
@@ -0,0 +1,218 @@
+/* This file is part of the KDE project
+ Copyright (C) 2002-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 KPLUGINSELECTOR_H
+#define KPLUGINSELECTOR_H
+
+#include <qwidget.h>
+#include <qstring.h>
+
+#include <kdelibs_export.h>
+
+class KInstance;
+class KPluginInfo;
+class QWidgetStack;
+class KConfig;
+class KConfigGroup;
+
+/**
+ * @ingroup main
+ * @ingroup plugin
+ * @short A widget to select what plugins to load and configure the plugins.
+ *
+ * It shows the list of available plugins on top (if there's more than one
+ * category this is a TabWidget) and the configuration of the selected plugin
+ * below that.
+ *
+ * Since the user needs a way to know what a specific plugin does every plugin
+ * sould install a desktop file containing a name, comment and category field.
+ * The category is usefull for applications that can use different kinds of
+ * plugins like a playlist, skin or visualization.
+ *
+ * The location of these desktop files is the
+ * share/apps/&lt;instancename&gt;/&lt;plugindir&gt; directory. But if you need
+ * you may use a different directory.
+ *
+ * Often a program has more than one kind of plugin. In that case you want to
+ * make a visible distinction between those plugins. All you have to do is to
+ * create a KPluginSelectionWidget for every category and then add them all
+ * to the KPluginSelector.
+ *
+ * @author Matthias Kretz <kretz@kde.org>
+ * @since 3.2
+ */
+class KUTILS_EXPORT KPluginSelector : public QWidget
+{
+ friend class KPluginSelectionWidget;
+
+ Q_OBJECT
+ public:
+ /**
+ * Create a new KPluginSelector.
+ */
+ KPluginSelector( QWidget * parent, const char * name = 0 );
+ ~KPluginSelector();
+
+ /**
+ * Add a list of KParts plugins
+ *
+ * If you want to support non-KParts plugins use the following
+ * function.
+ *
+ * The information about the plugins will be loaded from the
+ * share/apps/&lt;instancename&gt;/kpartplugins directory.
+ *
+ * @param instanceName The name of the KInstance of the plugin's parent.
+ * @param catname The translated name of the category. This is the
+ * name that is shown in the TabWidget if there is
+ * more than one category.
+ * @param category When you have different categories of KParts
+ * plugins you distinguish between the plugins using
+ * the Category key in the .desktop file. Use this
+ * parameter to select only those KParts plugins
+ * with the Category key == @p category. If @p
+ * category is not set the Category key is ignored
+ * and all plugins are shown.
+ * @param config The KConfig object that holds the state of the
+ * plugins being enabled or not. By default it should
+ * be instance->config(). It is recommended to
+ * always pass a KConfig object if you use
+ * KSettings::PluginPage since you never know from where the
+ * page will be called (think global config app).
+ * For example KViewCanvas passes KSimpleConfig(
+ * "kviewcanvas" ).
+ */
+ void addPlugins( const QString & instanceName,
+ const QString & catname = QString::null,
+ const QString & category = QString::null,
+ KConfig * config = 0 );
+
+ /**
+ * Add a list of KParts plugins. Convenience method for the one above.
+ * If not set explicitely, @p config is set to instance->config().
+ */
+ void addPlugins( const KInstance * instance,
+ const QString & catname = QString::null,
+ const QString & category = QString::null,
+ KConfig * config = 0 );
+
+ /**
+ * Add a list of non-KParts plugins
+ *
+ * @param plugininfos A list of KPluginInfo objects containing the
+ * necessary information for the plugins you want to
+ * add to the list.
+ * @param catname The translated name of the category. This is the
+ * name that is shown in the TabWidget if there is
+ * more than one category.
+ * @param category When you have different categories of KParts
+ * plugins you distinguish between the plugins using
+ * the Category key in the .desktop file. Use this
+ * parameter to select only those KParts plugins
+ * with the Category key == @p category. If @p
+ * category is not set the Category key is ignored
+ * and all plugins are shown.
+ * @param config The KConfig object that holds the state of the
+ * plugins being enabled or not. By default it will
+ * use KGlobal::config(). It is recommended to
+ * always pass a KConfig object if you use
+ * KSettings::PluginPage since you never know from where the
+ * page will be called (think global config app).
+ * For example KViewCanvas passes KSimpleConfig(
+ * "kviewcanvas" ).
+ */
+ void addPlugins( const QValueList<KPluginInfo*> & plugininfos,
+ const QString & catname = QString::null,
+ const QString & category = QString::null,
+ KConfig * config = 0 );
+
+ /**
+ * Set whether the area for showing the KCMs of the plugins should be
+ * hidden if the plugin doesn't have a KCM or whether the layout should
+ * rather stay static and only an message should be shown.
+ *
+ * By default the config page is not hidden.
+ */
+ void setShowEmptyConfigPage( bool );
+
+ /**
+ * Load the state of the plugins (selected or not) from the KPluginInfo
+ * objects. For KParts plugins everything should work automatically. For
+ * your own type of plugins you might need to reimplement the
+ * KPluginInfo::isPluginEnabled() method. If that doesn't fit your needs
+ * you can also reimplement this method.
+ */
+ void load();
+
+ /**
+ * Save the configuration
+ */
+ void save();
+
+ /**
+ * Change to applications defaults
+ */
+ void defaults();
+
+ signals:
+ /**
+ * Tells you whether the configuration is changed or not.
+ */
+ void changed( bool );
+
+ /**
+ * Emitted after the config of an embedded KCM has been saved. The
+ * argument is the name of the parent component that needs to reload
+ * its config
+ */
+ void configCommitted( const QCString & instanceName );
+
+ private:
+ /**
+ * return the KCM widgetstack
+ *
+ * @internal
+ */
+ QWidgetStack * widgetStack();
+
+ /**
+ * Show an info page in the widgetstack.
+ *
+ * @internal
+ */
+ void configPage( int id );
+
+ /**
+ * @internal
+ */
+ void checkNeedForTabWidget();
+
+ /**
+ * @internal
+ */
+ void addPluginsInternal( const QValueList<KPluginInfo*> plugininfos,
+ const QString & catname, const QString & category,
+ KConfigGroup* cfgGroup );
+
+ class KPluginSelectorPrivate;
+ KPluginSelectorPrivate * d;
+};
+
+// vim: sw=4 sts=4 et tw=80
+#endif // KPLUGINSELECTOR_H