libkdeedu/extdate/extcalendarsystem.h

   1 /*
   2    Copyright (c) 2002 Carlos Moro <cfmoro@correo.uniovi.es>
   3    Copyright (c) 2002-2003 Hans Petter Bieker <bieker@kde.org>
   4    Copyright (c) 2004 Jason Harris <jharris@30doradus.org>
   5
   6          This class has been derived from KCalendarSystem;
   7          the changesd made just replace QDate objects with ExtDate objects.
   8          These changes by Jason Harris <jharris@30doradus.org>
   9
  10    This library is free software; you can redistribute it and/or
  11    modify it under the terms of the GNU Library General Public
  12    License as published by the Free Software Foundation; either
  13    version 2 of the License, or (at your option) any later version.
  14
  15    This library is distributed in the hope that it will be useful,
  16    but WITHOUT ANY WARRANTY; without even the implied warranty of
  17    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18    Library General Public License for more details.
  19
  20    You should have received a copy of the GNU Library General Public License
  21    along with this library; see the file COPYING.LIB.  If not, write to
  22    the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  23    Boston, MA 02111-1307, USA.
  24 */
  25
  26 #ifndef EXTCALENDARSYSTEM_H
  27 #define EXTCALENDARSYSTEM_H
  28
  29 #include "extdatetime.h"
  30
  31 class KLocale;
  32
  33 class ExtCalendarSystemPrivate;
  34
  35 /**
  36  * CalendarSystem abstract class, default derived kde gregorian class and
  37  * factory class. Provides support for different calendar types for kde
  38  * calendar widget and related stuff.
  39  *
  40  * Derived classes must be created through ExtCalendarFactory class
  41  *
  42  * @author Carlos Moro <cfmoro@correo.uniovi.es>
  43  * @version $Id$
  44  * @since 3.2
  45  */
  46 class ExtCalendarSystem
  47 {
  48 public:
  49   /**
  50    * Constructor of abstract calendar class. This will be called by the derived classes.
  51    *
  52    * @param locale It will use this locale for translations, 0 means global.
  53    */
  54   ExtCalendarSystem(const KLocale * locale = 0);
  55
  56   /**
  57    * Descructor.
  58    */
  59   virtual ~ExtCalendarSystem();
  60
  61   /**
  62    * Gets specific calendar type year for a given gregorian date
  63    *
  64    * @param date gregorian date
  65    * @return year
  66    */
  67   virtual int year (const ExtDate & date) const = 0;
  68
  69   /**
  70    * Converts a date into a year literal
  71    *
  72    * @param pDate The date to convert
  73    * @param bShort If the short version of should be used
  74    * @return The year literal of the date
  75    */
  76   virtual QString yearString(const ExtDate & pDate, bool bShort) const;
  77
  78   /**
  79    * Converts a year literal of a part of a string into a integer starting at the beginning of the string
  80    *
  81    * @param sNum The string to parse
  82    * @param iLength The number of QChars used, and 0 if no valid symbols was found in the string
  83    * @return An integer corresponding to the year
  84    */
  85   virtual int yearStringToInteger(const QString & sNum, int & iLength) const;
  86
  87   /**
  88    * Gets specific calendar type month for a given gregorian date
  89    *
  90    * @param date gregorian date
  91    * @return month number
  92    */
  93   virtual int month (const ExtDate & date) const = 0;
  94
  95   /**
  96    * Converts a date into a month literal
  97    *
  98    * @param pDate The date to convert
  99    * @param bShort If the short version of should be used
 100    * @return The month literal of the date
 101    */
 102   virtual QString monthString(const ExtDate & pDate, bool bShort) const;
 103
 104   /**
 105    * Converts a month literal of a part of a string into a integer starting at the beginning of the string
 106    *
 107    * @param sNum The string to parse
 108    * @param iLength The number of QChars used, and 0 if no valid symbols was found in the string
 109    * @return An integer corresponding to the month
 110    */
 111   virtual int monthStringToInteger(const QString & sNum, int & iLength) const;
 112
 113   /**
 114    * Gets specific calendar type day number of month for a given date
 115    *
 116    * @param date gregorian date equivalent to the specific one
 117    * @return day of the month
 118    */
 119   virtual int day (const ExtDate & date) const = 0;
 120
 121   /**
 122    * Converts a date into a day literal
 123    *
 124    * @param pDate The date to convert
 125    * @param bShort If the short version of should be used
 126    * @return The day literal of the date
 127    */
 128   virtual QString dayString(const ExtDate & pDate, bool bShort) const;
 129
 130   /**
 131    * Converts a day literal of a part of a string into a integer starting at the beginning of the string
 132    *
 133    * @param sNum The string to parse
 134    * @param iLength The number of QChars used, and 0 if no valid symbols was found in the string
 135    * @return An integer corresponding to the day
 136    */
 137   virtual int dayStringToInteger(const QString & sNum, int & iLength) const;
 138
 139   /**
 140    * Gets specific calendar type number of day of week number for a given
 141    * date
 142    *
 143    * @param date gregorian date
 144    * @return day of week
 145    */
 146   virtual int dayOfWeek (const ExtDate & date) const = 0;
 147
 148   /**
 149    * Gets specific calendar type day number of year for a given date
 150    *
 151    * @param date gregorian date equivalent to the specific one
 152    * @return day number
 153    */
 154   virtual int dayOfYear (const ExtDate & date) const = 0;
 155
 156   /**
 157    * Changes the date's year, month and day. The range of the year, month
 158    * and day depends on which calendar is being used.
 159    *
 160    * @param date Date to change
 161    * @param y Year
 162    * @param m Month number
 163    * @param d Day of month
 164    * @return true if the date is valid; otherwise returns false.
 165    */
 166   virtual bool setYMD(ExtDate & date, int y, int m, int d) const = 0;
 167
 168   /**
 169    * Returns a QDate object containing a date nyears later.
 170    *
 171    * @param date The old date
 172    * @param nyears The number of years to add
 173    * @return The new date
 174    */
 175   virtual ExtDate addYears(const ExtDate & date, int nyears) const = 0;
 176
 177   /**
 178    * Returns a QDate object containing a date nmonths later.
 179    *
 180    * @param date The old date
 181    * @param nmonths The number of months to add
 182    * @return The new date
 183    */
 184   virtual ExtDate addMonths(const ExtDate & date, int nmonths) const = 0;
 185
 186   /**
 187    * Returns a QDate object containing a date ndays later.
 188    *
 189    * @param date The old date
 190    * @param ndays The number of days to add
 191    * @return The new date
 192    */
 193   virtual ExtDate addDays(const ExtDate & date, int ndays) const = 0;
 194
 195   /**
 196    * Gets specific calendar type number of month for a given year
 197    *
 198    * @param date The date whose year to use
 199    * @return The number of months in that year
 200    */
 201   virtual int monthsInYear (const ExtDate & date) const = 0;
 202
 203   /**
 204    * Gets the number of days in date whose years specified.
 205    *
 206    * @param date Gregorian date equivalent to the specific one
 207    * @return The number of days in year
 208    */
 209   virtual int daysInYear (const ExtDate & date) const = 0;
 210
 211   /**
 212    * Gets specific calendar type number of days in month for a given date
 213    *
 214    * @param date gregorian date
 215    * @return number of days for month in date
 216    */
 217   virtual int daysInMonth (const ExtDate & date) const = 0;
 218
 219   /**
 220    * Gets the number of weeks in a specified year
 221    *
 222    * @param year the year
 223    * @return number of weeks in year
 224    */
 225   virtual int weeksInYear(int year) const = 0;
 226
 227   /**
 228    * Gets specific calendar type week number for a given date
 229    *
 230    * @param date gregorian date
 231    * @param yearNum The year the date belongs to
 232    * @return week number
 233    */
 234   virtual int weekNumber(const ExtDate& date, int * yearNum = 0) const = 0;
 235
 236   /**
 237    * Gets specific calendar type month name for a given month number
 238    * If an invalid month is specified, QString::null is returned.
 239    *
 240    * @param month The month number
 241    * @param year The year the month belongs to
 242    * @param shortName Specifies if the short month name should be used
 243    * @return The name of the month
 244    */
 245   virtual QString monthName (int month, int year, bool shortName = false) const = 0;
 246
 247   /**
 248    * Gets specific calendar type month name for a given gregorian date
 249    *
 250    * @param date Gregorian date
 251    * @param shortName Specifies if the short month name should be used
 252    * @return The name of the month
 253    */
 254   virtual QString monthName (const ExtDate & date, bool shortName = false ) const = 0;
 255
 256   /**
 257    * Returns a string containing the possessive form of the month name.
 258    * ("of January", "of February", etc.)
 259    * It's needed in long format dates in some languages.
 260    * If an invalid month is specified, QString::null is returned.
 261    *
 262    * @param month The month number
 263    * @param year The year the month belongs to
 264    * @param shortName Specifies if the short month name should be used
 265    *
 266    * @return The possessive form of the name of the month
 267    */
 268   virtual QString monthNamePossessive(int month, int year, bool shortName = false) const = 0;
 269
 270   /**
 271    * Returns a string containing the possessive form of the month name.
 272    * ("of January", "of February", etc.)
 273    * It's needed in long format dates in some languages.
 274    *
 275    * @param date Gregorian date
 276    * @param shortName Specifies if the short month name should be used
 277    *
 278    * @return The possessive form of the name of the month
 279    */
 280   virtual QString monthNamePossessive(const ExtDate & date, bool shortName = false) const = 0;
 281
 282   /**
 283    * Gets specific calendar type week day name
 284    * If an invalid week day is specified, QString::null is returned.
 285    *
 286    * @param weekDay number of day in week (1 -> Monday)
 287    * @param shortName short or complete day name
 288    * @return day name
 289    */
 290   virtual QString weekDayName (int weekDay, bool shortName = false) const = 0;
 291
 292   /**
 293    * Gets specific calendar type week day name
 294    *
 295    * @param date the date
 296    * @param shortName short or complete day name
 297    * @return day name
 298    */
 299   virtual QString weekDayName (const ExtDate & date, bool shortName = false) const = 0;
 300
 301   /**
 302    * Gets the first year value supported by specific calendar type
 303    * algorithms.
 304    *
 305    * @return first year supported
 306    */
 307   virtual int minValidYear () const = 0;
 308
 309   /**
 310    * Gets the maximum year value supported by specific calendar type
 311    * algorithms (QDate, 8000)
 312    *
 313    * @return maximum year supported
 314    */
 315   virtual int maxValidYear () const = 0;
 316
 317   /**
 318    * Gets the day of the week traditionaly associated with pray
 319    *
 320    * @return day number
 321    */
 322   virtual int weekDayOfPray () const = 0;
 323
 324   /**
 325    * Gets the string representing the calendar
 326    */
 327   virtual QString calendarName() const = 0;
 328
 329   /**
 330    * Gets if the calendar is lunar based
 331    *
 332    * @return if the calendar is lunar based
 333    */
 334   virtual bool isLunar() const = 0;
 335
 336   /**
 337    * Gets if the calendar is lunisolar based
 338    *
 339    * @return if the calendar is lunisolar based
 340    */
 341   virtual bool isLunisolar() const = 0;
 342
 343   /**
 344    * Gets if the calendar is solar based
 345    *
 346    * @return if the calendar is solar based
 347    */
 348   virtual bool isSolar() const = 0;
 349
 350 protected:
 351   const KLocale * locale() const;
 352
 353 private:
 354   ExtCalendarSystemPrivate * d;
 355 };
 356
 357 #endif