Locale Manager
 

 < 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

-> iLocaleIndexIndex of the locale whose settings you want to retrieve.
-> iChoiceThe setting you want to retrieve. This is a constant in the form lmChoiceSettingName. See Table 38.1 for a list of possible values.
<- oValueThe value of the iChoice setting. The size of this buffer depends on the value of iChoice, as shown in Table 38.1.
-> iValueSizeThe size of the oValue buffer.

Result

Returns one of the following values:

errNoneSuccess.
lmErrBadLocaleIndexiLocaleIndex is out of range.
lmErrSettingDataOverflowThe oValue buffer is too small to hold the setting's value.
lmErrBadLocaleSettingChoiceThe 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
The short date format used in this locale. For example:

95/12/31

Locale
A structure containing the locale's language and country codes.
LongDateFormat
The long date format used in this locale. For example:

31 Dec 1995

MeasurementSystem
The measurement system (metric system or English system) used in this locale.
NumberFormat
The format used for numbers, with regards to the thousands separator and the decimal point, in this locale.
TimeFormat
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

-> iLocaleThe locale to convert.
<- oLocaleIndexThe 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."