diff options
Diffstat (limited to 'libkcal/calendarresources.h')
| -rw-r--r-- | libkcal/calendarresources.h | 696 |
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 |