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 | |
35 | class KAboutData; |
36 | class KAction; |
37 | class KConfig; |
38 | class KConfigGroup; |
39 | class QDropEvent; |
40 | class QMimeData; |
41 | class QStringList; |
42 | class QWidget; |
43 | namespace KParts { |
44 | class ReadOnlyPart; |
45 | } |
46 | |
47 | /** |
48 | Exports Kontact plugin. |
49 | */ |
50 | #define EXPORT_KONTACT_PLUGIN( pluginclass, pluginname ) \ |
51 | class 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 | }; \ |
57 | K_PLUGIN_FACTORY( KontactPluginFactory, registerPlugin< pluginclass > \ |
58 | ( QString(), Instance::createInstance ); ) \ |
59 | K_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 | |
66 | namespace KontactInterface { |
67 | |
68 | class Core; |
69 | class 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 | */ |
77 | class 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 () 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 ( 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 | |