net.rim.device.api.i18n
Class Locale

java.lang.Object
  net.rim.device.api.i18n.Locale

public final class Locale
extends Object

Represents a specific geographical, political, or cultural region to be used for localizing numbers, dates, and text.

Compatible with java.util.Locale in Java's standard edition.

Field Summary
static int	APPLICATION In a global event, check this flag to see if the change was an application or a global one.
static long	GUID_INPUT_LOCALE_CHANGED GUID for global event sent when the current input locale changes.
static long	GUID_LOCALE_CHANGED GUID for global event sent when the current locale changes.
static int	KEYBOARD_ID_QWERTY Deprecated. Use Keypad.HW_LAYOUT_* equivalent.
static int	KEYBOARD_ID_QWERTY_LEGACY Deprecated. Use Keypad.HW_LAYOUT_* equivalent.
static int	KEYBOARD_ID_QWERTY_PHONE Deprecated. Use Keypad.HW_LAYOUT_* equivalent.
static int	KEYBOARD_ID_QWERTY_REDUCED Deprecated. Use Keypad.HW_LAYOUT_* equivalent.
static int	LOCALE_ROOT Root locale.
static int	LOCALE_SET_DECLINED An identification of unsuccessful "set locale" operation
static int	LOCALE_SET_OK An identification of successful "set locale" operation
static int	LOCALE_af Afrikaans locale
static int	LOCALE_ar Arabic locale
static int	LOCALE_ca Catalan locale.
static int	LOCALE_cs Czech locale.
static int	LOCALE_da Danish locale.
static int	LOCALE_de German locale.
static int	LOCALE_el Greek locale.
static int	LOCALE_en English locale.
static int	LOCALE_en_GB English (Great Britain) locale.
static int	LOCALE_en_US English (United States) locale.
static int	LOCALE_es Spanish locale.
static int	LOCALE_es_MX Mexican Spanish locale.
static int	LOCALE_fa Persian/Farsi locale.
static int	LOCALE_fr French locale.
static int	LOCALE_fr_CA French Canadian locale.
static int	LOCALE_he Hebrew locale.
static int	LOCALE_hi Hindi locale.
static int	LOCALE_hr Croatian locale
static int	LOCALE_hu Hungarian locale.
static int	LOCALE_it Italian locale.
static int	LOCALE_ja Japanese locale.
static int	LOCALE_ko Korean locale.
static int	LOCALE_nl Dutch locale.
static int	LOCALE_no Norwegian locale.
static int	LOCALE_pl Polish locale.
static int	LOCALE_pt Portugese locale.
static int	LOCALE_pt_BR Brazillian Portugese locale.
static int	LOCALE_ro Romanian locale.
static int	LOCALE_ru Russian locale.
static int	LOCALE_sv Swedish locale.
static int	LOCALE_th Thai locale.
static int	LOCALE_tr Turkish locale.
static int	LOCALE_vi vietnamese locale.
static int	LOCALE_zh Chinese locale.
static int	LOCALE_zh_CN Chinese (mainland) locale.
static int	LOCALE_zh_HK Chinese (Hong Kong) locale.
static int	LOCALE_zh_TW Chinese (Taiwan) locale.

Method Summary
boolean	equals(Object obj) Determines if provided object is equal to this locale.
static Locale	get(int code) Retrieves locale by code.
static Locale	get(int code, String variant) Retrieves locale by code suggesting variant name.
static Locale	get(String language) Retrieves locale by language.
static Locale	get(String language, String country) Retrieves locale by language and country.
static Locale	get(String language, String country, String variant) Retrieves locale by language, country, and variant.
static Locale[]	getAvailableInputLocales() Retrieves list of known input locales.
static Locale[]	getAvailableLocales() Retrieves list of known locales.
int	getCode() Retrieves integer code for this locale.
String	getCountry() Retrieves this locale's ISO country code.
static Locale	getDefault() Retrieves the current application's default locale.
static Locale	getDefaultForKeyboard() Retrieves default locale for the keyboard.
static Locale	getDefaultForSystem() Retrieves system's current default locale.
static Locale	getDefaultInput() Deprecated. Use Locale.getDefaultInputForSystem()
static Locale	getDefaultInputForSystem() Retrieves system's current default input locale.
String	getDisplayCountry() Returns the display country, long format
String	getDisplayLanguage() Retrieves displayable name for this locale's language.
String	getDisplayName() Returns the display name for the local using the full country name
String	getDisplayVariant() Retrieves displayable name for this locale's variant.
static String[]	getISOCountries() Retrieves a list of all 2-letter country codes defined in ISO 3166.
static String[]	getISOLanguages() Retrieves a list of all 2-letter language codes defined in ISO 639.
String	getLanguage() Retrieves this locale's ISO language code.
String	getVariant() Retrieves this locale's variant name.
int	hashCode() Retrieves hash code for this locale.
static void	setDefault(Locale defaultLocale) Sets default locale for the current application.
static void	setDefaultInput(Locale defaultLocale) Deprecated. Use Locale.setDefaultInputForSystem(Locale)
static int	setDefaultInputForSystem(Locale locale) Sets the default system input locale.
String	toString() Retrieves the programmatic name for this entire locale.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

