KLocale Class Reference

KLocale provides support for country specific stuff like the national language. class for supporting locale settings and national language. More...

#include <klocale.h>

Collaboration diagram for KLocale:

[legend]List of all members.


Public Types
enum	SignPosition { ParensAround = 0, BeforeQuantityMoney = 1, AfterQuantityMoney = 2, BeforeMoney = 3, AfterMoney = 4 }
enum	ReadDateFlags { NormalFormat = 1, ShortFormat = 2 }
enum	ReadTimeFlags { WithSeconds = 0, WithoutSeconds = 1 }
enum	MeasureSystem { Metric, Imperial }
Public Member Functions
	KLocale (const QString &catalog, KConfig *config=0)
	KLocale (const KLocale &rhs)
KLocale &	operator= (const KLocale &rhs)
	~KLocale ()
QString	translate (const char *index) const
QString	translate (const char comment, const char fallback) const
QString	translate (const char singular, const char plural, unsigned long n) const
bool	setEncoding (int mibEnum)
bool	setLanguage (const QString &language)
bool	setLanguage (const QStringList &languages)
bool	setCountry (const QString &country)
QString	decimalSymbol () const
QString	thousandsSeparator () const
QString	currencySymbol () const
QString	monetaryDecimalSymbol () const
QString	monetaryThousandsSeparator () const
QString	positiveSign () const
QString	negativeSign () const
int	fracDigits () const
bool	positivePrefixCurrencySymbol () const
bool	negativePrefixCurrencySymbol () const
SignPosition	positiveMonetarySignPosition () const
SignPosition	negativeMonetarySignPosition () const
QString	formatMoney (double num, const QString &currency=QString::null, int digits=-1) const
QString	formatNumber (double num, int precision=-1) const
QString	formatLong (long num) const
bool	nounDeclension () const
QString	formatDate (const QDate &pDate, bool shortFormat=false) const
bool	dateMonthNamePossessive () const
QString	formatTime (const QTime &pTime, bool includeSecs=false) const
bool	use12Clock () const
bool	weekStartsMonday () const KDE_DEPRECATED
int	weekStartDay () const
QString	monthName (int i, bool shortName=false) const KDE_DEPRECATED
QString	monthNamePossessive (int i, bool shortName=false) const KDE_DEPRECATED
QString	weekDayName (int i, bool shortName=false) const KDE_DEPRECATED
const KCalendarSystem *	calendar () const
QString	calendarType () const
void	setCalendar (const QString &calendarType)
QString	formatDateTime (const QDateTime &pDateTime, bool shortFormat=true, bool includeSecs=false) const
double	readMoney (const QString &numStr, bool *ok=0) const
double	readNumber (const QString &numStr, bool *ok=0) 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	readTime (const QString &str, bool *ok=0) const
QTime	readTime (const QString &str, ReadTimeFlags flags, bool *ok=0) const
QString	language () const
QString	country () const
QStringList	languagesTwoAlpha () const
QStringList	languageList () const
const char *	encoding () const
int	encodingMib () const
QTextCodec *	codecForEncoding () const
int	fileEncodingMib () const
void	setDateFormat (const QString &format)
void	setDateFormatShort (const QString &format)
void	setDateMonthNamePossessive (bool possessive)
void	setTimeFormat (const QString &format)
void	setWeekStartsMonday (bool start) KDE_DEPRECATED
void	setWeekStartDay (int day)
QString	dateFormat () const
QString	dateFormatShort () const
QString	timeFormat () const
void	setDecimalSymbol (const QString &symbol)
void	setThousandsSeparator (const QString &separator)
void	setPositiveSign (const QString &sign)
void	setNegativeSign (const QString &sign)
void	setPositiveMonetarySignPosition (SignPosition signpos)
void	setNegativeMonetarySignPosition (SignPosition signpos)
void	setPositivePrefixCurrencySymbol (bool prefix)
void	setNegativePrefixCurrencySymbol (bool prefix)
void	setFracDigits (int digits)
void	setMonetaryThousandsSeparator (const QString &separator)
void	setMonetaryDecimalSymbol (const QString &symbol)
void	setCurrencySymbol (const QString &symbol)
int	pageSize () const
void	setPageSize (int paperFormat)
MeasureSystem	measureSystem () const
void	setMeasureSystem (MeasureSystem value)
void	insertCatalogue (const QString &catalog)
void	removeCatalogue (const QString &catalog)
void	setActiveCatalogue (const QString &catalog)
QString	translateQt (const char context, const char sourceText, const char *message) const
QStringList	allLanguagesTwoAlpha () const
QString	twoAlphaToLanguageName (const QString &code) const
QStringList	allCountriesTwoAlpha () const
QString	twoAlphaToCountryName (const QString &code) const
QString	formatMoney (const QString &numStr) const KDE_DEPRECATED
QString	formatNumber (const QString &numStr) const KDE_DEPRECATED
QString	languages () const KDE_DEPRECATED
bool	setCharset (const QString &charset) KDE_DEPRECATED
QString	charset () const KDE_DEPRECATED
Static Public Member Functions
void	splitLocale (const QString &str, QString &language, QString &country, QString &charset)
void	setMainCatalogue (const char *catalog)
QString	langLookup (const QString &fname, const char *rtype="html")
QString	defaultLanguage ()
QString	defaultCountry ()
QString	_initLanguage (KConfigBase *config)
Static Protected Member Functions
void	initInstance ()
Friends
class	KGlobal
Related Functions
(Note that these are not member functions.)
	I18N_NOOP(x)
