Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Location: e32std.h
Link against: euser.lib

Class TLocale

class TLocale;

Description

Sets and gets the system's locale settings.

Symbian OS maintains the locale information internally. On construction, this object is initialized with the system information for all locale items.

Members

Defined in TLocale:
AmPmSpaceBetween(), AmPmSymbolPosition(), ClockFormat(), CountryCode(), CurrencyDecimalPlaces(), CurrencyNegativeInBrackets(), CurrencySpaceBetween(), CurrencySymbolPosition(), CurrencyTriadsAllowed(), DateFormat(), DateSeparator(), DaylightSaving(), DecimalSeparator(), DeviceTime(), DigitType(), EDeviceUserTime, EFlagNegativeCurrencySymbolOpposite, EFlagNegativeLoseSpace, EInBrackets, EInterveningMinusSign, ELeadingMinusSign, ENITZNetworkTimeSync, ETrailingMinusSign, FormatCurrency(), FormatCurrency(), FormatCurrency(), FormatCurrency(), HomeDaylightSavingZone(), LanguageDowngrade(), NegativeCurrencyFormat(), NegativeCurrencySymbolOpposite(), NegativeLoseSpace(), QueryHomeHasDaylightSavingOn(), Refresh(), Set(), SetAmPmSpaceBetween(), SetAmPmSymbolPosition(), SetClockFormat(), SetCountryCode(), SetCurrencyDecimalPlaces(), SetCurrencyNegativeInBrackets(), SetCurrencySpaceBetween(), SetCurrencySymbolPosition(), SetCurrencyTriadsAllowed(), SetDateFormat(), SetDateSeparator(), SetDecimalSeparator(), SetDeviceTime(), SetDigitType(), SetLanguageDowngrade(), SetNegativeCurrencyFormat(), SetNegativeCurrencySymbolOpposite(), SetNegativeLoseSpace(), SetStartOfWeek(), SetThousandsSeparator(), SetTimeFormat(), SetTimeSeparator(), SetUnitsDistanceLong(), SetUnitsDistanceShort(), SetUnitsGeneral(), SetWorkDays(), StartOfWeek(), TDeviceTimeState, TLocale(), TLocale(), TNegativeCurrencyFormat, ThousandsSeparator(), TimeFormat(), TimeSeparator(), UnitsDistanceLong(), UnitsDistanceShort(), UnitsGeneral(), UniversalTimeOffset(), WorkDays(), anonymous


Construction and destruction


TLocale()

IMPORT_C TLocale();

Description

Default constructor.

It constructs the object with the system's locale settings.

A single copy of the locale information is maintained by the system. This copy may be refreshed under application control with TLocale::Refresh(), and the settings may be saved to the system with TLocale::Set(). However, the settings are never updated by the system apart from under application control. This enables applications to guarantee that consistent locale information is used.

See also:


TLocale()

inline TLocale(TInt);

Description

Parameters

TInt

[Top]


Member functions


Refresh()

IMPORT_C void Refresh();

Description

Refreshes the contents of this object with the system's locale settings.


Set()

Capability: WriteDeviceData

IMPORT_C TInt Set() const;

Description

Transfers the locale settings from this object to the system. Note that the timezone offset and daylight savings flags are ignored as setting these through TLocale is no longer supported.

After this function has been called, other applications may use the new settings for newly-constructed TLocale objects, or if they use TLocale::Refresh(), to refresh their settings from the system copy.

Return value

TInt

KErrNone if successful, otherwise one of the other system wide error codes.

See also:


FormatCurrency()

IMPORT_C void FormatCurrency(TDes &aText, TInt aAmount);

Description

Renders a currency value as text, based on the locale's currency and numeric format settings.

These settings include the currency symbol, the symbol's position and the way negative values are formatted.

Parameters

TDes &aText

On return, contains the currency value as text, formatted according to the locale's currency format settings.

TInt aAmount

The currency value to be formatted.

Panic codes

USER

11, if aText is not long enough to hold the formatted value.


FormatCurrency()

IMPORT_C void FormatCurrency(TDes &aText, TInt64 aAmount);

Description

Renders a currency value as text, based on the locale's currency and numeric format settings.

These settings include the currency symbol, the symbol's position and the way negative values are formatted.

Parameters

TDes &aText

On return, contains the currency value as text, formatted according to the locale's currency format settings.

TInt64 aAmount

The currency value to be formatted.

Panic codes

USER

11, if aText is not long enough to hold the formatted value.


FormatCurrency()

IMPORT_C void FormatCurrency(TDes &aText, TDesOverflow &aOverflowHandler, TInt aAmount);

