KDE Core/KLocale/Frameworks: Difference between revisions

From KDE Community Wiki
Line 5: Line 5:
=== Global locale ===
=== Global locale ===


KGlobal::locale() returns the application's locale, which defaults to the system locale unless set different using KGlobal::setLocale().  Settings can also be persistently overridden by the application in its config file.
KDE4 provides an app with its own Locale 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 system locale unless overridden using KGlobal::setLocale() or the applications config file.


Qt does not have an equivalent to the KGlobal::locale() application level locale settings, it only has the Qt default and system locales which apply at system-wide level (TODO: is this true or is at really at Application level???).  The default QLocale() constructor returns the Qt default locale which is the system locale unless set different using QLocale::setDefaultLocale()QLocale::system() will always return the system locale which may differ from the default, so should be avoided. Note that running with an envvar for the locale will force Qt to override the system locale but not the default locale.
Qt5 provides a System locale and a Default locale.  Both are declared as global static variables in the qlocale.ccp file with file scope.


Qt also doesn't offer setXxx() api in QLocale to allow apps to temporally 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.
#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;


For example:
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:


  KGlobal::locale()->setDateFormat("%y-%M-%d");
  static void setDefault(const QLocale &locale);
label->setText(KGlobal::formatDate(myDate));


When it should be:
void QLocale::setDefault(const QLocale &locale)
{
    default_lp = locale.d();
    default_number_options = locale.numberOptions();
}


label->setText(KGlobal::formatDate(myDate, "%y-%M-%d"));
This suggest the Qt Default Locale functions exactly the same as the KDE Global Locale and will take its place.


And under Qt5 will become:
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.


label->setText(QLocale().toString(myDate, "yyyy-MM-dd"));
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()?


This should be the correct way in Frameworks.  However, this does not allow for an application to be run using a different locale than the Qt default unless the app is specifically coded to
Running with an envvar for the locale 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 temporally 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->setText(KGlobal::formatDate(myDate));


When it should be:


The problem is each app would need to be individually coded to support running with a different locale. Short of re-introducing a KGlobals
  label->setText(KGlobal::formatDate(myDate, "%y-%M-%d"));


And under Qt5 will become:


label->setText(QLocale().toString(myDate, "yyyy-MM-dd"));


So change all KGlobal::locale().xxx() references to QLocale().xxx()???
I doubt there are few if any valid use cases that can't be easily recoded.
 
Would we want a QApplication::locale() ???


Side-note: QLocale::setDefaultLocale() could be used in KDE4 Workspace with a custom QSystemLocale to force all Qt apps to use the KDE settings!
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 ===
=== API Migration ===

Revision as of 19:06, 19 March 2012

KDE Frameworks 5 Migration

This page summarises the steps required for the migration form KLocale to Qlocale in KDE Frameworks 5.

Global locale

KDE4 provides an app with its own Locale 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 system locale unless overridden using KGlobal::setLocale() or the applications config file.

Qt5 provides a System locale and a Default locale. Both are declared as global static variables in the qlocale.ccp file 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 and will take its place.

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 for the locale 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 temporally 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->setText(KGlobal::formatDate(myDate));

When it should be:

label->setText(KGlobal::formatDate(myDate, "%y-%M-%d"));

And under Qt5 will become:

label->setText(QLocale().toString(myDate, "yyyy-MM-dd"));

I doubt there are few if any valid use cases that can't be easily recoded.

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

Locale

KLocale(const QString &catalog, KSharedConfig::Ptr config=KSharedConfig::Ptr()) KLocale(const QString &catalog, const QString &language, const QString &country=QString(), KConfig *config=0)

void reparseConfiguration()

static void splitLocale(const QString &locale, QString &language, QString &country, QString &modifier, QString &charset)

Countries

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.


KLocale Qt 5.0 Qt 5.1
ISO codes as strings enum Country Conversion methods to be added
allCountriesList() None, loop from QLocale::AnyCountry to QLocale::LastCountry To be added
QString country() Country country() or name.split('_').at(1) Provide ISO conversion methods
QString countryCodeToName(QString country) QString nativeCountryName() or QString countryToString(Country country) Add nativeCountryName(Country country) ???
QString defaultCountry() QLocale::C
bool setCountry(QString country, KConfig *config) QLocale(Language language, Country country)
QString countryDivisionCode () const Not used anywhere
bool setCountryDivisionCode (const QString &countryDivision) Not used anywhere

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.

KLocale Qt 5.0 Qt 5.1
ISO codes as strings enum Language Conversion methods to be added
QStringList allLanguagesList() const None, loop from QLocale::AnyLanguage to QLocale::LastLanguage To be added
QString language() Language language() or name.split('_').at(0) Provide ISO conversion methods
QString languageCodeToName(QString language) nativeLanguageName() or languageToString(Language language) Add nativeLanguageName(Language language) ???
QStringList languageList() uiLanguages()
static QString defaultLanguage() QLocale::C
bool setLanguage(QStringList languages) - KDE Platform module
bool setLanguage(const QString &language, KConfig *config) 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 &currency=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