KDECore

KLocale Class Reference

#include <klocale.h>

Detailed Description

KLocale provides support for country specific stuff like the national language.

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

Use KGlobal::locale() to get pointer to the global KLocale object, containing the applications current locale settings.

For example, to format the date May 17, 1995 in the current locale, use:

   QString date = KGlobal::locale()->formatDate(QDate(1995,5,17));

Author:: Stephan Kulow <coolo@kde.org>, Preston Brown <pbrown@kde.org>, Hans Petter Bieker <bieker@kde.org>, Lukas Tinkl <lukas.tinkl@suse.cz> class for supporting locale settings and national language

Definition at line 67 of file klocale.h.


Public Types
enum	DateFormat { ShortDate, LongDate, FancyShortDate, FancyLongDate }
enum	DateTimeFormatOption { TimeZone = 0x01, Seconds = 0x02 }
enum	MeasureSystem { Metric, Imperial }
enum	ReadDateFlags { NormalFormat = 1, ShortFormat = 2 }
enum	ReadTimeFlags { WithSeconds = 0, WithoutSeconds = 1 }
enum	SignPosition { ParensAround = 0, BeforeQuantityMoney = 1, AfterQuantityMoney = 2, BeforeMoney = 3, AfterMoney = 4 }
Public Member Functions
QStringList	allCountriesList () const
QStringList	allLanguagesList () const
const KCalendarSystem *	calendar () const
QString	calendarType () const
QTextCodec *	codecForEncoding () const
void	copyCatalogsTo (KLocale *locale)
QString	country () const
QString	countryCodeToName (const QString &country) const
QString	currencySymbol () const
QString	dateFormat () const
QString	dateFormatShort () const
bool	dateMonthNamePossessive () const
QString	decimalSymbol () const
const QByteArray	encoding () const
int	encodingMib () const
int	fileEncodingMib () const
QString	formatByteSize (double size) const
QString	formatDate (const QDate &date, DateFormat format=LongDate) const
QString	formatDateTime (const KDateTime &dateTime, DateFormat format=ShortDate, DateTimeFormatOptions options=0) const
QString	formatDateTime (const QDateTime &dateTime, DateFormat format=ShortDate, bool includeSecs=false) const
QString	formatDuration (unsigned long mSec) const
QString	formatLong (long num) const
QString	formatMoney (double num, const QString &currency=QString(), int digits=-1) const
QString	formatNumber (const QString &numStr, bool round=true, int precision=2) const
QString	formatNumber (double num, int precision=-1) const
QString	formatTime (const QTime &pTime, bool includeSecs=false, bool isDuration=false) const
int	fracDigits () const
void	insertCatalog (const QString &catalog)
bool	isApplicationTranslatedInto (const QString &language)
	KLocale (const KLocale &rhs)
	KLocale (const QString &catalog, const QString &language, const QString &country=QString(), KConfig *config=0)
	KLocale (const QString &catalog, KSharedConfig::Ptr config=KSharedConfig::Ptr())