QString	i18n (const char *text)
QString	i18n (const char comment, const char text)
QString	i18n (const char singular, const char plural, unsigned long n)
QString	tr2i18n (const char message, const char =0)

Detailed Description

KLocale provides support for country specific stuff like the national language. class for supporting locale settings and national language.

KLocale supports translating, as well as specifying the format for numbers, currency, time, and date.

Author:: Stephan Kulow <coolo@kde.org>, Preston Brown <pbrown@kde.org>, Hans Petter Bieker <bieker@kde.org>, Lukas Tinkl <lukas.tinkl@suse.cz>

Definition at line 103 of file klocale.h.

Member Enumeration Documentation

enum KLocale::SignPosition

Various positions for where to place the positive or negative sign when they are related to a monetary value.

Definition at line 246 of file klocale.h.
Referenced by negativeMonetarySignPosition(), and positiveMonetarySignPosition().

enum KLocale::MeasureSystem

The Metric system will give you information in mm, while the Imperial system will give you information in inches.

Definition at line 924 of file klocale.h.
Referenced by measureSystem().

Constructor & Destructor Documentation

KLocale::KLocale ( const QString & catalog,

KConfig * config = 0

)

Constructs a KLocale with the given catalog name.
The constructor looks for an entry Locale/Language in the configuration file. If no config file is specified, it will also look for languages using the environment variables (KDE_LANG, LC_MESSAGES, LC_ALL, LANG), as well as the global configuration fie. If we were not able to use non of the specified languages, the default language (en_US) will be used.
If you specify a configuration file, it has to be valid until the KLocale object is destroyed.

Parameters:

catalog The name of the main language file

config The configuration file to use.

Definition at line 76 of file klocale.cpp.
References KInstance::config(), KGlobal::instance(), and QString::isEmpty().

KLocale::KLocale ( const KLocale & rhs )

Copy constructor.

Definition at line 2164 of file klocale.cpp.

KLocale::~KLocale ( )

Destructor.

Definition at line 625 of file klocale.cpp.

Member Function Documentation

KLocale & KLocale::operator= ( const KLocale & rhs )

Assignment operator.

Definition at line 2171 of file klocale.cpp.
References d, m_country, m_currencySymbol, m_dateFormat, m_dateFormatShort, m_decimalSymbol, m_fracDigits, m_language, m_monetaryDecimalSymbol, m_monetaryThousandsSeparator, m_negativeMonetarySignPosition, m_negativePrefixCurrencySymbol, m_negativeSign, m_positiveMonetarySignPosition, m_positivePrefixCurrencySymbol, m_positiveSign, m_thousandsSeparator, and m_timeFormat.

QString KLocale::translate ( const char * index ) const

