home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / libkcal / recurrence.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-09-10  |  22.5 KB  |  514 lines
  1. /*
  2.     This file is part of libkcal.
  3.  
  4.     Copyright (c) 1998 Preston Brown <pbrown@kde.org>
  5.     Copyright (c) 2001,2003 Cornelius Schumacher <schumacher@kde.org>
  6.     Copyright (c) 2002 David Jarvie <software@astrojar.org.uk>
  7.     Copyright (C) 2005 Reinhold Kainhofer <reinhold@kainhofer.com>
  8.  
  9.     This library is free software; you can redistribute it and/or
  10.     modify it under the terms of the GNU Library General Public
  11.     License as published by the Free Software Foundation; either
  12.     version 2 of the License, or (at your option) any later version.
  13.  
  14.     This library is distributed in the hope that it will be useful,
  15.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  16.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17.     Library General Public License for more details.
  18.  
  19.     You should have received a copy of the GNU Library General Public License
  20.     along with this library; see the file COPYING.LIB.  If not, write to
  21.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  22.     Boston, MA 02110-1301, USA.
  23. */
  24. #ifndef KCAL_RECURRENCE_H
  25. #define KCAL_RECURRENCE_H
  26.  
  27. #include <qstring.h>
  28. #include <qbitarray.h>
  29. #include <qptrlist.h>
  30.  
  31. #include "libkcal_export.h"
  32. #include "recurrencerule.h"
  33.  
  34. namespace KCal {
  35.  
  36. class RecurrenceRule;
  37.  
  38. /**
  39.   This class represents a recurrence rule for a calendar incidence.
  40.  
  41.   It manages all recurrence rules, recurrence date/times, exception rules
  42.   and exception date times that can appear inside calendar items.
  43.   Each recurrence rule and exception rule is represented as an object
  44.   of type RecurrenceRule.
  45.  
  46.   For the simple case where at most one recurrence
  47.   rule is present, this class provides shortcut methods to set the type:
  48.     setMinutely()
  49.     setHourly()
  50.     setDaily()
  51.     setWeekly()
  52.     setMonthly()
  53.     setYearly()
  54.   to set/get general information about the recurrence:
  55.     setEndDate()
  56.     setEndDateTime()
  57.     duration()
  58.     durationTo()
  59.     setDuration()
  60.     frequency()
  61.     setFrequency()
  62.   and to set/get specific information about the recurrence within the interval:
  63.     days()
  64.     monthDays()
  65.     monthPositions()
  66.     yearDays()
  67.     yearDates()
  68.     yearMonths()
  69.     yearPositions()
  70.     addMonthlyPos()
  71.     addMonthlyDate()
  72.     addYearlyDay()
  73.     addYearlyDate()
  74.     addYearlyPos()
  75.     addYearlyMonth()
  76.   These are all available so that you don't have to work on the RecurrenceRule
  77.   objects themselves.
  78.   In other words, in that simple situation the interface stays almost the
  79.   same compared to the old Recurrence class, which allowed only one
  80.   recurrence rule.
  81.  
  82.   As soon as your recurrence consists of multiple recurrence rules or exception
  83.   rules, you cannot use the methods mentioned above any more (since each rule
  84.   will have a different type and different settings). If you still call
  85.   any of them, the set*ly methods will remove all rules and add one rule with
  86.   the specified type. The add* and the other set* methods will change only
  87.   the first recurrence rule, but leave the others untouched.
  88. */
  89. class LIBKCAL_EXPORT Recurrence : public RecurrenceRule::Observer
  90. {
  91.   public:
  92.     class Observer {
  93.       public:
  94.         virtual ~Observer() {}
  95.         /** This method will be called on each change of the recurrence object */
  96.         virtual void recurrenceUpdated( Recurrence * ) = 0;
  97.     };
  98.  
  99.     /** enumeration for describing how an event recurs, if at all. */
  100.     enum { rNone = 0, rMinutely = 0x001, rHourly = 0x0002, rDaily = 0x0003,
  101.            rWeekly = 0x0004, rMonthlyPos = 0x0005, rMonthlyDay = 0x0006,
  102.            rYearlyMonth = 0x0007, rYearlyDay = 0x0008, rYearlyPos = 0x0009,
  103.            rOther = 0x000A, rMax=0x00FF };
  104.  
  105.     Recurrence();
  106.     Recurrence( const Recurrence& );
  107.     virtual ~Recurrence();
  108.  
  109.     bool operator==( const Recurrence& ) const;
  110.     bool operator!=( const Recurrence& r ) const  { return !operator==(r); }
  111.  
  112.     /** Return the start date/time of the recurrence (Time for floating incidences will be 0:00).
  113.      @return the current start/time of the recurrence. */
  114.     QDateTime startDateTime() const;
  115.     /** Return the start date/time of the recurrence */
  116.     QDate startDate() const   { return mStartDateTime.date(); }
  117.     /** Set start of recurrence, as a date and time. Also sets the incidence to non-floating.
  118.        @param start the new start date/time of the incidence.
  119.     */
  120.     void setStartDateTime( const QDateTime &start );
  121.     /** Set start of recurrence, as a date. Also sets the incidence to floating.
  122.        @param start The new start date of the incidence.
  123.     */
  124.     void setStartDate( const QDate &start );
  125.  
  126.     /** Set whether the recurrence has no time, just a date.
  127.      * Floating means -- according to rfc2445 -- that the event has no time
  128.      * associated.
  129.      * N.B. This property is derived by default from whether setStartDateTime() or
  130.      * setStartDate() is called.
  131.      * @return whether the recurrence has a time (false) or it is just a date (true). */
  132.     bool doesFloat() const { return mFloating; }
  133.     /** Sets whether the dtstart is a floating time (i.e. has no time attached)
  134.        @param floats If the recurrence is for all-day item (true) or has a time associated (false).
  135.        */
  136.     void setFloats( bool floats );
  137.  
  138.     /** Set if recurrence is read-only or can be changed. */
  139.     void setRecurReadOnly(bool readOnly) { mRecurReadOnly = readOnly; }
  140.     /** Returns true if the recurrence is read-only, or false if it can be changed. */
  141.     bool recurReadOnly() const  { return mRecurReadOnly; }
  142.  
  143.     /** Returns whether the event recurs at all. */
  144.     bool doesRecur() const;
  145.     /** Returns the event's recurrence status.  See the enumeration at the top
  146.      * of this file for possible values. */
  147.     ushort recurrenceType() const;
  148.     /** Returns the recurrence status for a recurrence rule.
  149.      * See the enumeration at the top of this file for possible values. */
  150.     static ushort recurrenceType( const RecurrenceRule *rrule );
  151.     /** Returns true if the date specified is one on which the event will
  152.      * recur. */
  153.     bool recursOn( const QDate &qd ) const;
  154.     /** Returns true if the date/time specified is one at which the event will
  155.      * recur. Times are rounded down to the nearest minute to determine the result. */
  156.     bool recursAt( const QDateTime & ) const;
  157.     /** Removes all recurrence rules. Recurrence dates and exceptions are
  158.         not removed. */
  159.     void unsetRecurs();
  160.     /** Removes all recurrence and exception rules and dates. */
  161.     void clear();
  162.  
  163.     /** Returns a list of the times on the specified date at which the
  164.      * recurrence will occur.
  165.      * @param date the date for which to find the recurrence times.
  166.      */
  167.     QValueList<QTime> recurTimesOn(const QDate &date) const;
  168.  
  169.     /** Returns the date and time of the next recurrence, after the specified date/time.
  170.      * If the recurrence has no time, the next date after the specified date is returned.
  171.      * @param preDateTime the date/time after which to find the recurrence.
  172.      * @return date/time of next recurrence (strictly later than the given QDateTiem), or invalid date if none.
  173.      */
  174.     QDateTime getNextDateTime( const QDateTime& preDateTime ) const;
  175.     /** Returns the date and time of the last previous recurrence, before the specified date/time.
  176.      * If a time later than 00:00:00 is specified and the recurrence has no time, 00:00:00 on
  177.      * the specified date is returned if that date recurs.
  178.      * @param afterDateTime the date/time before which to find the recurrence.
  179.      * @return date/time of previous recurrence (strictly earlier than the given QDateTime), or invalid date if none.
  180.      */
  181.     QDateTime getPreviousDateTime( const QDateTime& afterDateTime ) const;
  182.  
  183.     /** Returns frequency of recurrence, in terms of the recurrence time period type. */
  184.     int frequency() const;
  185.     /** Sets the frequency of recurrence, in terms of the recurrence time period type. */
  186.     void setFrequency(int freq);
  187.  
  188.     /**
  189.      * Returns -1 if the event recurs infinitely, 0 if the end date is set,
  190.      * otherwise the total number of recurrences, including the initial occurrence.
  191.      */
  192.     int duration() const;
  193.     /** Sets the total number of times the event is to occur, including both the
  194.      * first and last. */
  195.     void setDuration(int duration);
  196.     /** Returns the number of recurrences up to and including the date/time specified. */
  197.     int durationTo(const QDateTime &) const;
  198.     /** Returns the number of recurrences up to and including the date specified. */
  199.     int durationTo( const QDate &date ) const { return durationTo( QDateTime( date, QTime( 23, 59, 59 ) ) ); }
  200.  
  201.     /** Returns the date/time of the last recurrence.
  202.      * An invalid date is returned if the recurrence has no end.
  203.      */
  204.     QDateTime endDateTime() const;
  205.     /** Returns the date of the last recurrence.
  206.      * An invalid date is returned if the recurrence has no end.
  207.      */
  208.     QDate endDate() const;
  209.     /** Sets the date of the last recurrence. The end time is set to the recurrence start time.
  210.      * @param endDate the ending date after which to stop recurring. If the
  211.      *   incidence is not floating, the end time will be 23:59.*/
  212.     void setEndDate( const QDate &endDate );
  213.     /** Sets the date and time of the last recurrence.
  214.      * @param endDateTime the ending date/time after which to stop recurring. */
  215.     void setEndDateTime( const QDateTime &endDateTime );
  216.  
  217.  
  218.  
  219.     /** Sets an event to recur minutely. By default infinite recurrence is used.
  220.         To set an end date use the method setEndDate and to set the number
  221.         of occurrences use setDuration.
  222.  
  223.         This method clears all recurrence rules and adds one rule with a
  224.         minutely recurrence. All other recurrence components (recurrence
  225.         date/times, exception date/times and exception rules) are not
  226.         modified.
  227.      * @param freq the frequency to recur, e.g. 2 is every other minute
  228.      */
  229.     void setMinutely( int freq );
  230.  
  231.     /** Sets an event to recur hourly. By default infinite recurrence is used.
  232.         The minute of the recurrence is taken from the start date (if you
  233.         need to change it, you will have to modify the defaultRRule's
  234.         byMinute list manually.
  235.         To set an end date use the method setEndDate and to set the number
  236.         of occurrences use setDuration.
  237.  
  238.         This method clears all recurrence rules and adds one rule with a
  239.         hourly recurrence. All other recurrence components (recurrence
  240.         date/times, exception date/times and exception rules) are not
  241.         modified.
  242.      * @param freq the frequency to recur, e.g. 2 is every other hour
  243.      */
  244.     void setHourly( int freq );
  245.  
  246.     /** Sets an event to recur daily. By default infinite recurrence is used.
  247.         The minute and second of the recurrence is taken from the start date
  248.         (if you need to change them, you will have to modify the defaultRRule's
  249.         byMinute list manually.
  250.         To set an end date use the method setEndDate and to set the number
  251.         of occurrences use setDuration.
  252.  
  253.         This method clears all recurrence rules and adds one rule with a
  254.         daily recurrence. All other recurrence components (recurrence
  255.         date/times, exception date/times and exception rules) are not
  256.         modified.
  257.      * @param freq the frequency to recur, e.g. 2 is every other day
  258.      */
  259.     void setDaily( int freq );
  260.  
  261.     /** Sets an event to recur weekly. By default infinite recurrence is used.
  262.         To set an end date use the method setEndDate and to set the number
  263.         of occurrences use setDuration.
  264.  
  265.         This method clears all recurrence rules and adds one rule with a
  266.         weekly recurrence. All other recurrence components (recurrence
  267.         date/times, exception date/times and exception rules) are not
  268.         modified.
  269.      * @param freq the frequency to recur, e.g. every other week etc.
  270.      * @param weekStart the first day of the week (Monday=1 .. Sunday=7, default is Monday).
  271.      */
  272.     void setWeekly( int freq, int weekStart = 1 );
  273.     /** Sets an event to recur weekly. By default infinite recurrence is used.
  274.         To set an end date use the method setEndDate and to set the number
  275.         of occurrences use setDuration.
  276.  
  277.         This method clears all recurrence rules and adds one rule with a
  278.         weekly recurrence. All other recurrence components (recurrence
  279.         date/times, exception date/times and exception rules) are not
  280.         modified.
  281.      * @param freq the frequency to recur, e.g. every other week etc.
  282.      * @param days a 7 bit array indicating which days on which to recur (bit 0 = Monday).
  283.      * @param weekStart the first day of the week (Monday=1 .. Sunday=7, default is Monday).
  284.      */
  285.     void setWeekly( int freq, const QBitArray &days, int weekStart = 1 );
  286.     /** Adds days to the weekly day recurrence list.
  287.      * @param days a 7 bit array indicating which days on which to recur (bit 0 = Monday).
  288.      */
  289.     void addWeeklyDays( const QBitArray &days );
  290.     /** Returns the first day of the week.  Uses only the
  291.      * first RRULE if present (i.e. a second RRULE as well as all EXRULES are
  292.      * ignored!
  293.      * @return Weekday of the first day of the week (Monday=1 .. Sunday=7)
  294.      */
  295.     int weekStart() const;
  296.     /** Returns week day mask (bit 0 = Monday). */
  297.     QBitArray days() const; // Emulate the old behavior
  298.  
  299.     /** Sets an event to recur monthly. By default infinite recurrence is used.
  300.         The date of the monthly recurrence will be taken from the start date
  301.         unless you explicitly add one or more recurrence dates with
  302.         addMonthlyDate or a recurrence position in the month (e.g. first
  303.         monday) using addMonthlyPos.
  304.         To set an end date use the method setEndDate and to set the number
  305.         of occurrences use setDuration.
  306.  
  307.         This method clears all recurrence rules and adds one rule with a
  308.         monthly recurrence. All other recurrence components (recurrence
  309.         date/times, exception date/times and exception rules) are not
  310.         modified.
  311.      * @param freq the frequency to recur, e.g. 3 for every third month.
  312.      */
  313.     void setMonthly( int freq );
  314.     /** Adds a position (e.g. first monday) to the monthly recurrence rule.
  315.      * @param pos the position in the month for the recurrence, with valid
  316.      * values being 1-5 (5 weeks max in a month).
  317.      * @param days the days for the position to recur on (bit 0 = Monday).
  318.      * Example: pos = 2, and bits 0 and 2 are set in days:
  319.      * the rule is to repeat every 2nd Monday and Wednesday in the month.
  320.      */
  321.     void addMonthlyPos( short pos, const QBitArray &days );
  322.     void addMonthlyPos( short pos, ushort day );
  323.     /** Adds a date (e.g. the 15th of each month) to the monthly day
  324.      *  recurrence list.
  325.      * @param day the date in the month to recur.
  326.      */
  327.     void addMonthlyDate( short day );
  328.     /** Returns list of day positions in months. */
  329.     QValueList<RecurrenceRule::WDayPos> monthPositions() const;
  330.     /** Returns list of day numbers of a  month. */
  331.     // Emulate old behavior
  332.     QValueList<int> monthDays() const;
  333.  
  334.     /** Sets an event to recur yearly. By default, this will recur every year
  335.      *  on the same date (e.g. every year on April 15 if the start date was
  336.      *  April 15).
  337.      *  The day of the year can be specified with addYearlyDay().
  338.      *  The day of the month can be specified with addYearlyByDate
  339.      *  If both a month and a day ar specified with addYearlyMonth and
  340.      *  addYearlyDay, the day is understood as day number within the month.
  341.      *
  342.      *  A position (e.g. 3rd Sunday of year/month, or last Friday of year/month)
  343.      *  can be specified with addYearlyPos. Again, if a month is specified,
  344.      *  this position is understood as within that month, otherwise within
  345.      *  the year.
  346.      *
  347.      *  By default infinite recurrence is used. To set an end date use the
  348.      *  method setEndDate and to set the number of occurrences use setDuration.
  349.  
  350.         This method clears all recurrence rules and adds one rule with a
  351.         yearly recurrence. All other recurrence components (recurrence
  352.         date/times, exception date/times and exception rules) are not
  353.         modified.
  354.      * @param freq the frequency to recur, e.g. 3 for every third year.
  355.      */
  356.     void setYearly( int freq );
  357.     /** Adds day number of year within a yearly recurrence.
  358.      *  By default infinite recurrence is used. To set an end date use the
  359.      *  method setEndDate and to set the number of occurrences use setDuration.
  360.      * @param day the day of the year for the event. E.g. if day is 60, this
  361.      *            means Feb 29 in leap years and March 1 in non-leap years.
  362.      */
  363.     void addYearlyDay( int day );
  364.     /** Adds date within a yearly recurrence. The month(s) for the recurrence
  365.      *  can be specified with addYearlyMonth(), otherwise the month of the
  366.      *  start date is used.
  367.      *
  368.      *   By default infinite recurrence is used. To set an end date use the
  369.      *   method setEndDate and to set the number of occurrences use setDuration.
  370.      * @param date the day of the month for the event
  371.      */
  372.     void addYearlyDate( int date );
  373.     /** Adds month in yearly recurrence. You can specify specific day numbers
  374.      *  within the months (by calling addYearlyDate()) or specific day positions
  375.      *  within the month (by calling addYearlyPos).
  376.      * @param _rNum the month in which the event shall recur.
  377.      */
  378.     void addYearlyMonth( short _rNum );
  379.     /** Adds position within month/year within a yearly recurrence. If months
  380.      *  are specified (via addYearlyMonth()), the parameters are understood as
  381.      *  position within these months, otherwise within the year.
  382.      *
  383.      *  By default infinite recurrence is used.
  384.      *   To set an end date use the method setEndDate and to set the number
  385.      *   of occurrences use setDuration.
  386.      * @param pos the position in the month/year for the recurrence, with valid
  387.      * values being 1 to 53 and -1 to -53 (53 weeks max in a year).
  388.      * @param days the days for the position to recur on (bit 0 = Monday).
  389.      * Example: pos = 2, and bits 0 and 2 are set in days
  390.      *   If months are specified (via addYearlyMonth), e.g. March, the rule is
  391.      *   to repeat every year on the 2nd Monday and Wednesday of March.
  392.      *   If no months are specified, the fule is to repeat every year on the
  393.      *   2nd Monday and Wednesday of the year.
  394.      */
  395.     void addYearlyPos( short pos, const QBitArray &days );
  396.  
  397.     /** Returns the day numbers within a yearly recurrence.
  398.      * @return the days of the year for the event. E.g. if the list contains
  399.      *         60, this means the recurrence happens on day 60 of the year, i.e.
  400.      *         on Feb 29 in leap years and March 1 in non-leap years.
  401.      */
  402.     QValueList<int> yearDays() const;
  403.     /** Returns the dates within a yearly recurrence.
  404.      * @return the days of the month for the event. E.g. if the list contains
  405.      *         13, this means the recurrence happens on the 13th of the month.
  406.      *         The months for the recurrence can be obtained through
  407.      *         yearlyMonths(). If this list is empty, the month of the start
  408.      *         date is used.
  409.      */
  410.     QValueList<int> yearDates() const;
  411.     /** Returns the months within a yearly recurrence.
  412.      * @return the months for the event. E.g. if the list contains
  413.      *         11, this means the recurrence happens in November.
  414.      *         The days for the recurrence can be obtained either through
  415.      *         yearDates() if they are given as dates within the month or
  416.      *         through yearlyPositions() if they are given as positions within the
  417.      *         month. If none is specified, the date of the start date is used.
  418.      */
  419.     QValueList<int> yearMonths() const;
  420.     /** Returns the positions within a yearly recurrence.
  421.      * @return the positions for the event, either within a month (if months
  422.      *         are set through addYearlyMonth()) or within the year.
  423.      *         E.g. if the list contains {Pos=3, Day=5}, this means the third
  424.      *         friday. If a month is set this position is understoodas third
  425.      *         Friday in the given months, otherwise as third Friday of the
  426.      *         year.
  427.      */
  428.     /** Returns list of day positions in months, for a recursYearlyPos recurrence rule. */
  429.     QValueList<RecurrenceRule::WDayPos> yearPositions() const;
  430.  
  431.     /** Upper date limit for recurrences */
  432.     static const QDate MAX_DATE;
  433.  
  434.     /**
  435.       Debug output.
  436.     */
  437.     void dump() const;
  438.  
  439.  
  440.     // RRULE
  441.     RecurrenceRule::List rRules() const;
  442.     void addRRule( RecurrenceRule *rrule );
  443.     void removeRRule( RecurrenceRule *rrule );
  444.     // EXRULE
  445.     RecurrenceRule::List exRules() const;
  446.     void addExRule( RecurrenceRule *exrule );
  447.     void removeExRule( RecurrenceRule *exrule );
  448.  
  449.     // RDATE
  450.     DateTimeList rDateTimes() const;
  451.     DateList rDates() const;
  452.     void setRDateTimes( const DateTimeList &rdates);
  453.     void setRDates( const DateList &rdates);
  454.     void addRDateTime( const QDateTime &rdate );
  455.     void addRDate( const QDate &rdate );
  456.  
  457.     // ExDATE
  458.     DateTimeList exDateTimes() const;
  459.     DateList exDates() const;
  460.     void setExDateTimes( const DateTimeList &exdates);
  461.     void setExDates( const DateList &exdates);
  462.     void addExDateTime( const QDateTime &exdate );
  463.     void addExDate( const QDate &exdate );
  464.  
  465.     RecurrenceRule *defaultRRule( bool create = false ) const;
  466.     RecurrenceRule *defaultRRuleConst() const;
  467.     void updated();
  468.  
  469.     /**
  470.       Installs an observer. Whenever some setting of this recurrence
  471.       object is changed, the recurrenceUpdated( Recurrence* ) method
  472.       of each observer will be called to inform it of changes.
  473.       @param observer the Recurrence::Observer-derived object, which
  474.       will be installed as an observer of this object.
  475.     */
  476.     void addObserver( Observer *observer );
  477.     /**
  478.       Removes an observer that was added with addObserver. If the
  479.       given object was not an observer, it does nothing.
  480.       @param observer the Recurrence::Observer-derived object to
  481.       be removed from the list of observers of this object.
  482.     */
  483.     void removeObserver( Observer *observer );
  484.  
  485.     void recurrenceChanged( RecurrenceRule * );
  486.  
  487.   protected:
  488.     RecurrenceRule *setNewRecurrenceType( RecurrenceRule::PeriodType type, int freq );
  489.  
  490.   private:
  491.     RecurrenceRule::List mExRules;
  492.     RecurrenceRule::List mRRules;
  493.     QValueList<QDateTime>mRDateTimes;
  494.     QValueList<QDate> mRDates;
  495.     QValueList<QDateTime> mExDateTimes;
  496.     QValueList<QDate> mExDates;
  497.  
  498.     QDateTime mStartDateTime;            // date/time of first recurrence
  499.     bool mFloating;                      // the recurrence has no time, just a date
  500.     bool mRecurReadOnly;
  501.  
  502.     // Cache the type of the recurrence with the old system (e.g. MonthlyPos)
  503.     mutable ushort mCachedType;
  504.  
  505.     QValueList<Observer*> mObservers;
  506.  
  507.     class Private;
  508.     Private *d;
  509. };
  510.  
  511. }
  512.  
  513. #endif
  514.