Description

Renders a currency value as text, based on the locale's currency and numeric format settings.

These settings include the currency symbol, the symbol's position and the way negative values are formatted. If aText is not long enough to hold the formatted currency value, the overflow handler's Overflow() function is called.

Parameters

TDes &aText

On return, contains the currency value as text, formatted according to the locale's currency format settings.

TDesOverflow &aOverflowHandler

An object derived from TDesOverflow which handles descriptor overflows.

TInt aAmount

The currency value to be formatted.


FormatCurrency()

IMPORT_C void FormatCurrency(TDes &aText, TDesOverflow &aOverflowHandler, TInt64 aAmount);

Description

Renders a currency value as text, based on the locale's currency and numeric format settings.

These settings include the currency symbol, the symbol's position and the way negative values are formatted. If aText is not long enough to hold the formatted currency value, the overflow handler's Overflow() function is called.

Parameters

TDes &aText

On return, contains the currency value as text, formatted according to the locale's currency format settings.

TDesOverflow &aOverflowHandler

An object derived from TDesOverflow which handles descriptor overflows.

TInt64 aAmount

The currency value to be formatted.


CountryCode()

inline TInt CountryCode() const;

Description

Gets the code which is used to select country-specific locale data.

The country code is the code used as the international dialling prefix. This code is also used to identify a country by the dialling software.

Return value

TInt

The country code.


SetCountryCode()

inline void SetCountryCode(TInt aCode);

Description

Sets the value which is used to select country-specific locale data.

This value can be retrieved by using TLocale::CountryCode(). The country code is the code used as the international dialling prefix. This code is also used to identify a country by the dialling software.

Parameters

TInt aCode

The country code.


UniversalTimeOffset()

inline TTimeIntervalSeconds UniversalTimeOffset() const;

Description

Gets the locale's universal time offset.

Return value

TTimeIntervalSeconds

Offset in seconds from universal time. Time zones east of universal time have positive offsets. Time zones west of universal time have negative offsets.


DateFormat()

inline TDateFormat DateFormat() const;

Description

Gets the date format.

Return value

TDateFormat

The date format.


SetDateFormat()

inline void SetDateFormat(TDateFormat aFormat);

Description

Sets the date format.

Parameters

TDateFormat aFormat

The date format to be used.


TimeFormat()

inline TTimeFormat TimeFormat() const;

Description

Gets the time format (12 or 24 hour).

Return value

TTimeFormat

The time format.


SetTimeFormat()

inline void SetTimeFormat(TTimeFormat aFormat);

Description

Sets the time format (12 or 24 hour).

Parameters

TTimeFormat aFormat

The time format.


CurrencySymbolPosition()

inline TLocalePos CurrencySymbolPosition() const;

Description

Gets the currency symbol position.

For negative currency values, this position may be reversed using SetNegativeCurrencySymbolOpposite().

Return value

TLocalePos

The currency symbol position.


SetCurrencySymbolPosition()

inline void SetCurrencySymbolPosition(TLocalePos aPos);

Description

Sets the currency symbol position.

Parameters

TLocalePos aPos

The currency symbol position.


CurrencySpaceBetween()

inline TBool CurrencySpaceBetween() const;

Description

Gets whether or not a space is inserted between the currency symbol and the currency value.

For negative currency values, the space can be removed using SetNegativeLoseSpace().

Return value

TBool

True if a space is inserted; false if not.


SetCurrencySpaceBetween()

inline void SetCurrencySpaceBetween(TBool aSpace);

Description

Sets whether a space is inserted between the currency symbol and the currency amount.

Parameters

TBool aSpace

ETrue if a space is inserted; EFalse if not.


CurrencyDecimalPlaces()

inline TInt CurrencyDecimalPlaces() const;

Description

Gets the number of decimal places to which currency values are set.

Return value

TInt

The number of decimal places.


SetCurrencyDecimalPlaces()

inline void SetCurrencyDecimalPlaces(TInt aPlaces);

Description

Sets the number of decimal places to which currency values should be set.

Parameters

TInt aPlaces

The number of decimal places.


CurrencyNegativeInBrackets()

inline TBool CurrencyNegativeInBrackets() const;

Description

Gets whether negative currency values are enclosed in brackets rather than being preceded by a minus sign.

This is deprecated, use NegativeCurrencyFormat() instead.

Return value

TBool

True if negative currency is enclosed in brackets and has no minus sign; false if negative currency has a minus sign and is not enclosed in brackets.


SetCurrencyNegativeInBrackets()