Translates the string into the corresponding string in the national language, if available.
If not, returns the string itself. There is a KDE wide message file that contains the most often used phrases, so we can avoid duplicating the translation of these phrases. If a phrase is not found in the catalog given to the constructor, it will search in the system catalog. This makes it possible to override some phrases for your needs.
The argument must be an UTF-8 encoded string (If you only use characters that are in US-ASCII you're on the safe side. But for e.g. german umlauts or french accents should be recoded to UTF-8)

Parameters:

index The lookup text and default text, if not found.

Definition at line 667 of file klocale.cpp.
Referenced by formatDateTime(), formatTime(), monthName(), monthNamePossessive(), readTime(), weekDayName(), and KCalendarSystemJalali::weekDayName().

QString KLocale::translate ( const char * comment,

const char * fallback

) const

Translates the string into the corresponding string in the national language, if available.
The real contents of the string is in the argument fallback, but the meaning of it is coded into the argument index. In some cases you'll need this function, when english is too ambiguous to express it.
Most of the times the translators will tell you if it can't be translated as it, but think of cases as "New", where the translations differs depending on what is New. Or simple cases as "Open", that can be used to express something is open or it can be used to express that you want something to open... There are tons of such examples.
If translate("Open") is not enough to translate it well, use translate("To Open", "Open") or translate("Is Open", "Open"). The english user will see "Open" in both cases, but the translated version may vary. Of course you can also use i18n()

Parameters:

comment the comment. The lookup text is made out of comment + fallback

fallback the default text, if not found

Returns:
translation

Definition at line 672 of file klocale.cpp.
References endl(), and QString::fromUtf8().

QString KLocale::translate ( const char * singular,

const char * plural,

unsigned long n

) const

Used to get the correct, translated singular or plural of a word.

Parameters:

singular the singular form of the word, for example "file".

plural the plural form of the word. Must contain a "%n" that will be replaced by the number
, for example "%n files"

n the number

Returns:
the correct singular or plural for the selected language, depending on n

Definition at line 708 of file klocale.cpp.
References endl(), QString::find(), QString::fromUtf8(), QString::isEmpty(), and QStringList::split().

bool KLocale::setEncoding ( int mibEnum )

Changes the current encoding.

Parameters:

mibEnum The mib of the preferred codec

Returns:
True on success.

Definition at line 2049 of file klocale.cpp.
References QTextCodec::codecForMib().

bool KLocale::setLanguage ( const QString & language )

Changes the current language.
The current language will be left unchanged if failed. It will force a reload of the country specific configuration as well.

Parameters:

language The language code.

Returns:
True on success.

Definition at line 397 of file klocale.cpp.
Referenced by setLanguage().

bool KLocale::setLanguage ( const QStringList & languages )

Changes the list of prefed languages for the locale.
The first valid language in the list will be used, or the default (en_US) language will be used if non of the specified languages were available.

Parameters:

languages The list of language codes.

Returns:
True if one of the specified languages were used.

Definition at line 418 of file klocale.cpp.
References defaultLanguage(), languageList(), and setLanguage().

bool KLocale::setCountry ( const QString & country )

Changes the current country.
The current country will be left unchanged if failed. It will force a reload of the country specific configuration.

Parameters:

country The ISO 3166 country code.

Returns:
True on success.

Definition at line 354 of file klocale.cpp.
References QString::isEmpty().

QString KLocale::decimalSymbol ( ) const

Returns what a decimal point should look like ("." or "," etc.) according to the current locale or user settings.

Returns:
The decimal symbol used by locale.

Definition at line 923 of file klocale.cpp.
Referenced by formatNumber(), and readNumber().

QString KLocale::thousandsSeparator ( ) const

Returns what the thousands separator should look like ("," or "." etc.) according to the current locale or user settings.

Returns:
The thousands separator used by locale.

Definition at line 929 of file klocale.cpp.
Referenced by formatNumber(), and readNumber().

QString KLocale::currencySymbol ( ) const

Returns what the symbol denoting currency in the current locale as as defined by user settings should look like.

Returns:
The default currency symbol used by locale.

Definition at line 935 of file klocale.cpp.
Referenced by formatMoney(), and readMoney().

QString KLocale::monetaryDecimalSymbol ( ) const

Returns what a decimal point should look like ("." or "," etc.) for monetary values, according to the current locale or user settings.

Returns:
The monetary decimal symbol used by locale.

Definition at line 941 of file klocale.cpp.
Referenced by formatMoney(), and readMoney().

QString KLocale::monetaryThousandsSeparator ( ) const

Returns what a thousands separator for monetary values should look like ("," or " " etc.) according to the current locale or user settings.

Returns:
The monetary thousands separator used by locale.

Definition at line 947 of file klocale.cpp.
Referenced by formatMoney(), and readMoney().

QString KLocale::positiveSign ( ) const

Returns what a positive sign should look like ("+", " ", etc.) according to the current locale or user settings.

Returns:
The positive sign used by locale.

Definition at line 953 of file klocale.cpp.
Referenced by formatMoney(), and formatNumber().

QString KLocale::negativeSign ( ) const

Returns what a negative sign should look like ("-", etc.) according to the current locale or user settings.

Returns:
The negative sign used by locale.

Definition at line 959 of file klocale.cpp.
Referenced by formatMoney(), formatNumber(), readMoney(), and readNumber().

int KLocale::fracDigits ( ) const

The number of fractional digits to include in numeric/monetary values (usually 2).

Returns:
Default number of fractional digits used by locale.

Definition at line 965 of file klocale.cpp.
Referenced by formatMoney().

bool KLocale::positivePrefixCurrencySymbol ( ) const

If and only if the currency symbol precedes a positive value, this will be true.

Returns:
Where to print the currency symbol for positive numbers.

Definition at line 971 of file klocale.cpp.
Referenced by formatMoney().

bool KLocale::negativePrefixCurrencySymbol ( ) const

If and only if the currency symbol precedes a negative value, this will be true.

Returns:
True if the currency symbol precedes negative numbers.

Definition at line 977 of file klocale.cpp.
Referenced by formatMoney().

KLocale::SignPosition KLocale::positiveMonetarySignPosition ( ) const

Returns the position of a positive sign in relation to a monetary value.

Returns:
Where/how to print the positive sign.

See also:
SignPosition

Definition at line 983 of file klocale.cpp.
References SignPosition.
Referenced by formatMoney().

KLocale::SignPosition KLocale::negativeMonetarySignPosition ( ) const

Denotes where to place a negative sign in relation to a monetary value.

Returns:
Where/how to print the negative sign.

See also:
SignPosition

Definition at line 989 of file klocale.cpp.
References SignPosition.
Referenced by formatMoney(), and readMoney().

QString KLocale::formatMoney ( double num,

const QString & currency = QString::null,

int digits = -1

) const

Given a double, converts that to a numeric string containing the localized monetary equivalent.
e.g. given 123456, return "$ 123,456.00".

Parameters:

num The number we want to format

currency The currency symbol you want.

digits Number of fractional digits, or -1 for the default value

Returns:
The number of money as a localized string

See also:
fracDigits()

Definition at line 1007 of file klocale.cpp.
References QString::append(), currencySymbol(), QString::find(), fracDigits(), QString::insert(), QString::isNull(), QString::length(), monetaryDecimalSymbol(), monetaryThousandsSeparator(), negativeMonetarySignPosition(), negativePrefixCurrencySymbol(), negativeSign(), QString::number(), positiveMonetarySignPosition(), positivePrefixCurrencySymbol(), positiveSign(), QString::prepend(), and QString::replace().
Referenced by formatMoney().

QString KLocale::formatNumber ( double num,

int precision = -1

) const

Given a double, converts that to a numeric string containing the localized numeric equivalent.
e.g. given 123456.78F, return "123,456.78" (for some European country). If precision isn't specified, 2 is used.

Parameters:

num The number to convert

precision Number of fractional digits used.

Returns:
The number as a localized string

Definition at line 1073 of file klocale.cpp.
References decimalSymbol(), QString::find(), QString::insert(), QString::length(), negativeSign(), QString::number(), positiveSign(), QString::prepend(), QString::replace(), and thousandsSeparator().
Referenced by formatLong(), and formatNumber().

QString KLocale::formatLong ( long num ) const

Given an integer, converts that to a numeric string containing the localized numeric equivalent.
e.g. given 123456L, return "123,456" (for some European country).

Parameters:

num The number to convert

Returns:
The number as a localized string

Since:
3.2

Definition at line 1091 of file klocale.cpp.
References formatNumber().

bool KLocale::nounDeclension ( ) const

Use this to determine whether nouns are declined in locale's language.
This property should remain read-only (no setter function)

Returns:
If nouns are declined

Since:
3.1

Definition at line 899 of file klocale.cpp.

QString KLocale::formatDate ( const QDate & pDate,

bool shortFormat = false

) const

Returns a string formatted to the current locale's conventions regarding dates.

Parameters:

pDate The date to be formated.

shortFormat True for non text dates.

Returns:
The date as a string

Definition at line 1101 of file klocale.cpp.
References QString::append(), QString::at(), calendar(), dateFormat(), dateFormatShort(), QString::length(), KCalendarSystem::month(), monthName(), monthNamePossessive(), weekDayName(), and KCalendarSystem::year().
Referenced by formatDateTime().

bool KLocale::dateMonthNamePossessive ( ) const

Use this to determine whether in dates a possessive form of month name is preferred ("of January" rather than "January").

Returns:
If possessive form should be used

Since:
3.1

Definition at line 905 of file klocale.cpp.

QString KLocale::formatTime ( const QTime & pTime,

bool includeSecs = false

) const

Returns a string formatted to the current locale's conventions regarding times.

Parameters:

pTime The time to be formated.

includeSecs if true, seconds are included in the output, otherwise only hours and minutes are formatted.

Returns:
The time as a string

Definition at line 1626 of file klocale.cpp.
References QString::at(), QTime::hour(), QString::length(), QTime::minute(), QTime::second(), timeFormat(), and translate().
Referenced by formatDateTime().

bool KLocale::use12Clock ( ) const

Use this to determine if the user wants a 12 hour clock.

Returns:
If the user wants 12h clock

Definition at line 1705 of file klocale.cpp.
References QString::contains(), and timeFormat().

bool KLocale::weekStartsMonday ( ) const

Deprecated:
Please use the weekStartDay method instead.
Use this to determine if the user wants the week to start on Monday.

Returns:
true if the week starts on Monday

Definition at line 917 of file klocale.cpp.

int KLocale::weekStartDay ( ) const

Use this to determine which day is the first day of the week.

Returns:
an integer (Monday=1..Sunday=7)

Since:
3.1

Definition at line 911 of file klocale.cpp.

QString KLocale::monthName ( int i,

bool shortName = false

) const

Deprecated:
Returns a string containing the name of the month name used in the Gregorian calendar.

Parameters:

i the month number of the year starting at 1/January.

shortName we will return the short version of the string.

Returns:
The name of the month

Definition at line 489 of file klocale.cpp.
References translate().
Referenced by formatDate().

QString KLocale::monthNamePossessive ( int i,

bool shortName = false

) const

Deprecated:
Returns a string containing the possessive form of the month name used in the Gregorian calendar. ("of January", "of February", etc.) It's needed in long format dates in some languages.

Parameters:

i the month number of the year starting at 1/January.

shortName we will return the short version of the string.

Returns:
The possessive form of the name of the month

Since:
3.1

Definition at line 527 of file klocale.cpp.
References translate().
Referenced by formatDate().

QString KLocale::weekDayName ( int i,

bool shortName = false

) const

Deprecated:
use calendar()->weekDayName
Returns a string containing the name of the week day used in the Gregorian calendar.

Parameters:

i the day number of the week starting at 1/Monday.

shortName we will return the short version of the string.

Returns:
The name of the day

Definition at line 565 of file klocale.cpp.
References translate().
Referenced by formatDate().

const KCalendarSystem * KLocale::calendar ( ) const

Returns a pointer to the calendar system object.

Returns:
the current calendar system instance

Since:
3.2

Definition at line 2153 of file klocale.cpp.
References KCalendarSystemFactory::create().
Referenced by formatDate(), and readDate().

QString KLocale::calendarType ( ) const

Returns the name of the calendar system that is currently being used by the system.

Returns:
the name of the calendar system

Since:
3.2

Definition at line 2146 of file klocale.cpp.

void KLocale::setCalendar ( const QString & calendarType )

Changes the current calendar system to the calendar specified.
Currently is "gregorian" and "hijri" supported. If the calendar system specified is not found, gregorian will be used.

Parameters:

calendarType the name of the calendar type

Since:
3.2

Definition at line 2136 of file klocale.cpp.

QString KLocale::formatDateTime ( const QDateTime & pDateTime,

bool shortFormat = true,

bool includeSecs = false

) const

Returns a string formated to the current locale's conventions regarding both date and time.

Parameters:

pDateTime The date and time to be formated.

shortFormat using the short date format.

includeSecs using the short date format.

Returns:
The date and time as a string

Definition at line 1724 of file klocale.cpp.
References QString::arg(), QDateTime::date(), formatDate(), formatTime(), QDateTime::time(), and translate().

double KLocale::readMoney ( const QString & numStr,

bool * ok = 0

) const

Converts a localized monetary string to a double.

Parameters:

numStr the string we want to convert.

ok the boolean that is set to false if it's not a number. If ok is 0, it will be ignored

Returns:
The string converted to a double

Definition at line 1244 of file klocale.cpp.
References currencySymbol(), QString::find(), QString::isEmpty(), QString::left(), QString::length(), QString::mid(), monetaryDecimalSymbol(), monetaryThousandsSeparator(), negativeMonetarySignPosition(), negativeSign(), QString::remove(), QString::stripWhiteSpace(), and QString::toDouble().

double KLocale::readNumber ( const QString & numStr,

bool * ok = 0

) const

Converts a localized numeric string to a double.

Parameters:

numStr the string we want to convert.

ok the boolean that is set to false if it's not a number. If ok is 0, it will be ignored

Returns:
The string converted to a double

Definition at line 1179 of file klocale.cpp.
References decimalSymbol(), QString::find(), QString::left(), QString::length(), QString::mid(), negativeSign(), QString::remove(), QString::stripWhiteSpace(), thousandsSeparator(), and QString::toDouble().

QDate KLocale::readDate ( const QString & str,

bool * ok = 0

) const

Converts a localized date string to a QDate.
The bool pointed by ok will be invalid if the date entered was not valid.

Parameters:

str the string we want to convert.

ok the boolean that is set to false if it's not a valid date. If ok is 0, it will be ignored

Returns:
The string converted to a QDate

Definition at line 1357 of file klocale.cpp.
References QDate::isValid().
Referenced by readDate().

QDate KLocale::readDate ( const QString & intstr,

const QString & fmt,

bool * ok = 0

) const

Converts a localized date string to a QDate, using the specified format.
You will usually not want to use this method.
Definition at line 1371 of file klocale.cpp.
References QString::at(), calendar(), KCalendarSystem::dayStringToInteger(), QChar::isSpace(), QString::length(), QString::lower(), QString::mid(), KCalendarSystem::monthName(), KCalendarSystem::monthNamePossessive(), KCalendarSystem::monthStringToInteger(), KCalendarSystem::setYMD(), QString::simplifyWhiteSpace(), KCalendarSystem::weekDayName(), KCalendarSystem::year(), and KCalendarSystem::yearStringToInteger().

QDate KLocale::readDate ( const QString & str,

ReadDateFlags flags,

bool * ok = 0

) const

Converts a localized date string to a QDate.
This method is stricter than readDate(str,&ok): it will either accept a date in full format or a date in short format, depending on flags.

Parameters:

str the string we want to convert.

flags whether the date string is to be in full format or in short format.

ok the boolean that is set to false if it's not a valid date. If ok is 0, it will be ignored

Returns:
The string converted to a QDate

Since:
3.2

Definition at line 1365 of file klocale.cpp.
References dateFormat(), dateFormatShort(), readDate(), and QString::simplifyWhiteSpace().

QTime KLocale::readTime ( const QString & str,

bool * ok = 0

) const

Converts a localized time string to a QTime.
This method will try to parse it with seconds, then without seconds. The bool pointed by ok will be false if the time entered was not valid.

Parameters:

str the string we want to convert.

ok the boolean that is set to false if it's not a valid time. If ok is 0, it will be ignored

Returns:
The string converted to a

kdecore Library API Documentation

KLocale Class Reference

Public Types

Public Member Functions

Static Public Member Functions

Static Protected Member Functions

Friends

Related Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation