[PATCH] *UPDATED* API review of KCalendarSystem* and KDate* widgets
John Layt
johnlayt at yahoo.com.au
Sat Jul 21 20:28:53 BST 2007
Hi,
Following on from Andreas' suggestions, I have implemented new methods for the
date strings to replace the bool parameters with new enums.
I've added 3 new enums:
StringFormat { ShortFormat,
LongFormat, };
MonthNameFormat { ShortName,
LongName,
ShortNamePossessive,
LongNamePossessive, };
WeekDayNameFormat { ShortDayName,
LongDayName, };
I had originally thought to use only 1 enum, but the month name is a clearly
separate case, and future-proofing makes 3 a good thing in case new formats
need adding to just one of them.
I've added unit test cases for these methods, all tests pass.
The change has the beneficial side effect of allowing me to get rid of the
monthNamePossessive() method which is replaced with a call to monthName with
one of the possessive formats enums.
At the moment, the old methods are marked as deprecated, not deleted. So far
I've patched all of kdelibs to use the new methods, I'll see how far I get
tomorrow as to whether I go the whole hog and delete the methods entirely.
Question is how far do I go? Obvioulsy kdelibs, kdecore, etc must be
patched, but playground and extragear seem going a little too far?
I've run the unit tests for the patched files, both klocale and kdatetimetest
had QMutex deadlocks which I'm investigating to see if they're my
fault... :-)
I've uploaded udated patches to my website at:
http://www.layt.net/john/system/files/calendar-api-review-patches-2007-07-21.tar.gz
Full details in the attached changelog.
Cheers!
John.
-------------- next part --------------
============================== SUMMARY OF CHANGES ===========================
Classes changed:
KCalendarSystem
KCalendarSystemGregorian
KCalendarSystemHebrew
KCalendarSystemHijri
KCalendarSystemJalali
KCalendarTest
KDateWidget
KDateTable
KDatePicker
Files changed:
kdelibs/kdecore/date/kcalendarsystem.h
kdelibs/kdecore/date/kcalendarsystem.cpp
kdelibs/kdecore/date/kcalendarsystemgregorian.h
kdelibs/kdecore/date/kcalendarsystemgregorian.cpp
kdelibs/kdecore/date/kcalendarsystemhebrew.h
kdelibs/kdecore/date/kcalendarsystemhebrew.cpp
kdelibs/kdecore/date/kcalendarsystemhijri.h
kdelibs/kdecore/date/kcalendarsystemhijri.cpp
kdelibs/kdecore/date/kcalendarsystemjalali.h
kdelibs/kdecore/date/kcalendarsystemjalali.cpp
kdelibs/kdecore/tests/kcalendartest.cpp
kdelibs/kdeui/widgets/kdatewidget.h
kdelibs/kdeui/widgets/kdatewidget.cpp
kdelibs/kdeui/widgets/kdatetable.h
kdelibs/kdeui/widgets/kdatetable.cpp
kdelibs/kdeui/widgets/kdatepicker.h
kdelibs/kdeui/widgets/kdatepicker.cpp
Files patched to fix use of deprecated/deleted methods:
kdelibs/kdecore/localization/klocale.cpp
kdelibs/kdecore/date/kdatetime.cpp
kdelibs/kdecore/tests/kdatetimetest.cpp
kdelibs/interfaces/ktexteditor/templateinterface.cpp
All KCalendarSystem* classes
----------------------------
Common changes to API of all these classes
API Enums added:
StringFormat { ShortFormat, LongFormat, };
MonthNameFormat { ShortName, LongName, ShortNamePossessive, LongNamePossessive, };
WeekDayNameFormat { ShortDayName, LongDayName, };
API Methods added:
public:
virtual QString calendarType() const = 0;
virtual QDate epoch() const;
virtual QDate earliestValidDate() const;
virtual QDate latestValidDate() const;
virtual bool isValid(int year, int month, int day) const = 0;
virtual bool isValid(const QDate &date) const;
virtual bool setDate(QDate &date, int year, int month, int day) const;
virtual bool isLeapYear(int year) const = 0;
virtual bool isLeapYear(const QDate &date) const;
virtual int weeksInYear(const QDate &date) const;
virtual int daysInWeek (const QDate &date) const;
virtual int weekStartDay() const;
virtual QString monthName( int month, int year, MonthNameFormat format = LongName ) const;
virtual QString monthName( const QDate & date, MonthNameFormat format = LongName ) const;
virtual QString weekDayName( int weekDay, WeekDayNameFormat format = LongDayName ) const;
virtual QString weekDayName( const QDate & date, WeekDayNameFormat format = LongDayName ) const;
virtual QString formatDate(const QDate &date, KLocale::DateFormat format = KLocale::LongDate) const;
virtual QDate readDate(const QString &str, bool* ok = 0) const;
virtual QDate readDate( const QString &intstr, const QString &fmt, bool* ok = 0) const;
virtual QDate readDate(const QString &str, KLocale::ReadDateFlags flags, bool *ok = 0) const;
virtual bool isProleptic() const = 0;
protected:
virtual bool julianDayToDate(int jd, int &year, int &month, int &day) const = 0;
virtual bool dateToJulianDay(int year, int month, int day, int &jd) const = 0;
API Methods deprecated:
virtual bool setYMD(QDate & date, int y, int m, int d) const;
* Doesn't do years 00 to 99, replaced by setDate which does.
* Matches QDate
* Used in 290 places in KDE, too many to change to delete
API Methods deprecated for now, likely to de deleted:
virtual QString yearString(const QDate & pDate, bool bShort) const;
virtual QString monthString(const QDate & pDate, bool bShort) const;
virtual QString dayString(const QDate & pDate, bool bShort) const;
virtual QString monthName (int month, int year, bool shortName) const = 0;
virtual QString monthName (const QDate & date, bool shortName ) const;
virtual QString monthNamePossessive(int month, int year, bool shortName = false) const = 0;
virtual QString monthNamePossessive(const QDate & date, bool shortName = false) const;
virtual QString weekDayName (int weekDay, bool shortName) const = 0;
virtual QString weekDayName (const QDate & date, bool shortName) const;
* All use a bool when they should use an enum
* Replaced by same name methods, except monthNamePossessive which is replaced by a call to monthName with a possessive format enum.
API Methods removed:
virtual QString calendarName() const = 0;
* KLocale now uses terminology calendarType, use internal calendarType instead
* Was only used internally by KCalendarSystem* and KDate* widgets
virtual int minValidYear () const = 0;
* Use earliestValidDate instead
* Was only used internally by KCalendarSystem* and KDate* widgets
virtual int maxValidYear () const = 0;
* Use latestValidDate instead
* Was only used internally by KCalendarSystem* and KDate* widgets
KCalendarSystem:
----------------
API Methods added:
public:
static QString calendarLabel( const QString &calendarType );
Implementation changes:
* Moved include of klocale.h to header to allow use of KLocale enums
* Implemented all new API methods, code copied from existing internal methods, or point to base class
* Implemented all missing existing API methods, most point to base class
* Existing methods overwise unchanged
KCalendarSystemGregorian:
-------------------------
For common API changes, see above.
Implementation changes:
* Implemented all new API methods
* Implemented some missing existing API methods, calendar specific methods not implemented
* Existing methods overwise unchanged
KCalendarSystemHebrew:
----------------------
For common API changes, see above.
API Methods removed:
int hndays(int month, int year) const;
* Declared as private method, moved to KCalendarSystemHebrewPrivate instead
Implementation changes:
* Added implementation of KCalendarSystemHebrewPrivate, added existing and new methods, initialise
* Replace calls to minValidYear, maxValidYear
* Changes all calls to hndays() to d->hndays()
* Implemented all new API methods, code copied from existing internal methods, or point to base class
* Implemented all missing existing API methods, most point to base class
* Existing methods overwise unchanged
KCalendarSystemHijri:
---------------------
For common API changes, see above.
Methods removed from API:
int hndays(int month, int year) const;
* Declared as private method, but not implemented or used (move to d-> if really needed)
Implementation changes:
* Replace calls to minValidYear, maxValidYear
* Implemented all new API methods, code copied from existing internal methods, or point to base class
* Implemented all missing existing API methods, most point to base class
* Existing methods overwise unchanged
KCalendarSystemJalali:
----------------------
For common API changes, see above.
Implementation changes:
* Replace calls to minValidYear, maxValidYear
* Implemented all new API methods, code copied from existing internal methods, or point to base class
* Implemented all missing existing API methods, most point to base class
* Existing methods overwise unchanged
KDateWidget:
------------
Have changed existing code to use new methods as test bed implementation of calendar(). Widget not used anywhere in KDE svn.
API Methods added:
const KCalendarSystem *calendar() const;
bool setCalendar( KCalendarSystem *calendar = 0 );
bool setCalendar( const QString &calendarType );
API Methods changed:
bool setDate(const QDate &date);
* Changed returned value from int to bool for consistancy and validation
Members added:
KCalendarSystem *m_cal;
* added to KDateWidgetPrivate
Implementation changes:
* Check passed in dates are valid in calendar system before using them
* Initialise m_cal = 0, i.e. global calendar
* Use calendar() in place of KGlobal::calendar()
* Replace calls to minValidYear, maxValidYear
* Existing methods overwise unchanged
KDateTable:
------------
No clean-up or use of calendar() as yet. Really needed more time to review moving move parts to KDateTablePrivate.
API Methods added:
const KCalendarSystem *calendar() const;
bool setCalendar( KCalendarSystem *calendar = 0 );
bool setCalendar( const QString &calendarType );
Implementation changes:
* Initialise m_calendar = 0, i.e. global calendar
* Use calendarType() in place of calendarName()
Members added:
KCalendarSystem *m_calendar;
* added to KDateTablePrivate
KDatePicker:
------------
No clean-up or use of new methods as yet. Uses KDateTable's calendar member, just passes calls through.
API Methods added:
const KCalendarSystem *calendar() const;
bool setCalendar( KCalendarSystem *calendar = 0 );
bool setCalendar( const QString &calendarType );
KCalendarTest:
--------------
Commented out tests on deleted methods, add tests for calendarType.
Fixes made for yearString / monthString / dayString / weekDayName / monthName / monthNamePossessive
---------------------------------------------------------------------------------------------------
Completed:
kdelibs:
kdecore/localization/klocale.cpp
kdecore/date/kdatetime.cpp
kdecore/tests/kdatetimetest.cpp
interfaces/ktexteditor/templateinterface.cpp
More information about the kde-core-devel
mailing list