GUID_LOCALE_CHANGED

public static final long GUID_LOCALE_CHANGED

GUID for global event sent when the current locale changes.

See Also:

Constant Field Values

GUID_INPUT_LOCALE_CHANGED

public static final long GUID_INPUT_LOCALE_CHANGED

GUID for global event sent when the current input locale changes.

See Also:

Constant Field Values

Since:

BlackBerry API 3.7.0

APPLICATION

public static final int APPLICATION

In a global event, check this flag to see if the change was an application or a global one.

See Also:

Constant Field Values

LOCALE_SET_DECLINED

public static final int LOCALE_SET_DECLINED

An identification of unsuccessful "set locale" operation

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.1

LOCALE_SET_OK

public static final int LOCALE_SET_OK

An identification of successful "set locale" operation

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.1

LOCALE_ROOT

public static final int LOCALE_ROOT

Root locale.

See Also:

Constant Field Values

LOCALE_af

public static final int LOCALE_af

Afrikaans locale

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

LOCALE_ar

public static final int LOCALE_ar

Arabic locale

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

LOCALE_ca

public static final int LOCALE_ca

Catalan locale.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

LOCALE_cs

public static final int LOCALE_cs

Czech locale.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

LOCALE_da

public static final int LOCALE_da

Danish locale.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

LOCALE_de

public static final int LOCALE_de

German locale.

See Also:

Constant Field Values

LOCALE_en

public static final int LOCALE_en

English locale.

See Also:

Constant Field Values

LOCALE_en_GB

public static final int LOCALE_en_GB

English (Great Britain) locale.

See Also:

Constant Field Values

LOCALE_en_US

public static final int LOCALE_en_US

English (United States) locale.

See Also:

Constant Field Values

LOCALE_es

public static final int LOCALE_es

Spanish locale.

See Also:

Constant Field Values

LOCALE_es_MX

public static final int LOCALE_es_MX

Mexican Spanish locale.

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.0

LOCALE_fr

public static final int LOCALE_fr

French locale.

See Also:

Constant Field Values

LOCALE_fr_CA

public static final int LOCALE_fr_CA

French Canadian locale.

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.0

LOCALE_he

public static final int LOCALE_he

Hebrew locale.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

LOCALE_hi

public static final int LOCALE_hi

Hindi locale.

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

LOCALE_hu

public static final int LOCALE_hu

Hungarian locale.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

LOCALE_it

public static final int LOCALE_it

Italian locale.

See Also:

Constant Field Values

LOCALE_ko

public static final int LOCALE_ko

Korean locale.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

LOCALE_nl

public static final int LOCALE_nl

Dutch locale.

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.0

LOCALE_no

public static final int LOCALE_no

Norwegian locale.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

LOCALE_fa

public static final int LOCALE_fa

Persian/Farsi locale.

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

LOCALE_pt

public static final int LOCALE_pt

Portugese locale.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

LOCALE_pt_BR

public static final int LOCALE_pt_BR

Brazillian Portugese locale.

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.0

LOCALE_sv

public static final int LOCALE_sv

Swedish locale.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

LOCALE_zh

public static final int LOCALE_zh

Chinese locale.

See Also:

Constant Field Values

Since:

BlackBerry API 3.7.0

LOCALE_zh_CN

public static final int LOCALE_zh_CN

Chinese (mainland) locale.

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.1

LOCALE_zh_HK

public static final int LOCALE_zh_HK

Chinese (Hong Kong) locale.

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.1

LOCALE_zh_TW

public static final int LOCALE_zh_TW

Chinese (Taiwan) locale.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

LOCALE_el

public static final int LOCALE_el

Greek locale.

See Also:

Constant Field Values

Since:

BlackBerry API 4.1.0

LOCALE_tr

public static final int LOCALE_tr

Turkish locale.

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.0

