[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