summaryrefslogtreecommitdiffstats
path: root/kparts/plugin.h
blob: 9c2c1651275eed40eb43f241da966bb2418babd3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
/* This file is part of the KDE project
   Copyright (C) 1999 Simon Hausmann <hausmann@kde.org>
             (C) 1999 David Faure <faure@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 as published by the Free Software Foundation; either
   version 2 of the License, or (at your option) any later version.

   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 PLUGIN_H
#define PLUGIN_H

#include <tqobject.h>
#include <kaction.h>
#include <kxmlguiclient.h>

class KInstance;

namespace KParts
{

/**
 * A plugin is the way to add actions to an existing KParts application,
 * or to a Part.
 *
 * The XML of those plugins looks exactly like of the shell or parts,
 * with one small difference: The document tag should have an additional
 * attribute, named "library", and contain the name of the library implementing
 * the plugin.
 *
 * If you want this plugin to be used by a part, you need to
 * install the rc file under the directory
 * "data" (KDEDIR/share/apps usually)+"/instancename/kpartplugins/"
 * where instancename is the name of the part's instance.
 *
 * You should also install a "plugin info" .desktop file with the same name.
 * \see PluginInfo
 */
class KPARTS_EXPORT Plugin : public TQObject, virtual public KXMLGUIClient
{
    Q_OBJECT
public:
    /**
     * Struct holding information about a plugin
     */
    struct PluginInfo
    {
        TQString m_relXMLFileName; ///< relative filename, i.e. kpartplugins/name
        TQString m_absXMLFileName; ///< full path of most recent filename matching the relative filename
        TQDomDocument m_document;
    };

    /**
     * Construct a new KParts plugin.
     */
    Plugin( TQObject* parent = 0, const char* name = 0 );
    /**
     * Destructor.
     */
    virtual ~Plugin();

    /**
     * Reimplemented for internal reasons
     */
    virtual TQString xmlFile() const;

    /**
     * Reimplemented for internal reasons
     */
    virtual TQString localXMLFile() const;

    /**
     * Load the plugin libraries from the directories appropriate
     * to @p instance and make the Plugin objects children of @p parent.
     *
     * It is recommended to use the last loadPlugins method instead,
     * to support enabling and disabling of plugins.
     */
    static void loadPlugins( TQObject *parent, const KInstance * instance );

    /**
     * Load the plugin libraries specified by the list @p docs and make the
     * Plugin objects children of @p parent .
     *
     * It is recommended to use the last loadPlugins method instead,
     * to support enabling and disabling of plugins.
     */
    static void loadPlugins( TQObject *parent, const TQValueList<PluginInfo> &pluginInfos );

    /**
     * Load the plugin libraries specified by the list @p pluginInfos, make the
     * Plugin objects children of @p parent, and use the given @p instance.
     *
     * It is recommended to use the last loadPlugins method instead,
     * to support enabling and disabling of plugins.
     */
    static void loadPlugins( TQObject *parent, const TQValueList<PluginInfo> &pluginInfos, const KInstance * instance );

    /**
     * Load the plugin libraries for the given @p instance, make the
     * Plugin objects children of @p parent, and insert the plugin as a child GUI client
     * of @p parentGUIClient.
     *
     * This method uses the KConfig object of the given instance, to tqfind out which
     * plugins are enabled and which are disabled. What happens by default (i.e.
     * for new plugins that are not in that config file) is controlled by
     * @p enableNewPluginsByDefault. It can be overridden by the plugin if it
     * sets the X-KDE-PluginInfo-EnabledByDefault key in the .desktop file
     * (with the same name as the .rc file)
     *
     * If a disabled plugin is already loaded it will be removed from the GUI
     * factory and deleted.
     *
     * This method is automatically called by KParts::Plugin and by KParts::MainWindow.
     *
     * If you call this method in an already constructed GUI (like when the user
     * has changed which plugins are enabled) you need to add the new plugins to
     * the KXMLGUIFactory:
     * \code
     * if( factory() )
     * {
     *   TQPtrList<KParts::Plugin> plugins = KParts::Plugin::pluginObjects( this );
     *   TQPtrListIterator<KParts::Plugin> it( plugins );
     *   KParts::Plugin * plugin;
     *   while( ( plugin = it.current() ) != 0 )
     *   {
     *     ++it;
     *     factory()->addClient(  plugin );
     *   }
     * }
     * \endcode
     */
    static void loadPlugins( TQObject *parent, KXMLGUIClient* parentGUIClient, KInstance* instance, bool enableNewPluginsByDefault = true );

    /**
     * Returns a list of plugin objects loaded for @p parent. This
     * functions basically calls the queryList method of
     * TQObject to retrieve the list of child objects inheriting
     * KParts::Plugin .
     **/
    static TQPtrList<Plugin> pluginObjects( TQObject *parent );

protected:
    /**
     * Look for plugins in the @p instance's "data" directory (+"/kpartplugins")
     *
     * @return A list of TQDomDocument s, containing the parsed xml documents returned by plugins.
     */
    static TQValueList<Plugin::PluginInfo> pluginInfos( const KInstance * instance );

    /**
     * @internal
     * @return The plugin created from the library @p libname
     */
    static Plugin* loadPlugin( TQObject * parent, const char* libname );

    virtual void setInstance( KInstance *instance );

private:
    static bool hasPlugin( TQObject* parent, const TQString& library );
    class PluginPrivate;
    PluginPrivate *d;
};

}

#endif