LOCALE_th

public static final int LOCALE_th

Thai locale.

See Also:

Constant Field Values

Since:

BlackBerry API 4.6.0

LOCALE_ru

public static final int LOCALE_ru

Russian locale.

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.1

LOCALE_ro

public static final int LOCALE_ro

Romanian locale.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

LOCALE_pl

public static final int LOCALE_pl

Polish locale.

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.1

LOCALE_ja

public static final int LOCALE_ja

Japanese locale.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

LOCALE_vi

public static final int LOCALE_vi

vietnamese locale.

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

LOCALE_hr

public static final int LOCALE_hr

Croatian locale

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

KEYBOARD_ID_QWERTY

public static final int KEYBOARD_ID_QWERTY

Deprecated. Use Keypad.HW_LAYOUT_* equivalent.

Standard QWERTY keyboard ID (58xx series)

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

KEYBOARD_ID_QWERTY_PHONE

public static final int KEYBOARD_ID_QWERTY_PHONE

Deprecated. Use Keypad.HW_LAYOUT_* equivalent.

QWERTY /w phone keyboard ID (65xx, 67xx, 72xx, 75xx, 77xx series).

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

KEYBOARD_ID_QWERTY_REDUCED

public static final int KEYBOARD_ID_QWERTY_REDUCED

Deprecated. Use Keypad.HW_LAYOUT_* equivalent.

Reduced QWERTY keyboard ID (71xx series).

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

KEYBOARD_ID_QWERTY_LEGACY

public static final int KEYBOARD_ID_QWERTY_LEGACY

Deprecated. Use Keypad.HW_LAYOUT_* equivalent.

Legacy QWERTY keyboard ID (57xx series).

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

Method Detail

equals

public boolean equals(Object obj)

Determines if provided object is equal to this locale.

Overrides:

equals in class Object

Parameters:

obj - Object to compare with this locale.

Returns:

True if provided object is equal to this locale (only if the language, country, and variant match); otherwise, false.

See Also:

Boolean.hashCode(), Hashtable

get

public static Locale get(int code)

Retrieves locale by code.

Note: This method simply invokes get(code,null); this it ignores variants. If no locale exists for the code you specify, then this method creates the new locale, with an empty variant name.

Parameters:

code - Locale code.

Returns:

Locale associated with provided code, or null if no locale is associated with your code.

get

public static Locale get(int code,
                         String variant)

Retrieves locale by code suggesting variant name.

Note: If no local exists for the code you specify, then this method creates the new locale. If, in such a case, you passed a null string in for the variant, this method gives an empty variant name to the new locale.

Parameters:

code - Locale code.

variant - Name of locale variant; may be null to indicate no variant. This parameter is only relevant if this method ends up creating a new locale; otherwise, it is ignored.

Returns:

Locale associated with code.

get

public static Locale get(String language)

Retrieves locale by language.