inline void SetCurrencyNegativeInBrackets(TBool aBool);

Description

Sets whether negative currency values are enclosed in brackets rather than being preceded by a minus sign.

This is deprecated, use SetNegativeCurrencyFormat() instead.

Parameters

TBool aBool

ETrue, if a negative currency value must be enclosed in brackets without a minus sign; EFalse, if a negative currency value is preceded by a minus sign without any enclosing brackets.


CurrencyTriadsAllowed()

inline TBool CurrencyTriadsAllowed() const;

Description

Gets whether triads are allowed in currency values. Triads are groups of three digits separated by the thousands separator.

Return value

TBool

True if triads are allowed; false if not.


SetCurrencyTriadsAllowed()

inline void SetCurrencyTriadsAllowed(TBool aBool);

Description

Sets whether triads are allowed in currency values.

Parameters

TBool aBool

ETrue if triads are allowed; EFalse if triads not allowed.


ThousandsSeparator()

inline TChar ThousandsSeparator() const;

Description

Gets the character used to separate groups of three digits to the left of the decimal separator.

A thousands separator character is only displayed in currency values if currency triads are allowed.

Return value

TChar

The character used as the thousands separator.


SetThousandsSeparator()

inline void SetThousandsSeparator(const TChar &aChar);

Description

Sets the character to be used to separate groups of three digits to the left of the decimal separator.

A thousands separator character is only displayed in currency values if currency triads are allowed.

Parameters

const TChar &aChar

The character to be used as the thousands separator.


DecimalSeparator()

inline TChar DecimalSeparator() const;

Description

Gets the character used to separate a whole number from its fractional part.

Return value

TChar

The character used as the decimal separator.


SetDecimalSeparator()

inline void SetDecimalSeparator(const TChar &aChar);

Description

Sets the character to be used to separate a whole number from its fractional part.

Parameters

const TChar &aChar

The character to be used as the decimal separator.


DateSeparator()

inline TChar DateSeparator(TInt aIndex) const;

Description

Gets one of the four characters used to separate the day, month and year components of the date.

If the four separators are represented by S0, S1, S2 and S3 and the three date components are represented by XX, YY and ZZ, then the separators are located: S0 XX S1 YY S2 ZZ S3.

Parameters

TInt aIndex

An index indicating which of the four separators is being accessed. This must be a value between zero and three inclusive.

Return value

TChar

A date separator character as determined by the value of aIndex.


SetDateSeparator()

inline void SetDateSeparator(const TChar &aChar, TInt aIndex);

Description

Sets one of the four characters used to separate the day, month and year components of the date.

If the four separators are represented by S0, S1, S2 and S3 and the three date components are represented by XX, YY and ZZ, then the separators are located: S0 XX S1 YY S2 ZZ S3.

Parameters

const TChar &aChar

A date separator character to be used.

TInt aIndex

An index indicating which of the four separators is being accessed. This must be a value between zero and three inclusive.


TimeSeparator()

inline TChar TimeSeparator(TInt aIndex) const;

Description

Gets one of the four characters used to separate the hour, second and minute components of the time.

If the four separators are represented by S0, S1, S2 and S3 and the three time components are represented by XX, YY and ZZ, then the separators are located: S0 XX S1 YY S2 ZZ S3.

Parameters

TInt aIndex

An index indicating which of the four separators is being accessed. This must be a value between zero and three inclusive.

Return value

TChar

A time separator character as determined by the value of aIndex.


SetTimeSeparator()

inline void SetTimeSeparator(const TChar &aChar, TInt aIndex);

Description

Sets one of the four characters used to separate the hour, minute and second components of the date.

If the four separators are represented by S0, S1, S2 and S3 and the three time components are represented by XX, YY and ZZ, then the separators are located: S0 XX S1 YY S2 ZZ S3.

Parameters

const TChar &aChar

A time separator character to be used.

TInt aIndex

An index indicating which of the four separators is being accessed. This must be a value between zero and three inclusive.


AmPmSpaceBetween()

inline TBool AmPmSpaceBetween() const;

Description

Tests whether or not a space is inserted between the time and the preceding or trailing am/pm text.

Return value

TBool

True if a space is inserted between the time and am/pm text; false if not.


SetAmPmSpaceBetween()

inline void SetAmPmSpaceBetween(TBool aSpace);

Description

Sets whether a space is inserted between the time and the preceding or trailing am/pm text.

Parameters

TBool aSpace


AmPmSymbolPosition()

inline TLocalePos AmPmSymbolPosition() const;

Description

Gets the am/pm text position (before or after the time value).

Return value

TLocalePos

