(68K) Locale Manager | Palm OS® Programmer's API Reference

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:

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 ^TOP^

CountryType Typedef ^TOP^

Purpose

The CountryType defines a country code. The Country Constants in PalmLocale.h define the possible values for CountryType variables.

Prototype

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 Typedef ^TOP^

Purpose

The LanguageType defines a language code. The Language Constants in PalmLocale.h define the possible values for LanguageType variables.

Prototype

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.

LmLocaleType Struct ^TOP^

Purpose

The LmLocaleType struct defines the country and language used in a locale.

Prototype

struct _LmLocaleType {
  UInt16 language;
  UInt16 country;
};

typedef struct _LmLocaleType LmLocaleType;

Fields

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 Enum ^TOP^

Purpose

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.

Prototype

typedef enum {
  nfCommaPeriod,
  nfPeriodComma,
  nfSpaceComma,
  nfApostrophePeriod,
  nfApostropheComma
} NumberFormatType;

Constants

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 ^TOP^

Character Encoding Constants ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

You can use the Locale Manager size constants to determine the size of strings to allocate for some of the locale settings.

NOTE: The constants 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 ^TOP^

LmGetLocaleSetting Function ^TOP^

Purpose

Return the requested setting for a given locale.

Declared In

LocaleMgr.h

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...; see Table 41.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 41.1.
→ iValueSize: The size of the oValue buffer.

Returns

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 41.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 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.

Table 41.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
`InboundDefault VObjectEncoding`	`CharEncodingType`	Inbound encoding for vObjects with no CHARSET property.
`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.
`OutboundVObject Encoding`	`CharEncodingType`	Outbound encoding for vObjects.
`PrimaryEmail Encoding`	`CharEncodingType`	First attempt at Email encoding.
`PrimarySMS Encoding`	`CharEncodingType`	First attempt at SMS encoding.
`SecondaryEmail Encoding`	`CharEncodingType`	Second attempt at Email encoding.
`SecondarySMS Encoding`	`CharEncodingType`	Second attempt at SMS encoding.
`SupportsLunar Calendar`	`Boolean`	Does locale support Chinese Lunar Calendar?
`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 80, "PalmOSGlue Library."

LmGetNumLocales Function ^TOP^

Purpose

Return the number of known locales.

Declared In

LocaleMgr.h

Prototype

UInt16 LmGetNumLocales (
   void
)

Parameters

None.

Returns

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 80, "PalmOSGlue Library."

LmLocaleToIndex Function ^TOP^

Purpose

Convert an LmLocaleType to an index.

Declared In

LocaleMgr.h

Prototype

Err LmLocaleToIndex (
   const LmLocaleType *iLocale,
   UInt16 *oLocaleIndex
)

Parameters

→ iLocale: The locale to convert.
← oLocaleIndex: The index of iLocale upon return.

Returns

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 80, "PalmOSGlue Library."

41 Locale Manager

Locale Manager Data Types ^TOP^

CountryType Typedef ^TOP^

Purpose

Prototype

Compatibility

LanguageType Typedef ^TOP^

Purpose

Prototype

Compatibility

LmLocaleType Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

NumberFormatType Enum ^TOP^

Purpose

Prototype

Constants

Locale Manager Constants ^TOP^

Character Encoding Constants ^TOP^

Country Constants ^TOP^

Language Constants ^TOP^

Locale Manager Size Constants ^TOP^

Locale Manager Functions ^TOP^

LmGetLocaleSetting Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility

See Also

LmGetNumLocales Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility

LmLocaleToIndex Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility