1 | /* |
2 | This file is part of libkresources |
3 | |
4 | Copyright (c) 2001-2003 Cornelius Schumacher <schumacher@kde.org> |
5 | Copyright (c) 2002 Jan-Pascal van Best <janpascal@vanbest.org> |
6 | |
7 | This library is free software; you can redistribute it and/or |
8 | modify it under the terms of the GNU Library General Public |
9 | License as published by the Free Software Foundation; either |
10 | version 2 of the License, or (at your option) any later version. |
11 | |
12 | This library is distributed in the hope that it will be useful, |
13 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
14 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
15 | Library General Public License for more details. |
16 | |
17 | You should have received a copy of the GNU Library General Public License |
18 | along with this library; see the file COPYING.LIB. If not, write to |
19 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
20 | Boston, MA 02110-1301, USA. |
21 | */ |
22 | #ifndef KRESOURCES_RESOURCE_H |
23 | #define KRESOURCES_RESOURCE_H |
24 | |
25 | #include "kresources_export.h" |
26 | |
27 | #include <kpluginfactory.h> |
28 | |
29 | #include <QtCore/QMutex> |
30 | #include <QWidget> |
31 | |
32 | class KConfig; |
33 | class KConfigGroup; |
34 | |
35 | namespace KRES { |
36 | |
37 | class ConfigWidget; |
38 | |
39 | /** |
40 | This class provides a resource which is managed in a general way. |
41 | |
42 | A Resource represents the concept of an object with the following attributes: |
43 | |
44 | - Applications operate on sets of one or more Resource objects. |
45 | - Creation and deletetion of Resource objects is done in a general way, |
46 | independent of concrete functionality of the Resource. |
47 | - The end user has control over creation, deletion and configuration of |
48 | Resource object. |
49 | - Properties, behaviour and configuration of different Resource objects can |
50 | widely differ. |
51 | - Resources can be active or inactive. |
52 | - There is one special Resource which is the standard Resource. This can for |
53 | example be used as default destination for newly created object managed |
54 | by a certain Resource family. |
55 | - Activation of Resources can be covered by a two step process of being opened |
56 | and then loaded. Deactivation corresponds to saving and closing. |
57 | - Different application ususally share the same set of Resources. |
58 | |
59 | The Resource base class provides the management functionality. Classes |
60 | inheriting from Resource automatically appear in the general kresources |
61 | kcontrol module. |
62 | |
63 | Concrete functionality of Resources is specified per family by a subclass of |
64 | Resource. This classes in turn have subclasses which implement the different |
65 | flavors of the functionality represented by the family. |
66 | |
67 | A subclass should reimplement at least the constructor and the |
68 | writeConfig method. |
69 | |
70 | An example for a Resource subclass hierarchy would be the "calendar" family. |
71 | The ResourceCalendar subclass would specify an API for accessing calendar |
72 | data. Subclasses of ResourceCalendar would implement this API for local files, |
73 | remote files, specific calendar servers etc. |
74 | */ |
75 | class KRESOURCES_DEPRECATED_EXPORT Resource : public QObject |
76 | { |
77 | friend class Factory; |
78 | friend class ManagerImpl; |
79 | |
80 | Q_OBJECT |
81 | public: |
82 | typedef QList<Resource *> List; |
83 | |
84 | /** |
85 | * Constructor. Construct resource with default settings. |
86 | */ |
87 | Resource(); |
88 | |
89 | /** |
90 | * Constructor. Construct resource from configuration group. |
91 | * @param group Configuration group to read persistence information from |
92 | */ |
93 | explicit Resource( const KConfigGroup &group ); |
94 | |
95 | /** |
96 | * Destructor. |
97 | */ |
98 | virtual ~Resource(); |
99 | |
100 | /** |
101 | * Write configuration information for this resource to a configuration |
102 | * file. If you override this method, remember to call Resource::writeConfig |
103 | * or Terrible Things(TM) will happen. |
104 | * @param group Configuration group to write persistence information to. |
105 | */ |
106 | virtual void writeConfig( KConfigGroup &group ); |
107 | |
108 | /** |
109 | * Open this resource, if it not already open. Increase the open |
110 | * count of this object, and open the resource by calling doOpen(). |
111 | * This method may block while another thread is concurrently opening |
112 | * or closing the resource. |
113 | * |
114 | * Returns true if the resource was already opened or if it was opened |
115 | * successfully; returns false if the resource was not opened successfully. |
116 | */ |
117 | bool open(); |
118 | |
119 | /** |
120 | * Decrease the open count of this object, and if the count reaches |
121 | * zero, close this resource by calling doClose(). |
122 | * This method may block while another thread is concurrently closing |
123 | * or opening the resource. |
124 | */ |
125 | void close(); |
126 | |
127 | /** |
128 | * Returns whether the resource is open or not. |
129 | */ |
130 | bool isOpen() const; |
131 | |
132 | /** |
133 | Sets the resource unique identifier. |
134 | */ |
135 | void setIdentifier( const QString &identifier ); |
136 | |
137 | /** |
138 | * Returns a unique identifier. The identifier is unique for this resource. |
139 | * It is created when the resource is first created, and it is retained |
140 | * in the resource family configuration file for this resource. |
141 | * @return This resource's identifier |
142 | */ |
143 | QString identifier() const; |
144 | |
145 | /** |
146 | Sets the resource type. |
147 | */ |
148 | void setType( const QString &type ); |
149 | |
150 | /** |
151 | * Returns the type of this resource. |
152 | */ |
153 | QString type() const; |
154 | |
155 | /** |
156 | * Mark the resource as read-only. You can override this method, |
157 | * but also remember to call Resource::setReadOnly(). |
158 | */ |
159 | virtual void setReadOnly( bool value ); |
160 | |
161 | /** |
162 | * Returns, if the resource is read-only. |
163 | */ |
164 | virtual bool readOnly() const; |
165 | |
166 | /** |
167 | * Set the name of resource. You can override this method, |
168 | * but also remember to call Resource::setResourceName(). |
169 | */ |
170 | virtual void setResourceName( const QString &name ); |
171 | |
172 | /** |
173 | * Returns the name of resource. |
174 | */ |
175 | virtual QString resourceName() const; |
176 | |
177 | /** |
178 | Sets, if the resource is active. |
179 | */ |
180 | void setActive( bool active ); |
181 | |
182 | /** |
183 | Return true, if the resource is active. |
184 | */ |
185 | bool isActive() const; |
186 | |
187 | /** |
188 | Print resource information as debug output. |
189 | */ |
190 | virtual void dump() const; |
191 | |
192 | protected: |
193 | /** |
194 | * Open this resource. When called, the resource must be in |
195 | * a closed state. |
196 | * |
197 | * Returns true if the resource was opened successfully; |
198 | * returns false if the resource was not opened successfully. |
199 | * |
200 | * The result of this call can be accessed later by isOpen() |
201 | */ |
202 | virtual bool doOpen(); |
203 | |
204 | /** |
205 | * Close this resource. Pre-condition: resource is open. |
206 | * Post-condition: resource is closed. |
207 | */ |
208 | virtual void doClose(); |
209 | |
210 | private: |
211 | class ResourcePrivate; |
212 | ResourcePrivate *const d; |
213 | }; |
214 | |
215 | class KRESOURCES_DEPRECATED_EXPORT PluginFactoryBase : public KPluginFactory |
216 | { |
217 | public: |
218 | explicit PluginFactoryBase( const char *componentName=0, |
219 | const char *catalogName=0, QObject *parent=0 ) |
220 | : KPluginFactory( componentName, catalogName, parent ) {} |
221 | explicit PluginFactoryBase( const KAboutData &aboutData, QObject *parent = 0 ) |
222 | : KPluginFactory( aboutData, parent ) {} |
223 | |
224 | virtual Resource *resource( const KConfigGroup &group ) = 0; |
225 | virtual Resource *resource() = 0; |
226 | |
227 | virtual ConfigWidget *configWidget( QWidget *parent ) = 0; |
228 | |
229 | protected: |
230 | virtual QObject *createObject( QObject *parent, const char *className, |
231 | const QStringList &args ); |
232 | }; |
233 | |
234 | template<class TR,class TC> |
235 | class PluginFactory : public PluginFactoryBase |
236 | { |
237 | public: |
238 | explicit PluginFactory( const char *componentName=0, |
239 | const char *catalogName=0, QObject *parent=0 ) |
240 | : PluginFactoryBase( componentName, catalogName, parent ) {} |
241 | explicit PluginFactory( const KAboutData &aboutData, QObject *parent = 0 ) |
242 | : PluginFactoryBase( aboutData, parent ) {} |
243 | |
244 | virtual Resource *resource( const KConfigGroup &group ) |
245 | { |
246 | return new TR( group ); |
247 | } |
248 | virtual Resource *resource() |
249 | { |
250 | return new TR(); |
251 | } |
252 | |
253 | ConfigWidget *configWidget( QWidget *parent ) |
254 | { |
255 | return new TC( parent ); |
256 | } |
257 | }; |
258 | |
259 | } |
260 | |
261 | #endif |
262 | |