This method simply invokes get(language,country=null,variant=null. If no such locale exists, this method creates an entry for it with an empty variant name.

Parameters:

language - Language for locale.

Returns:

Locale object for the given language; the object is interned.

get

public static Locale get(String language,
                         String country)

Retrieves locale by language and country.

This method simply invokes get(language,country,variant=null. If no such locale exists, this method creates an entry for it with an empty variant name.

Parameters:

language - Langauge for locale.

country - Country for locale; may be null to indicate no country specified.

Returns:

Locale object for the given language and country; the object is interned.

get

public static Locale get(String language,
                         String country,
                         String variant)

Retrieves locale by language, country, and variant.

If no such locale exists, this method creates an entry for it; if, in this case, you provide null for the variant name, this method gives an empty variant name to the new locale.

Parameters:

language - Langauge for locale.

country - Country for locale; may be null to indicate no country specified.

variant - Name of locale variant; may be null to indicate no variant (but see description).

Returns:

Locale object for the given language, country, and variant; the object is interned.

getAvailableLocales

public static Locale[] getAvailableLocales()

Retrieves list of known locales.

The elements are guaranteed to be in the order. It is equivalent to: (language, country, variant) tuples where empty is sorted before non empty and it is otherwise is alphabetical order.

Returns:

List of available locales known to the system.

getAvailableInputLocales

public static Locale[] getAvailableInputLocales()

Retrieves list of known input locales.

The elements are guaranteed to be in the order. It is equivalent to: (language, country, variant) tuples where empty is sorted before non empty and it is otherwise is alphabetical order.

Returns:

List of available locales known to the system.

Since:

BlackBerry API 3.7.0

getCode

public int getCode()

Retrieves integer code for this locale.

Returns:

Integer code for this locale (that is, the locale code without variant).

getCountry

public final String getCountry()

Retrieves this locale's ISO country code.

Returns:

ISO country/region code for this locale, or the empty string if this locale has no associated country.

getDefault

public static Locale getDefault()

Retrieves the current application's default locale.

This is either the locale that was specified by Locale.setDefault(net.rim.device.api.i18n.Locale), or if null, the return from Locale.getDefaultForSystem().

This is not guaranteed to be one of the available locales. An application may choose to set it to whatever it wishes.

Returns:

Current application's default locale.

getDefaultInput

public static Locale getDefaultInput()

Deprecated. Use Locale.getDefaultInputForSystem()

Retrieves the current application's default input locale.

This is either the input locale that was specified by Locale.setDefaultInput(net.rim.device.api.i18n.Locale), or if null, the return from Locale.getDefaultInputForSystem().

This is not guaranteed to be one of the available locales. An application may choose to set it to whatever it wishes.

Returns:

Current application's default input locale.

Since:

BlackBerry API 4.2.0

getDefaultForSystem

public static Locale getDefaultForSystem()

Retrieves system's current default locale.

This is guaranteed to return an available locale.

Returns:

System's current default locale.

getDefaultInputForSystem

public static Locale getDefaultInputForSystem()

Retrieves system's current default input locale.

This is guaranteed to return an available input locale.

Returns:

System's current default input locale.

Since:

BlackBerry API 3.7.0

getDefaultForKeyboard

public static Locale getDefaultForKeyboard()

Retrieves default locale for the keyboard.

This value is used to choose the input type for the device if it has not been selected by the user.

There are no restrictions on which locale can be returned from this function.

Returns:

Default keyboard locale.

getDisplayCountry

public final String getDisplayCountry()

Returns the display country, long format

Returns:

display couuntry, long format

getDisplayLanguage

public final String getDisplayLanguage()

Retrieves displayable name for this locale's language.

Returns:

Locale's displayable language name.

getDisplayVariant

public final String getDisplayVariant()

Retrieves displayable name for this locale's variant.

Returns:

Locale's displayable variant name.

getDisplayName

public final String getDisplayName()

Returns the display name for the local using the full country name

Returns:

local's display name using a long country name

Since:

BlackBerry API 6.0.0

getISOCountries

public static String[] getISOCountries()

Retrieves a list of all 2-letter country codes defined in ISO 3166.

Returns:

List of ISO-standard (3166) country codes.

getISOLanguages

public static String[] getISOLanguages()

Retrieves a list of all 2-letter language codes defined in ISO 639.

Returns:

List of ISO-standard (639) language codes.

getLanguage

public final String getLanguage()

Retrieves this locale's ISO language code.

Returns:

ISO Language code for this locale, or the empty string if this locale has no associated language code.

getVariant

public final String getVariant()

Retrieves this locale's variant name.

Returns:

Variant name for this locale, or the empty string if this locale has no associated variant.

hashCode

public int hashCode()

Retrieves hash code for this locale.

Overrides:

hashCode in class Object

Returns:

Hash code value for this object.

See Also:

Object.equals(java.lang.Object), Hashtable

setDefault

public static void setDefault(Locale defaultLocale)

Sets default locale for the current application.

Parameters:

defaultLocale - New default locale for the current application; this value always overrides the system value. If null, the current application will inherit the system locale, and the application's locale will change whenever the system locale changes.

setDefaultInput

public static void setDefaultInput(Locale defaultLocale)

Deprecated. Use Locale.setDefaultInputForSystem(Locale)

Sets default input locale for the current application.

Parameters:

defaultLocale - New default input locale for the current application; this value always overrides the system value. If null, the current application will inherit the system input locale, and the application's input locale will change whenever the system input locale changes.

Since:

BlackBerry API 3.7.0

setDefaultInputForSystem

public static int setDefaultInputForSystem(Locale locale)

Sets the default system input locale.

Parameters:

locale - New default input locale for the system.

Returns:

int Operation result. Possible values - Locale.LOCALE_SET_OK, Locale.LOCALE_SET_DECLINED

Since:

BlackBerry API 4.2.1

toString

public String toString()

Retrieves the programmatic name for this entire locale.

Overrides:

toString in class Object

Returns:

String representation of this locale: the language, country, and variant are separated by underbars. Country always has one underbar preceeding it, and variant always has two underbars preceeding it. Underbars are not included if all 3 parts are empty.