[Development] QCalendar and QCalendarBackend questions

[Edward Welbourne]

Wang Gary (25 December 2020 17:40) wrote:
> Hello,

Hello Gary, likewise.
As Thiago already said, you came to the right place,
albeit while many of us were on vacation.

> The first issue is, in order to get QCalendar support a new calendar
> system, it seems like I need to subclass QCalendarBackend first, which
> is a private Qt API. Is that correct?  If so, is there any plan to
> make it public? If not, I hope there can be a way to add custom
> calendar systems in a way similar to what Qt's imageformats plugin
> does.

The plan has always been to make it possible to add custom calendars, in
a similar manner to the various existing plugin mechanisms.  However, as
you note, the backend base is in a private header; this is partly
because we know we shall need some adaptations to its API and won't know
what those shall be until we're more familiar with what further
calendars need it to support.  (It's also partly because I'm not
familiar enough with how we do plugin APIs elsewhere, so it may need
some rearranging.)

The question of how to make custom backends possible is currently up for
discussion at:
https://codereview.qt-project.org/c/qt/qtbase/+/309672

However (see below) the Chinese calendar is one we can definitely
countenance accepting as a built-in calendar, side-stepping that.

> The second issue is, for example, Traditional Chinese calendar
> have their own (localized) day name, the first day of a month
> names "初一" and the 22nd day of the month names "廿二". It
> seems there are functions that can be used to get the localized
> month name and weekday name, but seems there is no function
> provided to get a localized day name. Is that correct? If so, can
> we add such a feature to QCalendar?

Indeed, day-of-month names (I guess the Julian calendar might call the
15th of each month the Ides) haven't come up and our date-formatting
code has no conception of it.  We just number the days of a month.  In
principle even English does have names, for days of the Gregorian
months, it just uses the usual ordinal, so "first" for 1, "seventeenth"
for 17.  If it's usual in the Chinese calendar to give days of the month
by name rather than number, we probably have to think quite carefully
about how to support that.  It'll also make the (already tangled)
date-time parser even more of a horror-show.

As Thiago said, whether it's even possible to do this depends on whether
we can get the localised forms of these day-of-month names; we get our
localisation data from the Unicode consortium's Common Locale Data
Repository (CLDR [0]), in whose zh.xml and zh_Hant.xml I fail to find
either string "初一" or "廿二", which rather suggests this information
isn't present, making this part of what you want impractical, at least
for the moment.

[0] http://cldr.unicode.org/index

It is, of course, possible that you might persuade the CLDR maintainers
to include it; or, if you find where else in the CLDR data-set I should
have looked to find it, this problem is solved already.  I just don't
know where to look !

I note that the LDML (see below [2]) date formats [1] don't make any
mention of day-of-month names, it only has formats using numbers for the
day of the month.  So presumably no CLDR-supported locale uses names for
days of the month in its standard formats.

[1] http://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table

> Also, currently, QCalendar doesn't seem to be able to get the Cyclic
> year name

Presumably cyclic year names are, for the relevant cycle, somewhat
analogous to the two-digit year numbers we use for the century-cycle
more familiar to users of the Gregorian calendar.  Adding support for
that would combine the problems of two-digit year numbers - which cycle
is it in ? - with the "names where we only support numbers at present"
issue for day-of-month above.  I have, at least, found where CLDR keeps
this data - the locale data markup language (LDML [2]) does describe the
information we'd need for this [3] and I see zh.xml, zh_Hant.xml,
yue.xml and yue_Hans.xml do all have cyclicNameSets elements,
although I haven't scrutinised the details.

[2] http://www.unicode.org/reports/tr35/
[3] http://www.unicode.org/reports/tr35/tr35-dates.html#monthPatterns_cyclicNameSets

Tantalisingly, the cyclicNameSets do include some with type="days" [4],
which might conceivably be the data for your day-of-month names, but I
find no documentation in the LDML spec for these, only for the years,
zodiacs and solarTerms.

[4] https://github.com/unicode-org/cldr/blob/ab7b30c5440b049818872cc64ff9f9af46531cd8/common/main/zh.xml#L2400

For reference, our scripts - to extract data from CLDR and generate the
tables QLocale and the various QCalendar backends use at run-time - live
in qtbase/util/locale_database/; they're written in python.

> and also get to know if the given month is leap month. I'm not sure if
> it's by design since QCalendar::monthName() mentioned that issue. Then
> it seems we are able to get the localized month name which can
> indicate it's a leap month or not to the user, but not able to know if
> it's a leap month from the API.

The month name methods do get passed the year; the idea was that this
would enable the methods to determine which months in that year, if any,
are leap months, so that it can adapt the naming suitably.  Does that
suffice ?  If not, why not ?

As for identifying leap months and leap days, see
https://codereview.qt-project.org/c/qt/qtbase/+/261857
although I now see [3] indicates the Hindu calendar can have more than
one leap month in a year, or can skip a month.  So apparently it's more
complicated than I realised !

> By the way, is there any plan to introduce the Chinese calendar
> system support in official Qt release?

If you look in qtbase/src/corelib/time/qcalendar.h, you'll find a
comment - search for "contributions welcome" - that sketches out the set
of calendars for which it'd at least be practical to accept a
contributed implementation, based on the fact that CLDR has at least
some data for them (and various other systems, such as ECMAScript, have
some semblance of support for them).  Whether we'd want to actually ship
all of them with Qt is another question, but Chinese is definitely a
strong contender for one worth including.  In particular, I expect it'll
give important insights into what we need the backend API to look like,
so it's one I'd be very happy to see added.

My expectation is that doing a good job of implementing any of these
shall depend on someone very familiar with the calendar in question
doing a large part of the work; I can help to fit it into the existing
structures, and adapt the python scripts to extract data from CLDR, but
the cultural knowledge has to come from someone else.  If you're willing
to work on that, let's create a ticket in Jira and sketch out what we
can do.  I can't claim my scrum master will put it at the top of my
priority list, but I'd definitely help out in moderation, at least,

	Eddy.