QString	language () const
QString	languageCodeToName (const QString &language) const
QStringList	languageList () const
QString	localizedFilePath (const QString &filePath) const
MeasureSystem	measureSystem () const
QString	monetaryDecimalSymbol () const
QString	monetaryThousandsSeparator () const
SignPosition	negativeMonetarySignPosition () const
bool	negativePrefixCurrencySymbol () const
QString	negativeSign () const
bool	nounDeclension () const
KLocale &	operator= (const KLocale &rhs)
int	pageSize () const
SignPosition	positiveMonetarySignPosition () const
bool	positivePrefixCurrencySymbol () const
QString	positiveSign () const
QString	prettyFormatDuration (unsigned long mSec) const
QDate	readDate (const QString &str, ReadDateFlags flags, bool *ok=0) const
QDate	readDate (const QString &intstr, const QString &fmt, bool *ok=0) const
QDate	readDate (const QString &str, bool *ok=0) const
double	readMoney (const QString &numStr, bool *ok=0) const
double	readNumber (const QString &numStr, bool *ok=0) const
QTime	readTime (const QString &str, ReadTimeFlags flags, bool *ok=0) const
QTime	readTime (const QString &str, bool *ok=0) const
void	removeCatalog (const QString &catalog)
void	setActiveCatalog (const QString &catalog)
void	setCalendar (const QString &calendarType)
bool	setCountry (const QString &country, KConfig *config)
void	setCurrencySymbol (const QString &symbol)
void	setDateFormat (const QString &format)
void	setDateFormatShort (const QString &format)
void	setDateMonthNamePossessive (bool possessive)
void	setDecimalSymbol (const QString &symbol)
bool	setEncoding (int mibEnum)
void	setFracDigits (int digits)
bool	setLanguage (const QStringList &languages)
bool	setLanguage (const QString &language, KConfig *config)
void	setMeasureSystem (MeasureSystem value)
void	setMonetaryDecimalSymbol (const QString &symbol)
void	setMonetaryThousandsSeparator (const QString &separator)
void	setNegativeMonetarySignPosition (SignPosition signpos)
void	setNegativePrefixCurrencySymbol (bool prefix)
void	setNegativeSign (const QString &sign)
void	setPageSize (int paperFormat)
void	setPositiveMonetarySignPosition (SignPosition signpos)
void	setPositivePrefixCurrencySymbol (bool prefix)
void	setPositiveSign (const QString &sign)
void	setThousandsSeparator (const QString &separator)
void	setTimeFormat (const QString &format)
void	setWeekStartDay (int day)
QString	thousandsSeparator () const
QString	timeFormat () const
QString	translateQt (const char context, const char sourceText, const char *comment) const
void	translateRaw (const char ctxt, const char singular, const char plural, unsigned long n, QString lang, QString *trans) const
void	translateRaw (const char singular, const char plural, unsigned long n, QString lang, QString trans) const
void	translateRaw (const char ctxt, const char msg, QString lang, QString trans) const
void	translateRaw (const char msg, QString lang, QString *trans) const
bool	use12Clock () const
bool	useTranscript () const
int	weekStartDay () const
virtual	~KLocale ()
Static Public Member Functions
static QString	defaultCountry ()
static QString	defaultLanguage ()
static QString	langLookup (const QString &fname, const char *rtype="html")
static void	setMainCatalog (const char *catalog)
static void	splitLocale (const QString &locale, QString &language, QString &country, QString &modifier, QString &charset)

Member Enumeration Documentation

enum KLocale::DateFormat

Format for date string.

Enumerator:

ShortDate	Short (numeric) date format, e.g. 08-04-2007
LongDate	Long (text) date format, e.g. Sunday 08 April 2007
FancyShortDate	Same as ShortDate for dates a week or more ago. For more recent dates, it is represented as Today, Yesterday, or the weekday name.
FancyLongDate	Same as LongDate for dates a week or more ago. For more recent dates, it is represented as Today, Yesterday, or the weekday name.

Definition at line 443 of file klocale.h.

enum KLocale::DateTimeFormatOption

Options for formatting date-time values.

Enumerator:

TimeZone	Include a time zone string.
Seconds	Include the seconds value.

Definition at line 481 of file klocale.h.

enum KLocale::MeasureSystem

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

Enumerator:

Metric	Metric system (used e.g. in Europe).
Imperial	Imperial system (used e.g. in the United States).

Definition at line 937 of file klocale.h.

enum KLocale::ReadDateFlags

Flags for readDate().

Enumerator:

NormalFormat	Only accept a date string in normal (long) format.
ShortFormat	Only accept a date string in short format.

Definition at line 604 of file klocale.h.

enum KLocale::ReadTimeFlags

Flags for readTime().

Enumerator:

