1 | /* |
2 | This file is part of the kcal library. |
3 | |
4 | Copyright (c) 1998 Preston Brown <pbrown@kde.org> |
5 | Copyright (c) 2001,2003 Cornelius Schumacher <schumacher@kde.org> |
6 | Copyright (c) 2002 Jan-Pascal van Best <janpascal@vanbest.org> |
7 | Copyright (C) 2003-2004 Reinhold Kainhofer <reinhold@kainhofer.com> |
8 | |
9 | This library is free software; you can redistribute it and/or |
10 | modify it under the terms of the GNU Library General Public |
11 | License as published by the Free Software Foundation; either |
12 | version 2 of the License, or (at your option) any later version. |
13 | |
14 | This library is distributed in the hope that it will be useful, |
15 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
17 | Library General Public License for more details. |
18 | |
19 | You should have received a copy of the GNU Library General Public License |
20 | along with this library; see the file COPYING.LIB. If not, write to |
21 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
22 | Boston, MA 02110-1301, USA. |
23 | */ |
24 | |
25 | #ifndef KCAL_RESOURCECALENDAR_H |
26 | #define KCAL_RESOURCECALENDAR_H |
27 | |
28 | #include "alarm.h" |
29 | #include "todo.h" |
30 | #include "event.h" |
31 | #include "journal.h" |
32 | #include "calendar.h" |
33 | #include "exceptions.h" |
34 | |
35 | #include "kresources/resource.h" |
36 | #include "kresources/manager.h" |
37 | #include "kabc/lock.h" |
38 | |
39 | #include <kdatetime.h> |
40 | #include <kconfig.h> |
41 | |
42 | #include <QtCore/QString> |
43 | |
44 | namespace KCal { |
45 | |
46 | /** |
47 | This class provides the interfaces for a calendar resource. It makes use of |
48 | the kresources framework. |
49 | */ |
50 | class KCAL_DEPRECATED_EXPORT ResourceCalendar : public KRES::Resource |
51 | { |
52 | Q_OBJECT |
53 | public: |
54 | ResourceCalendar(); |
55 | explicit ResourceCalendar( const KConfigGroup &group ); |
56 | virtual ~ResourceCalendar(); |
57 | |
58 | bool isResolveConflictSet() const; |
59 | void setResolveConflict( bool b ); |
60 | |
61 | virtual void writeConfig( KConfigGroup &group ); |
62 | |
63 | /** |
64 | Return rich text with info about the resource. Adds standard info and |
65 | then calls addInfoText() to add info about concrete resources. |
66 | */ |
67 | virtual QString infoText() const; |
68 | |
69 | /** |
70 | Load resource data. After calling this function all data is accessible by |
71 | calling the incidence/event/todo/etc. accessor functions. |
72 | |
73 | Whether data is actually loaded within this function or the loading is |
74 | delayed until it is accessed by another function depends on the |
75 | implementation of the resource. |
76 | |
77 | If loading the data takes significant time, the resource should return |
78 | cached values if available, and return the results via the resourceChanged |
79 | signal. When the resource has finished loading, the resourceLoaded() |
80 | signal is emitted. |
81 | |
82 | Calling this function multiple times should have the same effect as |
83 | calling it once, given that the data isn't changed between calls. |
84 | |
85 | This function calls doLoad() which has to be reimplented by the resource |
86 | to do the actual loading. |
87 | */ |
88 | virtual bool load(); |
89 | |
90 | /** |
91 | Save resource data. After calling this function it is safe to close the |
92 | resource without losing data. |
93 | |
94 | Whether data is actually saved within this function or saving is delayed |
95 | depends on the implementation of the resource. |
96 | |
97 | If saving the data takes significant time, the resource should return from |
98 | the function, do the saving in the background and notify the end of the |
99 | save by emitting the signal resourceSaved(). |
100 | |
101 | This function calls doSave() which has to be reimplented by the resource |
102 | to do the actual saving. |
103 | |
104 | @param incidence if given as 0, doSave() is called to save all incidences, |
105 | else doSave(incidence) is called to save only the given one. |
106 | */ |
107 | bool save( Incidence *incidence = 0 ); |
108 | |
109 | /** |
110 | Save resource data and deliver error message. |
111 | |
112 | This function calls save() and delivers the latest error msg. |
113 | |
114 | @param err reference QString to hand over the error msg to the caller. |
115 | @param incidence if given as 0, doSave() is called to save all incidences, |
116 | else doSave(incidence) is called to save only the given one. |
117 | */ |
118 | bool save( QString &err, Incidence *incidence = 0 ); |
119 | |
120 | /** |
121 | Return true if a save operation is still in progress, otherwise return |
122 | false. |
123 | */ |
124 | virtual bool isSaving(); |
125 | |
126 | /** |
127 | Inhibit or allow saves, overriding the save policy set by setSavePolicy(). |
128 | Inhibiting saves has the same effect as making all resources read-only, |
129 | except that the inhibit status is not stored in the resource configuration. |
130 | |
131 | @param inhibit true to inhibit saves, false to allow them |
132 | */ |
133 | void setInhibitSave( bool inhibit ); |
134 | |
135 | /** |
136 | Return whether saves have been inhibited by setInhibitSave(). |
137 | */ |
138 | bool saveInhibited() const; |
139 | |
140 | /** |
141 | Return object for locking the resource. |
142 | */ |
143 | virtual KABC::Lock *lock() = 0; |
144 | |
145 | /** |
146 | Add incidence to resource. |
147 | */ |
148 | virtual bool addIncidence( Incidence * ); |
149 | |
150 | /** |
151 | Delete incidence from resource. |
152 | */ |
153 | virtual bool deleteIncidence( Incidence * ); |
154 | |
155 | /** |
156 | Return incidence with given unique id. If there is no incidence with that |
157 | uid, return 0. |
158 | |
159 | @param uid the identifier of the Incidence to look for |
160 | */ |
161 | Incidence *incidence( const QString &uid ); |
162 | |
163 | /** |
164 | Add event to resource. |
165 | */ |
166 | virtual bool addEvent( Event *event ) = 0; |
167 | |
168 | /** |
169 | Delete event from this resource. |
170 | */ |
171 | virtual bool deleteEvent( Event * ) = 0; |
172 | |
173 | /** |
174 | Removes all Events from the calendar. |
175 | */ |
176 | virtual void deleteAllEvents() = 0; |
177 | |
178 | /** |
179 | Retrieves an event on the basis of the unique string ID. |
180 | */ |
181 | virtual Event *event( const QString &uid ) = 0; |
182 | |
183 | /** |
184 | Return unfiltered list of all events in calendar. Use with care, |
185 | this can be a bad idea for server-based calendars. |
186 | |
187 | @param sortField field used as the sort key for the result list |
188 | @param sortDirection direction of sorting according to @p sortField |
189 | */ |
190 | virtual Event::List rawEvents( |
191 | EventSortField sortField = EventSortUnsorted, |
192 | SortDirection sortDirection = SortDirectionAscending ) = 0; |
193 | |
194 | /** |
195 | Builds and then returns a list of all events that match the |
196 | date specified. Useful for dayView, etc. etc. |
197 | |
198 | @param date date for which to get the events |
199 | @param timeSpec the time specification of the date |
200 | @param sortField field used as the sort key for the result list |
201 | @param sortDirection direction of sorting according to @p sortField |
202 | */ |
203 | virtual Event::List rawEventsForDate( |
204 | const QDate &date, |
205 | const KDateTime::Spec &timeSpec = KDateTime::Spec(), |
206 | EventSortField sortField = EventSortUnsorted, |
207 | SortDirection sortDirection = SortDirectionAscending ) = 0; |
208 | |
209 | /** |
210 | Get unfiltered events for date \a dt. |
211 | */ |
212 | virtual Event::List rawEventsForDate( const KDateTime &dt ) = 0; |
213 | |
214 | /** |
215 | Get unfiltered events in a range of dates. If inclusive is set to true, |
216 | only events which are completely included in the range are returned. |
217 | |
218 | @param start date at the begin of the searching range |
219 | @param end date at the end of the searching range |
220 | @param timeSpec timeSpec of the searching range |
221 | @param inclusive if @c true, only match events which are completely within |
222 | the specified range |
223 | */ |
224 | virtual Event::List rawEvents( |
225 | const QDate &start, const QDate &end, |
226 | const KDateTime::Spec &timeSpec = KDateTime::Spec(), |
227 | bool inclusive = false ) = 0; |
228 | |
229 | /** |
230 | Sets a particular value of the resource's configuration. The possible |
231 | keys are resource specific. |
232 | |
233 | This method is provided to make it possible |
234 | to set resource-type specific settings without actually linking to |
235 | the resource's library. Its use is discouraged, but in |
236 | some situations the only possibility to avoid unwanted compiling and |
237 | linking dependencies. E.g. if you don't want to link to the remote |
238 | resource, but need to create a remote resource at the URL given in |
239 | yourURL, you can use code like the following: |
240 | KCal::ResourceCalendar *res = manager->createResource( "remote" ); |
241 | if ( res ) { |
242 | res->setTimeZoneId( timezone ); |
243 | res->setResourceName( i18n("Test resource") ); |
244 | res->setValue( "DownloadURL", yourURL ); |
245 | manager->add( res ); |
246 | } |
247 | |
248 | @param key the key of the resource configuration option |
249 | @param value the value to set for the given option |
250 | */ |
251 | virtual bool setValue( const QString &key, const QString &value ); |
252 | |
253 | Q_SIGNALS: |
254 | /** |
255 | This signal is emitted when the data in the resource has changed. The |
256 | resource has to make sure that this signal is emitted whenever any |
257 | pointers to incidences which the resource has previously given to the |
258 | calling code, become invalid. |
259 | */ |
260 | void resourceChanged( ResourceCalendar * ); |
261 | |
262 | /** |
263 | This signal is emitted when loading data into the resource has been |
264 | finished. |
265 | */ |
266 | void resourceLoaded( ResourceCalendar * ); |
267 | |
268 | /** |
269 | This signal is emitted when saving the data of the resource has been |
270 | finished. |
271 | */ |
272 | void resourceSaved( ResourceCalendar * ); |
273 | |
274 | /** |
275 | This signal is emitted when an error occurs during loading. |
276 | */ |
277 | void resourceLoadError( ResourceCalendar *, const QString &error ); |
278 | |
279 | /** |
280 | This signal is emitted when an error occurs during saving. |
281 | */ |
282 | void resourceSaveError( ResourceCalendar *, const QString &error ); |
283 | |
284 | /** |
285 | This signal is emitted when a subresource is added. |
286 | */ |
287 | void signalSubresourceAdded( ResourceCalendar *, const QString &type, |
288 | const QString &subresource, const QString &label ); |
289 | |
290 | /** |
291 | This signal is emitted when a subresource is removed. |
292 | */ |
293 | void signalSubresourceRemoved( ResourceCalendar *, const QString &, |
294 | const QString & ); |
295 | |
296 | public: |
297 | /** |
298 | Add a todo to the todolist. |
299 | */ |
300 | virtual bool addTodo( Todo *todo ) = 0; |
301 | |
302 | /** |
303 | Remove a todo from the todolist. |
304 | */ |
305 | virtual bool deleteTodo( Todo * ) = 0; |
306 | |
307 | /** |
308 | Removes all To-dos from the calendar. |
309 | */ |
310 | virtual void deleteAllTodos() = 0; |
311 | |
312 | /** |
313 | Searches todolist for an event with this unique id. |
314 | @param uid the identifier of the todo to look for |
315 | |
316 | @return pointer to todo or 0 if todo wasn't found |
317 | */ |
318 | virtual Todo *todo( const QString &uid ) = 0; |
319 | |
320 | /** |
321 | Return list of all todos. |
322 | */ |
323 | virtual Todo::List rawTodos( |
324 | TodoSortField sortField = TodoSortUnsorted, |
325 | SortDirection sortDirection = SortDirectionAscending ) = 0; |
326 | |
327 | /** |
328 | Returns list of todos due on the specified date. |
329 | */ |
330 | virtual Todo::List rawTodosForDate( const QDate &date ) = 0; |
331 | |
332 | /** |
333 | Add a Journal entry to the resource. |
334 | */ |
335 | virtual bool addJournal( Journal * ) = 0; |
336 | |
337 | /** |
338 | Remove a Journal entry from calendar. |
339 | */ |
340 | virtual bool deleteJournal( Journal * ) = 0; |
341 | |
342 | /** |
343 | Removes all Journals from the calendar. |
344 | */ |
345 | virtual void deleteAllJournals() = 0; |
346 | |
347 | /** |
348 | Return Journal with given unique id. |
349 | */ |
350 | virtual Journal *journal( const QString &uid ) = 0; |
351 | |
352 | /** |
353 | Return list of all journals. |
354 | */ |
355 | virtual Journal::List rawJournals( |
356 | JournalSortField sortField = JournalSortUnsorted, |
357 | SortDirection sortDirection = SortDirectionAscending ) = 0; |
358 | |
359 | /** |
360 | Returns list of journals for the given date. |
361 | */ |
362 | virtual Journal::List rawJournalsForDate( const QDate &date ) = 0; |
363 | |
364 | /** |
365 | Return all alarms which occur in the given time interval. |
366 | */ |
367 | virtual Alarm::List alarms( const KDateTime &from, |
368 | const KDateTime &to ) = 0; |
369 | |
370 | /** |
371 | Return all alarms which occur before given date. |
372 | */ |
373 | virtual Alarm::List alarmsTo( const KDateTime &to ) = 0; |
374 | |
375 | /** Returns a list of all incideces */ |
376 | Incidence::List rawIncidences(); |
377 | |
378 | /** |
379 | Sets the default and viewing time specification for the calendar. |
380 | |
381 | @param timeSpec is the time specification (time zone, etc.) for |
382 | viewing Incidence dates.\n |
383 | */ |
384 | virtual void setTimeSpec( const KDateTime::Spec &timeSpec ) = 0; |
385 | |
386 | /** |
387 | Get the viewing time specification (time zone etc.) for the calendar. |
388 | |
389 | @return time specification |
390 | */ |
391 | virtual KDateTime::Spec timeSpec() const = 0; |
392 | |
393 | /** |
394 | Sets the time zone ID for the Calendar. |
395 | |
396 | @param timeZoneId is a string containing a time zone ID, which is |
397 | assumed to be valid. The time zone ID is used to set the time zone |
398 | for viewing Incidence date/times. If no time zone is found, the |
399 | viewing time specification is set to local clock time. |
400 | @e Example: "Europe/Berlin" |
401 | */ |
402 | virtual void setTimeZoneId( const QString &timeZoneId ) = 0; |
403 | |
404 | /** |
405 | Returns the time zone ID used for creating or modifying incidences in |
406 | the calendar. |
407 | |
408 | @return the string containing the time zone ID, or empty string if the |
409 | creation/modification time specification is not a time zone. |
410 | */ |
411 | virtual QString timeZoneId() const = 0; |
412 | |
413 | /** |
414 | Shifts the times of all incidences so that they appear at the same clock |
415 | time as before but in a new time zone. The shift is done from a viewing |
416 | time zone rather than from the actual incidence time zone. |
417 | |
418 | For example, shifting an incidence whose start time is 09:00 America/New York, |
419 | using an old viewing time zone (@p oldSpec) of Europe/London, to a new time |
420 | zone (@p newSpec) of Europe/Paris, will result in the time being shifted |
421 | from 14:00 (which is the London time of the incidence start) to 14:00 Paris |
422 | time. |
423 | |
424 | @param oldSpec the time specification which provides the clock times |
425 | @param newSpec the new time specification |
426 | */ |
427 | virtual void shiftTimes( const KDateTime::Spec &oldSpec, |
428 | const KDateTime::Spec &newSpec ) = 0; |
429 | |
430 | /** |
431 | If this resource has subresources, return a QStringList of them. |
432 | In most cases, resources do not have subresources, so this is |
433 | by default just empty. |
434 | */ |
435 | virtual QStringList subresources() const; |
436 | |
437 | /** |
438 | * Is this resource capable of having subresources or not? |
439 | */ |
440 | virtual bool canHaveSubresources() const; |
441 | |
442 | /** |
443 | Is this subresource active or not? |
444 | */ |
445 | virtual bool subresourceActive( const QString &resource ) const; |
446 | |
447 | /** |
448 | What is the label for this subresource? |
449 | */ |
450 | virtual QString labelForSubresource( const QString &resource ) const; |
451 | |
452 | /** |
453 | Get the identifier of the subresource associated with a specified |
454 | incidence. |
455 | |
456 | @param incidence the incidence to get the identifier for |
457 | |
458 | @return the identifier of the subresource or an empty string. |
459 | */ |
460 | virtual QString subresourceIdentifier( Incidence *incidence ); |
461 | |
462 | public Q_SLOTS: |
463 | /** |
464 | (De-)activate a subresource. |
465 | */ |
466 | virtual void setSubresourceActive( const QString &resource, bool active ); |
467 | |
468 | /** |
469 | * Remove a subresource with the id @param resource |
470 | */ |
471 | virtual bool removeSubresource( const QString &resource ); |
472 | |
473 | /** |
474 | Add a subresource with the id @param resource and the parent id |
475 | @param parent |
476 | */ |
477 | virtual bool addSubresource( const QString &resource, const QString &parent ); |
478 | |
479 | /** |
480 | Returns the type of the subresource: "event", "todo", or "journal", |
481 | QString if unknown/mixed. |
482 | */ |
483 | virtual QString subresourceType( const QString &resource ); |
484 | |
485 | protected: |
486 | /** |
487 | Do the actual loading of the resource data. Called by load(). |
488 | */ |
489 | virtual bool doLoad( bool syncCache ) = 0; |
490 | |
491 | /** |
492 | Do the actual saving of the resource data. Called by save(). |
493 | */ |
494 | virtual bool doSave( bool syncCache ) = 0; |
495 | |
496 | /** |
497 | Do the actual saving of the resource data. Called by save(). |
498 | Save one Incidence. The default implementation calls doSave() |
499 | to save everything. |
500 | */ |
501 | virtual bool doSave( bool syncCache, Incidence * ); |
502 | |
503 | /** |
504 | Add info text for concrete resources. Called by infoText(). |
505 | */ |
506 | virtual void addInfoText( QString & ) const {} |
507 | |
508 | /** |
509 | A resource should call this function if a load error happens. |
510 | */ |
511 | void loadError( const QString &errorMessage = QString() ); |
512 | |
513 | /** |
514 | A resource should call this function if a save error happens. |
515 | */ |
516 | void saveError( const QString &errorMessage = QString() ); |
517 | |
518 | bool receivedLoadError() const; |
519 | void setReceivedLoadError( bool b ); |
520 | bool receivedSaveError() const; |
521 | void setReceivedSaveError( bool b ); |
522 | |
523 | /** |
524 | Specify whether individual incidences should be set read-only when a |
525 | read-only resource is loaded. |
526 | @param noReadOnly true to inhibit setting incidences read-only, |
527 | false to allow incidences to be set read-only |
528 | */ |
529 | void setNoReadOnlyOnLoad( bool noReadOnly ); |
530 | |
531 | /** |
532 | Return whether individual incidences are inhibited from being set |
533 | read-only when a read-only resources is loaded. |
534 | */ |
535 | bool noReadOnlyOnLoad() const; |
536 | |
537 | using QObject::event; // prevent warning about hidden virtual method |
538 | |
539 | private: |
540 | //@cond PRIVATE |
541 | Q_DISABLE_COPY( ResourceCalendar ) |
542 | |
543 | class Private; |
544 | Private *const d; |
545 | //@endcond |
546 | }; |
547 | |
548 | /** Type representing the manager of a ResourceCalendar. */ |
549 | typedef KRES::Manager<ResourceCalendar> CalendarResourceManager; |
550 | |
551 | } |
552 | |
553 | #endif |
554 | |