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_ar
          Arabic locale
static int LOCALE_ca
          Catalan locale.
static int LOCALE_cs
          Czech 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_fr
          French locale.
static int LOCALE_fr_CA
          French Canadian locale.
static int LOCALE_he
          Hebrew 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_pl
          Polish locale.
static int LOCALE_pt
          Portugese locale.
static int LOCALE_pt_BR
          Brazillian Portugese locale.
static int LOCALE_ROOT
          Root locale.
static int LOCALE_ru
          Russian 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_tr
          Turkish locale.
static int LOCALE_zh
          Chinese locale.
static int LOCALE_zh_CN
          Chinese (mainland) locale.
static int LOCALE_zh_HK
          Chinese (Hong Kong) 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 getDefaultInputForSystem()
static Locale getDefaultInputForSystem()
          Retrieves system's current default input locale.
 String getDisplayCountry()
          Retrieves displayable name for this locale's country.
 String getDisplayLanguage()
          Retrieves displayable name for this locale's language.
 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 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

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.

GUID_INPUT_LOCALE_CHANGED

public static final long GUID_INPUT_LOCALE_CHANGED
GUID for global event sent when the current input locale changes.
Since:
JDE 3.7.0

GUID_LOCALE_CHANGED

public static final long GUID_LOCALE_CHANGED
GUID for global event sent when the current locale changes.

KEYBOARD_ID_QWERTY

public static final int KEYBOARD_ID_QWERTY
Deprecated. Use Keypad.HW_LAYOUT_* equivalent.

Standard QWERTY keyboard ID (58xx series)
Since:
JDE 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).
Since:
JDE 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).
Since:
JDE 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).
Since:
JDE 4.0.0

LOCALE_ar

public static final int LOCALE_ar
Arabic locale
Since:
JDE 4.3.0

LOCALE_ca

public static final int LOCALE_ca
Catalan locale.
Since:
JDE 4.3.0

LOCALE_cs

public static final int LOCALE_cs
Czech locale.
Since:
JDE 4.3.0

LOCALE_de

public static final int LOCALE_de
German locale.

LOCALE_el

public static final int LOCALE_el
Greek locale.
Since:
JDE 4.1.0

LOCALE_en

public static final int LOCALE_en
English locale.

LOCALE_en_GB

public static final int LOCALE_en_GB
English (Great Britain) locale.

LOCALE_en_US

public static final int LOCALE_en_US
English (United States) locale.

LOCALE_es

public static final int LOCALE_es
Spanish locale.

LOCALE_es_MX

public static final int LOCALE_es_MX
Mexican Spanish locale.
Since:
JDE 4.2.0

LOCALE_fr

public static final int LOCALE_fr
French locale.

LOCALE_fr_CA

public static final int LOCALE_fr_CA
French Canadian locale.
Since:
JDE 4.2.0

LOCALE_he

public static final int LOCALE_he
Hebrew locale.
Since:
JDE 4.3.0

LOCALE_hu

public static final int LOCALE_hu
Hungarian locale.
Since:
JDE 4.3.0

LOCALE_it

public static final int LOCALE_it
Italian locale.

LOCALE_ja

public static final int LOCALE_ja
Japanese locale.
Since:
JDE 4.3.0

LOCALE_ko

public static final int LOCALE_ko
Korean locale.
Since:
JDE 4.3.0

LOCALE_nl

public static final int LOCALE_nl
Dutch locale.
Since:
JDE 4.2.0

LOCALE_pl

public static final int LOCALE_pl
Polish locale.
Since:
JDE 4.2.1

LOCALE_pt

public static final int LOCALE_pt
Portugese locale.
Since:
JDE 4.0.0

LOCALE_pt_BR

public static final int LOCALE_pt_BR
Brazillian Portugese locale.
Since:
JDE 4.2.0

LOCALE_ROOT

public static final int LOCALE_ROOT
Root locale.

LOCALE_ru

public static final int LOCALE_ru
Russian locale.
Since:
JDE 4.2.1

LOCALE_SET_DECLINED

public static final int LOCALE_SET_DECLINED
An identification of unsuccessful "set locale" operation
Since:
JDE 4.2.1

LOCALE_SET_OK

public static final int LOCALE_SET_OK
An identification of successful "set locale" operation
Since:
JDE 4.2.1

LOCALE_tr

public static final int LOCALE_tr
Turkish locale.
Since:
JDE 4.2.0

LOCALE_zh

public static final int LOCALE_zh
Chinese locale.
Since:
JDE 3.7.0

LOCALE_zh_CN

public static final int LOCALE_zh_CN
Chinese (mainland) locale.
Since:
JDE 4.2.1

LOCALE_zh_HK

public static final int LOCALE_zh_HK
Chinese (Hong Kong) locale.
Since:
JDE 4.2.1
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.

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.

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:
JDE 3.7.0

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.

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 setDefault(net.rim.device.api.i18n.Locale), or if null, the return from 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.

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.

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.

getDefaultInput

public static Locale getDefaultInput()
Deprecated. Use getDefaultInputForSystem()

Retrieves the current application's default input locale.

This is either the input locale that was specified by setDefaultInput(net.rim.device.api.i18n.Locale), or if null, the return from 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:
JDE 4.2.0

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:
JDE 3.7.0

getDisplayCountry

public final String getDisplayCountry()
Retrieves displayable name for this locale's country.
Returns:
Locale's displayable country name.

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.

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.

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 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:
JDE 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_SET_OK, LOCALE_SET_DECLINED
Since:
JDE 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.



Copyright 1999-2008 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.