[PATCH] ***FINAL*** API review of KCalendarSystem* and KDate* widgets
John Layt
johnlayt at yahoo.com.au
Mon Jul 23 01:40:23 BST 2007
Hi
I've finished porting the svn codebase over to the new format enums,
fortunately many uses were of the default case or false positives and didn't
need fixing, so I've now deleted the old bool versions entirely. The
modules / apps patched are:
klocale.cpp
kdatetime.cpp
kdelibs/interfaces/ktexteditor
kdepim/kmail
kdepim/korganizer
koffice/kplato
koffice/kspread
koffice/libs/kotext/
extragear/multimedia/amarok
extragear/graphics/digikam
playground/office/kraft
I couldn't get amarok and digikam to build due to their early stage of
porting, but the rest are fine.
I've added more unit tests, and fixed a couple of issues in the new methods as
a result. Test coverage is still not complete, but much better. Some tests
I've had to mark as expected failures as they currently return wrong results
on early dates because QDate uses the Julian calendar prior to 1753, whereas
the Hijri/Jalali/Hebrew conversion routines think they are Gregorian. I've
pending changes to fix that.
I've uploaded a new patch set to my website:
http://www.layt.net/john/system/files/calendar-api-review-patches-2007-07-22.tar.gz
Changelog is attached.
With tomorrow being the last day for API changes, its time to decide if the
changes are acceptable or not. If judged OK, then I will need someone to
commit for me as I don't have an svn account (yet). If not, then I'll move
onto cleaning up the calendar implementations, and look to put the widgets
into playground.
Please remember that these API changes are just a first step, that some of the
new implementations are not 100% yet, and that I will continue to work on the
implementations, unit tests, and apidox over the next couple of weeks.
Cheers!
John.
P.S. Quick question, pardon my ignorance on C++ & BIC, but does re-arranging
the order of methods in the header change the virtual table? I want a more
logical grouping of methods for the apidox, but doing so now makes the
patches very hard to review.
--
-------------- next part --------------
============================== SUMMARY OF CHANGES ===========================
Classes changed:
KCalendarSystem
KCalendarSystemGregorian
KCalendarSystemHebrew
KCalendarSystemHijri
KCalendarSystemJalali
KCalendarTest
KDateWidget
KDateTable
KDatePicker
Files changed:
/KDE/kdelibs/kdecore/date/kcalendarsystem.h
/KDE/kdelibs/kdecore/date/kcalendarsystem.cpp
/KDE/kdelibs/kdecore/date/kcalendarsystemgregorian.h
/KDE/kdelibs/kdecore/date/kcalendarsystemgregorian.cpp
/KDE/kdelibs/kdecore/date/kcalendarsystemhebrew.h
/KDE/kdelibs/kdecore/date/kcalendarsystemhebrew.cpp
/KDE/kdelibs/kdecore/date/kcalendarsystemhijri.h
/KDE/kdelibs/kdecore/date/kcalendarsystemhijri.cpp
/KDE/kdelibs/kdecore/date/kcalendarsystemjalali.h
/KDE/kdelibs/kdecore/date/kcalendarsystemjalali.cpp
/KDE/kdelibs/kdecore/tests/kcalendartest.cpp
/KDE/kdelibs/kdeui/widgets/kdatewidget.h
/KDE/kdelibs/kdeui/widgets/kdatewidget.cpp
/KDE/kdelibs/kdeui/widgets/kdatetable.h
/KDE/kdelibs/kdeui/widgets/kdatetable.cpp
/KDE/kdelibs/kdeui/widgets/kdatepicker.h
/KDE/kdelibs/kdeui/widgets/kdatepicker.cpp
Files patched to fix use of modified/deleted methods:
/KDE/kdelibs/kdecore/localization/klocale.cpp
/KDE/kdelibs/kdecore/date/kdatetime.cpp
/KDE/kdelibs/kdecore/tests/kdatetimetest.cpp
/KDE/kdelibs/interfaces/ktexteditor/templateinterface.cpp
/KDE/kdepim/kmail/templateparser.cpp
/KDE/kdepim/korganizer/kdatenavigator.cpp
/KDE/kdepim/korganizer/koagendaview.cpp
/KDE/kdepim/korganizer/koeditorrecurrence.cpp
/KDE/kdepim/korganizer/komonthview.cpp
/KDE/kdepim/korganizer/koprefsdialog.cpp
/KDE/kdepim/korganizer/plugins/hebrew/hebrew.cpp
/KDE/kdepim/korganizer/printing/calprintpluginbase.cpp
/extragear/multimedia/amarok/src/tracktooltip.cpp
/extragear/graphics/digikam/digikam/albumfolderview.cpp
/extragear/graphics/digikam/digikam/albumicongroupitem.cpp
/extragear/graphics/digikam/digikam/datefolderview.cpp
/extragear/graphics/digikam/digikam/monthwidget.cpp
/koffice/kplato/kptaccountsview.cc
/koffice/kplato/kptcalendarpanel.cc
/koffice/kplato/kptdatetable.cc
/koffice/kspread/attic/Numformat.cpp
/koffice/kspread/plugins/insertcalendar/InsertCalendar.cpp
/koffice/kspread/ValueFormatter.cpp
/koffice/libs/kotext/obsolete/KoVariable.cpp
/playground/office/kraft/src/portalview.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 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 changed:
virtual QString yearString( const QDate & pDate, StringFormat format = LongFormat ) const;
virtual QString monthString( const QDate & pDate, StringFormat format = LongFormat ) const;
virtual QString dayString( const QDate & pDate, StringFormat format = LongFormat ) 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;
* Changed from bool to enum for format
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 which has obsoleted but not deleted
* Used in 290 places in KDE, too many to change to delete
API Methods removed:
virtual QString calendarName() const = 0;
* KLocale now uses terminology calendarType, use KCS 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
virtual QString monthNamePossessive(int month, int year, bool shortName = false) const;
virtual QString monthNamePossessive(const QDate & date, bool shortName = false) const;
* Replaced by call to monthName with a possessive format enum.
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 otherwise 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
* Removed weekDayName() implementation that returned Western names, belongs to specific calendar classes
* Existing methods overwise unchanged
KCalendarSystemHebrew:
----------------------
For common API changes, see above.
API Methods removed:
int hndays(int month, int year) const;
* Originally 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.
More information about the kde-core-devel
mailing list