diff --git a/kcalcore/alarm.h b/kcalcore/alarm.h index 8759a55..9847810 100644 --- a/kcalcore/alarm.h +++ b/kcalcore/alarm.h @@ -1,697 +1,697 @@ /* This file is part of the kcalcore library. Copyright (c) 2001-2003 Cornelius Schumacher Copyright (c) 2003 David Jarvie Copyright (c) 2010 Klarälvdalens Datakonsult AB, a KDAB Group company 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 This file is part of the API for handling calendar data and defines the Alarm class. @author Cornelius Schumacher \ */ #ifndef KCALCORE_ALARM_H #define KCALCORE_ALARM_H #include "kcalcore_export.h" #include "customproperties.h" #include "duration.h" #include "person.h" -#include +#include #include #include #include #include #include namespace KCalCore { class Incidence; /** @brief Represents an alarm notification. Alarms are user notifications that occur at specified times. Notifications can be on-screen pop-up dialogs, email messages, the playing of audio files, or the running of another program. Alarms always belong to a parent Incidence. */ class KCALCORE_EXPORT Alarm : public CustomProperties { public: /** The different types of alarms. */ enum Type { Invalid, /**< Invalid, or no alarm */ Display, /**< Display a dialog box */ Procedure, /**< Call a script */ Email, /**< Send email */ Audio /**< Play an audio file */ }; /** A shared pointer to an Alarm object. */ typedef QSharedPointer Ptr; /** List of alarms. */ typedef QVector List; /** Constructs an alarm belonging to the @p parent Incidence. @param parent is the Incidence this alarm will belong to. */ // Can't find a way to use a shared pointer here. // Inside incidence.cpp, it does alarm->setParent( this ) explicit Alarm(Incidence *parent); /** Copy constructor. @param other is the alarm to copy. */ Alarm(const Alarm &other); /** Destroys the alarm. */ virtual ~Alarm(); /** Copy operator. */ Alarm &operator=(const Alarm &); /** Compares two alarms for equality. @param a is the comparison alarm. */ bool operator==(const Alarm &a) const; /** Compares two alarms for inequality. @param a is the comparison alarm. */ bool operator!=(const Alarm &a) const; /** Sets the @p parent Incidence of the alarm. @param parent is alarm parent Incidence to set. @see parentUid() */ // Is there a way to use QSharedPointer here? // although it's safe, Incidence's dtor calls setParent( 0 ) // se we don't dereference a deleted pointer here. // Also, I renamed "Incidence *parent()" to "QString parentUid()" // So we don't return raw pointers void setParent(Incidence *parent); /** Returns the parent's incidence UID of the alarm. @see setParent() */ // We don't have a share pointer to return, so return the UID. QString parentUid() const; /** Sets the #Type for this alarm to @p type. If the specified type is different from the current type of the alarm, then the alarm's type-specific properties are re-initialized. @param type is the alarm #Type to set. @see type() */ void setType(Type type); /** Returns the #Type of the alarm. @see setType() */ Type type() const; /** Sets the #Display type for this alarm. If @p text is specified non-empty, then it is used as the description text to display when the alarm is triggered. @param text is the description to display when the alarm is triggered. @see setText(), text() */ void setDisplayAlarm(const QString &text = QString()); /** Sets the description @p text to be displayed when the alarm is triggered. Ignored if the alarm is not a display alarm. @param text is the description to display when the alarm is triggered. @see setDisplayAlarm(), text() */ void setText(const QString &text); /** Returns the display text string for a #Display alarm type. Returns an empty string if the alarm is not a #Display type. @see setDisplayAlarm(), setText() */ QString text() const; /** Sets the #Audio type for this alarm and the name of the audio file to play when the alarm is triggered. @param audioFile is the name of the audio file to play when the alarm is triggered. @see setAudioFile(), audioFile() */ void setAudioAlarm(const QString &audioFile = QString()); /** Sets the name of the audio file to play when the audio alarm is triggered. Ignored if the alarm is not an #Audio type. @param audioFile is the name of the audio file to play when the alarm is triggered. @see setAudioAlarm(), audioFile() */ void setAudioFile(const QString &audioFile); /** Returns the audio file name for an #Audio alarm type. Returns an empty string if the alarm is not an #Audio type. @see setAudioAlarm(), setAudioFile() */ QString audioFile() const; /** Sets the #Procedure type for this alarm and the program (with arguments) to execute when the alarm is triggered. @param programFile is the name of the program file to execute when the alarm is triggered. @param arguments is a string of arguments to supply to @p programFile. @see setProgramFile(), programFile(), setProgramArguments(), programArguments() */ void setProcedureAlarm(const QString &programFile, const QString &arguments = QString()); /** Sets the program file to execute when the alarm is triggered. Ignored if the alarm is not a #Procedure type. @param programFile is the name of the program file to execute when the alarm is triggered. @see setProcedureAlarm(), programFile(), setProgramArguments(), programArguments() */ void setProgramFile(const QString &programFile); /** Returns the program file name for a #Procedure alarm type. Returns an empty string if the alarm is not a #Procedure type. @see setProcedureAlarm(), setProgramFile(), setProgramArguments(), programArguments() */ QString programFile() const; /** Sets the program arguments string when the alarm is triggered. Ignored if the alarm is not a #Procedure type. @param arguments is a string of arguments to supply to the program. @see setProcedureAlarm(), setProgramFile(), programFile(), programArguments() */ void setProgramArguments(const QString &arguments); /** Returns the program arguments string for a #Procedure alarm type. Returns an empty string if the alarm is not a #Procedure type. @see setProcedureAlarm(), setProgramFile(), programFile(), setProgramArguments() */ QString programArguments() const; /** Sets the #Email type for this alarm and the email @p subject, @p text, @p addresses, and @p attachments that make up an email message to be sent when the alarm is triggered. @param subject is the email subject. @param text is a string containing the body of the email message. @param addressees is Person list of email addresses. @param attachments is a a QStringList of optional file names of email attachments. @see setMailSubject(), setMailText(), setMailAddresses(), setMailAttachments() */ void setEmailAlarm(const QString &subject, const QString &text, const Person::List &addressees, const QStringList &attachments = QStringList()); /** Sets the email address of an #Email type alarm. Ignored if the alarm is not an #Email type. @param mailAlarmAddress is a Person to receive a mail message when an #Email type alarm is triggered. @see setMailSubject(), setMailText(), setMailAddresses(), setMailAttachment(), setMailAttachments(), mailAddresses() */ void setMailAddress(const Person::Ptr &mailAlarmAddress); /** Sets a list of email addresses of an #Email type alarm. Ignored if the alarm is not an #Email type. @param mailAlarmAddresses is a Person list to receive a mail message when an #Email type alarm is triggered. @see setMailSubject(), setMailText(), setMailAddress(), setMailAttachments(), setMailAttachment(), mailAddresses() */ void setMailAddresses(const Person::List &mailAlarmAddresses); /** Adds an address to the list of email addresses to send mail to when the alarm is triggered. Ignored if the alarm is not an #Email type. @param mailAlarmAddress is a Person to add to the list of addresses to receive a mail message when an #Email type alarm is triggered. @see setMailAddress(), setMailAddresses(), mailAddresses() */ void addMailAddress(const Person::Ptr &mailAlarmAddress); /** Returns the list of addresses for an #Email alarm type. Returns an empty list if the alarm is not an #Email type. @see addMailAddress(), setMailAddress(), setMailAddresses() */ Person::List mailAddresses() const; /** Sets the subject line of a mail message for an #Email alarm type. Ignored if the alarm is not an #Email type. @param mailAlarmSubject is a string to be used as a subject line of an email message to send when the #Email type alarm is triggered. @see setMailText(), setMailAddress(), setMailAddresses(), setMailAttachment(), setMailAttachments(), mailSubject() */ void setMailSubject(const QString &mailAlarmSubject); /** Returns the subject line string for an #Email alarm type. Returns an empty string if the alarm is not an #Email type. @see setMailSubject() */ QString mailSubject() const; /** Sets the filename to attach to a mail message for an #Email alarm type. Ignored if the alarm is not an #Email type. @param mailAttachFile is a string containing a filename to be attached to an email message to send when the #Email type alarm is triggered. @see setMailSubject(), setMailText(), setMailAddress(), setMailAddresses(), setMailAttachments(), mailAttachments() */ void setMailAttachment(const QString &mailAttachFile); /** Sets a list of filenames to attach to a mail message for an #Email alarm type. Ignored if the alarm is not an #Email type. @param mailAttachFiles is a QString list of filenames to attach to a mail message when an #Email type alarm is triggered. @see setMailSubject(), setMailText(), setMailAttachment(), setMailAddress(), setMailAddresses() */ void setMailAttachments(const QStringList &mailAttachFiles); /** Adds a filename to the list of files to attach to a mail message for an #Email alarm type. Ignored if the alarm is not an #Email type. @param mailAttachFile is a string containing a filename to be attached to an email message to send when the #Email type alarm is triggered. @see setMailAttachment(), setMailAttachments(), mailAttachments() */ void addMailAttachment(const QString &mailAttachFile); /** Returns the list of attachment filenames for an #Email alarm type. Returns an empty list if the alarm is not an #Email type. @see addMailAttachment(), setMailAttachment(), setMailAttachments() */ QStringList mailAttachments() const; /** Sets the body text for an #Email alarm type. Ignored if the alarm is not an #Email type. @param text is a string containing the body text of a mail message when an #Email type alarm is triggered. @see setMailSubject(), setMailAddress(), setMailAddresses(), setMailAttachment(), setMailAttachments() */ void setMailText(const QString &text); /** Returns the body text for an #Email alarm type. Returns an empty string if the alarm is not an #Email type. @see setMailText() */ QString mailText() const; /** Sets the trigger time of the alarm. @param alarmTime is the KDateTime alarm trigger. @see time() */ void setTime(const KDateTime &alarmTime); /** Returns the alarm trigger date/time. @see setTime() */ KDateTime time() const; /** Returns the next alarm trigger date/time after given date/time. Takes recurrent incidences into account. @param preTime date/time from where to start @param ignoreRepetitions don't take repetitions into account @see nextRepetition() */ KDateTime nextTime(const KDateTime &preTime, bool ignoreRepetitions = false) const; /** Returns the date/time when the last repetition of the alarm goes off. If the alarm does not repeat this is equivalent to calling time(). @see setTime() */ KDateTime endTime() const; /** Returns true if the alarm has a trigger date/time. */ bool hasTime() const; /** Sets the alarm offset relative to the start of the parent Incidence. @param offset is a Duration to be used as a time relative to the start of the parent Incidence to be used as the alarm trigger. @see setEndOffset(), startOffset(), endOffset() */ void setStartOffset(const Duration &offset); /** Returns offset of alarm in time relative to the start of the parent Incidence. If the alarm's time is not defined in terms of an offset relative to the start of the event, returns zero. @see setStartOffset(), hasStartOffset() */ Duration startOffset() const; /** Returns whether the alarm is defined in terms of an offset relative to the start of the parent Incidence. @see startOffset(), setStartOffset() */ bool hasStartOffset() const; /** Sets the alarm offset relative to the end of the parent Incidence. @param offset is a Duration to be used as a time relative to the end of the parent Incidence to be used as the alarm trigger. @see setStartOffset(), startOffset(), endOffset() */ void setEndOffset(const Duration &offset); /** Returns offset of alarm in time relative to the end of the event. If the alarm's time is not defined in terms of an offset relative to the end of the event, returns zero. @see setEndOffset(), hasEndOffset() */ Duration endOffset() const; /** Returns whether the alarm is defined in terms of an offset relative to the end of the event. @see endOffset(), setEndOffset() */ bool hasEndOffset() const; /** Shift the times of the alarm so that they appear at the same clock time as before but in a new time zone. The shift is done from a viewing time zone rather than from the actual alarm time zone. For example, shifting an alarm whose start time is 09:00 America/New York, using an old viewing time zone (@p oldSpec) of Europe/London, to a new time zone (@p newSpec) of Europe/Paris, will result in the time being shifted from 14:00 (which is the London time of the alarm start) to 14:00 Paris time. @param oldSpec the time specification which provides the clock times @param newSpec the new time specification */ void shiftTimes(const KDateTime::Spec &oldSpec, const KDateTime::Spec &newSpec); /** Sets the snooze time interval for the alarm. @param alarmSnoozeTime the time between snoozes. @see snoozeTime() */ void setSnoozeTime(const Duration &alarmSnoozeTime); /** Returns the snooze time interval. @see setSnoozeTime() */ Duration snoozeTime() const; /** Sets how many times an alarm is to repeat itself after its initial occurrence (w/snoozes). @param alarmRepeatCount is the number of times an alarm may repeat, excluding the initial occurrence. @see repeatCount() */ void setRepeatCount(int alarmRepeatCount); /** Returns how many times an alarm may repeats after its initial occurrence. @see setRepeatCount() */ int repeatCount() const; /** Returns the date/time of the alarm's initial occurrence or its next repetition after a given time. @param preTime the date/time after which to find the next repetition. @return the date/time of the next repetition, or an invalid date/time if the specified time is at or after the alarm's last repetition. @see previousRepetition() */ KDateTime nextRepetition(const KDateTime &preTime) const; /** Returns the date/time of the alarm's latest repetition or, if none, its initial occurrence before a given time. @param afterTime is the date/time before which to find the latest repetition. @return the date and time of the latest repetition, or an invalid date/time if the specified time is at or before the alarm's initial occurrence. @see nextRepetition() */ KDateTime previousRepetition(const KDateTime &afterTime) const; /** Returns the interval between the alarm's initial occurrence and its final repetition. */ Duration duration() const; /** Toggles the alarm status, i.e, an enable alarm becomes disabled and a disabled alarm becomes enabled. @see enabled(), setEnabled() */ void toggleAlarm(); /** Sets the enabled status of the alarm. @param enable if true, then enable the alarm; else disable the alarm. @see enabled(), toggleAlarm() */ void setEnabled(bool enable); /** Returns the alarm enabled status: true (enabled) or false (disabled). @see setEnabled(), toggleAlarm() */ bool enabled() const; /** Set if the location radius for the alarm has been defined. @param hasLocationRadius if true, then this alarm has a location radius. @see setLocationRadius() */ void setHasLocationRadius(bool hasLocationRadius); /** Returns true if alarm has location radius defined. @see setLocationRadius() */ bool hasLocationRadius() const; /** Set location radius for the alarm. This means that alarm will be triggered when user approaches the location. Given value will be stored into custom properties as X-LOCATION-RADIUS. @param locationRadius radius in meters @see locationRadius() */ void setLocationRadius(int locationRadius); /** Returns the location radius in meters. @see setLocationRadius() */ int locationRadius() const; protected: /** @copydoc CustomProperties::customPropertyUpdated() */ virtual void customPropertyUpdated(); /** @copydoc IncidenceBase::virtual_hook() */ virtual void virtual_hook(int id, void *data); private: //@cond PRIVATE class Private; Private *const d; //@endcond friend KCALCORE_EXPORT QDataStream &operator<<(QDataStream &s, const KCalCore::Alarm::Ptr &); friend KCALCORE_EXPORT QDataStream &operator>>(QDataStream &s, const KCalCore::Alarm::Ptr &); }; /** * Alarm serializer. * * @since 4.12 */ KCALCORE_EXPORT QDataStream &operator<<(QDataStream &out, const KCalCore::Alarm::Ptr &); /** * Alarm deserializer. * * @since 4.12 */ KCALCORE_EXPORT QDataStream &operator>>(QDataStream &in, const KCalCore::Alarm::Ptr &); } //@cond PRIVATE Q_DECLARE_TYPEINFO(KCalCore::Alarm::Ptr, Q_MOVABLE_TYPE); Q_DECLARE_METATYPE(KCalCore::Alarm::Ptr) //@endcond #endif diff --git a/kcalcore/incidencebase.h b/kcalcore/incidencebase.h index e2f0847..c991b25 100644 --- a/kcalcore/incidencebase.h +++ b/kcalcore/incidencebase.h @@ -1,786 +1,786 @@ /* This file is part of the kcalcore library. Copyright (c) 2001-2003 Cornelius Schumacher Copyright (c) 2003-2004 Reinhold Kainhofer Copyright (c) 2005 Rafal Rzepecki Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. Contact: Alvaro Manera 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 This file is part of the API for handling calendar data and defines the IncidenceBase class. @author Cornelius Schumacher \ @author Reinhold Kainhofer \ @author Rafal Rzepecki \ @glossary @anchor incidence @b incidence: General term for a calendar component. Examples are events, to-dos, and journals. @glossary @anchor event @b event: An @ref incidence that has a start and end time, typically representing some occurrence of social or personal importance. May be recurring. Examples are appointments, meetings, or holidays. @glossary @anchor to-do @b to-do: An @ref incidence that has an optional start time and an optional due time typically representing some undertaking to be performed. May be recurring. Examples are "fix the bug" or "pay the bills". @glossary @anchor todo @b todo: See @ref to-do. @glossary @anchor journal @b journal: An @ref incidence with a start date that represents a diary or daily record of one's activities. May @b not be recurring. */ #ifndef KCALCORE_INCIDENCEBASE_H #define KCALCORE_INCIDENCEBASE_H #include "attendee.h" #include "customproperties.h" #include "duration.h" #include "sortablelist.h" -#include +#include #include #include #include class KUrl; class QDate; namespace KCalCore { /** List of dates */ typedef SortableList DateList; /** List of times */ typedef SortableList DateTimeList; class Event; class Todo; class Journal; class FreeBusy; class Visitor; /** @brief An abstract class that provides a common base for all calendar incidence classes. define: organizer (person) define: uid (same as the attendee uid?) Several properties are not allowed for VFREEBUSY objects (see rfc:2445), so they are not in IncidenceBase. The hierarchy is: IncidenceBase + FreeBusy + Incidence + Event + Todo + Journal So IncidenceBase contains all properties that are common to all classes, and Incidence contains all additional properties that are common to Events, Todos and Journals, but are not allowed for FreeBusy entries. */ class KCALCORE_EXPORT IncidenceBase : public CustomProperties { public: /** A shared pointer to an IncidenceBase. */ typedef QSharedPointer Ptr; /** The different types of incidences, per RFC2445. @see type(), typeStr() */ enum IncidenceType { TypeEvent = 0, /**< Type is an event */ TypeTodo, /**< Type is a to-do */ TypeJournal, /**< Type is a journal */ TypeFreeBusy, /**< Type is a free/busy */ TypeUnknown /**< Type unknown */ }; /** The different types of incidence date/times roles. @see dateTime() */ enum DateTimeRole { RoleAlarmStartOffset = 0,/**< Role for an incidence alarm's starting offset date/time */ RoleAlarmEndOffset, /**< Role for an incidence alarm's ending offset date/time */ RoleSort, /**< Role for an incidence's date/time used when sorting */ RoleCalendarHashing, /**< Role for looking up an incidence in a Calendar */ RoleStartTimeZone, /**< Role for determining an incidence's starting timezone */ RoleEndTimeZone, /**< Role for determining an incidence's ending timezone */ RoleEndRecurrenceBase, RoleEnd, /**< Role for determining an incidence's dtEnd, will return an invalid KDateTime if the incidence does not support dtEnd */ RoleDisplayEnd, /**< Role used for display purposes, represents the end boundary if an incidence supports dtEnd */ RoleAlarm, /**< Role for determining the date/time of the first alarm. Returns invalid time if the incidence doesn't have any alarm */ RoleRecurrenceStart, /**< Role for determining the start of the recurrence. Currently that's DTSTART for an event and DTDUE for a to-do. (NOTE: If the incidence is a to-do, recurrence should be calculated having DTSTART for a reference, not DT-DUE. This is one place KCalCore isn't compliant with RFC2445) */ RoleDisplayStart, /**< Role for display purposes, represents the start boundary of an incidence. To-dos return dtDue here, for historical reasons */ RoleDnD /**< Role for determining new start and end dates after a DnD */ }; /** The different types of incidence fields. */ enum Field { FieldDtStart, ///> Field representing the DTSTART component. FieldDtEnd, ///> Field representing the DTEND component. FieldLastModified, ///> Field representing the LAST-MODIFIED component. FieldDescription, ///> Field representing the DESCRIPTION component. FieldSummary, ///> Field representing the SUMMARY component. FieldLocation, ///> Field representing the LOCATION component. FieldCompleted, ///> Field representing the COMPLETED component. FieldPercentComplete, ///> Field representing the PERCENT-COMPLETE component. FieldDtDue, ///> Field representing the DUE component. FieldCategories, ///> Field representing the CATEGORIES component. FieldRelatedTo, ///> Field representing the RELATED-TO component. FieldRecurrence, ///> Field representing the EXDATE, EXRULE, RDATE, and RRULE components. FieldAttachment, ///> Field representing the ATTACH component. FieldSecrecy, ///> Field representing the CLASS component. FieldStatus, ///> Field representing the STATUS component. FieldTransparency, ///> Field representing the TRANSPARENCY component. FieldResources, ///> Field representing the RESOURCES component. FieldPriority, ///> Field representing the PRIORITY component. FieldGeoLatitude, ///> Field representing the latitude part of the GEO component. FieldGeoLongitude, ///> Field representing the longitude part of the GEO component. FieldRecurrenceId, ///> Field representing the RECURRENCE-ID component. FieldAlarms, ///> Field representing the VALARM component. FieldSchedulingId, ///> Field representing the X-KDE-LIBKCAL-ID component. FieldAttendees, ///> Field representing the ATTENDEE component. FieldOrganizer, ///> Field representing the ORGANIZER component. FieldCreated, ///> Field representing the CREATED component. FieldRevision, ///> Field representing the SEQUENCE component. FieldDuration, ///> Field representing the DURATION component. FieldContact, ///> Field representing the CONTACT component. FieldComment, ///> Field representing the COMMENT component. FieldUid, ///> Field representing the UID component. FieldUnknown, ///> Something changed. Always set when you use the assignment operator. FieldUrl ///> Field representing the URL component. }; /** The IncidenceObserver class. */ class KCALCORE_EXPORT IncidenceObserver { public: /** Destroys the IncidenceObserver. */ virtual ~IncidenceObserver(); /** The IncidenceObserver interface. This function is called before any changes are made. @param uid is the string containing the incidence @ref uid. @param recurrenceId is possible recurrenceid of incidence. */ virtual void incidenceUpdate(const QString &uid, const KDateTime &recurrenceId) = 0; /** The IncidenceObserver interface. This function is called after changes are completed. @param uid is the string containing the incidence @ref uid. @param recurrenceId is possible recurrenceid of incidence. */ virtual void incidenceUpdated(const QString &uid, const KDateTime &recurrenceId) = 0; }; /** Constructs an empty IncidenceBase. */ IncidenceBase(); /** Destroys the IncidenceBase. */ virtual ~IncidenceBase(); /** Assignment operator. All data belonging to derived classes are also copied. @see assign(). The caller guarantees that both types match. @code if ( i1.type() == i2.type() ) { i1 = i2; } else { kDebug() << "Invalid assignment!"; } @endcode Dirty field FieldUnknown will be set. @param other is the IncidenceBase to assign. */ IncidenceBase &operator=(const IncidenceBase &other); /** Compares this with IncidenceBase @p ib for equality. All data belonging to derived classes are also compared. @see equals(). @param ib is the IncidenceBase to compare against. @return true if the incidences are equal; false otherwise. */ bool operator==(const IncidenceBase &ib) const; /** Compares this with IncidenceBase @p ib for inequality. @param ib is the IncidenceBase to compare against. @return true if the incidences are /not/ equal; false otherwise. */ bool operator!=(const IncidenceBase &ib) const; /** Accept IncidenceVisitor. A class taking part in the visitor mechanism has to provide this implementation: 
        bool accept(Visitor &v) { return v.visit(this); }
