Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

6    Locale Manager

Text and Localization

Exploring Palm OS®

This chapter describes the Locale Manager API as described in the header file LocaleMgr.h. It discusses the following topics:

Locale Manager Functions and Macros

For more information on the Locale Manager, see the chapter "Localized Applications".

Locale Manager Functions and Macros ^TOP^

LmBestLocaleToIndex Function ^TOP^

Purpose

Converts an LmLocaleType to an index.

Declared In

LocaleMgr.h

Prototype

uint16_t LmBestLocaleToIndex (
   const LmLocaleType *iLocale
)

Parameters

iLocale
The locale to convert. This locale can use the constants lmAnyCountry or lmAnyLanguage as wildcards.

Returns

The index of the known locale that most closely matches iLocale.

Comments

This function first tries to find a locale that matches both the language and country of iLocale. If it does not exist, it then tries to match only the country and only the language. If it cannot find a match for either the country or the language, it returns the index of the first locale (in other words, it returns an index of 0).

Example

The following example shows using LmGetFormatsLocale() to return the locale used to set the display preferences for such things as dates and numbers, and then passing that to LmBestLocaleToIndex() to obtain a valid index to pass to LmGetLocaleSetting().


LmLocaleType locale; 
char oValue[kMaxCurrencySymbolLen+1]; 
uint16_t index; 
  
LmGetFormatsLocale(&locale); 
index = LmBestLocaleToIndex(&locale); 
LmGetLocaleSetting(index, lmChoiceCurrencySymbol, oValue,  
  sizeof(oValue)); 

See Also

LmLocaleToIndex()

LmCountryToISOName Function ^TOP^

Purpose

Converts an LmCountryType to a string.

Declared In

LocaleMgr.h

Prototype

status_t LmCountryToISOName (
   LmCountryType iCountry,
   char *oISONameStr
)

Parameters

iCountry
An LmCountryType variable specifying the country code as it is stored in a locale.
oISONameStr
A string that is at least three bytes long. Upon return, this string contains the country code converted to a string.

Returns

errNone upon success or lmErrUnknownLocale if iCountry is not a valid country code.

Comments

The Database Manager uses this function to convert the overlay locale's country code into a string so that it can construct an overlay database name.

See Also

LmISONameToCountry(), LmISONameToLanguage(), LmLanguageToISOName()

LmGetFormatsLocale Function ^TOP^

Purpose

Returns the formats locale.

Declared In

LocaleMgr.h

Prototype

void LmGetFormatsLocale (
   LmLocaleType *oFormatsLocale
)

Parameters

oFormatsLocale
An LmLocaleType that identifies the formats locale.

Returns

Nothing.

Comments

The formats locale is initially set to the system locale; however, the users can change the formats locale in the Formats Preference panel if they prefer a different locale.

See Also

LmSetFormatsLocale(), LmGetSystemLocale()

LmGetLocaleSetting Function ^TOP^

Purpose

Returns the requested setting for a given locale.

Declared In

LocaleMgr.h

Prototype

status_t LmGetLocaleSetting (
   uint16_t iLocaleIndex,
   LmLocaleSettingChoice iChoice,
   void *oValue,
   uint16_t iValueSize
)

Parameters

iLocaleIndex
Index of the locale whose settings you want to retrieve. Use LmLocaleToIndex() or LmBestLocaleToIndex() to obtain this value.
iChoice
The LmLocaleSettingChoice constant for the setting you want to retrieve.
oValue
The value of the iChoice setting.
iValueSize
The size of the oValue buffer. The size of this buffer depends on the value of iChoice.

Returns

One of the following values:

errNone
Success.
lmErrBadLocaleIndex
iLocaleIndex is out of range.
lmErrSettingDataOverflow
The oValue buffer is too small to hold the setting's value.
lmErrBadLocaleSettingChoice
The iChoice parameter contains an unknown or unsupported value.

Comments

This function accesses the private locale system resource and returns the requested information in the oValue parameter. The size and type of the oValue parameter depends on which setting you want to retrieve. The LmLocaleSettingChoice documentation describes the type of data returned in oValue for each setting. For fixed-size values, make sure that the size of the oValue buffer is exactly the size of the returned value. It should be neither larger than nor smaller than the size of the returned value.

This function returns the default settings for the locale. Users can override many of the locale settings using the Preferences application. Applications should always honor the user's preferences rather than the locale defaults. For this reason, it's recommended that if a corresponding system preference is available, you should check it instead (using PrefGetPreference()). Use LmGetLocaleSetting() only if you want to retrieve values that the user cannot override (such as the country name or currency symbol) or if you want to retrieve information about a locale other than the current locale.

See Also

LmGetNumLocales(), LmLocaleToIndex()

LmGetNumberSeparators Function ^TOP^

Purpose

Gets localized number separators.

Declared In

LocaleMgr.h

Prototype

void LmGetNumberSeparators (
   NumberFormatType iNumberFormat,
   char *oThousandSeparatorChar,
   char *oDecimalSeparatorChar
)

Parameters

iNumberFormat
The format to use (see NumberFormatType).
oThousandSeparatorChar
A pointer to the character used for the thousands separator. This is not a string. It does not have the terminating null character.
oDecimalSeparatorChar
A pointer to the character used for the decimal separator. This is not a string. It does not have the terminating null character.

Returns

Nothing.

Comments

The format to use is stored in the system preferences. You can obtain it by passing prefNumberFormat to PrefGetPreference().

See Also

StrLocalizeNumber(), StrDelocalizeNumber(), "Numbers"

LmGetNumLocales Function ^TOP^

Purpose

Returns the number of known locales.

Declared In