The am/pm text position (0 before, 1 after).


SetAmPmSymbolPosition()

inline void SetAmPmSymbolPosition(TLocalePos aPos);

Description

Sets the am/pm text position (before or after the time value).

Parameters

TLocalePos aPos


DaylightSaving()

inline TUint DaylightSaving() const;

Description

Gets the zones in which daylight saving is in effect.

If daylight saving is in effect, one hour is added to the time.

Use TLocale::QueryHomeHasDaylightSavingOn() to find out whether daylight saving is in effect for the home city. This is because the daylight saving setting for the home city may differ from that of the zone in which home is located.

Return value

TUint

A bit mask in which the three least significant bits are defined, indicating which of the three daylight saving zones are adjusted for daylight saving. These bits represent: Northern (non-European countries in the northern hemisphere), Southern (southern hemisphere), and European.

See also:


QueryHomeHasDaylightSavingOn()

inline TBool QueryHomeHasDaylightSavingOn() const;

Description

Tests whether or not daylight saving is set for the home city.

Return value

TBool

True if home daylight saving is set; false if not.


HomeDaylightSavingZone()

inline TDaylightSavingZone HomeDaylightSavingZone() const;

Description

Gets the daylight saving zone in which the home city is located.

Return value

TDaylightSavingZone

The daylight saving zone in which the home city is located.


WorkDays()

inline TUint WorkDays() const;

Description

Gets a bit mask representing the days of the week which are considered as working days.

Return value

TUint

A bit mask of seven bits indicating (by being set) which days are workdays. The least significant bit corresponds to Monday, the next bit to Tuesday and so on.


SetWorkDays()

inline void SetWorkDays(TUint aMask);

Description

Sets the days of the week which are considered as working days.

Parameters

TUint aMask

A bit mask of seven bits indicating (by being set) which days are workdays. The least significant bit corresponds to Monday, the next bit is Tuesday and so on.


StartOfWeek()

inline TDay StartOfWeek() const;

Description

Gets the day which is considered the first day of the week.

Return value

TDay

The first day of the week.


SetStartOfWeek()

inline void SetStartOfWeek(TDay aDay);

Description

Sets the day which is considered to be the first day of the week.

Parameters

TDay aDay

The first day of the week.


ClockFormat()

inline TClockFormat ClockFormat() const;

Description

Gets the clock display format.

Return value

TClockFormat

The clock display format.


SetClockFormat()

inline void SetClockFormat(TClockFormat aFormat);

Description

Sets the clock display format.

Parameters

TClockFormat aFormat

The clock display format.


UnitsGeneral()

inline TUnitsFormat UnitsGeneral() const;

Description

Gets the general units of measurement.

This function should be used when both short and long distances use the same units of measurement.

Return value

TUnitsFormat

General units of measurement.


SetUnitsGeneral()

inline void SetUnitsGeneral(TUnitsFormat aFormat);

Description

Sets the general units of measurement. This function should be used when both short and long distances use the same units of measurement.

Parameters

TUnitsFormat aFormat

General units of measurement.


UnitsDistanceShort()

inline TUnitsFormat UnitsDistanceShort() const;

Description

Gets the units of measurement for short distances.

Short distances are those which would normally be represented by either metres and centimetres or feet and inches.

Return value

TUnitsFormat

Units of measurement for short distances.


SetUnitsDistanceShort()

inline void SetUnitsDistanceShort(TUnitsFormat aFormat);

Description

Sets the units of measurement for short distances.

Short distances are those which would normally be represented by either metres and centimetres or feet and inches.

Parameters

TUnitsFormat aFormat

Units of measurement for short distances.


UnitsDistanceLong()

inline TUnitsFormat UnitsDistanceLong() const;

Description

Gets the units of measurement for long distances.

Long distances are those which would normally be represented by either miles or kilometres.

Return value

TUnitsFormat

Units of measurement for long distances.


SetUnitsDistanceLong()

inline void SetUnitsDistanceLong(TUnitsFormat aFormat);

Description

Sets the units of measurement for long distances.

Long distances are those which would normally be represented by either miles or kilometres.

Parameters

TUnitsFormat aFormat

Units of measurement for long distances.


NegativeCurrencyFormat()

inline TNegativeCurrencyFormat NegativeCurrencyFormat() const;

Description

Gets the negative currency format.

Return value

TNegativeCurrencyFormat

How negative currency values are formatted.


SetNegativeCurrencyFormat()

inline void SetNegativeCurrencyFormat(TNegativeCurrencyFormat aNegativeCurrencyFormat);

Description

Sets the negative currency format.