WithSeconds	Only accept a time string with seconds. Default (no flag set).
WithoutSeconds	Only accept a time string without seconds.

Definition at line 640 of file klocale.h.

enum KLocale::SignPosition

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

Enumerator:

ParensAround	Put parantheses around the quantity, e.g. "$ (217)"
BeforeQuantityMoney	Prefix the quantity with the sign, e.g. "$ -217"
AfterQuantityMoney	Suffix the quanitity with the sign, e.g. "$ 217-"
BeforeMoney	Prefix the currency symbol with the sign, e.g. "-$ 217"
AfterMoney	Suffix the currency symbol with the sign, e.g. "$- 217"

Definition at line 206 of file klocale.h.

Constructor & Destructor Documentation

KLocale::KLocale	(	const QString &	catalog,
		KSharedConfig::Ptr	config = `KSharedConfig::Ptr()`
	)			`[explicit]`

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 file. If KLocale is not able to use any 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 255 of file klocale.cpp.

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

Definition at line 260 of file klocale.cpp.

KLocale::KLocale ( const KLocale & rhs )

Copy constructor.

Definition at line 2361 of file klocale.cpp.

KLocale::~KLocale ( ) [virtual]

Destructor.

Definition at line 690 of file klocale.cpp.

Member Function Documentation

QStringList KLocale::allCountriesList ( ) const

Provides list of all known country codes.

Use countryCodeToName(country) to get human readable, localized country names.

Returns:: a list of all country codes

See also:: countryCodeToName

Definition at line 2313 of file klocale.cpp.

QStringList KLocale::allLanguagesList ( ) const

Provides list of all known language codes.

Use languageCodeToName(language) to get human readable, localized language names.

Returns:: list of all language codes

See also:: languageCodeToName

Definition at line 2296 of file klocale.cpp.

const KCalendarSystem * KLocale::calendar ( ) const

Returns a pointer to the calendar system object.

Returns:: the current calendar system instance

Definition at line 2352 of file klocale.cpp.

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

Definition at line 2347 of file klocale.cpp.

QTextCodec * KLocale::codecForEncoding ( ) const

Returns the user's preferred encoding.

Should never be NULL.

Returns:: The codec for the preferred encoding

See also:: encoding
encodingMib

Definition at line 2277 of file klocale.cpp.

void KLocale::copyCatalogsTo ( KLocale * locale )

Copies the catalogs of this objct to an other KLocale object.

Definition at line 2377 of file klocale.cpp.

QString KLocale::country ( ) const

Returns the country code of the country where the user lives.

defaultCountry() is returned by default, if no other available.

Use countryCodeToName(country) to get human readable, localized country names.

Returns:: the country code for the user

See also:: countryCodeToName

Definition at line 617 of file klocale.cpp.

QString KLocale::countryCodeToName ( const QString & country ) const

Convert a known country code to a human readable, localized form.

If an unknown country code is supplied, empty string is returned; this will never happen if the code has been obtained by one of the KLocale methods.

Parameters:

code

the country code

Returns:: the human readable and localized form of the country name

See also:: country
allCountriesList

Definition at line 2327 of file klocale.cpp.

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 884 of file klocale.cpp.

QString KLocale::dateFormat ( ) const

Returns the currently selected date format.

Returns:: Current date format.

See also:: setDateFormat()

Definition at line 2135 of file klocale.cpp.

QString KLocale::dateFormatShort ( ) const

Returns the currently selected short date format.

Returns:: Current short date format.

See also:: setDateFormatShort()

Definition at line 2140 of file klocale.cpp.

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

Definition at line 863 of file klocale.cpp.

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 874 of file klocale.cpp.

QString KLocale::defaultCountry ( ) [static]

Returns the name of the default country.

Returns:: Name of the default country

Definition at line 2238 of file klocale.cpp.

QString KLocale::defaultLanguage ( ) [static]

Returns the name of the internal language.

