< Home < Developers < Development Support < Documentation

## 38 Locale Manager

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part II: System Management 38 Locale Manager Locale Manager Data Types CountryType LanguageType LmLocaleType NumberFormatType Locale Manager Constants Character Encoding Constants Country Constants Language Constants Locale Manager Size Constants Locale Manager Functions LmGetLocaleSetting LmGetNumLocales LmLocaleToIndex |  |  |  | This chapter describes the Locale Manager API as described in the header files LocaleMgr.h, Localize.h, and PalmLocale.h. It discusses the following topics: Locale Manager Data Types Locale Manager Constants Locale Manager Functions For more information on the Locale Manager, see the chapter "Localized Applications" of the Palm OS Programmer's Companion, vol. I. ## Locale Manager Data Types ## CountryType The CountryType defines a country code. The Country Constants in PalmLocale.h define the possible values for CountryType variables.
    typedef UInt8 CountryType;
#### Compatibility Prior to version 4.0, CountryType was an enum in Preferences.h that defined only 33 country codes. The Palm OS® 4.0 definition of CountryType is compatible with the previous definition. ## LanguageType The LanguageType defines a language code. The Language Constants in PalmLocale.h define the possible values for LanguageType variables.
    typedef UInt8 LanguageType;
#### Compatibility The LanguageType definition was added in Palm OS 3.5. Prior to version 4.0, LanguageType was an enum in Preferences.h that defined only eight language codes. The Palm OS 4.0 definition of LanguageType is compatible with the previous definition. ## New LmLocaleType The LmLocaleType struct defines the country and language used in a locale.
    struct _LmLocaleType {
      UInt16         language;
      UInt16         country;
    };
    typedef struct _LmLocaleType LmLocaleType;
#### Field Descriptions #####
language | One of the Language Constants. This value identifies the language spoken in the current locale.
country | One of the Country Constants. This value identifies the locale's country, which helps to identify the language dialect. For example, a language of lEnglish specifies a different dialect if the country is cUnitedKingdom than if it is cUnitedStates.
Note that the language and country fields are type UInt16 instead of LanguageType and CountryType. #### Compatibility The LmLocaleType is defined only if 4.0 New Feature Set is present. It supersedes the OmLocaleType that was introduced with Palm OS 3.5. LmLocaleType is bit-compatible with OmLocaleType. ## NumberFormatType The NumberFormatType enum specifies how numbers are formatted. You can pass a NumberFormatType value to LocGetNumberSeparators and receive the appropriate separator characters for thousands and decimals.
    typedef enum {
      nfCommaPeriod,
      nfPeriodComma,
      nfSpaceComma,
      nfApostrophePeriod,
      nfApostropheComma
    } NumberFormatType;
#### Value Descriptions #####
nfCommaPeriod | Uses a comma (,) as the thousands separator and a period (.) as the decimal separator.
nfPeriodComma | Uses a period as the thousands separator and a comma as the decimal separator.
nfSpaceComma | Uses a space ( ) as the thousands separator and a comma as the decimal separator.
nfApostrophePeriod | Uses an apostrophe (') as the thousands separator and a period as the decimal separator.
nfApostropheComma | Uses an apostrophe as the thousands separator and a comma as the decimal separator.
## Locale Manager Constants ## Character Encoding Constants The PalmLocale.h file defines several character encoding constants that are used as values of CharEncodingType variables. The character encoding constants generally follow the format:
    charEncodingName
where Name is the name of the character encoding. The following table shows examples of the character encoding constants. For a complete list, see the PalmLocale.h file. #####
Constant | Description
--- | ---
charEncodingUnknown | Unknown to this version of Palm OS®
charEncodingAscii | ISO 646-1991
charEncodingISO8859_1 | ISO 8859 Part 1 (also known as ISO Latin 1). This encoding is commonly used for the Roman alphabet
charEncodingPalmLatin | Palm OS version of Microsoft Windows code page 1252. This encoding is identical to code page 1252 with Palm-specific characters added in the control range.
charEncodingShiftJIS | Encoding for 0208-1990 with single-byte Japanese Katakana. This encoding is commonly used for Japanese alphabets.
charEncodingPalmSJIS | Palm OS version of Microsoft Windows code page 932. This encoding is identical to code page 932, with Palm-specific characters added in the control range and with a Yen symbol instead of the Reverse Solidus at location 0x5c.
charEncodingCP1252 | Microsoft Windows extensions to ISO 8859 Part 1
charEncodingCP932 | Microsoft Windows extensions to Shift JIS
charEncodingUTF8 | Eight-bit safe encoding for Unicode
## Country Constants The PalmLocale.h file defines several country constants that are used as values of CountryType variables. The country type constants have the following format:
    cCountryName
where CountryName is the name of the country. There is one constant for each country identified in the ISO 3166 standard, which currently defines 239 countries. The following table shows examples of the country type constants. For a complete list, see the PalmLocale.h file. #####
Constant | Description
--- | ---
cAustralia | Australia
cAustria | Austria
cBelgium | Belgium
## Language Constants The PalmLocale.h file defines several language constants that are used as values of LanguageType variables. The language type constants have the following format:
    lLanguageName
where LanguageName is the name of the language. There is one constant for each language specified in the ISO 639 standard, which currently defines 137 languages. The following table shows examples of the language type constants. For a complete list, see the PalmLocale.h file. #####
Constant | Description
--- | ---
lEnglish | English
lFrench | French
lGerman | German
## Locale Manager Size Constants You can use the Locale Manager size constants to determine the size of strings to allocate for some of the locale settings. NOTE: The variables in the table below do not count the terminating null character. Therefore, you need to allocate a string of size kMaxCountryNameLen+1 to hold a country name, for example. #####
Constant | Value | Description
--- | --- | ---
kMaxCountryNameLen | 19 | The maximum length of a country name string.
kMaxCurrencyNameLen | 19 | The maximum length of a currency name string.
kMaxCurrencySymbolLen | 5 | The maximum length of a currency symbol string.
## Locale Manager Functions ## New LmGetLocaleSetting #### Purpose Return the requested setting for a given locale. #### Prototype Err LmGetLocaleSetting (UInt16 iLocaleIndex, LmLocaleSettingChoice iChoice, void *oValue, UInt16 iValueSize) #### Parameters #####
-> iLocaleIndex | Index of the locale whose settings you want to retrieve.
#####
-> iChoice | The setting you want to retrieve. This is a constant in the form lmChoice SettingName. See Table 38.1 for a list of possible values.
#####
<- oValue | The value of the iChoice setting. The size of this buffer depends on the value of iChoice, as shown in Table 38.1.
#####
-> iValueSize | The size of the oValue buffer.
#### Result 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 depend on which setting you want to retrieve. Table 38.1 lists and describes the possible settings and the type of data returned in oValue for each setting. For fixed-size values, make sure that oValue is no larger than 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. #####
Table 38.1 LmGetLocaleSetting choices and sizes
lmChoice... | oValue Data Type | Description
--- | --- | ---
CountryName | String buffer of size kMaxCountryNameLen+1 bytes | The name of the locale's country.
CurrencyName | String buffer of size kMaxCurrencyNameLen+1 bytes | The name of the currency used in this locale.
CurrencySymbol | String buffer of size kMaxCurrencySymbolLen+1 bytes | The symbol used to denote monetary values in this locale.
CurrencyDecimal Places | UInt16 | The number of decimal places that monetary values are typically given.
DateFormat | DateFormatType | The short date format used in this locale. For example: 95/12/31
Locale | LmLocaleType | A structure containing the locale's language and country codes.
LongDateFormat | DateFormatType | The long date format used in this locale. For example: 31 Dec 1995
MeasurementSystem | MeasurementSystemType | The measurement system (metric system or English system) used in this locale.
NumberFormat | NumberFormatType | The format used for numbers, with regards to the thousands separator and the decimal point, in this locale.
TimeFormat | TimeFormatType | The format used for time values in this locale.
TimeZone | Int16 | The locale's default time zone given as the number of minutes east of Greenwich Mean Time (GMT).
UniqueCurrency Symbol | String buffer of size kMaxCurrencySymbolLen+1 bytes | A unique symbol for monetary values. For example, the symbol $ is used both for US dollars and Portuguese escudos. The unique currency symbol for US dollars is US$.
WeekStartDay | UInt16 | The first day of the week (Sunday or Monday) in this locale. Days of the week are numbered from 0 to 6 starting with Sunday = 0.
#### Compatibility Implemented only if 4.0 New Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call LmGlueGetLocaleSetting. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also LmGetNumLocales, LmLocaleToIndex ## New LmGetNumLocales #### Purpose Return the number of known locales. #### Prototype UInt16 LmGetNumLocales (void) #### Parameters #####
None.
#### Result 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. #### Compatibility Implemented only if 4.0 New Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call LmGlueGetNumLocales. For more information, see Chapter 76, "PalmOSGlue Library." ## New LmLocaleToIndex #### Purpose Convert an LmLocaleType to an index. #### Prototype Err LmLocaleToIndex (const LmLocaleType *iLocale, UInt16 *oLocaleIndex) #### Parameters #####
-> iLocale | The locale to convert.
#####
<- oLocaleIndex | The index of iLocale upon return.
#### Result Returns errNone upon success or lmErrUnknownLocale if the locale could not be found. #### Comments You can use this function to obtain a valid index to pass to LmGetLocaleSetting. For example, you might use the Overlay Manager routine OmGetSystemLocale to return the locale used on the current system and then pass that locale to this function to obtain its index.
    LmLocaleType locale;
    Char oValue[kMaxCurrencySymbolLen+1];
    UInt16 index;

    OmGetSystemLocale(&locale);
    LmLocaleToIndex(&locale, &index);
    LmGetLocaleSetting(index,
      lmChoiceCurrencySymbol, oValue,
      sizeof(oValue));
The LmLocaleType that is passed in iLocale can use the constants lmAnyCountry or lmAnyLanguage as wildcards. For example, if the country is lmAnyCountry, LmLocaleToIndex returns the index of the first locale that matches the language. #### Compatibility Implemented only if 4.0 New Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call LmGlueLocaleToIndex. For more information, see Chapter 76, "PalmOSGlue Library." |