Parameters

TNegativeCurrencyFormat aNegativeCurrencyFormat

How negative currency values are formatted.


NegativeLoseSpace()

inline TBool NegativeLoseSpace() const;

Description

Gets whether negative currency values lose the space between the currency symbol and the value.

Return value

TBool

True, if negative currency values lose the space between the value and the symbol; false, if not.


SetNegativeLoseSpace()

inline void SetNegativeLoseSpace(TBool aBool);

Description

Sets whether negative currency values lose the space between the currency symbol and the value.

Parameters

TBool aBool

ETrue to set a flag which indicates that negative currency values should lose the space between the value and the symbol. EFalse to unset it.


NegativeCurrencySymbolOpposite()

inline TBool NegativeCurrencySymbolOpposite() const;

Description

Gets whether in negative currency values, the position of the currency symbol is set to be the opposite of the position used for non-negative values (before or after the value, as set by SetCurrencySymbolPosition()).

Return value

TBool

True, if the currency symbol position for negative currency values is the opposite of the position set by SetCurrencySymbolPosition(); false, otherwise.


SetNegativeCurrencySymbolOpposite()

inline void SetNegativeCurrencySymbolOpposite(TBool aBool);

Description

Sets whether the position of the currency symbol for negative currency values should be the opposite of the position used for non-negative values (before or after the value, as set by SetCurrencySymbolPosition()).

Parameters

TBool aBool

ETrue to set the position of the currency symbol in negative currency values to be the opposite of the position as set using SetCurrencySymbolPosition(). EFalse to leave the position unchanged.


LanguageDowngrade()

inline TLanguage LanguageDowngrade(TInt aIndex) const;

Description

Gets the language that is stored at the specified index into the customisable part of the language downgrade path.

The second, third and fourth languages in the language downgrade path can be customised. These can be enquired using this function. The first language in the path is always the language of the current locale, as returned by User::Language().

The languages in the downgrade path are used in turn by the BaflUtils::NearestLanguageFile() function to find the best matching language-specific version of a language-neutral filename.

The full language downgrade path can be retrieved using BaflUtils::GetDowngradePath().

Parameters

TInt aIndex

An index into the customisable part of the language downgrade path. Between zero and two inclusive.

Return value

TLanguage

The language at the specified index.


SetLanguageDowngrade()

inline void SetLanguageDowngrade(TInt aIndex, TLanguage aLanguage);

Description

Sets a language in the customisable part of the language downgrade path.

Parameters

TInt aIndex

An index into the customisable part of the path at which to add the language, a value between zero and two.

TLanguage aLanguage

The language to add. ELangNone is considered to be the last language in the path, no more will be searched, so can be used to specify that no language downgrade is required.


DigitType()

inline TDigitType DigitType() const;

Description

Gets the number mode stored in the locale.

Return value

TDigitType

The number mode for the locale.


SetDigitType()

inline void SetDigitType(TDigitType aDigitType);

Description

Sets the number mode for the locale.

Parameters

TDigitType aDigitType

The number mode to be set.


DeviceTime()

inline TDeviceTimeState DeviceTime() const;

Description

Gets the device time state.

Return value

TDeviceTimeState

The device time state.


SetDeviceTime()

inline void SetDeviceTime(TDeviceTimeState aState);

Description

Sets the device time state.

Parameters

TDeviceTimeState aState

The device time state.

[Top]


Member enumerations


Enum TNegativeCurrencyFormat

TNegativeCurrencyFormat

Description

Indicates how negative currency values are formatted.

ELeadingMinusSign

A minus sign is inserted before the currency symbol and value.

EInBrackets

The currency value and symbol are enclosed in brackets (no minus sign is used).

ETrailingMinusSign

A minus sign is inserted after the currency symbol and value.

EInterveningMinusSign

A minus sign is inserted between the currency symbol and the value.


Enum anonymous

n/a

Description

Flags for negative currency values formatting

EFlagNegativeLoseSpace

If this flag is set and the currency value being formatted is negative, if there is a space between the currency symbol and the value, that space is lost.

EFlagNegativeCurrencySymbolOpposite

If this flag is set and the currency value being formatted is negative, the position of the currency symbol is placed in the opposite direction from the position set for the positive currency value.


Enum TDeviceTimeState

TDeviceTimeState

Description

Indicates how the device universal time is maintained

EDeviceUserTime

Universal time is maintained by the device RTC and the user selection of the locale of the device indicating offset from GMT and daylight saving

ENITZNetworkTimeSync

Universal time and offset from GMT is supplied by the mobile network and maintained by device RTC