@param v is a reference to a Visitor object. @param incidence is a valid IncidenceBase object for visting. */ virtual bool accept(Visitor &v, IncidenceBase::Ptr incidence); /** Returns the incidence type. */ virtual IncidenceType type() const = 0; /** Prints the type of incidence as a string. */ virtual QByteArray typeStr() const = 0; /** Sets the unique id for the incidence to @p uid. @param uid is the string containing the incidence @ref uid. @see uid() */ void setUid(const QString &uid); /** Returns the unique id (@ref uid) for the incidence. @see setUid() */ QString uid() const; /** Returns the uri for the incidence, of form urn:x-ical:\ */ KUrl uri() const; /** Sets the time the incidence was last modified to @p lm. It is stored as a UTC date/time. @param lm is the KDateTime when the incidence was last modified. @see lastModified() */ virtual void setLastModified(const KDateTime &lm); /** Returns the time the incidence was last modified. @see setLastModified() */ KDateTime lastModified() const; /** Sets the organizer for the incidence. @param organizer is a non-null Person to use as the incidence @ref organizer. @see organizer(), setOrganizer(const QString &) */ void setOrganizer(const Person::Ptr &organizer); /** Sets the incidence organizer to any string @p organizer. @param organizer is a string to use as the incidence @ref organizer. @see organizer(), setOrganizer(const Person &) */ void setOrganizer(const QString &organizer); /** Returns the Person associated with this incidence. If no Person was set through setOrganizer(), a default Person() is returned. @see setOrganizer(const QString &), setOrganizer(const Person &) */ Person::Ptr organizer() const; /** Sets readonly status. @param readOnly if set, the incidence is read-only; else the incidence can be modified. @see isReadOnly(). */ virtual void setReadOnly(bool readOnly); /** Returns true the object is read-only; false otherwise. @see setReadOnly() */ bool isReadOnly() const; /** Sets the incidence's starting date/time with a KDateTime. The incidence's all-day status is set according to whether @p dtStart is a date/time (not all-day) or date-only (all-day). @param dtStart is the incidence start date/time. @see dtStart(). */ virtual void setDtStart(const KDateTime &dtStart); /** Returns an incidence's starting date/time as a KDateTime. @see setDtStart(). */ virtual KDateTime dtStart() const; /** Sets the incidence duration. @param duration the incidence duration @see duration() */ virtual void setDuration(const Duration &duration); /** Returns the length of the incidence duration. @see setDuration() */ Duration duration() const; /** Sets if the incidence has a duration. @param hasDuration true if the incidence has a duration; false otherwise. @see hasDuration() */ void setHasDuration(bool hasDuration); /** Returns true if the incidence has a duration; false otherwise. @see setHasDuration() */ bool hasDuration() const; /** Returns true or false depending on whether the incidence is all-day. i.e. has a date but no time attached to it. @see setAllDay() */ bool allDay() const; /** Sets whether the incidence is all-day, i.e. has a date but no time attached to it. @param allDay sets whether the incidence is all-day. @see allDay() */ void setAllDay(bool allDay); /** Shift the times of the incidence so that they appear at the same clock time as before but in a new time zone. The shift is done from a viewing time zone rather than from the actual incidence time zone. For example, shifting an incidence whose start time is 09:00 America/New York, using an old viewing time zone (@p oldSpec) of Europe/London, to a new time zone (@p newSpec) of Europe/Paris, will result in the time being shifted from 14:00 (which is the London time of the incidence start) to 14:00 Paris time. @param oldSpec the time specification which provides the clock times @param newSpec the new time specification */ virtual void shiftTimes(const KDateTime::Spec &oldSpec, const KDateTime::Spec &newSpec); /** Adds a comment to the incidence. Does not add a linefeed character; simply appends the text as specified. @param comment is the QString containing the comment to add. @see removeComment(). */ void addComment(const QString &comment); /** Removes a comment from the incidence. Removes the first comment whose string is an exact match for the specified string in @p comment. @param comment is the QString containing the comment to remove. @return true if match found, false otherwise. @see addComment(). */ bool removeComment(const QString &comment); /** Deletes all incidence comments. */ void clearComments(); /** Returns all incidence comments as a list of strings. */ QStringList comments() const; /** Adds a contact to thieincidence. Does not add a linefeed character; simply appends the text as specified. @param contact is the QString containing the contact to add. @see removeContact(). */ void addContact(const QString &contact); /** Removes a contact from the incidence. Removes the first contact whose string is an exact match for the specified string in @p contact. @param contact is the QString containing the contact to remove. @return true if match found, false otherwise. @see addContact(). */ bool removeContact(const QString &contact); /** Deletes all incidence contacts. */ void clearContacts(); /** Returns all incidence contacts as a list of strings. */ QStringList contacts() const; /** Add Attendee to this incidence. IncidenceBase takes ownership of the Attendee object. @param attendee a pointer to the attendee to add @param doUpdate If true the Observers are notified, if false they are not. */ void addAttendee(const Attendee::Ptr &attendee, bool doUpdate = true); /** Removes all attendees from the incidence. */ void clearAttendees(); /** Delete single attendee from the incidence. The given attendee will be delete()d at the end of this call. @param attendee The attendee to be removeComment @param doUpdate If true the Observers are notified, if false they are not. */ void deleteAttendee(const Attendee::Ptr &attendee, bool doUpdate = true); /** Returns a list of incidence attendees. All pointers in the list are valid. */ Attendee::List attendees() const; /** Returns the number of incidence attendees. */ int attendeeCount() const; /** Returns the attendee with the specified email address. @param email is a QString containing an email address of the form "FirstName LastName ". @see attendeeByMails(), attendeesByUid(). */ Attendee::Ptr attendeeByMail(const QString &email) const; /** Returns the first incidence attendee with one of the specified email addresses. @param emails is a list of QStrings containing email addresses of the form "FirstName LastName ". @param email is a QString containing a single email address to search in addition to the list specified in @p emails. @see attendeeByMail(), attendeesByUid(). */ Attendee::Ptr attendeeByMails(const QStringList &emails, const QString &email = QString()) const; /** Returns the incidence attendee with the specified attendee @acronym UID. @param uid is a QString containing an attendee @acronym UID. @see attendeeByMail(), attendeeByMails(). */ Attendee::Ptr attendeeByUid(const QString &uid) const; /** Sets the incidences url. This property can be used to point to a more dynamic rendition of the incidence. I.e. a website related to the incidence. @param url of the incience. @see url() @since 4.12 */ void setUrl(const QUrl &url); /** Returns the url. @return incidences url value @see setUrl() @since 4.12 */ QUrl url() const; /** Register observer. The observer is notified when the observed object changes. @param observer is a pointer to an IncidenceObserver object that will be watching this incidence. @see unRegisterObserver() */ void registerObserver(IncidenceObserver *observer); /** Unregister observer. It isn't notified anymore about changes. @param observer is a pointer to an IncidenceObserver object that will be watching this incidence. @see registerObserver(). */ void unRegisterObserver(IncidenceObserver *observer); /** Call this to notify the observers after the IncidenceBase object will be changed. */ void update(); /** Call this to notify the observers after the IncidenceBase object has changed. */ void updated(); /** Call this when a group of updates is going to be made. This suppresses change notifications until endUpdates() is called, at which point updated() will automatically be called. */ void startUpdates(); /** Call this when a group of updates is complete, to notify observers that the instance has changed. This should be called in conjunction with startUpdates(). */ void endUpdates(); /** Returns a date/time corresponding to the specified DateTimeRole. @param role is a DateTimeRole. */ virtual KDateTime dateTime(DateTimeRole role) const = 0; /** Sets the date/time corresponding to the specified DateTimeRole. @param dateTime is KDateTime value to set. @param role is a DateTimeRole. */ virtual void setDateTime(const KDateTime &dateTime, DateTimeRole role) = 0; /** Returns the Akonadi specific sub MIME type of a KCalCore::IncidenceBase item, e.g. getting "application/x-vnd.akonadi.calendar.event" for a KCalCore::Event. */ virtual QLatin1String mimeType() const = 0; /** Returns the incidence recurrenceId. @return incidences recurrenceId value @see setRecurrenceId(). */ virtual KDateTime recurrenceId() const; /** Returns a QSet with all Fields that were changed since the incidence was created or resetDirtyFields() was called. @see resetDirtyFields() */ QSet dirtyFields() const; /** Sets which fields are dirty. @see dirtyFields() @since 4.8 */ void setDirtyFields(const QSet &); /** Resets dirty fields. @see dirtyFields() */ void resetDirtyFields(); /** * Constant that identifies KCalCore data in a binary stream. * * @since 4.12 */ static quint32 magicSerializationIdentifier(); protected: /** Marks Field @p field as dirty. @param field is the Field type to mark as dirty. @see dirtyFields() */ void setFieldDirty(IncidenceBase::Field field); /** @copydoc CustomProperties::customPropertyUpdate() */ virtual void customPropertyUpdate(); /** @copydoc CustomProperties::customPropertyUpdated() */ virtual void customPropertyUpdated(); /** Constructs an IncidenceBase as a copy of another IncidenceBase object. @param ib is the IncidenceBase to copy. */ IncidenceBase(const IncidenceBase &ib); /** Provides polymorfic comparison for equality. Only called by IncidenceBase::operator==() which guarantees that @p incidenceBase is of the right type. @param incidenceBase is the IncidenceBase to compare against. @return true if the incidences are equal; false otherwise. */ virtual bool equals(const IncidenceBase &incidenceBase) const; /** Provides polymorfic assignment. @param other is the IncidenceBase to assign. */ virtual IncidenceBase &assign(const IncidenceBase &other); /** Standard trick to add virtuals later. @param id is any integer unique to this class which we will use to identify the method to be called. @param data is a pointer to some glob of data, typically a struct. // TODO_KDE5: change from int to VirtualHook type. */ virtual void virtual_hook(int id, void *data) = 0; enum VirtualHook { SerializerHook, DeserializerHook }; /** Identifies a read-only incidence. */ bool mReadOnly; private: //@cond PRIVATE class Private; Private *const d; //@endcond friend KCALCORE_EXPORT QDataStream &operator<<(QDataStream &stream, const KCalCore::IncidenceBase::Ptr &); friend KCALCORE_EXPORT QDataStream &operator>>(QDataStream &stream, const KCalCore::IncidenceBase::Ptr &); }; /** * Incidence serializer. * Uses the virtual_hook internally to avoid slicing. * * // TODO_KDE5: Provide a virtual serialize() method, as done with assign() and equals(). * * @since 4.12 */ KCALCORE_EXPORT QDataStream &operator<<(QDataStream &out, const KCalCore::IncidenceBase::Ptr &); /** * Incidence deserializer. * Uses the virtual_hook internally to avoid slicing. * * // TODO_KDE5: Provide a virtual serialize() method, as done with assign() and equals(). * * @since 4.12 */ KCALCORE_EXPORT QDataStream &operator>>(QDataStream &in, const KCalCore::IncidenceBase::Ptr &); } Q_DECLARE_METATYPE(KCalCore::IncidenceBase *) Q_DECLARE_METATYPE(KCalCore::IncidenceBase::Ptr) #endif diff --git a/kcalcore/recurrencerule.h b/kcalcore/recurrencerule.h index 991d9d7..7f93cde 100644 --- a/kcalcore/recurrencerule.h +++ b/kcalcore/recurrencerule.h @@ -1,348 +1,348 @@ /* This file is part of the kcalcore library. Copyright (c) 1998 Preston Brown Copyright (c) 2001,2003 Cornelius Schumacher Copyright (c) 2002,2006,2007 David Jarvie Copyright (c) 2005, Reinhold Kainhofer 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. */ #ifndef KCALCORE_RECURRENCERULE_H #define KCALCORE_RECURRENCERULE_H #include "kcalcore_export.h" #include "sortablelist.h" -#include +#include namespace KCalCore { // These two are duplicates wrt. incidencebase.h typedef SortableList DateTimeList; typedef SortableList DateList; /* List of times */ typedef SortableList TimeList; /** This class represents a recurrence rule for a calendar incidence. */ class KCALCORE_EXPORT RecurrenceRule { public: class RuleObserver { public: virtual ~RuleObserver(); /** This method is called on each change of the recurrence object */ virtual void recurrenceChanged(RecurrenceRule *) = 0; }; typedef QList List; /** enum for describing the frequency how an event recurs, if at all. */ enum PeriodType { rNone = 0, rSecondly, rMinutely, rHourly, rDaily, rWeekly, rMonthly, rYearly }; /** structure for describing the n-th weekday of the month/year. */ class KCALCORE_EXPORT WDayPos //krazy:exclude=dpointer { public: explicit WDayPos(int ps = 0, short dy = 0); void setDay(short dy); short day() const; void setPos(int ps); int pos() const; bool operator==(const RecurrenceRule::WDayPos &pos2) const; bool operator!=(const RecurrenceRule::WDayPos &pos2) const; protected: short mDay; // Weekday, 1=monday, 7=sunday int mPos; // week of the day (-1 for last, 1 for first, 0 for all weeks) // Bounded by -366 and +366, 0 means all weeks in that period friend KCALCORE_EXPORT QDataStream& operator<<(QDataStream &out, const KCalCore::RecurrenceRule::WDayPos &); friend KCALCORE_EXPORT QDataStream& operator>>(QDataStream &in, KCalCore::RecurrenceRule::WDayPos &); }; // Q_DECLARE_TYPEINFO(RecurrenceRule::WDayPos, Q_MOVABLE_TYPE) TODO_KDE5 RecurrenceRule(); RecurrenceRule(const RecurrenceRule &r); ~RecurrenceRule(); bool operator==(const RecurrenceRule &r) const; bool operator!=(const RecurrenceRule &r) const { return !operator==(r); } RecurrenceRule &operator=(const RecurrenceRule &r); /** Set if recurrence is read-only or can be changed. */ void setReadOnly(bool readOnly); /** Returns true if the recurrence is read-only; false if it can be changed. */ bool isReadOnly() const; /** Returns the event's recurrence status. See the enumeration at the top of this file for possible values. */ bool recurs() const; void setRecurrenceType(PeriodType period); PeriodType recurrenceType() const; /** Turns off recurrence for the event. */ void clear(); /** Returns the recurrence frequency, in terms of the recurrence time period type. */ uint frequency() const; /** Sets the recurrence frequency, in terms of the recurrence time period type. */ void setFrequency(int freq); /** Returns the recurrence start date/time. Note that the recurrence does not necessarily occur on the start date/time. For this to happen, it must actually match the rule. */ KDateTime startDt() const; /** Sets the recurrence start date/time. Note that setting the start date/time does not make the recurrence occur on that date/time, it simply sets a lower limit to when the recurrences take place (this applies only for the by- rules, not for i.e. an hourly rule where the startDt is the first occurrence). Note that setting @p start to a date-only value does not make an all-day recurrence: to do this, call setAllDay(true). @param start the recurrence's start date and time */ void setStartDt(const KDateTime &start); /** Returns whether the start date has no time associated. All-Day means -- according to rfc2445 -- that the event has no time associate. */ bool allDay() const; /** Sets whether the dtstart is all-day (i.e. has no time attached) * * @param allDay Whether start datetime is all-day */ void setAllDay(bool allDay); /** Returns the date and time of the last recurrence. * An invalid date is returned if the recurrence has no end. * @param result if non-null, *result is updated to true if successful, * or false if there is no recurrence or its end date cannot be determined. */ KDateTime endDt(bool *result = 0) const; /** Sets the date and time of the last recurrence. * @param endDateTime the ending date/time after which to stop recurring. */ void setEndDt(const KDateTime &endDateTime); /** * Returns -1 if the event recurs infinitely, 0 if the end date is set, * otherwise the total number of recurrences, including the initial occurrence. */ int duration() const; /** Sets the total number of times the event is to occur, including both the * first and last. */ void setDuration(int duration); /** Returns the number of recurrences up to and including the date/time specified. */ int durationTo(const KDateTime &dt) const; /** Returns the number of recurrences up to and including the date specified. */ int durationTo(const QDate &date) const; /** Shift the times of the rule so that they appear at the same clock time as before but in a new time zone. The shift is done from a viewing time zone rather than from the actual rule time zone. For example, shifting a rule whose start time is 09:00 America/New York, using an old viewing time zone (@p oldSpec) of Europe/London, to a new time zone (@p newSpec) of Europe/Paris, will result in the time being shifted from 14:00 (which is the London time of the rule start) to 14:00 Paris time. @param oldSpec the time specification which provides the clock times @param newSpec the new time specification */ void shiftTimes(const KDateTime::Spec &oldSpec, const KDateTime::Spec &newSpec); /** Returns true if the date specified is one on which the event will * recur. The start date returns true only if it actually matches the rule. * * @param date date to check * @param timeSpec time specification for @p date */ bool recursOn(const QDate &date, const KDateTime::Spec &timeSpec) const; /** Returns true if the date/time specified is one at which the event will * recur. Times are rounded down to the nearest minute to determine the result. * The start date/time returns true only if it actually matches the rule. * * @param dt the date+time to check for recurrency */ bool recursAt(const KDateTime &dt) const; /** Returns true if the date matches the rules. It does not necessarily mean that this is an actual occurrence. In particular, the method does not check if the date is after the end date, or if the frequency interval matches. @param dt the date+time to check for matching the rules */ bool dateMatchesRules(const KDateTime &dt) const; /** Returns a list of the times on the specified date at which the * recurrence will occur. The returned times should be interpreted in the * context of @p timeSpec. * @param date the date for which to find the recurrence times * @param timeSpec time specification for @p date */ TimeList recurTimesOn(const QDate &date, const KDateTime::Spec &timeSpec) const; /** Returns a list of all the times at which the recurrence will occur * between two specified times. * * There is a (large) maximum limit to the number of times returned. If due to * this limit the list is incomplete, this is indicated by the last entry being * set to an invalid KDateTime value. If you need further values, call the * method again with a start time set to just after the last valid time returned. * @param start inclusive start of interval * @param end inclusive end of interval * @return list of date/time values */ DateTimeList timesInInterval(const KDateTime &start, const KDateTime &end) const; /** Returns the date and time of the next recurrence, after the specified date/time. * If the recurrence has no time, the next date after the specified date is returned. * @param preDateTime the date/time after which to find the recurrence. * @return date/time of next recurrence, or invalid date if none. */ KDateTime getNextDate(const KDateTime &preDateTime) const; /** Returns the date and time of the last previous recurrence, before the specified date/time. * If a time later than 00:00:00 is specified and the recurrence has no time, 00:00:00 on * the specified date is returned if that date recurs. * @param afterDateTime the date/time before which to find the recurrence. * @return date/time of previous recurrence, or invalid date if none. */ KDateTime getPreviousDate(const KDateTime &afterDateTime) const; void setBySeconds(const QList &bySeconds); void setByMinutes(const QList &byMinutes); void setByHours(const QList &byHours); void setByDays(const QList &byDays); void setByMonthDays(const QList &byMonthDays); void setByYearDays(const QList &byYearDays); void setByWeekNumbers(const QList &byWeekNumbers); void setByMonths(const QList &byMonths); void setBySetPos(const QList &bySetPos); void setWeekStart(short weekStart); const QList &bySeconds() const; const QList &byMinutes() const; const QList &byHours() const; const QList &byDays() const; const QList &byMonthDays() const; const QList &byYearDays() const; const QList &byWeekNumbers() const; const QList &byMonths() const; const QList &bySetPos() const; short weekStart() const; /** Set the RRULE string for the rule. This is merely stored for future reference. The string is not used in any way by the RecurrenceRule. @param rrule the RRULE string */ void setRRule(const QString &rrule); QString rrule() const; void setDirty(); /** Installs an observer. Whenever some setting of this recurrence object is changed, the recurrenceUpdated( Recurrence* ) method of each observer will be called to inform it of changes. @param observer the Recurrence::Observer-derived object, which will be installed as an observer of this object. */ void addObserver(RuleObserver *observer); /** Removes an observer that was added with addObserver. If the given object was not an observer, it does nothing. @param observer the Recurrence::Observer-derived object to be removed from the list of observers of this object. */ void removeObserver(RuleObserver *observer); /** Debug output. */ void dump() const; private: //@cond PRIVATE class Private; Private *const d; //@endcond friend KCALCORE_EXPORT QDataStream& operator<<(QDataStream &out, const KCalCore::RecurrenceRule *); friend KCALCORE_EXPORT QDataStream& operator>>(QDataStream &in, const KCalCore::RecurrenceRule *); }; /** * RecurrenceRule serializer and deserializer. * @since 4.12 */ KCALCORE_EXPORT QDataStream& operator<<(QDataStream &out, const KCalCore::RecurrenceRule *); KCALCORE_EXPORT QDataStream& operator>>(QDataStream &in, const KCalCore::RecurrenceRule *); /** * RecurrenceRule::WDayPos serializer and deserializer. * @since 4.12 */ KCALCORE_EXPORT QDataStream& operator<<(QDataStream &out, const KCalCore::RecurrenceRule::WDayPos &); KCALCORE_EXPORT QDataStream& operator>>(QDataStream &in, KCalCore::RecurrenceRule::WDayPos &); } #endif