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.

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
  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 locale.
LocaleManager
  
formatDate(date:Date, dateStyle:String, timeStyle:String):String
Returns a formatted Date String based on the locale.
LocaleManager
  
formatNumber(num:Number):String
Returns a String in the number format of the current locale.
LocaleManager
  
getCountry():String
Returns the two character country code of the locale.
LocaleManager
  
getCurrentLocale():String
Returns the current locale of the application.
LocaleManager
  
getDateOrder():Vector.<String>
Returns the day, month, year order basede on locale.
LocaleManager
  
getDeviceLocale():String
Returns the current locale 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
LocaleManager
  
removeResourceLoader(loader:ILocaleResourceLoader):void
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
Events
 Event Summary Defined By
  
change
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_LOCALEproperty
public static var DEFAULT_LOCALE:String = en_US

A String representing the default locale of the device.

localeManagerproperty 
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()Constructor
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()method
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()method 
public function formatCurrency(currency:Number, withCurrencySymbol:Boolean):String

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

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()method 
public function formatDate(date:Date, dateStyle:String, timeStyle:String):String

Returns a formatted Date String based on the locale.

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

flash.globalization.DateTimeStyle()
formatNumber()method 
public function formatNumber(num:Number):String

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

Parameters

num:Number — The number to be formatted.

Returns
String — The formatted String.
getCountry()method 
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()method 
public function getCurrentLocale():String

Returns the current locale of the application.

Returns
String — The ID of the current locale.

See also

getLocalePath
getDateOrder()method 
public function getDateOrder():Vector.<String>

Returns the day, month, year order basede on locale.

Returns
Vector.<String> — A String Vector with values of LocalDateTime.DAY, LocalDateTime.MONTH, LocaleDateTime.YEAR, in the order which they should be displayed.
getDeviceLocale()method 
public function getDeviceLocale():String

Returns the current locale of the device.

Returns
String — The ID of the current locale.
getLanguage()method 
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()method 
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()method 
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()method 
public function isTime24Hr():Boolean

Returns whether the clock format should be displayed as 24hr format

Returns
Boolean
removeResourceLoader()method 
public function removeResourceLoader(loader:ILocaleResourceLoader):void

Removes a ILocaleResourceLoader from the chain of resource loaders.

Parameters

loader:ILocaleResourceLoader — The ILocaleResourceLoader to remove.

setLocale()method 
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.

Parameters

locale:String — The ID of the locale.

Event Detail
change Event
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_FOLDERConstant
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



Copyright 2012 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Mon Jan 23 2012, 01:04 PM -05:00