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
LmBestLocaleToIndex Function
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
orlmAnyLanguage
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
LmCountryToISOName Function
Purpose
Converts an LmCountryType
to a string.
Declared In
LocaleMgr.h
Prototype
status_t LmCountryToISOName ( LmCountryTypeiCountry
, 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
Purpose
Declared In
LocaleMgr.h
Prototype
void LmGetFormatsLocale (
LmLocaleType *oFormatsLocale
)
Parameters
-
← oFormatsLocale
- An
LmLocaleType
that identifies the formats locale.
Returns
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
Purpose
Returns the requested setting for a given locale.
Declared In
LocaleMgr.h
Prototype
status_t LmGetLocaleSetting ( uint16_tiLocaleIndex
, LmLocaleSettingChoiceiChoice
, void*oValue
, uint16_tiValueSize
)
Parameters
-
→ iLocaleIndex
- Index of the locale whose settings you want to retrieve. Use
LmLocaleToIndex()
orLmBestLocaleToIndex()
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 ofiChoice
.
Returns
-
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
Purpose
Gets localized number separators.
Declared In
LocaleMgr.h
Prototype
void LmGetNumberSeparators ( NumberFormatTypeiNumberFormat
, 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
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
Purpose
Returns the number of known locales.
Declared In
LocaleMgr.h
Prototype
uint16_t LmGetNumLocales ( void )
Parameters
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
Purpose
Declared In
LocaleMgr.h
Prototype
CharEncodingType LmGetROMLocale (
LmLocaleType *oROMLocale
)
Parameters
-
← oROMLocale
- Points to an
LmLocaleType
that identifies the ROM locale. PassNULL
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 Function
Purpose
Declared In
LocaleMgr.h
Prototype
CharEncodingType LmGetSystemLocale (
LmLocaleType *oSystemLocale
)
Parameters
-
← oSystemLocale
- Points to an
LmLocaleType
struct that identifies the system locale. PassNULL
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
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
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
Purpose
Converts an LmLanguageType
to a string.
Declared In
LocaleMgr.h
Prototype
status_t LmLanguageToISOName ( LmLanguageTypeiLanguage
, 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
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
orlmAnyLanguage
as wildcards. -
← oLocaleIndex
- The index of
iLocale
upon return.
Returns
errNone
upon success or lmErrUnknownLocale
if the locale could not be found.
See Also
LmSetFormatsLocale Function
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.