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

[John Layt]

Hi Thiago,

Many thanks for your thoughts, below a few points in reply.

Basically I'm just looking to be pragmatic here.  As it stands, we have QDate 
differing in subtle ways from KDE, and KDE imposing no longer necessary 
restrictions.  I'm just looking to smooth those out, and make life easier for 
calendar obsessed app developers like me :-)

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

Hey, I'll admit to looking to make my life easier, maintaining a fork is 
basically wasted effort.  But there was mention in the earlier threads on the 
list of other people wanting a true proleptic Gregorian calendar for whatever 
use.  Then there's various official civil (Ethiopian, Nepali, etc) and 
religious calendars (Coptic, Julian, etc) in active use across the world that 
we don't currently support.  Remember that the Jalali calendar came 
originally from the FarsiKDE internationalisation project.  We could put 
these in libs later, but for now people can implement one themselves and 
still use it with the libs provided date picker.  

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

No real upper limit other than possibly the date formats in locale, their 
reaction to a YYYYY is unknown at this stage.  Also the ISO standard only 
defines up to 9999.  Besides, who needs past that yet?

> 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?

For the core calendar systems, I will have patches this weekend, almost 
certainly without breaking BIC, as they are all new methods, most of 1 line 
in implementation.  The widgets I may have done by this weekend, but next 
weekend would be a better bet.  The only thing that I think will break BIC in 
the widgets is changing the existing KDateTable method setDate() to return 
bool instead of void, and even then people wouldn't need to change their code 
(what few might use it).

My biggest delay is getting a KDE4 dev environment set up without a home 
internet connection at the moment, after that it's a breeze :-)

Do we really need the API changes?  Sure, the world won't end if they don't 
get in, but if we want the implementation fixes around date ranges and other 
clean-ups, then the API additions are required to support those.  I did have 
plenty of other suggested additions to the API, but I whittled them down to 
those I felt were most needed.  The rest I'll leave for 4.1.

> 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.

Exactly.  Use case should be just like the clock, chuck as many clock 
plasmoids as you like on the desktop, right click to set each one to a 
different time zone, but locale stays as is.  Same with calendars, plasmoid 
shows the standard libs KDatePicker, user right-clicks to choose from the 
supported list of systems in libs, locale stays the same, done.  Nice and 
simple, but the current KDatePicker won't let you, you would have to fork or 
implement your own.  Get 3 or 4 people doing it for their own apps and its a 
waste of effort for something libs could so easily provide.

With regard to wanting to display multiple calendars, there's uses that might 
be more common than you think, especially in the international and religious 
communities.  In Israel, the Gregorian and Jewish calendars are used 
interchangeably in daily life.  The same across the Middle East with the 
Islamic and Gregorian, and the Orthodox world with Gregorian and Julian: 
religious and business calendars in constant side-by-side use.  KDE Apps list 
several religious apps, such as Islamic prayer guides that may benefit as I 
believe they had to fork the date picker too.  And I could think of future 
educational apps, such as a foreign language tutor needing to teach the local 
calendar system.

> After the freeze, no changes in API are allowed.

But for the exisiting implementation code, are changes still allowed to clean 
up and fix date ranges without changing the API?  Or only bugfixes?  

The plan I had in mind was:
1) Fully implement new API methods before freeze, but nothing calls to them 
yet.  No unit tests yet due to short time and simple nature of methods.
2) After API freeze modify existing code to call new methods, fix date ranges, 
etc.  All changes to be fully supported by unit test cases of course :-)
3) Build a plasmoid in playground...

> 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.

Just bikeshedding here for a moment :-)  You also need to remember countries 
like China and Japan that switched from their local lunar based calendars to 
Gregorian early in the 20th century.  A locale calendar class could hold two 
instances of a KCalendarSystem, the old and the new, and a switchover jd.  
Before the jd the old system is used, after the jd the new system is used.  
All actual KCalendarSystems would thus be pure and proleptic.  Locale files 
would hold the names of the before system, the after system, and changeover 
jd.  But that's something for KDE5 I think :-)

> 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.

Exactly.  Those few who need it can build it themselves.  Everyone else falls 
within QDate and KCalendarSystem supported range.  Including a couple of other 
history/edu apps I have planned...

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

OK.

> 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.

Well, my intent is to write such a plasmoid for playground as I described 
above.  It would just be far easier if KDatePicker already supported having 
its calendar system set to something other than global, rather than having to 
fork it.  But I guess that could be the proving ground for those changes if 
required.  

As for the need for a different locale, the educational and religious use 
cases would be prime examples, you may have an English/German/Spanish desktop 
but want to see your religions calendar in Arabic or Hebrew.  OK, so a 
limited use case, but the libs should be able to provide for it.  

Obviously, I need to put a lot more thought and research into the issue of how 
this could be done, but I would rather have the multiple calendars fix in 
without it then miss out entirely.

Anyway, time to hack.  I'll make the API changes I think are needed and submit 
patches to the list by Saturday for review.  Then I'll see if there's enough 
concensus to proceed now, or retry for 4.1.

Cheers!

John.

--
Send instant messages to your online friends http://au.messenger.yahoo.com