QDate, KCalendarSystem, KDatePicker, and some API change proposals (long)

[Thiago Macieira]

John Layt wrote:
>Before going into my (rather long winded) reasoning, here's what I
> propose to do for 4.0:
>
>1) Add some new methods to KCalendarClass API to match QDate4, to
> support proper date range validation, and help app programmers
> implement their own calendar systems.

Why would an app programmer want to implement their own calendar system? 
Unless it's an application about calendars, that is.

>2) Change the date range limits hard-coded into KCalendarSystem to match
>QDate4 or each calendars epoch, as appropriate.

QDate's range is from Julian Day 1 until "int jd" overflows. So, there's 
no real upper limit.

>3) Clean up the KCalendarSystem implementations to be simpler, more
>consistant, and to share more code (and add unit tests!)

Unit tests are always welcome!

But I am unsure about more API cleanup at this stage. Is it really needed? 
How much will it break? How soon could you accomplish it?

The hard freeze date is July 24th.

>4) Modify KDateWidget, KDateTable and KDatePicker API (& BIC?) to allow
>multiple calender systems to be displayed at the same time, as well as
> do code clean-up.

I am unsure about multiple calendar systems at the same time... If this is 
not a common thing to do, I'd suggest a specialised widget and/or 
specialised plasmoid.

>2) Do I have enough time before the API freeze to make the proposed
> changes, or do we hold everything over to 4.1?

Yes, the hard freeze is July 24th, but we're already in soft freeze. You 
need the approval of more developers.

>3) Are BIC breakages still allowed before the API freeze?

Yes. But your comments "or in d-> if BIC breakage not allowed" are wrong: 
they are always in the d-pointer, regardless of BIC being allowed or not.

>4) What's the policy after the API freeze for changes to kdelibs
>implementations for clean-up purposes?

After the freeze, no changes in API are allowed.

>As discussed on the list previously, QDate now has an extended date
> range, and a hybrid of the Julian and Gregorian calendars with a fixed
> switchover date. 

I was against that. I much preferred the proleptic Gregorian calendar and 
allow people to convert to/from Gregorian or the JD as they need to. With 
this change, if you want to have a different switchover date, you need to 
implement three periods: before 1582, between 1582 and the switchover 
date and after the switchover date.

>The lower limit on the date range is disappointing, but it's far better
> than the old limit as it covers most of recorded history which the
> majority of apps and users will be interested in.  

I really am skeptical about the need for day-accuracy for dates before 
4712 B.C. I thought people agreed that a per-month or per-year recording 
(or even per-decade) for that time period would be enough. Even for 
KStars.

>This however creates the problem of the ambiguity of years 00 to 99.  In
>QDate3, these were interpreted as 1900 to 1999.  In KDE3 they were
> rejected by setYMD() and interpreted by yearStringToInteger() as 1969
> to 2068.  In QDate4 01 to 99 are interpreted literally and the year 0
> rejected (i.e. BC/AD Julian implementation, not BCE/CE) by obsoleting
> setYMD() and introducing setDate().  The only real choice for the
> calendar systems is to do the same, otherwise those years would be
> impossible to set.

Agreed.

>On the hybrid/switchover issue, a proleptic Gregorian calendar has no
> uses in the real world.  The QDate implementation actually reflects how
> people experienced the calendar in real life, even if calling the
> result Gregorian is a confusing misnomer.  What's important is for
> locale to return what people actually call any given jd in their
> locale, which was Julian until the switchover then Gregorian.  For 4.0
> we should ensure KCalendarSystem matches the QDate API and
> implementation for consistency with those apps that use QDate instead
> or interchangeably.  Later we can see if reimplementing
> KCalendarSystemGregorian with historically accurate switchover dates
> set up by the locale or manual override is a desirable thing.  The vast
> majority of apps don't care about dates that historic and so won't
> notice any difference. Apps that do care will probably be aware of the
> issues and can choose to use whatever implementation is suitable
> instead of what locale returns, e.g implement their own
> KCalendarSystemGregorianProleptic class.

Agreed.

> This can be solved by
> adding a KCalendarSystem pointer member in KDateWidget and KDateTable
> which by default will point to the KGlobal calendar system, or can be
> set to the required calendar system.  New constructors will be required
> to accept a KCalendarSystem 

No new constructors, please. Keep the API simple: add just a getter and a 
setter method.

> The one
> hitch I see is that any KCalendarSystem passed in can have its own
> KLocale set to enable it to use different translations which the
> widgets would have to respect in place of the KGlobal translations. 
> The widgets will need to call the KCalendarSystem protected method
> locale() for this purpose, which would suggest making them friends, but
> this is not an area I know much about.  

Then I suggest you leave it alone. I don't understand why a different 
locale would be required. It will be already very difficult to have an 
application show two different calendar systems -- I imagine we'll have 
all applications sharing the global one, except one plasmoid that can 
show other calendar systems. So let's wait until that plasmoid is 
written.

>3) Add the Gregorian switchover date to KLocale and the KCM to allow
> user override.

No KCM for that, please. It looks incredibly specific and almost no one 
understands what the switchover date means. I mean, people who list the 
month of September 1752 using /usr/bin/cal think it's a bug in the 
application.

>4) Reimplement KCalendarGregorian to obey the switchover date, but
> otherwise remain consistent with QDate

The API otherwise sounds fine.

-- 
  Thiago Macieira  -  thiago (AT) macieira.info - thiago (AT) kde.org
    PGP/GPG: 0x6EF45358; fingerprint:
    E067 918B B660 DBD1 105C  966C 33F5 F005 6EF4 5358
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20070708/69ac2d9c/attachment.sig>