qnx.locale.LocaleManager

LocaleManager

Properties | Methods | Events | Constants | Examples


Packageqnx.locale
Classpublic class LocaleManager
InheritanceLocaleManager Inheritance flash.events.EventDispatcher

The LocaleManager class manages system locale changes. It enables you to both listen for system locale changes and set the locale of an application.

You can place a resource String file in the following folder in your application directory:

locale/<locale id>/resource.properties 
     
where <locale id> is a valid locale ID, such as en_US. You can place any other localized assets in this folder, such as images and fonts. The getLocalePath() function returns the path to the current locale directory.

A resource file has the following format:

key1=resource_string_1
key2=resource_string_2
key3=resource_string_3
     

where key1 is a resource key, and resource_string_1 is the translatable, locale-specific String. See the LocaleResourceBundle class for more information about resource bundles.

Note: Currently only the US English locale (en_US) is supported.



Class information:
BlackBerry 10 Version:   10.0.0

View the examples

See also

Locale
LocaleResourceBundle



Public Properties

 PropertyDefined By
  DEFAULT_LOCALE : String = en_US
[static] A String representing the default locale of the device.
LocaleManager
  DEFAULT_REGION : String = en_US
[static] A String representing the default region of the device.
LocaleManager
  localeManager : LocaleManager
[static] [read-only] Returns the Singleton instance of the LocaleManager.
LocaleManager

Public Methods

 MethodDefined By
  
LocaleManager(enforcer:SingletonEnforcer)
Do not instantiate the LocaleManager by using this constructor.
LocaleManager
  
addResourceLoader(loader:ILocaleResourceLoader, load:Boolean = true):void
Adds a ILocaleResourceLoader to the chain of loaders which will be given the oppturnity to loader resources before the Locale Event.CHANGE is fired.
LocaleManager
  
formatCurrency(currency:Number, withCurrencySymbol:Boolean):String
Returns a String in the currency format of the current region.
LocaleManager
  
formatDate(date:Date, dateStyle:String, timeStyle:String):String
Returns a formatted Date String based on the region.
LocaleManager
  
formatNumber(num:Number):String
Returns a String in the number format of the current region.
LocaleManager
  
getCountry():String
Returns the two character country code of the locale.
LocaleManager
  
Returns the current locale of the application.
LocaleManager
  
Returns the current region of the application.
LocaleManager
  
getDateOrder(dateStyle:String, timeStyle:String):Vector.<String>
Returns the day, month, year order based on region.
LocaleManager
  
Returns the current locale of the device.
LocaleManager
  
Returns the current region of the device.
LocaleManager
  
getLanguage():String
Returns the two character language code of the locale.
LocaleManager
  
getLocalePath():String
[static] Returns the path from the application directory to the current locale directory in the format, locale/{locale id}/.
LocaleManager
  
getResource(key:String, ... args):String
Returns the resource for the specified key from the currently loaded localization file.
LocaleManager
  
isTime24Hr():Boolean
Returns whether the clock format should be displayed as 24hr format based the users settings.
LocaleManager
  
Removes a ILocaleResourceLoader from the chain of resource loaders.
LocaleManager
  
setLocale(locale:String):void
Sets the locale of the application, given the locale ID.
LocaleManager
  
setRegion(region:String):void
Sets the region of the application, given the region ID.
LocaleManager

Events

 Event Summary Defined By
  Dispatched when the locale has been changed and the associated localization resources have finished loading.LocaleManager

Public Constants

 ConstantDefined By
  LOCALE_FOLDER : String = locale/
[static] A String representing the location of the locale folder.
LocaleManager

Property Detail

DEFAULT_LOCALE


public static var DEFAULT_LOCALE:String = en_US

A String representing the default locale of the device.

DEFAULT_REGION


public static var DEFAULT_REGION:String = en_US

A String representing the default region of the device.

localeManager


localeManager:LocaleManager  [read-only]

Returns the Singleton instance of the LocaleManager. You can only instantiate a single instance in an application.

The following example returns an instance of the LocaleManager and adds an event listener to listen for locale changes:

var lm:LocaleManager = LocaleManager.localeManager;
lm.addEventListener(Event.CHANGE, onLocaleChange);
        

Do not instantiate the LocaleManager from its public constructor.


Implementation

public static function get localeManager():LocaleManager

Constructor Detail

LocaleManager()


public function LocaleManager(enforcer:SingletonEnforcer)

Do not instantiate the LocaleManager by using this constructor.

Instead, use the LocaleManager.localeManager property to return the Singleton instance.

Parameters

enforcer:SingletonEnforcer

See also

localeManager

Method Detail

addResourceLoader()


public function addResourceLoader(loader:ILocaleResourceLoader, load:Boolean = true):void

Adds a ILocaleResourceLoader to the chain of loaders which will be given the oppturnity to loader resources before the Locale Event.CHANGE is fired.

Parameters

loader:ILocaleResourceLoader — The ILocaleResourceLoader to add.
load:Boolean (default = true) — A Boolean to determin whether to load from the loader immediately.

formatCurrency()


public function formatCurrency(currency:Number, withCurrencySymbol:Boolean):String

Returns a String in the currency format of the current region.

Parameters

currency:Number — The current currency value to be formatted.
withCurrencySymbol:Boolean — A Boolean that determines whether or not the currency symbol will appear in the String.

Returns

String — A String containing the formatted currency.

formatDate()


public function formatDate(date:Date, dateStyle:String, timeStyle:String):String

Returns a formatted Date String based on the region.

Parameters

date:Date — The date to be formatted.
dateStyle:String (default = NaN) — The date style to use when formatting the date. See the DateTimeStyle class for valid values. The default is DateTimeStyle.NONE.
timeStyle:String (default = NaN) — The time style to use when formatting the time. See the DateTimeStyle class for valid values. The default is DateTimeStyle.NONE.

Returns

String — A String representing the formatted date.

See also

DateTimeStyle

formatNumber()


public function formatNumber(num:Number):String

Returns a String in the number format of the current region.

Parameters

num:Number — The number to be formatted.

Returns

String — The formatted String.

getCountry()


public function getCountry():String

Returns the two character country code of the locale. For example the locale en_US would have a country code of US.

Returns

String — The country of the current locale.

getCurrentLocale()


public function getCurrentLocale():String

Returns the current locale of the application.

Returns

String — The ID of the current locale.

See also

getLocalePath

getCurrentRegion()


public function getCurrentRegion():String

Returns the current region of the application.

Returns

String — The ID of the current region id.

getDateOrder()


public function getDateOrder(dateStyle:String, timeStyle:String):Vector.<String>

Returns the day, month, year order based on region.

The order of the date elements is dependent on the style used to format the date. By default both date and time styles use DateTimeStyle.SHORT. Valid values for each parameter can be found in flash.globalization.DateTimeStyle;

  • DateTimeStyle.NONE
  • DateTimeStyle.SHORT
  • DateTimeStyle.MEDIUM
  • DateTimeStyle.LONG

Parameters

dateStyle:String (default = NaN) — The date style to be used. The default is DateTimeStyle.SHORT.
timeStyle:String (default = NaN) — The time style to be used. The default is DateTimeStyle.SHORT.

Returns

Vector.<String> — A String Vector with values of LocalDateTime.DAY, LocalDateTime.MONTH, LocaleDateTime.YEAR, in the order which they should be displayed.

getDeviceLocale()


public function getDeviceLocale():String

Returns the current locale of the device.

Returns

String — The ID of the current locale.

getDeviceRegion()


public function getDeviceRegion():String

Returns the current region of the device.

Returns

String — The ID of the current region.

getLanguage()


public function getLanguage():String

Returns the two character language code of the locale. For example the locale en_US would have a country code of en.

Returns

String — The language of the current locale.

getLocalePath()


public static function getLocalePath():String

Returns the path from the application directory to the current locale directory in the format, locale/{locale id}/.

You can place any localized asset in the application's locale directory. This path allows you to reference an asset in the currently selected locale. In the example below, the getLocalePath() method is called to load a locale-specific image in an IconButton instance:

private function initializeIconButton():void
{
    myIconButton = new IconButton();
    myIconButton.setIcon( LocaleManager.getLocalePath() + 
        "/icon.gif");
    myIconButton.width = 100;
    myIconButton.setPosition(30, 30);
    
    this.addChild(myIconButton);
                    
}
        

Returns

String — The path to the current locale folder.

