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
44namespace KCal {
45
46/**
47 This class provides the interfaces for a calendar resource. It makes use of
48 the kresources framework.
49*/
50class 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. */
549typedef KRES::Manager<ResourceCalendar> CalendarResourceManager;
550
551}
552
553#endif
554