Returns:: Name of the default language

Definition at line 2233 of file klocale.cpp.

const QByteArray KLocale::encoding ( ) const

Returns the user's preferred encoding.

Returns:: The name of the preferred encoding

See also:: codecForEncoding
encodingMib

Definition at line 2248 of file klocale.cpp.

int KLocale::encodingMib ( ) const

Returns the user's preferred encoding.

Returns:: The Mib of the preferred encoding

See also:: encoding
codecForEncoding

Definition at line 2265 of file klocale.cpp.

int KLocale::fileEncodingMib ( ) const

Returns the file encoding.

Returns:: The Mib of the file encoding

See also:: QFile::encodeName
QFile::decodeName

Definition at line 2270 of file klocale.cpp.

QString KLocale::formatByteSize ( double size ) const

Converts size from bytes to the string representation using the IEC 60027-2 standard.

Example: formatByteSize(1024) returns "1.0 KiB"

Parameters:

size

size in bytes

Returns:: converted size as a string - e.g. 123.4 KiB , 12.0 MiB

Definition at line 1174 of file klocale.cpp.

QString KLocale::formatDate	(	const QDate &	date,
		DateFormat	format = `LongDate`
	)			const

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

Parameters:

	date	the date to be formatted.
	format	category of date format to use

Returns:: The date as a string

Definition at line 1286 of file klocale.cpp.

QString KLocale::formatDateTime	(	const KDateTime &	dateTime,
		DateFormat	format = `ShortDate`,
		DateTimeFormatOptions	options = `0`
	)			const

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

Parameters:

	dateTime	the date and time to be formatted
	format	category of date format to use
	options	additional output options

Returns:: The date and time as a string

Definition at line 1971 of file klocale.cpp.

QString KLocale::formatDateTime	(	const QDateTime &	dateTime,
		DateFormat	format = `ShortDate`,
		bool	includeSecs = `false`
	)			const

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

Parameters:

	dateTime	the date and time to be formatted
	format	category of date format to use
	options	additional output options

Returns:: The date and time as a string

Definition at line 1953 of file klocale.cpp.

QString KLocale::formatDuration ( unsigned long mSec ) const

Given a number of milliseconds, converts that to a string containing the localized equivalent.

e.g. given formatDuration(60000), returns "1.0 minutes"

Parameters:

mSec

Time duration in milliseconds

Returns:: converted duration as a string - e.g. "5.5 seconds" "23.0 minutes"

Definition at line 1219 of file klocale.cpp.

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

Definition at line 1026 of file klocale.cpp.

