1/*
2 This file is part of the KDE Kontact Plugin Interface Library.
3
4 Copyright (c) 2001 Matthias Hoelzer-Kluepfel <mhk@kde.org>
5 Copyright (c) 2002-2003 Daniel Molkentin <molkentin@kde.org>
6 Copyright (c) 2003 Cornelius Schumacher <schumacher@kde.org>
7
8 This library is free software; you can redistribute it and/or
9 modify it under the terms of the GNU Library General Public
10 License as published by the Free Software Foundation; either
11 version 2 of the License, or (at your option) any later version.
12
13 This library is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 Library General Public License for more details.
17
18 You should have received a copy of the GNU Library General Public License
19 along with this library; see the file COPYING.LIB. If not, write to
20 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
21 Boston, MA 02110-1301, USA.
22*/
23
24#ifndef KONTACTINTERFACE_PLUGIN_H
25#define KONTACTINTERFACE_PLUGIN_H
26
27#include "kontactinterface_export.h"
28
29#include <kpluginfactory.h>
30#include <kxmlguiclient.h>
31
32#include <QtCore/QList>
33#include <QtCore/QObject>
34
35class KAboutData;
36class KAction;
37class KConfig;
38class KConfigGroup;
39class QDropEvent;
40class QMimeData;
41class QStringList;
42class QWidget;
43namespace KParts {
44 class ReadOnlyPart;
45}
46
47/**
48 Exports Kontact plugin.
49 */
50#define EXPORT_KONTACT_PLUGIN( pluginclass, pluginname ) \
51class Instance \
52{ \
53 public: \
54 static QObject *createInstance( QWidget *, QObject *parent, const QVariantList &list ) \
55 { return new pluginclass( static_cast<KontactInterface::Core*>( parent ), list ); } \
56}; \
57K_PLUGIN_FACTORY( KontactPluginFactory, registerPlugin< pluginclass > \
58 ( QString(), Instance::createInstance ); ) \
59K_EXPORT_PLUGIN( KontactPluginFactory( "kontact_" #pluginname "plugin" ) )
60
61/**
62 Increase this version number whenever you make a change in the API.
63 */
64#define KONTACT_PLUGIN_VERSION 9
65
66namespace KontactInterface {
67
68class Core;
69class Summary;
70
71/**
72 * @short Base class for all Plugins in Kontact.
73 *
74 * Inherit from it to get a plugin. It can insert an icon into the sidepane,
75 * add widgets to the widgetstack and add menu items via XMLGUI.
76 */
77class KONTACTINTERFACE_EXPORT Plugin : public QObject, virtual public KXMLGUIClient
78{
79 Q_OBJECT
80
81 public:
82 /**
83 * Creates a new plugin.
84 *
85 * @param core The core object that manages the plugin.
86 * @param parent The parent object.
87 * @param appName The name of the application that
88 * provides the part. This is the name used for DBus registration.
89 * It's ok to have several plugins using the same application name.
90 * @param pluginName The unique name of the plugin. Defaults to appName if not set.
91 */
92 Plugin( Core *core, QObject *parent, const char *appName, const char *pluginName = 0 );
93
94 /**
95 * Destroys the plugin.
96 */
97 virtual ~Plugin();
98
99 /**
100 * Sets the @p identifier of the plugin.
101 */
102 void setIdentifier( const QString &identifier );
103
104 /**
105 * Returns the identifier of the plugin.
106 */
107 QString identifier() const;
108
109 /**
110 * Sets the localized @p title of the plugin.
111 */
112 void setTitle( const QString &title );
113
114 /**
115 * Returns the localized title of the plugin.
116 */
117 QString title() const;
118
119 /**
120 * Sets the @p icon name that is used for the plugin.
121 */
122 void setIcon( const QString &icon );
123
124 /**
125 * Returns the icon name that is used for the plugin.
126 */
127 QString icon() const;
128
129 /**
130 * Sets the @p name of executable (if existent).
131 */
132 void setExecutableName( const QString &name );
133
134 /**
135 * Returns the name of the executable (if existent).
136 */
137 QString executableName() const;
138
139 /**
140 * Set @p name of library which contains the KPart used by this plugin.
141 */
142 void setPartLibraryName( const QByteArray &name );
143
144 /**
145 * Create the D-Bus interface for the given @p serviceType, if this
146 * plugin provides it. Returns @c true on success, @c false otherwise.
147 * @param serviceType the D-Bus service type to create an interface for
148 */
149 virtual bool createDBUSInterface( const QString &serviceType );
150
151 /**
152 * Reimplement this method and return whether a standalone application
153 * is still running. This is only required if your part is also available
154 * as standalone application.
155 */
156 virtual bool isRunningStandalone() const;
157
158 /**
159 * Reimplement this method if your application needs a different approach to be brought
160 * in the foreground. The default behaviour is calling the binary.
161 * This is only required if your part is also available as standalone application.
162 */
163 virtual void bringToForeground();
164
165 /**
166 * Reimplement this method if you want to add your credits to the Kontact
167 * about dialog.
168 */
169 virtual const KAboutData *aboutData() const;
170
171 /**
172 * You can use this method if you need to access the current part. You can be
173 * sure that you always get the same pointer as long as the part has not been
174 * deleted.
175 */
176 KParts::ReadOnlyPart *part();
177
178 /**
179 * Reimplement this method and return the a path relative to "data" to the tips file.
180 * The tips file contains hints/tips that are displayed at the beginning of the program
181 * as "tip of the day". It has nothing to do with tooltips.
182 */
183 virtual QString tipFile() const;
184
185 /**
186 * This function is called when the plugin is selected by the user before the
187 * widget of the KPart belonging to the plugin is raised.
188 */
189 virtual void select();
190
191 /**
192 * Called by kontact when the plugin is selected by the user.
193 * Calls the virtual method select(), but also handles some standard behavior
194 * like "invisible toolbar actions".
195 */
196 void aboutToSelect();
197
198 /**
199 * This function is called whenever the config dialog has been closed
200 * successfully.
201 */
202 virtual void configUpdated();
203
204 /**
205 * Reimplement this method if you want to add a widget for your application
206 * to Kontact's summary page.
207 *
208 * @param parent The parent widget of the summary widget.
209 */
210 virtual Summary *createSummaryWidget( QWidget *parent );
211
212 /**
213 * Returns whether the plugin provides a part that should be shown in the sidebar.
214 */
215 virtual bool showInSideBar() const;
216
217 /**
218 * Set if the plugin provides a part that should be shown in the sidebar.
219 * @param hasPart shows part in sidebar if set as @c true
220 */
221 void setShowInSideBar( bool hasPart );
222
223 /**
224 * Reimplement this method if you want to add checks before closing the
225 * main kontact window. Return true if it's OK to close the window.
226 * If any loaded plugin returns false from this method, then the
227 * main kontact window will not close.
228 */
229 virtual bool queryClose() const;
230
231 /**
232 * Registers the client at DBus and returns the dbus identifier.
233 */
234 QString registerClient();
235
236 /**
237 * Return the weight of the plugin. The higher the weight the lower it will
238 * be displayed in the sidebar. The default implementation returns 0.
239 */
240 virtual int weight() const;
241
242 /**
243 * Inserts a custom "New" @p action.
244 * @param action the new action to insert
245 */
246 void insertNewAction( KAction *action );
247
248 /**
249 * Inserts a custom "Sync" @p action.
250 * @param action the custom Sync action to insert
251 */
252 void insertSyncAction( KAction *action );
253
254 /**
255 * Returns the list of custom "New" actions.
256 */
257 QList<KAction*> newActions() const;
258
259 /**
260 * Returns the list of custom "Sync" actions.
261 */
262 QList<KAction*> syncActions() const;
263
264 /**
265 * Returns a list of action names that shall be hidden in the main toolbar.
266 */
267 virtual QStringList invisibleToolbarActions() const;
268
269 /**
270 * Returns whether the plugin can handle the drag object of the given mime type.
271 */
272 virtual bool canDecodeMimeData( const QMimeData *data ) const;
273
274 /**
275 * Process drop event.
276 */
277 virtual void processDropEvent( QDropEvent * );
278
279 /**
280 * Session management: read properties
281 */
282 virtual void readProperties( const KConfigGroup & );
283
284 /**
285 * Session management: save properties
286 */
287 virtual void saveProperties( KConfigGroup & );
288
289 /**
290 * Returns a pointer to the kontact core object.
291 */
292 Core *core() const;
293
294 /**
295 * Sets whether the plugin shall be disabled.
296 */
297 void setDisabled( bool value );
298
299 /**
300 * Returns whether the plugin is disabled.
301 */
302 bool disabled() const;
303
304 /**
305 * @since 4.13
306 */
307 virtual void shortcutChanged();
308
309 public Q_SLOTS:
310 /**
311 * @internal usage
312 *
313 * This slot is called whenever the configuration has been changed.
314 */
315 void slotConfigUpdated();
316
317 protected:
318 /**
319 * Reimplement and return the part here. Reimplementing createPart() is
320 * mandatory!
321 */
322 virtual KParts::ReadOnlyPart *createPart() = 0;
323
324 /**
325 * Returns the loaded part.
326 */
327 KParts::ReadOnlyPart *loadPart();
328
329 /**
330 * Virtual hook for BC extension.
331 */
332 virtual void virtual_hook( int id, void *data );
333
334 private:
335 //@cond PRIVATE
336 class Private;
337 Private *const d;
338
339 Q_PRIVATE_SLOT( d, void partDestroyed() )
340 //@endcond
341};
342
343}
344
345#endif
346