See also

getCurrentLocale

getResource()


public function getResource(key:String, ... args):String

Returns the resource for the specified key from the currently loaded localization file.

In the following example, the getResource method is called to populate the label for a SegmentedControl button.

mySegmented.addItem({label: LocaleManager.localeManager.getResource("day-sunday")});
        

Parameters

key:String — The key of the resource to be returned.
... args — Optional parameters that can be used as wildcard replacements in the returned String.

Returns

String — A String representing the value of the key in the localization file.

isTime24Hr()


public function isTime24Hr():Boolean

Returns whether the clock format should be displayed as 24hr format based the users settings.

Returns

Boolean

removeResourceLoader()


public function removeResourceLoader(loader:ILocaleResourceLoader):void

Removes a ILocaleResourceLoader from the chain of resource loaders.

Parameters

loader:ILocaleResourceLoader — The ILocaleResourceLoader to remove.

setLocale()


public function setLocale(locale:String):void

Sets the locale of the application, given the locale ID.

This function dispatches a flash.events.Event.CHANGE event when the current locale resources have been loaded and parsed. Until the resouces have been loaded and parsed, any queries to getResouce will return resources from the previous locale.

Parameters

locale:String — The ID of the locale.

setRegion()


public function setRegion(region:String):void

Sets the region of the application, given the region ID.

Parameters

region:String — The ID of the region.

Event Detail

change


Event Object Type: flash.events.Event
Event.type property = flash.events.Event.CHANGE

Dispatched when the locale has been changed and the associated localization resources have finished loading.

Constant Detail

LOCALE_FOLDER


public static const LOCALE_FOLDER:String = locale/

A String representing the location of the locale folder.

Examples

The following example uses the LocaleManager to load a set of locale-specific resource Strings. A list is instantiated and loaded with resource Strings and an event listener is added to listen for locale changes. When a locale change occurs, or when the application loads, the onLocaleChange function is called to load the resource strings for the current locale. You can add this same functionality to your application in order to globalize your Strings or images.

package
{
    import flash.display.Sprite;
    import flash.events.Event;
    
    import qnx.locale.LocaleManager;
    import qnx.ui.data.DataProvider;
    import qnx.ui.listClasses.List;
    import qnx.ui.listClasses.ListSelectionMode;
    import qnx.ui.text.Label;
    
    
    [SWF(height="600", width="1024", frameRate="30", backgroundColor="#FFFFFF")]
    public class MyLocaleChangeSample extends Sprite
    {
        
        private var myList:List;
        private var myLabel:Label;
        private var myDP:DataProvider;
        
        public function MyLocaleChangeSample()
        {
            initializeUI();
        }
        
        private function initializeUI():void
        {
            
            //Listen for locale changes.
            var lm:LocaleManager = LocaleManager.localeManager;
            lm.addEventListener(Event.CHANGE, onLocaleChange);
            
            //Create a label.
            myLabel = new Label();    
            myLabel.width = 200;
            myLabel.setPosition(100, 150);    
            stage.addChild(myLabel);
            
            //Create a list.
            myList = new List();
            myList.setPosition(100, 200);            
            myList.width = 400;
            myList.height = 500;            
            myList.selectionMode = ListSelectionMode.MULTIPLE;
            stage.addChild(myList);
            
            myDP = new DataProvider();
        }
        
        //This function is called when the locale of the device changes.
        private function onLocaleChange(event:Event):void{
            
            myDP.setItems([{label: LocaleManager.localeManager.getResource("list-corn")},
                           {label: LocaleManager.localeManager.getResource("list-potato")},
                           {label: LocaleManager.localeManager.getResource("list-asparagus")},
                           {label: LocaleManager.localeManager.getResource("list-bacon")},
                           {label: LocaleManager.localeManager.getResource("list-celery")}]);
            
            myList.dataProvider = myDP;
            
            myLabel.text = LocaleManager.localeManager.getResource("label-title");
            
        }
        
    }
}
    

The example above uses a resource file (resource.properties) which is located in the English language locale directory (locale/en_US). The file is listed below:

list-potato=Potato 
list-asparagus=Asparagus 
list-bacon=Bacon 
list-celery=Celery
list-corn=Corn
label-title=Grocery List
     




comments powered by Disqus