summaryrefslogtreecommitdiffstats
path: root/kded/kdedmodule.h
blob: 855a02824ae930083705e82e3c09b03f49f18664 (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
/*
   This file is part of the KDE libraries

   Copyright (c) 2001 Waldo Bastian <bastian@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 __KDEDMODULE_H__
#define __KDEDMODULE_H__

#include <tqobject.h>
#include <dcopobject.h>
#include <ksharedptr.h>

class KDEDModulePrivate;
class Kded;

/**
 * The base class for KDED modules.
 *
 * In KDE 2 and KDE 3, KDED modules are realized as shared
 * libraries that are loaded on-demand into kded at runtime.
 *
 * To write a config module, you have to create a library
 * that contains at least one factory function like this:
 *
 * \code
 *   extern "C" {
 *     KDE_EXPORT KDEDModule *create_xyz(TQCString *name)
 *     {
 *       return new XYZ(name);
 *     }
 *   }
 * \endcode
 *
 * See tdelibs/kded/HOWTO for more detailed documentation.
 *
 * @author Waldo Bastian <bastian@kde.org>
 */

class KDE_EXPORT KDEDModule : public TQObject, public DCOPObject
{
  Q_OBJECT
// For inclusion in KDE4 (since it's BIC) long-needed fix for allowing
// DCOP-based kdedmodules -- Gav <gav@kde.org>.
//  K_DCOP
  friend class Kded;
public:
  
  /**
   * Create a DCOPObject named @p name
   */
  KDEDModule(const TQCString &name);
  
  virtual ~KDEDModule();
  
  /**
   * Specifies the idle timeout in seconds. The default is 0. 
   *
   * This will call the idle slot @p secs seconds after the last 
   * reference was removed.
   */
  void setIdleTimeout(int secs);

  /**
   * Reset the idle timeout counter. 
   *
   * (re)starts the timeout counter if no objects are being referenced.
   */
  void resetIdle();

  /**
   * Insert @p obj indexed with @p app and @p key. The
   * object will be automatically deleted when the application
   * @p app unregisters with DCOP.
   *
   * Any previous object inserted with the same values for @p app 
   * and @p key will be removed.
   */
  void insert(const TQCString &app, const TQCString &key, KShared *obj);

  /**
   * Lookup object indexed with @p app and @p key
   */
  KShared *find(const TQCString &app, const TQCString &key);
  
  /**
   * remove object indexed with @p app and @p key.
   * The object will be deleted when it is no more referenced.
   */
  void remove(const TQCString &app, const TQCString &key);

  /**
   * remove all objects indexed with @p app. 
   * The objects will be deleted when they are no more referenced.
   */
  void removeAll(const TQCString &app);

  /**
   * Returns whether a certain mainwindow has registered itself with KDED
   */
  bool isWindowRegistered(long windowId);
  
public slots:
  /**
   * Called whenever the last referenced object gets dereferenced.
   *
   * See also setIdleTimeout()
   *
   * You may delete the module from this slot.
   */
  virtual void idle() { };

signals:
  /**
   * Emitted when the module is being deleted.
   */
  void moduleDeleted(KDEDModule *);

  /**
   * Emitted when a mainwindow registers itself.
   */
  void windowRegistered(long windowId);

  /**
   * Emitted when a mainwindow unregisters itself.
   */
  void windowUnregistered(long windowId);

private:
  KDEDModulePrivate *d;
};

#endif