summaryrefslogtreecommitdiffstats
path: root/kontact/interfaces/plugin.h
blob: af7cbfa71b77539750c93e66cf97425810202c99 (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
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
/*
   This file is part of KDE Kontact.

   Copyright (c) 2001 Matthias Hoelzer-Kluepfel <mhk@kde.org>
   Copyright (c) 2002-2003 Daniel Molkentin <molkentin@kde.org>
   Copyright (c) 2003 Cornelius Schumacher <schumacher@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 KONTACT_PLUGIN_H
#define KONTACT_PLUGIN_H

#include <tqobject.h>
#include <kxmlguiclient.h>
#include <kdemacros.h>
#include <tqptrlist.h>

class TQStringList;
class DCOPClient;
class DCOPObject;
class TDEAboutData;
class TDEAction;
class TDEConfig;
class TQWidget;
namespace KParts { class ReadOnlyPart; }

/**
  Increase this version number whenever you make a change
  in the API.
 */
#define KONTACT_PLUGIN_VERSION 6

namespace Kontact
{

class Core;
class Summary;

/**
  Base class for all Plugins in Kontact. Inherit from it
  to get a plugin. It can insert an icon into the sidepane,
  add widgets to the widgetstack and add menu items via XMLGUI.
 */
class KDE_EXPORT Plugin : public TQObject, virtual public KXMLGUIClient
{
  TQ_OBJECT

  public:
    /**
      Creates a new Plugin, note that name parameter name is required if
      you want your plugin to do dcop via it's own instance of
      DCOPClient by calling dcopClient.
      @note name MUST be the name of the application that
      provides the part! This is the name used for DCOP registration.
      It's ok to have several plugins using the same application name.
    */
    Plugin( Core *core, TQObject *parent, const char *name );

    virtual ~Plugin();

    /**
      Sets the identifier.
    */
    void setIdentifier( const TQString &identifier );

    /**
      Returns the identifier. It is used as argument for several
      methods of Kontacts core.
    */
    TQString identifier() const;

    /**
      Sets the localized title.
     */
    void setTitle( const TQString &title );

    /**
      Returns the localized title.
    */
    TQString title() const;

    /**
      Sets the icon name.
    */
    void setIcon( const TQString &icon );

    /**
      Returns the icon name.
    */
    TQString icon() const;

    /**
      Sets the name of executable (if existant).
    */
    void setExecutableName( const TQString &bin );

    /**
      Returns the name of the binary (if existant).
    */
    TQString executableName() const;

    /**
      Set name of library which contains the KPart used by this plugin.
    */
    void setPartLibraryName( const TQCString & );

    /**
      Create the DCOP interface for the given @p serviceType, if this
      plugin provides it. Return false otherwise.
    */
    virtual bool createDCOPInterface( const TQString& /*serviceType*/ ) { return false; }

    /**
      Reimplement this method and return whether a standalone application is still running
      This is only required if your part is also available as standalone application.
    */
    virtual bool isRunningStandalone() { return false; }

    /**
      Reimplement this method if your application needs a different approach to be brought
      in the foreground. The default behaviour is calling the binary.
      This is only required if your part is also available as standalone application.
    */
    virtual void bringToForeground();

    /**
      Reimplement this method if you want to add your credits to the Kontact
      about dialog.
    */
    virtual const TDEAboutData *aboutData();

    /**
      You can use this method if you need to access the current part. You can be
      sure that you always get the same pointer as long as the part has not been
      deleted.
    */
    KParts::ReadOnlyPart *part();

     /**
       Reimplement this method and return the a path relative to "data" to the tips file.
     */
    virtual TQString tipFile() const;

    /**
      This function is called when the plugin is selected by the user before the
      widget of the KPart belonging to the plugin is raised.
    */
    virtual void select();

    /**
      This function is called whenever the config dialog has been closed
      successfully.
     */
    virtual void configUpdated();

    /**
      Reimplement this method if you want to add a widget for your application
      to Kontact's summary page.
    */
    virtual Summary *createSummaryWidget( TQWidget * /*parent*/ ) { return 0; }

    /**
      Returns whether the plugin provides a part that should be shown in the sidebar.
    */
    virtual bool showInSideBar() const;

    /**
      Set if the plugin provides a part that should be shown in the sidebar.
    */
    void setShowInSideBar( bool hasPart );

    /**
      Reimplement this method if you want to add checks before closing down the main kontact
      window.  Return true if it's OK to close the window.  If any loaded plugin returns false
      from this method, then the main kontact window will not close.
    */
    virtual bool queryClose() const { return true; }

    /**
      Retrieve the current DCOP Client for the plugin.

      The clients name is taken from the name argument in the constructor.
      @note: The DCOPClient object will only be created when this method is
      called for the first time. Make sure that the part has been loaded
      before calling this method, if it's the one that contains the DCOP
      interface that other parts might use.
    */
    DCOPClient *dcopClient() const;

    /**
      Return the weight of the plugin. The higher the weight the lower it will
      be displayed in the sidebar. The default implementation returns 0.
    */
    virtual int weight() const { return 0; }

    /**
      Insert "New" action.
    */
    void insertNewAction( TDEAction *action );

    /**
      Insert "Sync" action.
    */
    void insertSyncAction( TDEAction *action );

    /**
      FIXME: write API doc for Kontact::Plugin::newActions().
    */
    TQPtrList<TDEAction>* newActions() const;

    /**
      FIXME: write API doc for Kontact::Plugin::syncActions().
    */
    TQPtrList<TDEAction>* syncActions() const;

    /**
      Returns a list of action name which shall be hidden in the main toolbar.
     */
    virtual TQStringList invisibleToolbarActions() const { return TQStringList(); }

    /**
      Return, if the plugin can handle the drag object of the given mime type.
    */
    virtual bool canDecodeDrag( TQMimeSource * ) { return false; }

    /**
      Process drop event.
    */
    virtual void processDropEvent( TQDropEvent * ) {}

    virtual void loadProfile( const TQString& directoryPath );

    virtual void saveToProfile( const TQString& directoryPath ) const;

    /**
     * Session management: read properties
     */
    virtual void readProperties( TDEConfig * ) {}

    /**
     * Session management: save properties
     */
    virtual void saveProperties( TDEConfig * ) {}

    Core *core() const;

    bool disabled() const;
    void setDisabled( bool v );

  public slots:
    /**
      internal usage
     */
    void slotConfigUpdated();

  protected:
    /**
      Reimplement and return the part here. Reimplementing createPart() is
      mandatory!
    */
    virtual KParts::ReadOnlyPart *createPart() = 0;

    KParts::ReadOnlyPart *loadPart();

    virtual void virtual_hook(  int id, void* data );

  private slots:
    void partDestroyed();

  private:
    class Private;
    Private *d;
};

}

#endif