KDE Core/KLocale/Frameworks: Difference between revisions
| Line 103: | Line 103: | ||
==== Countries ==== | ==== Countries ==== | ||
QLocale uses an enum value where KDE uses | QLocale uses an enum value where KDE uses a QString ISO Code. Support may be added to Qt 5.1 to convert between the two, or this may be provided in the planned QtIsoCodes addon. | ||
Revision as of 20:54, 19 March 2012
KDE Frameworks 5 Migration
This page summarises the steps required for the migration from KLocale to Qlocale in KDE Frameworks 5.
Split Locale and Translations
KLocale merges localisation and translation. In Qt these are separate. In Frameworks we will follow this model and split KLocale into 2. We will use QLocale everywhere for the localisation methods. We will use QTranslator / tr() in the tier 1 libraries where translation needs should be simple, but still hook this into the KDE translators workflow. In KDE applications we will use KLocalizedString (or a replacement) and i18n().
We can make a start on this now by replace many #include <klocale.h> references with <klocalizedstring.h> when i18n() is the only function required by a class.
Later KLocalizedString (or replacement) will need porting to use QLocale instead of KLocale.
Replace KDE Global Locale
KDE4 provides an app with its own KLocale instance which applies throughout the application instance and can be manipulated within that application instance. KGlobal::locale() returns the applications locale, which defaults to the KDE Locale unless overridden using KGlobal::setLocale() or the applications config file. This allows apps to seamlessly run with an alternative locale than the system locale and is a feature we need to retain.
Qt5 provides a System Locale and a Default Locale. Both are declared as global static variables in qlocale.ccp with file scope:
#ifndef QT_NO_SYSTEMLOCALE QT_BEGIN_NAMESPACE class QSystemLocale; static QSystemLocale *QSystemLocale_globalSystemLocale(); QT_END_NAMESPACE #endif
static const QLocalePrivate *default_lp = 0; static uint default_number_options = 0;
The System Locale is what the system is currently set to and remains the same unless updated by the system, but the Default Locale can be changed by the application:
static void setDefault(const QLocale &locale);
void QLocale::setDefault(const QLocale &locale)
{
default_lp = locale.d();
default_number_options = locale.numberOptions();
}
This suggest the Qt Default Locale functions exactly the same as the KDE Global Locale in applying per application instance and will take the place of the KDE Global Locale.
To confirm:
- This does apply at application level
- This does apply to any Qt based libraries called by the application
The default QLocale() constructor returns the Qt Default Locale which is usually the System Locale unless changed using QLocale::setDefault(). QLocale::system() will always return the System Locale which may differ from the Default, so should be avoided unless explicitly required.
This implies that all code accessing KGlobal::locale().xxx() should simply be changed to be QLocale().yyy(). Due to the static privates the repeated construction should not be a performance issue, but apps can create a local var if needed, or we could request a QApplication::locale()?
Running with an envvar locale override will force Qt to override the system locale with the chosen locale under UNIX, behaviour under other platforms is unclear.
QLocale doesn't offer setXxx() api to allow apps to temporarily override a setting while running, and probably never will. Usually in KDE this is abused for things like temp changes to the date format when the normal format options api should be used, or a different locale object created.
For example:
KGlobal::locale()->setDateFormat("%y-%M-%d");
label = KGlobal::formatDate(myDate);
When it should be:
label = KGlobal::formatDate(myDate, "%y-%M-%d");
And under Qt5 will become:
label = QLocale().toString(myDate, "yyyy-MM-dd");
I doubt there are few if any valid use cases that can't be easily recoded. If the app wants say the date format to persist they can just save it in a local string and use that whenever they call the method.
Side-note: QLocale::setDefault() could be used in KDE4 Workspace with a custom QSystemLocale to force all Qt apps to use the KDE settings.
API Migration
While Qt 4.8 / Qt 5.0 provides most of the API needed, this are usually with very different method names, enums, and format codes. Some APi will not be available before Qt 5.1.
Migration is likely to be a very manual affair. A conversion table is provided below. Note method footprints are simplified for clarity.
Some interim migration tools may be required in a temporary class, such as ISO code conversions and splitLocale(), etc. The need for this can be assessed as we go.
Locale
| KLocale | Qt 5.0 | Qt 5.1 |
|---|---|---|
| KLocale(QString catalog, KSharedConfig::Ptr config) | Use QLocale() - Config no longer used - Set catalog in translation system | |
| KLocale(QString catalog, QString language, QString country, KConfig *config) | QLocale(Language laanguage, Country country) - Config no longer used - Set catalog in translation system | |
| void reparseConfiguration() | No longer used | |
| static void splitLocale(QString locale, QString language, QString country, QString modifier, QString charset) | Not public, need to instantiate a locale and obtain that way. | Qt to be make public? |
Countries
QLocale uses an enum value where KDE uses a QString ISO Code. Support may be added to Qt 5.1 to convert between the two, or this may be provided in the planned QtIsoCodes addon.
| KLocale API | kdelibs usage | Qt 5.0 | Qt 5.1 |
|---|---|---|---|
| ISO codes as strings | enum Country | Conversion methods to be added | |
| allCountriesList() | - | Not in Qt - loop from QLocale::AnyCountry to QLocale::LastCountry | Qt to add |
| QString country() | klocalizedstring.cpp | Country country() or name.split('_').at(1) | Provide ISO conversion methods |
| QString countryCodeToName(QString country) | Various | QString nativeCountryName() or QString countryToString(Country country) | Add nativeCountryName(Country country) ??? |
| QString defaultCountry() | - | QLocale::C | |
| bool setCountry(QString country, KConfig *config) | - | Create new instance QLocale(Language language, Country country) | |
| QString countryDivisionCode () const | - | ||
| bool setCountryDivisionCode (const QString &countryDivision) | - |
Languages
QLocale uses an enum value where KDE uses the ISO Code. Support may be added to Qt to convert between the two, or this may be provided in the planned QtIsoCodes addon. Need some more thought with regard to localisation and translation split.
| KLocale | kdelibs | Qt 5.0 | Qt 5.1 |
|---|---|---|---|
| ISO codes as strings | enum Language | Conversion methods to be added | |
| QStringList allLanguagesList() const | kswitchlanguagedialog_p.cpp | None, loop from QLocale::AnyLanguage to QLocale::LastLanguage | To be added |
| QString language() | Various | Language language() or name.split('_').at(0) | Provide ISO conversion methods |
| QString languageCodeToName(QString language) | Various | nativeLanguageName() or English languageToString(Language language) | Add nativeLanguageName(Language language) ??? |
| QStringList languageList() | Various | uiLanguages() | |
| static QString defaultLanguage() | Various | QLocale::C | |
| bool setLanguage(QStringList languages) | kswitchlanguagedialog_p.cpp | KDE Platform module | |
| bool setLanguage(const QString &language, KConfig *config) | - | Create new QLocale(Language language, Country country) |
Calendar / Date / Time
enum CalendarSystem enum DateFormat enum DateTimeComponent enum DateTimeComponentFormat enum DateTimeFormatOption enum DateTimeFormatStandard enum DateTimeParseMode enum ReadDateFlags enum ReadTimeFlags enum TimeFormatOption enum TimeProcessingOption enum WeekNumberSystem
const KCalendarSystem * calendar () const KLocale::CalendarSystem calendarSystem () const QString calendarType () const
QString dateFormat () const QString dateFormatShort () const bool dateMonthNamePossessive () const DigitSet dateTimeDigitSet () const QString dayPeriodText (const QTime &time, DateTimeComponentFormat format=DefaultComponentFormat) const QString formatDate (const QDate &date, DateFormat format=LongDate) const QString formatDateTime (const QDateTime &dateTime, DateFormat format=ShortDate, bool includeSecs=false) const QString formatDateTime (const KDateTime &dateTime, DateFormat format=ShortDate, DateTimeFormatOptions options=0) const QString formatDuration (unsigned long mSec) const QString formatLocaleTime (const QTime &pTime, TimeFormatOptions options=KLocale::TimeDefault) const QString formatTime (const QTime &pTime, bool includeSecs=false, bool isDuration=false) const QString prettyFormatDuration (unsigned long mSec) const
QDate readDate (const QString &str, bool *ok=0) const QDate readDate (const QString &intstr, const QString &fmt, bool *ok=0) const QDate readDate (const QString &str, ReadDateFlags flags, bool *ok=0) const QTime readLocaleTime (const QString &str, bool *ok=0, TimeFormatOptions options=KLocale::TimeDefault, TimeProcessingOptions processing=ProcessNonStrict) const QTime readTime (const QString &str, bool *ok=0) const QTime readTime (const QString &str, ReadTimeFlags flags, bool *ok=0) const
void setCalendar (const QString &calendarType) void setCalendarSystem (KLocale::CalendarSystem calendarSystem) void setDateFormat (const QString &format) void setDateFormatShort (const QString &format) void setDateMonthNamePossessive (bool possessive) void setDateTimeDigitSet (DigitSet digitSet) void setTimeFormat (const QString &format) void setWeekDayOfPray (int day) void setWeekNumberSystem (KLocale::WeekNumberSystem weekNumberSystem) void setWeekStartDay (int day) void setWorkingWeekEndDay (int day) void setWorkingWeekStartDay (int day)
bool use12Clock () const => Remove int weekDayOfPray () const => Remove, try replace with weeend days instead
KLocale::WeekNumberSystem weekNumberSystem () KLocale::WeekNumberSystem weekNumberSystem () const int weekStartDay () const int workingWeekEndDay () const int workingWeekStartDay () const QString timeFormat () const
Numbers
int decimalPlaces() const QString decimalSymbol() const int fracDigits() const QString negativeSign() const QString positiveSign() const QString thousandsSeparator() const
void setDecimalPlaces(int digits) void setDecimalSymbol(const QString &symbol) void setFracDigits(int digits) void setNegativeSign(const QString &sign) void setPositiveSign(const QString &sign) void setThousandsSeparator(const QString &separator)
QString formatLong(long num) const QString formatNumber(double num, int precision=-1) const QString formatNumber(const QString &numStr, bool round=true, int precision=-1) const
double readNumber(const QString &numStr, bool *ok=0) const
Currency / Money
Basic functions supported in Qt 5.0, more in 5.1, advanced features of KCurrencyCode to be moved to new QtIsoCodes library.
KCurrencyCode *currency () const QString currencyCode () const QStringList currencyCodeList () const QString currencySymbol () const int monetaryDecimalPlaces () const QString monetaryDecimalSymbol () const QString monetaryThousandsSeparator () const SignPosition negativeMonetarySignPosition () const bool negativePrefixCurrencySymbol () const SignPosition positiveMonetarySignPosition () const bool positivePrefixCurrencySymbol () const static QString defaultCurrencyCode ()
void setCurrencyCode (const QString &newCurrencyCode) void setCurrencySymbol (const QString &symbol) void setMonetaryDecimalPlaces (int digits) void setMonetaryDecimalSymbol (const QString &symbol) void setMonetaryThousandsSeparator (const QString &separator) void setNegativeMonetarySignPosition (SignPosition signpos) void setNegativePrefixCurrencySymbol (bool prefix) void setPositiveMonetarySignPosition (SignPosition signpos) void setPositivePrefixCurrencySymbol (bool prefix)
QString formatMoney (double num, const QString ¤cy=QString(), int precision=-1) const
double readMoney (const QString &numStr, bool *ok=0) const
Digit Sets
Not supported directly in Qt 5.0, some conversion happens implicitly, defer to 5.1 if really needed. In ICU fully supported implicitly.
QList<DigitSet> allDigitSetsList () const DigitSet digitSet () const void setDigitSet (DigitSet digitSet) DigitSet monetaryDigitSet () const void setMonetaryDigitSet (DigitSet digitSet) QString digitSetToName (DigitSet digitSet, bool withDigits=false) const QString convertDigits (const QString &str, DigitSet digitSet, bool ignoreContext=false) const
Binary Units
Not supported in QLocale.
enum BinarySizeUnits enum BinaryUnitDialect
BinaryUnitDialect binaryUnitDialect () const void setBinaryUnitDialect (BinaryUnitDialect newDialect) QString formatByteSize (double size) const QString formatByteSize (double size, int precision, BinaryUnitDialect dialect=KLocale::DefaultBinaryDialect, BinarySizeUnits specificUnit=KLocale::DefaultBinaryUnits) const
Measurement Systems
enum MeasureSystem
MeasureSystem measureSystem() void setMeasureSystem(MeasureSystem value)
int pageSize() void setPageSize(int paperFormat)
Encoding
QTextCodec *codecForEncoding() const QByteArray encoding() bool setEncoding(int mibEnum) int encodingMib int fileEncodingMib()
Translations
Replace with QTranslator / tr() at lowest level, or new KTranslator at higher level.
QStringList installedLanguages () const bool isApplicationTranslatedInto (const QString &language)
void copyCatalogsTo (KLocale *locale) void insertCatalog (const QString &catalog) void removeCatalog (const QString &catalog) void setActiveCatalog (const QString &catalog) static void setMainCatalog (const char *catalog)
bool useTranscript () const
QString translateQt(const char *context, const char *sourceText, const char *comment) const void translateRaw(const char *singular, const char *plural, unsigned long n, QString *lang, QString *trans) const void translateRaw(const char *ctxt, const char *singular, const char *plural, unsigned long n, QString *lang, QString *trans) const void translateRaw(const char *msg, QString *lang, QString *trans) const void translateRaw(const char *ctxt, const char *msg, QString *lang, QString *trans) const void translateRawFrom(const char *catname, const char *msg, QString *lang, QString *trans) const void translateRawFrom(const char *catname, const char *singular, const char *plural, unsigned long n, QString *lang, QString *trans) const void translateRawFrom(const char *catname, const char *ctxt, const char *msg, QString *lang, QString *trans) const void translateRawFrom(const char *catname, const char *ctxt, const char *singular, const char *plural, unsigned long n, QString *lang, QString *trans) const
QString localizedFilePath (const QString &filePath) const static QString langLookup (const QString &fname, const char *rtype="html")
bool nounDeclension () const QString removeAcceleratorMarker (const QString &label) const