-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
http://svn.reviewboard.kde.org/r/5692/
-----------------------------------------------------------
(Updated 2010-10-30 22:30:16.219842)
Review request for kdelibs.
Changes
-------
Crikey, what started as a quick one night hack has now taken on a life of it's
own with tentacles reaching everywhere, but it's good to get the new api right
up front then have to hack it around later. I've only posted the
KLocalizedDate implementation, for the upstream KLocale and KCalendarSystem
changes I've only posted the headers as that's the interesting part.
Updates:
1) Added lots of apidox, but still not finished, I just need a day off tomorrow
so I'm posting it so the api can have another going over :-)
2) Figured out how to allow special use case for setting custom Locales and
Calendar Systems, this is fully documented in the apidox.
3) Made readDate() methods static using global local but with option to
override.
4) Added KLocale::WeekNumberSystem enum and api for different Week Number
Systems (originally planned for 4.7), although we only have the ISO Weeks
implemented at the moment.
5) Added KLocale::DateTimeParseMode enum and api for setting strictness of date
parsing (originally planned for 4.7), although only Liberal parsing is
available for now.
6) Removed all the dayString() type methods and replaced them with a single
formatDateComponent() method. This call uses a new KLocale::DateTimeComponent
enum to specify which component to return. This cleans up a lot of messy api.
I've done the enum as flags so in the future we can do dynamic date formats,
e.g. request just a Day and Month and have it automatically formatted correctly
for the locale without needing translations or extra DateFormat enum values
(again something originally planned to start in 4.7)
7) Added a DefaultComponentFormat value to the KLocale::DateTimeComponentFormat
enum so I don't have to hard code default values into the api, allowing the
default to be changed based on locale.
This is all in addition to the new KLocale::CalendarSystem enum I've posted in
a separate review, which KLocalizedDate now uses.
There's a few new enums there that are placeholders for now, but I'd rather get
them into the api now than have to duplicate api later.
Phew!
Summary
-------
The KCalendarSystem api for localizing dates is awkward, inconvenient,
unintuitive, and long-winded, causing many mistakes to be made or localization
to be ignored altogether. This change adds a new KDate class designed to make
localizing dates as easy as using QDate.
Some QDate code may look like:
QDate myDate( aYear, aMonth, aDay );
int doy = myDate.dayOfYear();
The KDE localized date code looks something like:
QDate myDate;
KGlobal::locale()->calendar()->setDate( myDate, aYear, aMonth, aDay );
int doy = KGlobal::locale()->calendar()->dayOfYear( myDate );
The localized KDate code would look like:
KDate myDate( aYear, aMonth, aDay );
int doy = myDate.dayOfYear();
Much easier.
KDate is a thin wrapper around KCalendarSystem and QDate, with a near identical
api to QDate and as such can be used as a drop-in replacement with very few
changes. Some deprecated or unnecessary KCalendarSystem methods have not been
included, but these can still be accessed via the calendar() methods. Some new
convenience methods have also been added such as setCurrentDate() and
addYearsOn().
Some methods have QDate overloads for convenience, and the assignment and
comparison operators partially work with QDate on the rhs. If anyone knows how
to make it work with QDate on the lhs, or any other QDate compatibility ideas,
I'm all ears.
For now I only intend this to be used as a convenience class by apps internally
and not to be used in kdelibs api as I don't see much advantage in that, but I
may do so if the demand for convenience is there.
I have named it KDate, but there is the possibility people may get confused and
think that KDateTime also localizes datetime's, but that is not the case. If
people think this will be a problem KLocalizedDate is an alternative if more
awkward name.
Diffs (updated)
-----
/trunk/KDE/kdelibs/kdecore/date/klocalizeddate.h PRE-CREATION
/trunk/KDE/kdelibs/kdecore/date/kcalendarsystem.h 1191250
/trunk/KDE/kdelibs/kdecore/date/klocalizeddate.cpp PRE-CREATION
/trunk/KDE/kdelibs/kdecore/localization/klocale.h 1191250
Diff: http://svn.reviewboard.kde.org/r/5692/diff
Testing
-------
Full unit tests included.
Thanks,
John
