1/*
2 This file is part of the kcal library.
3
4 Copyright (c) 2003 Cornelius Schumacher <schumacher@kde.org>
5 Copyright (C) 2003-2004 Reinhold Kainhofer <reinhold@kainhofer.com>
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/**
23 @file
24 This file is part of the API for handling calendar data and
25 defines the CalendarResources class.
26
27 @author Cornelius Schumacher \<schumacher@kde.org\>
28 @author Reinhold Kainhofer \<reinhold@kainhofer.com\>
29*/
30
31#ifndef KCAL_CALENDARRESOURCES_H
32#define KCAL_CALENDARRESOURCES_H
33
34#include <QtCore/QMap>
35
36#include "calendar.h"
37#include "exceptions.h"
38#include "resourcecalendar.h"
39
40#include "kcal_export.h"
41
42class QWidget;
43
44namespace KCal {
45
46/**
47 @brief
48 This class provides a Calendar which is composed of other Calendars
49 known as "Resources".
50
51 Examples of Calendar Resources are:
52 - Calendars stored as local ICS formatted files
53 - a set of incidences (one-per-file) within a local directory
54 - birthdays and anniversaries contained in an addressbook
55
56*/
57class KCAL_DEPRECATED_EXPORT CalendarResources
58 : public Calendar, public KRES::ManagerObserver<ResourceCalendar>
59{
60 Q_OBJECT
61 public:
62 /**
63 @class DestinationPolicy
64 */
65 class DestinationPolicy
66 {
67 public:
68 /**
69 Constructs a destination policy.
70 @param manager is a pointer to the CalendarResourceManager.
71 @param parent is a pointer to a QWidget to use for new dialogs.
72 */
73 explicit DestinationPolicy( CalendarResourceManager *manager, QWidget *parent = 0 );
74
75 /**
76 Destructor.
77 */
78 virtual ~DestinationPolicy();
79
80 /**
81 Returns parent widget to use for new dialogs.
82 */
83 virtual QWidget *parent();
84
85 /**
86 Sets the parent widget for new dialogs.
87 @param parent is a pointer to a QWidget containing the parent.
88 */
89 virtual void setParent( QWidget *parent );
90
91 /**
92 Returns the destination ResourceCalendar for the specified incidence.
93 @param incidence is a pointer to a valid Incidence object.
94 */
95 virtual ResourceCalendar *destination( Incidence *incidence ) = 0;
96
97 /**
98 Return true if we have resources configure. Otherwise returns false.
99 @since 4.3
100 */
101 bool hasCalendarResources();
102 protected:
103 /**
104 Returns the CalendarResourceManager used by this calendar.
105 */
106 CalendarResourceManager *resourceManager();
107
108 private:
109 //@cond PRIVATE
110 Q_DISABLE_COPY( DestinationPolicy )
111 class Private;
112 Private *d;
113 //@endcond
114 };
115
116 /**
117 @class StandardDestinationPolicy
118 */
119 class StandardDestinationPolicy : public DestinationPolicy
120 {
121 public:
122 /**
123 Constructs a standard destination policy.
124 @param manager is a pointer to the CalendarResourceManager.
125 @param parent is a pointer to a QWidget to use for new dialogs.
126 */
127 explicit StandardDestinationPolicy( CalendarResourceManager *manager, QWidget *parent = 0 );
128
129 /**
130 Destructor.
131 */
132 virtual ~StandardDestinationPolicy();
133
134 /**
135 Returns the destination ResourceCalendar for the specified incidence.
136 @param incidence is a pointer to a valid Incidence object.
137 */
138 ResourceCalendar *destination( Incidence *incidence );
139
140 private:
141 //@cond PRIVATE
142 Q_DISABLE_COPY( StandardDestinationPolicy )
143 class Private;
144 Private *d;
145 //@endcond
146 };
147
148 /**
149 @class AskDestinationPolicy
150 */
151 class AskDestinationPolicy : public DestinationPolicy
152 {
153 public:
154 /**
155 Constructs an Ask destination policy.
156 @param manager is a pointer to the CalendarResourceManager.
157 @param parent is a pointer to a QWidget to use for new dialogs.
158 */
159 explicit AskDestinationPolicy( CalendarResourceManager *manager, QWidget *parent = 0 );
160
161 /**
162 Destructor.
163 */
164 virtual ~AskDestinationPolicy();
165
166 /**
167 Returns the destination ResourceCalendar for the specified incidence.
168 @param incidence is a pointer to a valid Incidence object.
169 */
170 ResourceCalendar *destination( Incidence *incidence );
171 private:
172 //@cond PRIVATE
173 Q_DISABLE_COPY( AskDestinationPolicy )
174 class Private;
175 Private *d;
176 //@endcond
177 };
178
179 /**
180 @class Ticket
181 */
182 class Ticket
183 {
184 friend class CalendarResources;
185
186 public:
187 /**
188 Returns the ResourceCalendar associated with the ticket.
189 */
190 ResourceCalendar *resource() const;
191
192 /**
193 Destructor.
194 */
195 ~Ticket();
196
197 private:
198 /**
199 Constructs a Ticket for a ResourceCalendar.
200 @param resource is a pointer to a valid ResourceCalendar object.
201 */
202 Ticket( ResourceCalendar *resource );
203
204 //@cond PRIVATE
205 Q_DISABLE_COPY( Ticket )
206 class Private;
207 Private *d;
208 //@endcond
209 };
210
211 /**
212 Construct CalendarResource object using a time specification (time
213 zone, etc.) and a Family name.
214
215 @param timeSpec is a time specification which is used for creating
216 or modifying incidences in the Calendar. It is also used for viewing
217 incidences (see setViewTimeSpec()).
218
219 @param family is any QString representing a unique name.
220 */
221 CalendarResources(
222 const KDateTime::Spec &timeSpec,
223 const QString &family = QLatin1String( "calendar" ) );
224
225 /**
226 Construct CalendarResource object using a time zone ID and a Family name.
227
228 @param timeZoneId is used for creating or modifying incidences in the
229 Calendar. It is also used for viewing incidences. The time zone does
230 not alter existing incidences.
231
232 @param family is any QString representing a unique name.
233 */
234 CalendarResources(
235 const QString &timeZoneId,
236 const QString &family = QLatin1String( "calendar" ) );
237
238 /**
239 Destroys the Calendar Resources.
240 */
241 ~CalendarResources();
242
243 /**
244 Clears the exception status.
245 @since 4.2
246 */
247 void clearException();
248
249 /**
250 Returns an exception, if there is any, containing information about the
251 last error that occurred.
252 @since 4.2
253 */
254 ErrorFormat *exception();
255
256 /**
257 Loads all Incidences from the Resources. The Resources must be added
258 first using either readConfig(KConfig *config), which adds the system
259 Resources, or manually using resourceAdded(ResourceCalendar *resource).
260 */
261 void load();
262
263 /**
264 * Reloads all Incidences from all Resources.
265 * @return true if the reload was successful; otherwise failure.
266 */
267 bool reload();
268
269 /**
270 @copydoc
271 Calendar::close()
272 */
273 void close();
274
275 /**
276 Saves this Calendar.
277 If the save is successful the Ticket is deleted. Otherwise, the
278 caller must release the Ticket with releaseSaveTicket() to abandon
279 the save operation or call save() to try the save again.
280
281 @param ticket is a pointer to the Ticket object.
282 @param incidence is a pointer to the Incidence object.
283 If incidence is null, save the entire Calendar (all Resources)
284 else only the specified Incidence is saved.
285
286 @return true if the save was successful; false otherwise.
287 */
288 virtual bool save( Ticket *ticket, Incidence *incidence = 0 );
289
290 /**
291 @copydoc
292 Calendar::save()
293 */
294 bool save();
295
296 /**
297 @copydoc
298 Calendar::isSaving()
299 */
300 bool isSaving();
301
302 /**
303 Returns the CalendarResourceManager used by this calendar.
304 */
305 CalendarResourceManager *resourceManager() const;
306
307 /**
308 Returns the Resource associated with a specified Incidence.
309
310 @param incidence is a pointer to an Incidence whose Resource
311 is to be located.
312 */
313 ResourceCalendar *resource( Incidence *incidence );
314
315 /**
316 Reads the Resources settings from a config file.
317
318 @param config The KConfig object which points to the config file.
319 If no object is given (@p config is 0) the standard config file is used.
320
321 @note Call this method <em>before</em> load().
322 */
323 void readConfig( KConfig *config = 0 );
324
325 /**
326 Set the destination policy such that Incidences are always added
327 to the standard Resource.
328 */
329 void setStandardDestinationPolicy();
330
331 /**
332 Set the destination policy such that Incidences are added to a
333 Resource which is queried.
334 */
335 void setAskDestinationPolicy();
336
337 /**
338 Return true if we have resources configure. Otherwise returns false.
339 @since 4.3
340 */
341 bool hasCalendarResources();
342
343 /**
344 Returns the current parent for new dialogs. This is a bad hack, but we
345 need to properly set the parent for the resource selection dialog.
346 Otherwise the dialog will not be modal to the editor dialog in
347 korganizer and the user can still work in the editor dialog (and thus
348 crash korganizer).
349 Afterwards we need to reset it (to avoid pointers to widgets that are
350 already deleted) so we also need the accessor
351
352 @return a pointer to the parent QWidget.
353 @see setDialogParentWidget()
354 */
355 QWidget *dialogParentWidget();
356
357 /**
358 Set the widget parent for new dialogs. This is a bad hack, but we need
359 to properly set the parent for the resource selection dialog. Otherwise
360 the dialog will not be modal to the editor dialog in korganizer and
361 the user can still work in the editor dialog (and thus crash korganizer).
362
363 @param parent is a pointer to the parent QWidget.
364 @see dialogparentWidget()
365 */
366 void setDialogParentWidget( QWidget *parent );
367
368 /**
369 Requests a ticket for saving the Calendar. If a ticket is returned the
370 Calendar is locked for write access until save() or releaseSaveTicket()
371 is called.
372
373 @param resource is a pointer to the ResourceCalendar object.
374
375 @return a pointer to a Ticket object indicating that the Calendar
376 is locked for write access; otherwise a null pointer.
377 @see releaseSaveTicket()
378 */
379 Ticket *requestSaveTicket( ResourceCalendar *resource );
380
381 /**
382 Releases the save Ticket. The Calendar is unlocked without saving.
383
384 @param ticket is a pointer to a Ticket object.
385 @see requestSaveTicket()
386 */
387 virtual void releaseSaveTicket( Ticket *ticket );
388
389 /**
390 Add an active Resource to the Calendar, and loads that resource
391 if it is open. Additionally, emits the @b signalResourceAdded signal.
392
393 @note This method must be public, because in-process added Resources
394 do not emit the corresponding signal, so this method has to be
395 called manually!
396
397 @param resource is a pointer to the ResourceCalendar to add.
398 @see signalResourceAdded()
399 */
400 void resourceAdded( ResourceCalendar *resource );
401
402 // Incidence Specific Methods //
403
404 /**
405 Inserts an Incidence into the calendar.
406 @param incidence is a pointer to the Incidence to insert.
407 @return true if the Incidence was successfully inserted; false otherwise.
408 @return Will also return false if there are multiple writable resources
409 and the user declines to select one to those resources in which to save
410 the Incidence.
411 */
412 bool addIncidence( Incidence *incidence );
413
414 /**
415 Inserts an Incidence into a Calendar Resource.
416
417 @param incidence is a pointer to the Incidence to insert.
418 @param resource is a pointer to the ResourceCalendar to be added to.
419
420 @return true if the Incidence was successfully inserted; false otherwise.
421 */
422 bool addIncidence( Incidence *incidence, ResourceCalendar *resource );
423
424 /**
425 @copydoc
426 Calendar::beginChange()
427 */
428 bool beginChange( Incidence *incidence );
429
430 /**
431 @copydoc
432 Calendar::endChange()
433 */
434 bool endChange( Incidence *incidence );
435
436 // Event Specific Methods //
437
438 /**
439 @copydoc
440 Calendar::addEvent()
441 */
442 bool addEvent( Event *event );
443
444 /**
445 Inserts an Event into a Calendar Resource.
446
447 @param event is a pointer to the Event to insert.
448 @param resource is a pointer to the ResourceCalendar to be added to.
449
450 @return true if the Event was successfully inserted; false otherwise.
451
452 @note In most cases use
453 addIncidence( Incidence *incidence, ResourceCalendar *resource ) instead.
454 */
455 bool addEvent( Event *event, ResourceCalendar *resource );
456
457 /**
458 @copydoc
459 Calendar::deleteEvent()
460 */
461 bool deleteEvent( Event *event );
462
463 /**
464 @copydoc
465 Calendar::deleteAllEvents()
466 */
467 void deleteAllEvents();
468
469 /**
470 @copydoc
471 Calendar::rawEvents(EventSortField, SortDirection)
472 */
473 Event::List rawEvents(
474 EventSortField sortField = EventSortUnsorted,
475 SortDirection sortDirection = SortDirectionAscending );
476
477 /**
478 @copydoc
479 Calendar::rawEventsForDate( const KDateTime &)
480 */
481 Event::List rawEventsForDate( const KDateTime &dt );
482
483 /**
484 @copydoc
485 Calendar::rawEvents(const QDate &, const QDate &, const KDateTime::Spec &, bool)
486 */
487 Event::List rawEvents( const QDate &start, const QDate &end,
488 const KDateTime::Spec &timeSpec = KDateTime::Spec(),
489 bool inclusive = false );
490
491 /**
492 Returns an unfiltered list of all Events which occur on the given date.
493
494 @param date request unfiltered Event list for this QDate only.
495 @param timeSpec time zone etc. to interpret @p date, or the calendar's
496 default time spec if none is specified
497 @param sortField specifies the EventSortField.
498 @param sortDirection specifies the SortDirection.
499
500 @return the list of unfiltered Events occurring on the specified QDate.
501 */
502 Event::List rawEventsForDate( const QDate &date,
503 const KDateTime::Spec &timeSpec = KDateTime::Spec(),
504 EventSortField sortField = EventSortUnsorted,
505 SortDirection sortDirection = SortDirectionAscending );
506
507 /**
508 @copydoc
509 Calendar::event()
510 */
511 Event *event( const QString &uid );
512
513 // Todo Specific Methods //
514
515 /**
516 @copydoc
517 Calendar::addTodo()
518 */
519 bool addTodo( Todo *todo );
520
521 /**
522 Inserts a Todo into a Calendar Resource.
523
524 @param todo is a pointer to the Todo to insert.
525 @param resource is a pointer to the ResourceCalendar to be added to.
526
527 @return true if the Todo was successfully inserted; false otherwise.
528
529 @note In most cases use
530 addIncidence( Incidence *incidence, ResourceCalendar *resource ) instead.
531 */
532 bool addTodo( Todo *todo, ResourceCalendar *resource );
533
534 /**
535 @copydoc
536 Calendar::deleteTodo()
537 */
538 bool deleteTodo( Todo *todo );
539
540 /**
541 @copydoc
542 Calendar::deleteAllTodos()
543 */
544 void deleteAllTodos();
545
546 /**
547 @copydoc
548 Calendar::rawTodos()
549 */
550 Todo::List rawTodos( TodoSortField sortField = TodoSortUnsorted,
551 SortDirection sortDirection = SortDirectionAscending );
552
553 /**
554 @copydoc
555 Calendar::rawTodosForDate()
556 */
557 Todo::List rawTodosForDate( const QDate &date );
558
559 /**
560 @copydoc
561 Calendar::todo()
562 */
563 Todo *todo( const QString &uid );
564
565 // Journal Specific Methods //
566
567 /**
568 @copydoc
569 Calendar::addJournal()
570 */
571 bool addJournal( Journal *journal );
572
573 /**
574 Inserts a Journal into a Calendar Resource.
575
576 @param journal is a pointer to the Journal to insert.
577 @param resource is a pointer to the ResourceCalendar to be added to.
578
579 @return true if the Journal was successfully inserted; false otherwise.
580
581 @note In most cases use
582 addIncidence( Incidence *incidence, ResourceCalendar *resource ) instead.
583 */
584 bool addJournal( Journal *journal, ResourceCalendar *resource );
585
586 /**
587 @copydoc
588 Calendar::deleteJournal()
589 */
590 bool deleteJournal( Journal *journal );
591
592 /**
593 @copydoc
594 Calendar::deleteAllJournals()
595 */
596 void deleteAllJournals();
597
598 /**
599 @copydoc
600 Calendar::rawJournals()
601 */
602 Journal::List rawJournals(
603 JournalSortField sortField = JournalSortUnsorted,
604 SortDirection sortDirection = SortDirectionAscending );
605
606 /**
607 @copydoc
608 Calendar::rawJournalsForDate()
609 */
610 Journal::List rawJournalsForDate( const QDate &date );
611
612 /**
613 @copydoc
614 Calendar::journal()
615 */
616 Journal *journal( const QString &uid );
617
618 // Alarm Specific Methods //
619
620 /**
621 @copydoc
622 Calendar::alarms()
623 */
624 Alarm::List alarms( const KDateTime &from, const KDateTime &to );
625
626 /**
627 Return a list of Alarms that occur before the specified timestamp.
628
629 @param to is the ending timestamp.
630
631 @return the list of Alarms occurring before the specified KDateTime.
632 */
633 Alarm::List alarmsTo( const KDateTime &to );
634
635 using QObject::event; // prevent warning about hidden virtual method
636
637 Q_SIGNALS:
638 /**
639 Signals that the Resource has been modified.
640
641 @param resource is a pointer to a ResourceCalendar that was changed.
642 @see resourceModified()
643 */
644 void signalResourceModified( ResourceCalendar *resource );
645
646 /**
647 Signals that an Incidence has been inserted to the Resource.
648
649 @param resource is a pointer to a ResourceCalendar that was added.
650 @see resourceAdded()
651 */
652 void signalResourceAdded( ResourceCalendar *resource );
653
654 /**
655 Signals that an Incidence has been removed from the Resource.
656
657 @param resource is a pointer to a ResourceCalendar that was removed.
658 @see resourceDeleted()
659 */
660 void signalResourceDeleted( ResourceCalendar *resource );
661
662 /**
663 Signals an error message.
664 @param err is the error message.
665 */
666 void signalErrorMessage( const QString &err );
667
668 protected:
669 /**
670 Connects all necessary signals and slots to the resource.
671 @param resource is a pointer to a ResourceCalendar.
672 */
673 void connectResource( ResourceCalendar *resource );
674
675 /**
676 Emits the @b signalResourceModified signal for the specified @p resource.
677
678 @param resource is a pointer to a ResourceCalendar that was changed.
679 @see signalResourceDeleted()
680 */
681 void resourceModified( ResourceCalendar *resource );
682
683 /**
684 Emits the @b signalResourceDeleted signal for the specified @p resource.
685 @param resource is a pointer to a ResourceCalendar that was removed.
686 @see signalResourceModified()
687 */
688 void resourceDeleted( ResourceCalendar *resource );
689
690 /**
691 @copydoc
692 Calendar::doSetTimeSpec()
693 */
694 virtual void doSetTimeSpec( const KDateTime::Spec &timeSpec );
695
696 /**
697 Increment the number of times this Resource has been changed by 1.
698
699 @param resource is a pointer to the ResourceCalendar to be counted.
700 @return the new number of times this Resource has been changed.
701 @see decrementChangeCount()
702 */
703 int incrementChangeCount( ResourceCalendar *resource );
704
705 /**
706 Decrement the number of times this Resource has been changed by 1.
707
708 @param resource is a pointer to the ResourceCalendar to be counted.
709 @return the new number of times this Resource has been changed.
710 @see incrementChangeCount()
711 */
712 int decrementChangeCount( ResourceCalendar *resource );
713
714 protected Q_SLOTS:
715 /**
716 Emits the @b signalErrorMessage signal with an error message
717 when an error occurs loading a ResourceCalendar.
718
719 @param resource is a pointer to the ResourceCalendar that failed to load.
720 @param err is the error message.
721 @see slotSaveError()
722 */
723 void slotLoadError( ResourceCalendar *resource, const QString &err );
724
725 /**
726 Emits the @b signalErrorMessage signal with an error message
727 when an error occurs saving a ResourceCalendar.
728
729 @param resource is a pointer to the ResourceCalendar that failed to save.
730 @param err is the error message.
731 @see slotLoadError()
732 */
733 void slotSaveError( ResourceCalendar *resource, const QString &err );
734
735 /**
736 All addIncidence( Incidence * ), addTodo( Todo * ) addEvent( Event * )
737 and addJournal( Journal * ) calls made between beginAddingIncidences()
738 and endAddingIncidences() will only ask the user to choose a resource once.
739 @since 4.4
740 */
741 void beginAddingIncidences();
742
743 /**
744 @see beginAddingIncidences()
745 @since 4.4
746 */
747 void endAddingIncidences();
748
749 private:
750 //@cond PRIVATE
751 Q_DISABLE_COPY( CalendarResources )
752 class Private;
753 Private *d;
754 //@endcond
755};
756
757}
758
759#endif
760