KCal Library

KCal::Calendar

KCal::Calendar Class Reference

#include <calendar.h>

Inheritance diagram for KCal::Calendar:

[legend]

List of all members.

Detailed Description

Represents the main calendar class.

A calendar contains information like incidences (events, to-dos, journals), alarms, time zones, and other useful information.

This is an abstract base class defining the interface to a calendar. It is implemented by subclasses like CalendarLocal, which use different methods to store and access the data.

Ownership of Incidences:

Incidence ownership is handled by the following policy: as soon as an incidence (or any other subclass of IncidenceBase) is added to the Calendar by an add...() method it is owned by the Calendar object. The Calendar takes care of deleting the incidence using the delete...() methods. All Incidences returned by the query functions are returned as pointers so that changes to the returned Incidences are immediately visible in the Calendar. Do Not attempt to 'delete' any Incidence object you get from Calendar -- use the delete...() methods.

Definition at line 119 of file calendar.h.


Signals
void	calendarChanged ()
void	calendarLoaded ()
void	calendarSaved ()
Public Member Functions
virtual bool	addEvent (Event *event)=0
virtual bool	addIncidence (Incidence *incidence)
virtual bool	addJournal (Journal *journal)=0
virtual bool	addTodo (Todo *todo)=0
virtual Alarm::List	alarms (const KDateTime &from, const KDateTime &to)=0
virtual bool	beginChange (Incidence *incidence)
	Calendar (const QString &timeZoneId)
	Calendar (const KDateTime::Spec &timeSpec)
QStringList	categories ()
virtual void	close ()=0
virtual void	deleteAllEvents ()=0
virtual void	deleteAllJournals ()=0
virtual void	deleteAllTodos ()=0
virtual bool	deleteEvent (Event *event)=0
virtual bool	deleteIncidence (Incidence *incidence)
virtual bool	deleteJournal (Journal *journal)=0
virtual bool	deleteTodo (Todo *todo)=0
Incidence *	dissociateOccurrence (Incidence *incidence, const QDate &date, const KDateTime::Spec &spec, bool single=true)
virtual bool	endChange (Incidence *incidence)
virtual Event *	event (const QString &uid)=0
Event::List	events (const QDate &date, const KDateTime::Spec &timespec=KDateTime::Spec(), EventSortField sortField=EventSortUnsorted, SortDirection sortDirection=SortDirectionAscending)
Event::List	events (const QDate &start, const QDate &end, const KDateTime::Spec &timespec=KDateTime::Spec(), bool inclusive=false)
Event::List	events (const KDateTime &dt)
virtual Event::List	events (EventSortField sortField=EventSortUnsorted, SortDirection sortDirection=SortDirectionAscending)
CalFilter *	filter ()
Incidence *	incidence (const QString &uid)
Incidence *	incidenceFromSchedulingID (const QString &sid)
virtual Incidence::List	incidences (const QDate &date)
virtual Incidence::List	incidences ()
Incidence::List	incidencesFromSchedulingID (const QString &sid)
bool	isModified () const
virtual bool	isSaving ()
virtual Journal *	journal (const QString &uid)=0
virtual Journal::List	journals (const QDate &date)
virtual Journal::List	journals (JournalSortField sortField=JournalSortUnsorted, SortDirection sortDirection=SortDirectionAscending)
Person	owner () const
QString	productId () const
virtual Event::List	rawEvents (const QDate &start, const QDate &end, const KDateTime::Spec &timespec=KDateTime::Spec(), bool inclusive=false)=0
virtual Event::List	rawEvents (EventSortField sortField=EventSortUnsorted, SortDirection sortDirection=SortDirectionAscending)=0
virtual Event::List	rawEventsForDate (const QDate &date, const KDateTime::Spec &timespec=KDateTime::Spec(), EventSortField sortField=EventSortUnsorted, SortDirection sortDirection=SortDirectionAscending)=0
virtual Event::List	rawEventsForDate (const KDateTime &dt)=0
virtual Incidence::List	rawIncidences ()
virtual Journal::List	rawJournals (JournalSortField sortField=JournalSortUnsorted, SortDirection sortDirection=SortDirectionAscending)=0
virtual Journal::List	rawJournalsForDate (const QDate &date)=0
virtual Todo::List	rawTodos (TodoSortField sortField=TodoSortUnsorted, SortDirection sortDirection=SortDirectionAscending)=0
virtual Todo::List	rawTodosForDate (const QDate &date)=0
void	registerObserver (CalendarObserver *observer)
virtual bool	reload ()=0
virtual void	removeRelations (Incidence *incidence)
virtual bool	save ()=0
void	setFilter (CalFilter *filter)
void	setModified (bool modified)
void	setOwner (const Person &owner)
void	setProductId (const QString &id)
void	setTimeSpec (const KDateTime::Spec &timeSpec)
void	setTimeZoneId (const QString &timeZoneId)
void	setTimeZones (const ICalTimeZones &zones)
virtual void	setupRelations (Incidence *incidence)
void	setViewTimeSpec (const KDateTime::Spec &timeSpec) const
void	setViewTimeZoneId (const QString &timeZoneId) const
void	shiftTimes (const KDateTime::Spec &oldSpec, const KDateTime::Spec &newSpec)
KDateTime::Spec	timeSpec () const
QString	timeZoneId () const
ICalTimeZones *	timeZones () const
virtual Todo *	todo (const QString &uid)=0
virtual Todo::List	todos (const QDate &date)
virtual Todo::List	todos (TodoSortField sortField=TodoSortUnsorted, SortDirection sortDirection=SortDirectionAscending)
void	unregisterObserver (CalendarObserver *observer)
KDateTime::Spec	viewTimeSpec () const
QString	viewTimeZoneId () const
virtual	~Calendar ()
Static Public Member Functions
static Incidence::List	mergeIncidenceList (const Event::List &events, const Todo::List &todos, const Journal::List &journals)
static Event::List	sortEvents (Event::List *eventList, EventSortField sortField, SortDirection sortDirection)
static Journal::List	sortJournals (Journal::List *journalList, JournalSortField sortField, SortDirection sortDirection)
static Todo::List	sortTodos (Todo::List *todoList, TodoSortField sortField, SortDirection sortDirection)
Protected Member Functions
void	appendAlarms (Alarm::List &alarms, Incidence *incidence, const KDateTime &from, const KDateTime &to)
void	appendRecurringAlarms (Alarm::List &alarms, Incidence *incidence, const KDateTime &from, const KDateTime &to)
virtual void	customPropertyUpdated ()
virtual void	doSetTimeSpec (const KDateTime::Spec &timeSpec)
void	incidenceUpdated (IncidenceBase *incidenceBase)
void	notifyIncidenceAdded (Incidence *incidence)
void	notifyIncidenceChanged (Incidence *incidence)
void	notifyIncidenceDeleted (Incidence *incidence)
void	setObserversEnabled (bool enabled)
Classes
class	CalendarObserver
	The CalendarObserver class. More...

Constructor & Destructor Documentation

Calendar::Calendar ( const KDateTime::Spec & timeSpec ) [explicit]

Constructs a calendar with a specified time zone timeZoneid.

Private class that helps to provide binary compatibility between releases.

The time specification is used as the default for creating or modifying incidences in the Calendar. The time specification does not alter existing incidences.

The constructor also calls setViewTimeSpec(timeSpec).

Parameters:

timeSpec

time specification

For internal use only.

Definition at line 103 of file calendar.cpp.

Calendar::Calendar ( const QString & timeZoneId ) [explicit]

Construct Calendar object using a time zone ID.

The time zone ID is used as the default for creating or modifying incidences in the Calendar. The time zone does not alter existing incidences.

The constructor also calls setViewTimeZoneId(timeZoneId).

Parameters:

timeZoneId

is a string containing a time zone ID, which is assumed to be valid. If no time zone is found, the viewing time specification is set to local clock time. Example: "Europe/Berlin"

Definition at line 110 of file calendar.cpp.

Calendar::~Calendar ( ) [virtual]

Destroys the calendar.

Definition at line 116 of file calendar.cpp.

Member Function Documentation

virtual bool KCal::Calendar::addEvent ( Event * event ) [pure virtual]

Inserts an Event into the calendar.

Parameters:

event

is a pointer to the Event to insert.

Returns:: true if the Event was successfully inserted; false otherwise.

See also:: deleteEvent()

Implemented in KCal::CalendarLocal, KCal::CalendarNull, and KCal::CalendarResources.

bool Calendar::addIncidence ( Incidence * incidence ) [virtual]

Inserts an Incidence into the calendar.

Parameters:

incidence

is a pointer to the Incidence to insert.

Returns:: true if the Incidence was successfully inserted; false otherwise.

See also:: deleteIncidence()

Reimplemented in KCal::CalendarResources.

Definition at line 415 of file calendar.cpp.

virtual bool KCal::Calendar::addJournal ( Journal * journal ) [pure virtual]

Inserts a Journal into the calendar.

Parameters:

journal

is a pointer to the Journal to insert.

Returns:: true if the Journal was successfully inserted; false otherwise.

See also:: deleteJournal()

Implemented in KCal::CalendarLocal, KCal::CalendarNull, and KCal::CalendarResources.

virtual bool KCal::Calendar::addTodo ( Todo * todo ) [pure virtual]

Inserts a Todo into the calendar.

Parameters:

todo

is a pointer to the Todo to insert.

Returns:: true if the Todo was successfully inserted; false otherwise.

See also:: deleteTodo()

Implemented in KCal::CalendarLocal, KCal::CalendarNull, and KCal::CalendarResources.

virtual Alarm::List KCal::Calendar::alarms	(	const KDateTime &	from,
		const KDateTime &	to
	)			`[pure virtual]`

Returns a list of Alarms within a time range for this Calendar.

Parameters:

	from	is the starting timestamp.
	to	is the ending timestamp.

Returns:: the list of Alarms for the for the specified time range.

Implemented in KCal::CalendarLocal, KCal::CalendarNull, and KCal::CalendarResources.

void Calendar::appendAlarms	(	Alarm::List &	alarms,
		Incidence *	incidence,
		const KDateTime &	from,
		const KDateTime &	to
	)			`[protected]`

Appends alarms of incidence in interval to list of alarms.

Parameters:

	alarms	is a List of Alarms to be appended onto.
	incidence	is a pointer to an Incidence containing the Alarm to be appended.
	from	is the lower range of the next Alarm repitition.
	to	is the upper range of the next Alarm repitition.

Definition at line 1043 of file calendar.cpp.

void Calendar::appendRecurringAlarms	(	Alarm::List &	alarms,
		Incidence *	incidence,
		const KDateTime &	from,
		const KDateTime &	to
	)			`[protected]`

Appends alarms of recurring events in interval to list of alarms.

Parameters:

	alarms	is a List of Alarms to be appended onto.
	incidence	is a pointer to an Incidence containing the Alarm to be appended.
	from	is the lower range of the next Alarm repitition.
	to	is the upper range of the next Alarm repitition.

Definition at line 1060 of file calendar.cpp.

bool Calendar::beginChange ( Incidence * incidence ) [virtual]

Flag that a change to a Calendar Incidence is starting.

Parameters:

incidence

is a pointer to the Incidence that will be changing.

Reimplemented in KCal::CalendarResources.

Definition at line 1026 of file calendar.cpp.

void KCal::Calendar::calendarChanged ( ) [signal]

Signals that the calendar has been modified.

void KCal::Calendar::calendarLoaded ( ) [signal]

Signals that the calendar has been loaded into memory.

void KCal::Calendar::calendarSaved ( ) [signal]

Signals that the calendar has been saved.

QStringList Calendar::categories ( )

Returns a list of all categories used by Incidences in this Calendar.

Returns:: a QStringList containing all the categories.

Definition at line 255 of file calendar.cpp.

virtual void KCal::Calendar::close ( ) [pure virtual]

Clears out the current calendar, freeing all used memory etc.

Implemented in KCal::CalendarLocal, KCal::CalendarNull, and KCal::CalendarResources.

void Calendar::customPropertyUpdated ( ) [protected, virtual]

Called when a custom property has been changed.

The default implementation does nothing: override in derived classes to perform change processing.

Reimplemented from KCal::CustomProperties.

Definition at line 989 of file calendar.cpp.