LocaleMgr.h

Prototype

uint16_t LmGetNumLocales (
   void
)

Parameters

None.

Returns

The number of locales that the locale system resource defines.

Comments

Use this function to obtain the range of possible values that you can pass as an index to LmGetLocaleSetting(). If LmGetNumLocales() returns 3, then LmGetLocaleSetting() accepts indexes in the range of 0 to 2.

This function returns only the number of locales for which the ROM has locale information. It does not return the number of locales that could possibly be defined. For example, the system resource currently contains no locale whose language is lHebrew and country is cIsrael, even though that is a valid locale.

LmGetROMLocale Function ^TOP^

Purpose

Returns the ROM locale.

Declared In

LocaleMgr.h

Prototype

CharEncodingType LmGetROMLocale (
   LmLocaleType *oROMLocale
)

Parameters

oROMLocale
Points to an LmLocaleType that identifies the ROM locale. Pass NULL if you don't want to retrieve this value.

Returns

A CharEncodingType constant that specifies the character encoding used in the ROM locale. Note that this character encoding is not necessarily the encoding in use.

Comments

The ROM locale is the default locale stored in the ROM. On certain ROMs, such as an EFIGS ROM, the system locale differs from the ROM locale after the user chooses a language. The ROM locale is used as the fallback overlay locale (used when the Database Manager cannot find a database for the overlay locale) unless that has been explicitly changed with the function DmSetFallbackOverlayLocale(). If the device is hard reset, the system locale is reset to the ROM locale.

See Also

LmGetSystemLocale()

LmGetSystemLocale Function ^TOP^

Purpose

Returns the system locale.

Declared In

LocaleMgr.h

Prototype

CharEncodingType LmGetSystemLocale (
   LmLocaleType *oSystemLocale
)

Parameters

oSystemLocale
Points to an LmLocaleType struct that identifies the system locale. Pass NULL if you don't want to retrieve this value.

Returns

A CharEncodingType constant that specifies the character encoding used in the system locale.

Comments

You typically use this function only to obtain the character encoding used on the device. The system locale is used for various system settings. Applications should instead use the values stored in the user's preferences or those in the formats locale (LmGetFormatsLocale()), which the user can change in the Formats Preference panel.

See Also

LmGetFormatsLocale(), LmGetSystemLocale()

LmISONameToCountry Function ^TOP^

Purpose

Converts a country code string into an LmCountryType constant.

Declared In

LocaleMgr.h

Prototype

status_t LmISONameToCountry (
   const char *iISONameStr,
   LmCountryType *oCountry
)

Parameters

iISONameStr
A string containing a two-character ASCII ISO 3166 country code.
oCountry
The corresponding LmCountryType constant.

Returns

errNone upon success or lmErrUnknownLocale if iISONameStr does not contain a valid country code.

See Also

LmCountryToISOName(), LmISONameToLanguage(), LmLanguageToISOName()

LmISONameToLanguage Function ^TOP^

Purpose

Converts a language code string into an LmLanguageType constant.

Declared In

LocaleMgr.h

Prototype

status_t LmISONameToLanguage (
   const char *iISONameStr,
   LmLanguageType *oLanguage
)

Parameters

iISONameStr
A string containing a two-character ASCII ISO 639 language code.
oLanguage
The corresponding LmLanguageType constant.

Returns

errNone upon success or lmErrUnknownLocale if iISONameStr does not contain a valid language code.

See Also

LmISONameToCountry(), LmISONameToCountry(), LmLanguageToISOName()

LmLanguageToISOName Function ^TOP^

Purpose

Converts an LmLanguageType to a string.

Declared In

LocaleMgr.h

Prototype

status_t LmLanguageToISOName (
   LmLanguageType iLanguage,
   char *oISONameStr
)

Parameters

iLanguage
An LmLanguageType variable specifying the language code as it is stored in a locale.
oISONameStr
A string that is at least three bytes long. Upon return, this string contains the language code converted to a string.

Returns

errNone upon success or lmErrUnknownLocale if iLanguage is not a valid language code.

Comments

The Database Manager uses this function to convert the overlay locale's language code into a string so that it can construct an overlay database name.

See Also

LmISONameToCountry(), LmISONameToCountry(), LmCountryToISOName()

LmLocaleToIndex Function ^TOP^

Purpose

Converts an LmLocaleType to an index suitable for passing to LmGetLocaleSetting().

Declared In

LocaleMgr.h

Prototype

status_t LmLocaleToIndex (
   const LmLocaleType *iLocale,
   uint16_t *oLocaleIndex
)

Parameters

iLocale
The locale to convert. This locale can use the constants lmAnyCountry or lmAnyLanguage as wildcards.
oLocaleIndex
The index of iLocale upon return.

Returns

errNone upon success or lmErrUnknownLocale if the locale could not be found.

See Also

LmBestLocaleToIndex()

LmSetFormatsLocale Function ^TOP^

Purpose

Sets the formats locale and changes the preference settings for locale-specific items to the default values from this locale.

Declared In

LocaleMgr.h

Prototype

status_t LmSetFormatsLocale (
   const LmLocaleType *iFormatsLocale
)

Parameters

iFormatsLocale
An LmLocaleType to use for the formats locale.

Returns

errNone upon success or memErrNotEnoughSpace if the Locale Manager fails to allocate memory for an internal structure identifying the preferences.

Comments

The Formats Preference panel uses this function when the user selects a new country from the country pop-up list. It then changes the formats locale and all locale-dependent preferences to the settings in the first locale that it finds matching the country.

Applications should not call this function without first confirming with the user that the formats locale should be changed.

See Also

LmGetFormatsLocale()