net.rim.device.api.i18n
Class Locale

java.lang.Object
  extended by 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_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_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_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_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_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

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.





Copyright 1999-2010 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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.