virtual void KCal::Calendar::deleteAllEvents ( ) [pure virtual]

Removes all Events from the calendar.

See also:: deleteEvent()

Implemented in KCal::CalendarLocal, KCal::CalendarNull, and KCal::CalendarResources.

virtual void KCal::Calendar::deleteAllJournals ( ) [pure virtual]

Removes all Journals from the calendar.

See also:: deleteJournal()

Implemented in KCal::CalendarLocal, KCal::CalendarNull, and KCal::CalendarResources.

virtual void KCal::Calendar::deleteAllTodos ( ) [pure virtual]

Removes all To-dos from the calendar.

See also:: deleteTodo()

Implemented in KCal::CalendarLocal, KCal::CalendarNull, and KCal::CalendarResources.

virtual bool KCal::Calendar::deleteEvent ( Event * event ) [pure virtual]

Removes an Event from the calendar.

Parameters:

event

is a pointer to the Event to remove.

Returns:: true if the Event was successfully remove; false otherwise.

See also:: addEvent(), deleteAllEvents()

Implemented in KCal::CalendarLocal, KCal::CalendarNull, and KCal::CalendarResources.

bool Calendar::deleteIncidence ( Incidence * incidence ) [virtual]

Removes an Incidence from the calendar.

Parameters:

incidence

is a pointer to the Incidence to remove.

Returns:: true if the Incidence was successfully removed; false otherwise.

See also:: addIncidence()

Definition at line 422 of file calendar.cpp.

virtual bool KCal::Calendar::deleteJournal ( Journal * journal ) [pure virtual]

Removes a Journal from the calendar.

Parameters:

journal

is a pointer to the Journal to remove.

Returns:: true if the Journal was successfully removed; false otherwise.

See also:: addJournal(), deleteAllJournals()

Implemented in KCal::CalendarLocal, KCal::CalendarNull, and KCal::CalendarResources.

virtual bool KCal::Calendar::deleteTodo ( Todo * todo ) [pure virtual]

Removes a Todo from the calendar.

Parameters:

todo

is a pointer to the Todo to remove.

Returns:: true if the Todo was successfully removed; false otherwise.

See also:: addTodo(), deleteAllTodos()

Implemented in KCal::CalendarLocal, KCal::CalendarNull, and KCal::CalendarResources.

Incidence * Calendar::dissociateOccurrence	(	Incidence *	incidence,
		const QDate &	date,
		const KDateTime::Spec &	spec,
		bool	single = `true`
	)

Dissociate an Incidence from a recurring Incidence.

By default, only one single Incidence for the specified date will be dissociated and returned. If single is false, then the recurrence will be split at date, the old Incidence will have its recurrence ending at date and the new Incidence will have all recurrences past the date.

Parameters:

	incidence	is a pointer to a recurring Incidence.
	date	is the QDate within the recurring Incidence on which the dissociation will be performed.
	spec	is the spec in which the date is formulated.
	single	is a flag meaning that a new Incidence should be created from the recurring Incidences after date.

Returns:: a pointer to a new recurring Incidence if single is false.

Definition at line 437 of file calendar.cpp.

void Calendar::doSetTimeSpec ( const KDateTime::Spec & timeSpec ) [protected, virtual]

Let Calendar subclasses set the time specification.

Parameters:

timeSpec

is the time specification (time zone, etc.) for viewing Incidence dates.

Reimplemented in KCal::CalendarResources.

Definition at line 951 of file calendar.cpp.

bool Calendar::endChange ( Incidence * incidence ) [virtual]

Flag that a change to a Calendar Incidence has completed.

Parameters:

incidence

is a pointer to the Incidence that was changed.

Reimplemented in KCal::CalendarResources.

Definition at line 1032 of file calendar.cpp.

virtual Event* KCal::Calendar::event ( const QString & uid ) [pure virtual]

Returns the Event associated with the given unique identifier.

Parameters:

uid

is a unique identifier string.

Returns:: a pointer to the Event. A null pointer is returned if no such Event exists.

Implemented in KCal::CalendarLocal, KCal::CalendarNull, and KCal::CalendarResources.