QString KLocale::formatMoney	(	double	num,
		const QString &	currency = `QString()`,
		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 957 of file klocale.cpp.

QString KLocale::formatNumber	(	const QString &	numStr,
		bool	round = `true`,
		int	precision = `2`
	)			const

Given a string representing a number, converts that to a numeric string containing the localized numeric equivalent.

e.g. given 123456.78F, return "123,456.78" (for some European country).

Parameters:

	numStr	The number to format, as a string.
	round	Round fractional digits. (default true)
	precision	Number of fractional digits used for rounding. Unused if round=false. (default 2)

Returns:: The number as a localized string

Definition at line 1127 of file klocale.cpp.

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.

This function is a wrapper that is provided for convenience.

Parameters:

	num	The number to convert
	precision	Number of fractional digits used.

Returns:: The number as a localized string

See also:: formatNumber(const QString, bool, int)

Definition at line 1019 of file klocale.cpp.

QString KLocale::formatTime	(	const QTime &	pTime,
		bool	includeSecs = `false`,
		bool	isDuration = `false`
	)			const

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

Parameters:

	pTime	The time to be formatted.
	includeSecs	if true, seconds are included in the output, otherwise only hours and minutes are formatted.
	isDuration	if true, the given time is a duration, not a clock time. This means "am/pm" shouldn't be displayed.

Returns:: The time as a string

Definition at line 1838 of file klocale.cpp.

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 909 of file klocale.cpp.

void KLocale::insertCatalog ( const QString & catalog )

Adds another catalog to search for translation lookup.

This function is useful for extern libraries and/or code, that provide there own messages.

If the catalog does not exist for the chosen language, it will be ignored and en_US will be used.

Parameters:

catalog

The catalog to add.

Definition at line 622 of file klocale.cpp.

bool KLocale::isApplicationTranslatedInto ( const QString & language )

Checks whether or not the active catalog is found for the given language.

Parameters:

language

language to check

Definition at line 539 of file klocale.cpp.

QString KLocale::langLookup	(	const QString &	fname,
		const char *	rtype = `"html"`
	)			`[static]`

Deprecated:

Finds localized resource in resourceDir( rtype ) + <lang> + fname.

Since KDE 4.1, this service is provided in a slightly different form, automatically by e.g. KStandardDirs::locate() and other KDE core classes dealing with paths. For manual use, it is replaced by localizedFilePath().

Parameters:

	fname	relative path to find
	rtype	resource type to use

Returns:: path to localized resource

See also:: localizedFilePath

Definition at line 2016 of file klocale.cpp.

QString KLocale::language ( ) const

Returns the language code used by this object.

The domain AND the library translation must be available in this language. defaultLanguage() is returned by default, if no other available.

Use languageCodeToName(language) to get human readable, localized language name.

Returns:: the currently used language code

See also:: languageCodeToName

Definition at line 612 of file klocale.cpp.

QString KLocale::languageCodeToName ( const QString & language ) const

Convert a known language code to a human readable, localized form.

If an unknown language code is supplied, empty string is returned; this will never happen if the code has been obtained by one of the KLocale methods.

Parameters:

language

the language code

Returns:: the human readable and localized form if the code is known, empty otherwise

See also:

language

languageList

allLanguagesList

Definition at line 2304 of file klocale.cpp.

QStringList KLocale::languageList ( ) const

Returns the language codes selected by user, ordered by decreasing priority.

Use languageCodeToName(language) to get human readable, localized language name.

Returns:: list of language codes

See also:: languageCodeToName

Definition at line 1938 of file klocale.cpp.

QString KLocale::localizedFilePath ( const QString & filePath ) const

Since:: 4.1

Tries to find a path to the localized file for the given original path. This is intended mainly for non-text resources (images, sounds, etc.), whereas text resources should be handled in more specific ways.

The possible localized paths are checked in turn by priority of set languages, in form of dirname/l10n/ll/basename, where dirname and basename are those of the original path, and ll is the language code.

KDE core classes which resolve paths internally (e.g. KStandardDirs) will usually perform this lookup behind the scene. In general, you should pipe resource paths through this method only on explicit translators' request, or when a resource is an obvious candidate for localization (e.g. a splash screen or a custom icon with some text drawn on it).

Parameters:

filePath

path to the original file

Returns:: path to the localized file if found, original path otherwise

Definition at line 2383 of file klocale.cpp.

KLocale::MeasureSystem KLocale::measureSystem ( ) const

Returns which measuring system we use.

Returns:: The preferred measuring system

Definition at line 2223 of file klocale.cpp.

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 889 of file klocale.cpp.

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 894 of file klocale.cpp.

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 929 of file klocale.cpp.

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 919 of file klocale.cpp.

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 904 of file klocale.cpp.

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

Definition at line 858 of file klocale.cpp.

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

Assignment operator.

Definition at line 2367 of file klocale.cpp.

int KLocale::pageSize ( ) const

Returns the preferred page size for printing.

Returns:: The preferred page size, cast it to QPrinter::PageSize

Definition at line 2212 of file klocale.cpp.

KLocale::SignPosition KLocale::positiveMonetarySignPosition ( ) const

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

KDECore

KLocale Class Reference

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation