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

41    Locale Manager

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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 PalmOS®

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 ISO639 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 (
   UInt16iLocaleIndex,
   LmLocaleSettingChoiceiChoice,
   void*oValue,
   UInt16iValueSize
)

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

See Also

LmGetNumLocales(), LmLocaleToIndex()

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 (
   constLmLocaleType*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."