Event::List Calendar::events	(	const QDate &	date,
		const KDateTime::Spec &	timespec = `KDateTime::Spec()`,
		EventSortField	sortField = `EventSortUnsorted`,
		SortDirection	sortDirection = `SortDirectionAscending`
	)

Returns a sorted, filtered list of all Events which occur on the given date.

The Events are sorted according to sortField and sortDirection.

Parameters:

	date	request filtered Event list for this QDate only.
	timespec	time zone etc. to interpret `start` and `end`, or the calendar's default time spec if none is specified
	sortField	specifies the EventSortField.
	sortDirection	specifies the SortDirection.

Returns:: the list of sorted, filtered Events occurring on date.

Definition at line 381 of file calendar.cpp.

Event::List Calendar::events	(	const QDate &	start,
		const QDate &	end,
		const KDateTime::Spec &	timespec = `KDateTime::Spec()`,
		bool	inclusive = `false`
	)

Returns a filtered list of all Events occurring within a date range.

Parameters:

	start	is the starting date.
	end	is the ending date.
	timespec	time zone etc. to interpret `start` and `end`, or the calendar's default time spec if none is specified
	inclusive	if true only Events which are completely included within the date range are returned.

Returns:: the list of filtered Events occurring within the specified date range.

Definition at line 398 of file calendar.cpp.

Event::List Calendar::events ( const KDateTime & dt )

Returns a filtered list of all Events which occur on the given timestamp.

Parameters:

request filtered Event list for this KDateTime only.

Returns:: the list of filtered Events occurring on the specified timestamp.

Definition at line 391 of file calendar.cpp.

Event::List Calendar::events	(	EventSortField	sortField = `EventSortUnsorted`,
		SortDirection	sortDirection = `SortDirectionAscending`
	)			`[virtual]`

Returns a sorted, filtered list of all Events for this Calendar.

Parameters:

	sortField	specifies the EventSortField.
	sortDirection	specifies the SortDirection.

Returns:: the list of all filtered Events sorted as specified.

Definition at line 407 of file calendar.cpp.

CalFilter * Calendar::filter ( )

Returns the calendar filter.

Returns:: a pointer to the calendar CalFilter. A null pointer is returned if no such CalFilter exists.

See also:: setFilter()

Definition at line 250 of file calendar.cpp.

Incidence * Calendar::incidence ( const QString & uid )

Returns the Incidence associated with the given unique identifier.

Parameters:

uid

is a unique identifier string.

Returns:: a pointer to the Incidence. A null pointer is returned if no such Incidence exists.

Definition at line 507 of file calendar.cpp.

Incidence * Calendar::incidenceFromSchedulingID ( const QString & sid )

Returns the Incidence associated with the given scheduling identifier.

Parameters:

sid

is a unique scheduling identifier string.

Returns:: a pointer to the Incidence. A null pointer is returned if no such Incidence exists.

Definition at line 536 of file calendar.cpp.

Incidence::List Calendar::incidences ( const QDate & date ) [virtual]

Returns a filtered list of all Incidences which occur on the given date.

Parameters:

date

request filtered Incidence list for this QDate only.

Returns:: the list of filtered Incidences occurring on the specified date.

Definition at line 274 of file calendar.cpp.

Incidence::List Calendar::incidences ( ) [virtual]

Returns a filtered list of all Incidences for this Calendar.

Returns:: the list of all filtered Incidences.

Definition at line 279 of file calendar.cpp.

Incidence::List Calendar::incidencesFromSchedulingID ( const QString & sid )

Searches all events and todos for an incidence with this scheduling identifiere.

Returns a list of matching results.

Parameters:

sid

is a unique scheduling identifier string.

Definition at line 523 of file calendar.cpp.

void Calendar::incidenceUpdated ( IncidenceBase * incidenceBase ) [protected, virtual]

The Observer interface.

So far not implemented.

Parameters:

incidenceBase

is a pointer an IncidenceBase object.

Implements KCal::IncidenceBase::IncidenceObserver.

Reimplemented in KCal::CalendarLocal, and KCal::CalendarNull.

Definition at line 938 of file calendar.cpp.

bool Calendar::isModified ( ) const

Determine the calendar's modification status.

Returns:: true if the calendar has been modified since open or last save.

See also:: setModified()

Definition at line 933 of file calendar.cpp.

bool Calendar::isSaving ( ) [virtual]

Determine if the calendar is currently being saved.

Returns:: true if the calendar is currently being saved; false otherwise.

Reimplemented in KCal::CalendarResources.

Definition at line 917 of file calendar.cpp.

virtual Journal* KCal::Calendar::journal ( const QString & uid ) [pure virtual]

Returns the Journal associated with the given unique identifier.

Parameters:

uid

is a unique identifier string.

Returns:: a pointer to the Journal. A null pointer is returned if no such Journal exists.

Implemented in KCal::CalendarLocal, KCal::CalendarNull, and KCal::CalendarResources.

Journal::List Calendar::journals ( const QDate & date ) [virtual]

Returns a filtered list of all Journals for on the specified date.

Parameters:

date

request filtered Journals for this QDate only.

Returns:: the list of filtered Journals for the specified date.

Definition at line 770 of file calendar.cpp.

Journal::List Calendar::journals	(	JournalSortField	sortField = `JournalSortUnsorted`,
		SortDirection	sortDirection = `SortDirectionAscending`
	)			`[virtual]`

Returns a sorted, filtered list of all Journals for this Calendar.

Parameters:

	sortField	specifies the JournalSortField.
	sortDirection	specifies the SortDirection.

Returns:: the list of all filtered Journals sorted as specified.

Definition at line 762 of file calendar.cpp.

Incidence::List Calendar::mergeIncidenceList	(	const Event::List &	events,
		const Todo::List &	todos,
		const Journal::List &	journals
	)			`[static]`

Create a merged list of Events, Todos, and Journals.

Parameters:

	events	is an Event list to merge.
	todos	is a Todo list to merge.
	journals	is a Journal list to merge.

Returns:: a list of merged Incidences.

Definition at line 1004 of file calendar.cpp.

void Calendar::notifyIncidenceAdded ( Incidence * incidence ) [protected]

Let Calendar subclasses notify that they inserted an Incidence.

Parameters:

incidence

is a pointer to the Incidence object that was inserted.

Definition at line 956 of file calendar.cpp.

void Calendar::notifyIncidenceChanged ( Incidence * incidence ) [protected]

Let Calendar subclasses notify that they modified an Incidence.

Parameters:

incidence

is a pointer to the Incidence object that was modified.

Definition at line 967 of file calendar.cpp.

void Calendar::notifyIncidenceDeleted ( Incidence * incidence ) [protected]

Let Calendar subclasses notify that they removed an Incidence.

Parameters:

incidence

is a pointer to the Incidence object that was removed.

Definition at line 978 of file calendar.cpp.

Person Calendar::owner ( ) const

Returns the owner of the calendar.

Returns:: the owner Person object.

See also:: setOwner()

Definition at line 121 of file calendar.cpp.

QString Calendar::productId ( ) const

Returns the calendar's Product ID.

See also:: setProductId()

Definition at line 999 of file calendar.cpp.

virtual Event::List KCal::Calendar::rawEvents	(	const QDate &	start,
		const QDate &	end,
		const KDateTime::Spec &	timespec = `KDateTime::Spec()`,
		bool	inclusive = `false`
	)			`[pure virtual]`

Returns an unfiltered list of all Events occurring within a date range.

Parameters:

	start	is the starting date
	end	is the ending date
	timespec	time zone etc. to interpret `start` and `end`, or the calendar's default time spec if none is specified
	inclusive	if true only Events which are completely included within the date range are returned.

Returns:: the list of unfiltered Events occurring within the specified date range.

Implemented in KCal::CalendarLocal, KCal::CalendarNull, and KCal::CalendarResources.

virtual Event::List KCal::Calendar::rawEvents	(	EventSortField	sortField = `EventSortUnsorted`,
		SortDirection	sortDirection = `SortDirectionAscending`
	)			`[pure virtual]`

Returns a sorted, unfiltered list of all Events for this

KCal Library

KCal::Calendar Class Reference

Detailed Description

Signals

Public Member Functions

Static Public Member Functions

Protected Member Functions

Classes

Constructor & Destructor Documentation

Member Function Documentation