summaryrefslogtreecommitdiffstats
path: root/libkcal/calendarresources.h
diff options
context:
space:
mode:
Diffstat (limited to 'libkcal/calendarresources.h')
-rw-r--r--libkcal/calendarresources.h696
1 files changed, 696 insertions, 0 deletions
diff --git a/libkcal/calendarresources.h b/libkcal/calendarresources.h
new file mode 100644
index 000000000..a9e0fa808
--- /dev/null
+++ b/libkcal/calendarresources.h
@@ -0,0 +1,696 @@
+/*
+ This file is part of libkcal.
+
+ Copyright (c) 2003 Cornelius Schumacher <schumacher@kde.org>
+ Copyright (C) 2003-2004 Reinhold Kainhofer <reinhold@kainhofer.com>
+
+ 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.
+*/
+/**
+ @file calendarresources.h
+ Provides a Calendar composed of several Calendar Resources.
+
+ @author Cornelius Schumacher
+ @author Reinhold Kainhofer
+ */
+#ifndef KCAL_CALENDARRESOURCES_H
+#define KCAL_CALENDARRESOURCES_H
+
+#include <qintdict.h>
+#include <qmap.h>
+
+#include "calendar.h"
+#include "resourcecalendar.h"
+
+#include "libkcal_export.h"
+
+#include <kresources/manager.h>
+
+class QWidget;
+
+/**
+ @namespace KCal
+ Namespace KCal is for global classes, objects and/or functions in libkcal.
+*/
+namespace KCal {
+
+class CalFormat;
+
+/**
+ @class CalendarResources
+
+ This class provides a Calendar which is composed of other Calendars
+ known as "Resources".
+
+ Examples of Calendar Resources are:
+ - Calendars stored as local ICS formatted files
+ - a set of incidences (one-per-file) within a local directory
+ - birthdays and anniversaries contained in an addressbook
+
+*/
+class LIBKCAL_EXPORT CalendarResources :
+ public Calendar,
+ public KRES::ManagerObserver<ResourceCalendar>
+{
+ Q_OBJECT
+ public:
+ /**
+ @class DestinationPolicy
+ */
+ class DestinationPolicy
+ {
+ public:
+ DestinationPolicy( CalendarResourceManager *manager,
+ QWidget *parent = 0 ) :
+ mManager( manager ), mParent( parent ) {}
+
+ virtual ResourceCalendar *destination( Incidence *incidence ) = 0;
+ virtual QWidget *parent() { return mParent; }
+ virtual void setParent( QWidget *newparent ) { mParent = newparent; }
+
+ protected:
+ CalendarResourceManager *resourceManager()
+ { return mManager; }
+
+ private:
+ CalendarResourceManager *mManager;
+ QWidget *mParent;
+ };
+
+ /**
+ @class StandardDestinationPolicy
+ */
+ class StandardDestinationPolicy : public DestinationPolicy
+ {
+ public:
+ StandardDestinationPolicy( CalendarResourceManager *manager,
+ QWidget *parent = 0 ) :
+ DestinationPolicy( manager, parent ) {}
+
+ ResourceCalendar *destination( Incidence *incidence );
+
+ private:
+ class Private;
+ Private *d;
+ };
+
+ /**
+ @class AskDestinationPolicy
+ */
+ class AskDestinationPolicy : public DestinationPolicy
+ {
+ public:
+ AskDestinationPolicy( CalendarResourceManager *manager,
+ QWidget *parent = 0 ) :
+ DestinationPolicy( manager, parent ) {}
+
+ ResourceCalendar *destination( Incidence *incidence );
+
+ private:
+ class Private;
+ Private *d;
+ };
+
+ /**
+ @class Ticket
+ */
+ class Ticket
+ {
+ friend class CalendarResources;
+ public:
+ ResourceCalendar *resource() const
+ { return mResource; }
+
+ private:
+ Ticket( ResourceCalendar *r ) : mResource( r ) {}
+
+ ResourceCalendar *mResource;
+
+ class Private;
+ Private *d;
+ };
+
+ /**
+ Construct CalendarResource object using a Time Zone and a Family name.
+
+ @param timeZoneId is a string containing a Time Zone ID, which is
+ assumed to be valid. The Time Zone Id is used to set the time zone
+ for viewing Incidence dates.\n
+ On some systems, /usr/share/zoneinfo/zone.tab may be available for
+ reference.\n
+ @e Example: "Europe/Berlin"
+
+ @warning
+ Do Not pass an empty timeZoneId string as this may cause unintended
+ consequences when storing Incidences into the Calendar.
+
+ @param family is any QString representing a unique name.
+ */
+ CalendarResources(
+ const QString &timeZoneId,
+ const QString &family = QString::fromLatin1( "calendar" ) );
+
+ /**
+ Destructor
+ */
+ ~CalendarResources();
+
+ /**
+ Loads all Incidences from the Resources. The Resources must be added
+ first using either readConfig(KConfig *config), which adds the system
+ Resources, or manually using resourceAdded(ResourceCalendar *resource).
+ */
+ void load();
+
+ /**
+ * Reloads all incidences from all resources.
+ * @par tz The timezone to set.
+ * @return success or failure
+ */
+ bool reload( const QString &tz );
+
+ /**
+ Clear out the current Calendar, freeing all used memory etc.
+ */
+ void close();
+
+ /**
+ Save this Calendar.
+ If the save is successfull, the Ticket is deleted. Otherwise, the
+ caller must release the Ticket with releaseSaveTicket() to abandon
+ the save operation or call save() to try the save again.
+
+ @param ticket is a pointer to the Ticket object.
+ @param incidence is a pointer to the Incidence object.
+ If incidence is null, save the entire Calendar (all Resources)
+ else only the specified Incidence is saved.
+
+ @return true if the save was successful; false otherwise.
+ */
+ virtual bool save( Ticket *ticket, Incidence *incidence = 0 );
+
+ /**
+ Sync changes in memory to persistant storage.
+ */
+ void save();
+
+ /**
+ Determine if the Calendar is currently being saved.
+
+ @return true if the Calendar is currently being saved; false otherwise.
+ */
+ bool isSaving();
+
+ /**
+ Get the CalendarResourceManager used by this calendar.
+
+ @return a pointer to the CalendarResourceManage.
+ */
+ CalendarResourceManager *resourceManager() const
+ { return mManager; }
+
+ /**
+ Get the Resource associated with a specified Incidence.
+
+ @param incidence is a pointer to an Incidence whose Resource
+ is to be located.
+
+ @return a pointer to the Resource containing the Incidence.
+ */
+ ResourceCalendar *resource( Incidence *incidence );
+
+ /**
+ Read the Resources settings from a config file.
+
+ @param config The KConfig object which points to the config file.
+ If no object is given (null pointer) the standard config file is used.
+
+ @note Call this method <em>before</em> load().
+ */
+ void readConfig( KConfig *config = 0 );
+
+ /**
+ Set the destination policy such that Incidences are always added
+ to the standard Resource.
+ */
+ void setStandardDestinationPolicy();
+
+ /**
+ Set the destination policy such that Incidences are added to a
+ Resource which is queried.
+ */
+ void setAskDestinationPolicy();
+
+ /**
+ Returns the current parent for new dialogs. This is a bad hack, but we need
+ to properly set the parent for the resource selection dialog. Otherwise
+ the dialog will not be modal to the editor dialog in korganizer and
+ the user can still work in the editor dialog (and thus crash korganizer).
+ Afterwards we need to reset it (to avoid pointers to widgets that are
+ already deleted) so we also need the accessor
+ */
+ QWidget *dialogParentWidget();
+ /**
+ Set the widget parent for new dialogs. This is a bad hack, but we need
+ to properly set the parent for the resource selection dialog. Otherwise
+ the dialog will not be modal to the editor dialog in korganizer and
+ the user can still work in the editor dialog (and thus crash korganizer).
+ */
+ void setDialogParentWidget( QWidget *parent );
+
+ /**
+ Request ticket for saving the Calendar. If a ticket is returned the
+ Calendar is locked for write access until save() or releaseSaveTicket()
+ is called.
+
+ @param resource is a pointer to the ResourceCalendar object.
+
+ @return a pointer to a Ticket object indicating that the Calendar
+ is locked for write access; otherwise a null pointer.
+ */
+ Ticket *requestSaveTicket( ResourceCalendar *resource );
+
+ /**
+ Release the save Ticket. The Calendar is unlocked without saving.
+
+ @param ticket is a pointer to a Ticket object.
+ */
+ virtual void releaseSaveTicket( Ticket *ticket );
+
+ /**
+ Add a Resource to the Calendar.
+ This method must be public, because in-process added Resources
+ do not emit the corresponding signal, so this methodd has to be
+ called manually!
+
+ @param resource is a pointer to the ResourceCalendar to add.
+ */
+ void resourceAdded( ResourceCalendar *resource );
+
+// Incidence Specific Methods //
+
+ /**
+ Insert an Incidence into the Calendar.
+
+ @param incidence is a pointer to the Incidence to insert.
+
+ @return true if the Incidence was successfully inserted; false otherwise.
+ */
+ bool addIncidence( Incidence *incidence );
+
+ /**
+ Insert an Incidence into a Calendar Resource.
+
+ @param incidence is a pointer to the Incidence to insert.
+ @param resource is a pointer to the ResourceCalendar to be added to.
+
+ @return true if the Incidence was successfully inserted; false otherwise.
+ */
+ bool addIncidence( Incidence *incidence, ResourceCalendar *resource );
+
+ /**
+ Flag that a change to a Calendar Incidence is starting.
+
+ @param incidence is a pointer to the Incidence that will be changing.
+ */
+ bool beginChange( Incidence *incidence );
+
+ /**
+ Flag that a change to a Calendar Incidence has completed.
+
+ @param incidence is a pointer to the Incidence that was changed.
+ */
+ bool endChange( Incidence *incidence );
+
+// Event Specific Methods //
+
+ /**
+ Insert an Event into the Calendar.
+
+ @param event is a pointer to the Event to insert.
+
+ @return true if the Event was successfully inserted; false otherwise.
+
+ @note In most cases use
+ addIncidence( Incidence *incidence ) instead.
+ */
+ bool addEvent( Event *event );
+
+ /**
+ Insert an Event into a Calendar Resource.
+
+ @param event is a pointer to the Event to insert.
+ @param resource is a pointer to the ResourceCalendar to be added to.
+
+ @return true if the Event was successfully inserted; false otherwise.
+
+ @note In most cases use
+ addIncidence( Incidence *incidence, ResourceCalendar *resource ) instead.
+ */
+ bool addEvent( Event *event, ResourceCalendar *resource );
+
+ /**
+ Remove an Event from the Calendar.
+
+ @param event is a pointer to the Event to remove.
+
+ @return true if the Event was successfully removed; false otherwise.
+
+ @note In most cases use
+ deleteIncidence( Incidence *incidence) instead.
+ */
+ bool deleteEvent( Event *event );
+
+ /**
+ Return a sorted, unfiltered list of all Events.
+
+ @param sortField specifies the EventSortField.
+ @param sortDirection specifies the SortDirection.
+
+ @return the list of all unfiltered Events sorted as specified.
+ */
+ Event::List rawEvents(
+ EventSortField sortField = EventSortUnsorted,
+ SortDirection sortDirection = SortDirectionAscending );
+
+ /**
+ Return an unfiltered list of all Events which occur on the given
+ timestamp.
+
+ @param qdt request unfiltered Event list for this QDateTime only.
+
+ @return the list of unfiltered Events occurring on the specified
+ timestamp.
+ */
+ Event::List rawEventsForDate( const QDateTime &qdt );
+
+ /**
+ Return an unfiltered list of all Events occurring within a date range.
+
+ @param start is the starting date.
+ @param end is the ending date.
+ @param inclusive if true only Events which are completely included
+ within the date range are returned.
+
+ @return the list of unfiltered Events occurring within the specified
+ date range.
+ */
+ Event::List rawEvents( const QDate &start, const QDate &end,
+ bool inclusive = false );
+
+ /**
+ Return a sorted, unfiltered list of all Events which occur on the given
+ date. The Events are sorted according to @a sortField and
+ @a sortDirection.
+
+ @param date request unfiltered Event list for this QDate only.
+ @param sortField specifies the EventSortField.
+ @param sortDirection specifies the SortDirection.
+
+ @return the list of sorted, unfiltered Events occurring on @a date.
+ */
+ Event::List rawEventsForDate(
+ const QDate &date,
+ EventSortField sortField = EventSortUnsorted,
+ SortDirection sortDirection = SortDirectionAscending );
+
+ /**
+ Returns the Event associated with the given unique identifier.
+
+ @param uid is a unique identifier string.
+
+ @return a pointer to the Event.
+ A null pointer is returned if no such Event exists.
+ */
+ Event *event( const QString &uid );
+
+// Todo Specific Methods //
+
+ /**
+ Insert a Todo into a Calendar Resource.
+
+ @param todo is a pointer to the Todo to insert.
+
+ @return true if the Todo was successfully inserted; false otherwise.
+
+ @note In most cases use
+ addIncidence( Incidence *incidence ) instead.
+ */
+ bool addTodo( Todo *todo );
+
+ /**
+ Insert an Todo into a Calendar Resource.
+
+ @param todo is a pointer to the Todo to insert.
+ @param resource is a pointer to the ResourceCalendar to be added to.
+
+ @return true if the Todo was successfully inserted; false otherwise.
+
+ @note In most cases use
+ addIncidence( Incidence *incidence, ResourceCalendar *resource ) instead.
+ */
+ bool addTodo( Todo *todo, ResourceCalendar *resource );
+
+ /**
+ Remove an Todo from the Calendar.
+
+ @param todo is a pointer to the Todo to remove.
+
+ @return true if the Todo was successfully removed; false otherwise.
+
+ @note In most cases use
+ deleteIncidence( Incidence *incidence ) instead.
+ */
+ bool deleteTodo( Todo *todo );
+
+ /**
+ Return a sorted, unfiltered list of all Todos for this Calendar.
+
+ @param sortField specifies the TodoSortField.
+ @param sortDirection specifies the SortDirection.
+
+ @return the list of all unfiltered Todos sorted as specified.
+ */
+ Todo::List rawTodos( TodoSortField sortField = TodoSortUnsorted,
+ SortDirection sortDirection = SortDirectionAscending );
+
+ /**
+ Return an unfiltered list of all Todos which are due on the specified
+ date.
+
+ @param date request unfiltered Todos due on this QDate.
+
+ @return the list of unfiltered Todos due on the specified date.
+ */
+ Todo::List rawTodosForDate( const QDate &date );
+
+ /**
+ Returns the Todo associated with the given unique identifier.
+
+ @param uid is a unique identifier string.
+
+ @return a pointer to the Todo.
+ A null pointer is returned if no such Todo exists.
+ */
+ Todo *todo( const QString &uid );
+
+// Journal Specific Methods //
+
+ /**
+ Insert a Journal into the Calendar.
+
+ @param journal is a pointer to the Journal to insert.
+
+ @return true if the Journal was successfully inserted; false otherwise.
+
+ @note In most cases use
+ addIncidence( Incidence *incidence ) instead.
+ */
+ bool addJournal( Journal *journal );
+
+ /**
+ Insert a Journal into a Calendar Resource.
+
+ @param journal is a pointer to the Journal to insert.
+ @param resource is a pointer to the ResourceCalendar to be added to.
+
+ @return true if the Journal was successfully inserted; false otherwise.
+
+ @note In most cases use
+ addIncidence( Incidence *incidence, ResourceCalendar *resource ) instead.
+ */
+ bool addJournal( Journal *journal, ResourceCalendar *resource );
+
+ /**
+ Remove a Journal from the Calendar.
+
+ @param journal is a pointer to the Journal to remove.
+
+ @return true if the Journal was successfully removed; false otherwise.
+
+ @note In most cases use
+ deleteIncidence( Incidence *incidence ) instead.
+ */
+ bool deleteJournal( Journal *journal );
+
+ /**
+ Return a sorted, unfiltered list of all Journals for this Calendar.
+
+ @param sortField specifies the JournalSortField.
+ @param sortDirection specifies the SortDirection.
+
+ @return the list of all unfiltered Journals sorted as specified.
+ */
+ Journal::List rawJournals(
+ JournalSortField sortField = JournalSortUnsorted,
+ SortDirection sortDirection = SortDirectionAscending );
+
+ /**
+ Return an unfiltered list of all Journals for on the specifed date.
+
+ @param date request unfiltered Journals for this QDate only.
+
+ @return the list of unfiltered Journals for the specified date.
+ */
+ Journal::List rawJournalsForDate( const QDate &date );
+
+ /**
+ Returns the Journal associated with the given unique identifier.
+
+ @param uid is a unique identifier string.
+
+ @return a pointer to the Journal.
+ A null pointer is returned if no such Journal exists.
+ */
+ Journal *journal( const QString &uid );
+
+// Alarm Specific Methods //
+
+ /**
+ Return a list of Alarms within a time range for this Calendar.
+
+ @param from is the starting timestamp.
+ @param to is the ending timestamp.
+
+ @return the list of Alarms for the for the specified time range.
+ */
+ Alarm::List alarms( const QDateTime &from, const QDateTime &to );
+
+ /**
+ Return a list of Alarms that occur before the specified timestamp.
+
+ @param to is the ending timestamp.
+
+ @return the list of Alarms occurring before the specified QDateTime.
+ */
+ Alarm::List alarmsTo( const QDateTime &to );
+
+ /**
+ * Set the viewing time zone, which requires that all resources are saved,
+ * and then reloaded such that the event times are re-interpreted in the new
+ * timezone. Note that the absolute times of events do not change with this.
+ * If you want to change the times of the contents of the resources, use
+ * setTimeZoneId
+ */
+ void setTimeZoneIdViewOnly( const QString& tz );
+
+ signals:
+ /**
+ Signal that the Resource has been modified.
+ */
+ void signalResourceModified( ResourceCalendar *resource );
+
+ /**
+ Signal that an Incidence has been inserted to the Resource.
+ */
+ void signalResourceAdded( ResourceCalendar *resource );
+
+ /**
+ Signal that an Incidence has been removed from the Resource.
+ */
+ void signalResourceDeleted( ResourceCalendar *resource );
+
+ /**
+ Signal an error message.
+ */
+ void signalErrorMessage( const QString &err );
+
+ protected:
+ void connectResource( ResourceCalendar *resource );
+ void resourceModified( ResourceCalendar *resource );
+ void resourceDeleted( ResourceCalendar *resource );
+
+ /**
+ Let CalendarResource subclasses set the Time Zone ID.
+
+ First parameter is a string containing a Time Zone ID, which is
+ assumed to be valid. On some systems, /usr/share/zoneinfo/zone.tab
+ may be available for reference.\n
+ @e Example: "Europe/Berlin"
+
+ @warning
+ Do Not pass an empty timeZoneId string as this may cause unintended
+ consequences when storing Incidences into the Calendar.
+ */
+ virtual void doSetTimeZoneId( const QString &timeZoneId );
+
+ /**
+ Increment the number of times this Resource has been changed by 1.
+
+ @param resource is a pointer to the ResourceCalendar to be counted.
+
+ @return the new number of times this Resource has been changed.
+ */
+ int incrementChangeCount( ResourceCalendar *resource );
+
+ /**
+ Decrement the number of times this Resource has been changed by 1.
+
+ @param resource is a pointer to the ResourceCalendar to be counted.
+
+ @return the new number of times this Resource has been changed.
+ */
+ int decrementChangeCount( ResourceCalendar *resource );
+
+ protected slots:
+ void slotLoadError( ResourceCalendar *resource, const QString &err );
+ void slotSaveError( ResourceCalendar *resource, const QString &err );
+
+ private:
+ /**
+ Initialize the Resource object with starting values.
+ */
+ void init( const QString &family );
+
+ bool mOpen;
+
+ KRES::Manager<ResourceCalendar>* mManager;
+ QMap <Incidence*, ResourceCalendar*> mResourceMap;
+
+ DestinationPolicy *mDestinationPolicy;
+ StandardDestinationPolicy *mStandardPolicy;
+ AskDestinationPolicy *mAskPolicy;
+
+ QMap<ResourceCalendar *, Ticket *> mTickets;
+ QMap<ResourceCalendar *, int> mChangeCounts;
+
+ class Private;
+ Private *d;
+};
+
+}
+
+#endif