Adobe® Flex® 4 Language Reference
Hide Packages and Classes List |  Packages  |  Classes  |  Index  |  Appendixes
mx.resources 
IResourceManager 
Packagemx.resources
Interfacepublic interface IResourceManager extends IEventDispatcher

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

The APIs of the IResourceManager interface provide localization support for Flex applications.

There are three main concepts involved in localization: locales, resources, and resource bundles.

A locale specifies a language and a country for which your application has been localized. For example, the locale "en_US" specifies English as spoken in the United States. (See the mx.resources.Locale class for more information.)

A resource is a named value that is locale-dependent. For example, your application might have a resource whose name is "OPEN" and whose value for an English locale is "Open" but whose value for a French locale is "Ouvrir".

A resource bundle is a named group of resources whose values have been localized for a particular locale. A resource bundle is identified by the combination of its bundleName and its locale, and has a content object that contains the name-value pairs for the bundle's resources. See the documentation for mx.resources.IResourceBundle for information about how you typically create resource bundles from properties files.

A single ResourceManager object implementing the IResourceManager interface manages multiple resource bundles, possibly for multiple locales, and provides access to the resources that they contain. For example, you can retrieve a specific resource as a String by calling resourceManager.getString(bundleName, resourceName).

All classes that extend UIComponent, Formatter, or Validator have a resourceManager property that provides a reference to the object implementing this interface. Other classes can call ResourceManager.getInstance() to obtain this object.

Resource retrieval methods such as getString() search for resources in the locales specified by the localeChain property. By changing this property, you can make your application suddenly use, for example, Japanese rather than English resources.

When your application starts, the ResourceManager is automatically populated with whatever resource bundles were compiled into the application. If you create a code module, by default the resources that its classes need are compiled into the module. When the module is loaded into an application, any bundles that the application does not already have are added to the ResourceManager.

You can compile "resource modules" which have only resources in them, and load them with the loadResourceModule() method of IResourceManager. With resource modules, you can support multiple locales by loading the resources you need at run time rather than compiling them into your application.

Although the ResourceManager is normally populated with resource bundles that were compiled into your application or loaded from modules, you can also programmatically create resource bundles and add them to the ResourceManager yourself with the addResourceBundle() method.

See also



Public Properties
 PropertyDefined By
  localeChain : Array
An Array of locale Strings, such as [ "en_US" ], which specifies one or more locales to be searched for resources.
IResourceManager
Public Methods
 MethodDefined By
 Inherited
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.
IEventDispatcher
  
Adds the specified ResourceBundle to the ResourceManager so that its resources can be accessed by ResourceManager methods such as getString().
IResourceManager
 Inherited
Dispatches an event into the event flow.
IEventDispatcher
  
Searches the locales in the localeChain for the specified resource and returns the first resource bundle in which it is found.
IResourceManager
  
getBoolean(bundleName:String, resourceName:String, locale:String = null):Boolean
Gets the value of a specified resource as a Boolean.
IResourceManager
  
Returns an Array of Strings specifying the bundle names for all ResourceBundle objects that exist in the ResourceManager and that belong to the specified locale.
IResourceManager
  
getClass(bundleName:String, resourceName:String, locale:String = null):Class
Gets the value of a specified resource as a Class.
IResourceManager
  
getInt(bundleName:String, resourceName:String, locale:String = null):int
Gets the value of a specified resource as an int.
IResourceManager
  
Returns an Array of Strings specifying all locales for which ResourceBundle objects exist in the ResourceManager.
IResourceManager
  
getNumber(bundleName:String, resourceName:String, locale:String = null):Number
Gets the value of a specified resource as a Number.
IResourceManager
  
getObject(bundleName:String, resourceName:String, locale:String = null):*
Gets the value of a specified resource as an Object.
IResourceManager
  
Returns an Array of Strings specifying all locales for which ResourceBundle objects exist in the ResourceManager, ordered using user preferences as reported by Capabilities.language or Capabilities.languages.
IResourceManager
  
Returns a ResourceBundle with the specified locale and bundleName that has been previously added to the ResourceManager with addResourceBundle().
IResourceManager
  
getString(bundleName:String, resourceName:String, parameters:Array = null, locale:String = null):String
Gets the value of a specified resource as a String, after substituting specified values for placeholders.
IResourceManager
  
getStringArray(bundleName:String, resourceName:String, locale:String = null):Array
Gets the value of a specified resource as an Array of Strings.
IResourceManager
  
getUint(bundleName:String, resourceName:String, locale:String = null):uint
Gets the value of a specified resource as a uint.
IResourceManager
 Inherited
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
IEventDispatcher
  
Used only by classes which implement IFlexModuleFactory.
IResourceManager
  
installCompiledResourceBundles(applicationDomain:ApplicationDomain, locales:Array, bundleNames:Array):void
Used only by classes which implement IFlexModuleFactory.
IResourceManager
  
loadResourceModule(url:String, update:Boolean = true, applicationDomain:ApplicationDomain = null, securityDomain:SecurityDomain = null):IEventDispatcher
Begins loading a resource module containing resource bundles.
IResourceManager
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Removes a listener from the EventDispatcher object.
IEventDispatcher
  
Removes the specified ResourceBundle from the ResourceManager so that its resources can no longer be accessed by ResourceManager methods such as getString().
IResourceManager
  
Removes all ResourceBundles for the specified locale from the ResourceManager so that their resources can no longer be accessed by ResourceManager methods such as getString().
IResourceManager
  
Begins unloading a loaded resource module.
IResourceManager
  
Dispatches a change event from the ResourceManager.
IResourceManager
 Inherited
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
IEventDispatcher
Property Detail

localeChain

property
localeChain:Array

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

An Array of locale Strings, such as [ "en_US" ], which specifies one or more locales to be searched for resources.

When you call the ResourceManager methods getObject(), getString(), getStringArray(), getNumber(), getInt(), getUint(), getBoolean(), or getClass() to get the value of a resource, you specify a bundle name and a resource name, but not a locale. The ResourceManager starts with the first locale in the localeChain and looks for a ResourceBundle with the specified bundle name for that locale. If such a ResourceBundle exists, and the specified resource exists in it, then the value of that resource is returned. Otherwise, the ResourceManager proceeds on to the other locales in the localeChain.

This scheme makes it possible to have locales that do not necessarily contain a complete set of localized resources. For example, if you are localizing your application for Indian English rather than U.S. English, you need only supply resources for the en_IN locale in which the Indian spelling or usage differs from that in the U.S., and then set the localeChain property to [ "en_IN", "en_US" ].

Many framework classes assume that they can always obtain, from some locale, the resources that they expect, and they will throw errors if they cannot do so. Therefore, you must ensure that the localeChain always contains a complete set of resources. Unless you have done a complete localization of all the framework's resources as well as your own application's resources, you can keep the "en_US" locale at the end of your localeChain to ensure this.

Setting this property causes the ResourceManager to dispatch a "change" Event.



Implementation
    public function get localeChain():Array
    public function set localeChain(value:Array):void
Method Detail

addResourceBundle

()method
public function addResourceBundle(resourceBundle:IResourceBundle):void

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Adds the specified ResourceBundle to the ResourceManager so that its resources can be accessed by ResourceManager methods such as getString().

Parameters

resourceBundle:IResourceBundle — The resource bundle to be added.

findResourceBundleWithResource

()method 
public function findResourceBundleWithResource(bundleName:String, resourceName:String):IResourceBundle

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Searches the locales in the localeChain for the specified resource and returns the first resource bundle in which it is found. If the resource isn't found, this method returns null.

Parameters

bundleName:String — A bundle name such as "MyResources".
 
resourceName:String — The name of a resource in the resource bundle.

Returns
IResourceBundle — The first ResourceBundle in the localeChain that contains the specified resource, or null.

getBoolean

()method 
public function getBoolean(bundleName:String, resourceName:String, locale:String = null):Boolean

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Gets the value of a specified resource as a Boolean.

This method first calls getString() and converts the result to lowercase. It then returns true if the result was "true". and false otherwise.

If the specified resource is not found, this method returns false.

Parameters

bundleName:String — The name of a resource bundle.
 
resourceName:String — The name of a resource in the resource bundle.
 
locale:String (default = null) — A specific locale to be used for the lookup, or null to search all locales in the localeChain. This parameter is optional and defaults to null; you should seldom need to specify it.

Returns
Boolean — The resource value, as a Boolean, or false if it is not found.

getBundleNamesForLocale

()method 
public function getBundleNamesForLocale(locale:String):Array

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Returns an Array of Strings specifying the bundle names for all ResourceBundle objects that exist in the ResourceManager and that belong to the specified locale.

The order of bundle names in this Array is not specified.

Parameters

locale:String — A locale string such as "en_US".

Returns
Array — An Array of bundle names.

See also

getClass

()method 
public function getClass(bundleName:String, resourceName:String, locale:String = null):Class

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Gets the value of a specified resource as a Class.

This method calls getObject() and coerces it to type Class using the as operator. The result will be null if the resource value was not a class reference. It is useful if you have written a lines such as

      IMAGE=Embed("image.jpg")
      BUTTON_SKIN=ClassReference("skins.ButtonSkin_en_US")
      

in a properties file and want to obtain the Class that the Embed() or ClassReference() directive produced.

If the specified resource is not found, this method returns null.

Parameters

bundleName:String — The name of a resource bundle.
 
resourceName:String — The name of a resource in the resource bundle.
 
locale:String (default = null) — A specific locale to be used for the lookup, or null to search all locales in the localeChain. This parameter is optional and defaults to null; you should seldom need to specify it.

Returns
Class — The resource value, as a Class, or null if it is not found.

getInt

()method 
public function getInt(bundleName:String, resourceName:String, locale:String = null):int

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Gets the value of a specified resource as an int.

This method calls getObject() and casts the result to an int. It is useful if you have written a line such as:

      MINIMUM=5
      

in a properties file and want to obtain the value 5 rather than "5".

If the specified resource is not found, this method returns 0.

Parameters

bundleName:String — The name of a resource bundle.
 
resourceName:String — The name of a resource in the resource bundle.
 
locale:String (default = null) — A specific locale to be used for the lookup, or null to search all locales in the localeChain. This parameter is optional and defaults to null; you should seldom need to specify it.

Returns
int — The resource value, as an int, or 0 if it is not found.

getLocales

()method 
public function getLocales():Array

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Returns an Array of Strings specifying all locales for which ResourceBundle objects exist in the ResourceManager.

The order of locales in this array is not specified.

Returns
Array — An Array of locale Strings.

getNumber

()method 
public function getNumber(bundleName:String, resourceName:String, locale:String = null):Number

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Gets the value of a specified resource as a Number.

This method calls getObject() and casts the result to a Number. It is useful if you have written a line such as:

      LONGITUDE=170.3
      

in a properties file and want to obtain the value 170.3 rather than "170.3".

If the specified resource is not found, this method returns NaN.

Parameters

bundleName:String — The name of a resource bundle.
 
resourceName:String — The name of a resource in the resource bundle.
 
locale:String (default = null) — A specific locale to be used for the lookup, or null to search all locales in the localeChain. This parameter is optional and defaults to null; you should seldom need to specify it.

Returns
Number — The resource value, as a Number, or NaN if it is not found.

getObject

()method 
public function getObject(bundleName:String, resourceName:String, locale:String = null):*

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Gets the value of a specified resource as an Object.

The value is returned exactly as it is stored in the content Object of the ResourceBundle, with no conversion. If the resource was compiled from a properties files, the resource value in the content Object is always a String unless you used the Embed() or ClassReference() directive, in which case it is a Class. Use the getString(), getStringArray(), getNumber(), getInt() getUint(), getBoolean(), and getClass() methods to convert the value to more specific types.

If the specified resource is not found, this method returns undefined.

Parameters

bundleName:String — The name of a resource bundle.
 
resourceName:String — The name of a resource in the resource bundle.
 
locale:String (default = null) — A specific locale to be used for the lookup, or null to search all locales in the localeChain. This parameter is optional and defaults to null; you should seldom need to specify it.

Returns
* — The resource value, exactly as it is stored in the content Object, or undefined if the resource is not found.

getPreferredLocaleChain

()method 
public function getPreferredLocaleChain():Array

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Returns an Array of Strings specifying all locales for which ResourceBundle objects exist in the ResourceManager, ordered using user preferences as reported by Capabilities.language or Capabilities.languages.

Returns
Array — An Array of locale Strings.

getResourceBundle

()method 
public function getResourceBundle(locale:String, bundleName:String):IResourceBundle

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Returns a ResourceBundle with the specified locale and bundleName that has been previously added to the ResourceManager with addResourceBundle(). If no such ResourceBundle exists, this method returns null.

Parameters

locale:String — A locale string such as "en_US".
 
bundleName:String — A bundle name such as "MyResources".

Returns
IResourceBundle — The ResourceBundle with the specified locale and bundleName if one exists; otherwise null.

See also

getString

()method 
public function getString(bundleName:String, resourceName:String, parameters:Array = null, locale:String = null):String

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Gets the value of a specified resource as a String, after substituting specified values for placeholders.

This method calls getObject() and then casts the result to a String.

If a parameters Array is passed to this method, the parameters in it are converted to Strings and then substituted, in order, for the placeholders "{0}", "{1}", and so on, in the String before it is returned.

If the specified resource is not found, this method returns null.

Parameters

bundleName:String — The name of a resource bundle.
 
resourceName:String — The name of a resource in the resource bundle.
 
parameters:Array (default = null) — An Array of parameters that are substituted for the placeholders. Each parameter is converted to a String with the toString() method before being substituted.
 
locale:String (default = null) — A specific locale to be used for the lookup, or null to search all locales in the localeChain. This parameter is optional and defaults to null; you should seldom need to specify it.

Returns
String — The resource value, as a String, or null if it is not found.

getStringArray

()method 
public function getStringArray(bundleName:String, resourceName:String, locale:String = null):Array

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Gets the value of a specified resource as an Array of Strings.

This method assumes that the resource value is a String containing a comma-separated list of items. It calls the getString() method, splits the String into items at the commas, and trims white space before and after each item. It is useful if you have written a line such as:

      COUNTRIES=India, China, Japan
      

in a properties file and you want to obtain the value [ "India", "China", "Japan" ] rather than the value "India, China, Japan".

If the specified resource is not found, this method returns null.

Parameters

bundleName:String — The name of a resource bundle.
 
resourceName:String — The name of a resource in the resource bundle.
 
locale:String (default = null) — A specific locale to be used for the lookup, or null to search all locales in the localeChain. This parameter is optional and defaults to null; you should seldom need to specify it.

Returns
Array — The resource value, as an Array of Strings, or null if it is not found.

getUint

()method 
public function getUint(bundleName:String, resourceName:String, locale:String = null):uint

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Gets the value of a specified resource as a uint.

This method calls the getObject() method and casts the result to a uint. It is useful if you have written a line such as:

      MINIMUM=5
      

in a properties file and want to obtain the value 5 rather than "5".

If the specified resource is not found, this method returns 0.

Parameters

bundleName:String — The name of a resource bundle.
 
resourceName:String — The name of a resource in the resource bundle.
 
locale:String (default = null) — A specific locale to be used for the lookup, or null to search all locales in the localeChain. This parameter is optional and defaults to null; you should seldom need to specify it.

Returns
uint — The resource value, as a uint, or 0 if it is not found.

initializeLocaleChain

()method 
public function initializeLocaleChain(compiledLocales:Array):void

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Used only by classes which implement IFlexModuleFactory.

Parameters

compiledLocales:Array

installCompiledResourceBundles

()method 
public function installCompiledResourceBundles(applicationDomain:ApplicationDomain, locales:Array, bundleNames:Array):void

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Used only by classes which implement IFlexModuleFactory.

Parameters

applicationDomain:ApplicationDomain
 
locales:Array
 
bundleNames:Array

loadResourceModule

()method 
public function loadResourceModule(url:String, update:Boolean = true, applicationDomain:ApplicationDomain = null, securityDomain:SecurityDomain = null):IEventDispatcher

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Begins loading a resource module containing resource bundles.

Each call to this method returns a new event-dispatching object that you can use to learn how the loading is progressing and whether it completes successfully or results in an error. This object dispatches ResourceEvent.PROGRESS, ResourceEvent.COMPLETE, and ResourceEvent.ERROR events.

When the module has been loaded, the resource bundles are added to the ResourceManager, but the localeChain is left unchanged. If the update parameter is true, the update() method will be called.

Parameters

url:String — The URL from which to load the resource module.
 
update:Boolean (default = true) — Whether to call the update() method when the module finishes loading.
 
applicationDomain:ApplicationDomain (default = null) — The ApplicationDomain passed to the load() method of the IModuleInfo class that loads the resource module. This parameter is optional and defaults to null.
 
securityDomain:SecurityDomain (default = null) — The SecurityDomain passed to the load() method of the IModuleInfo class that loads the resource module. This parameter is optional and defaults to null.

Returns
IEventDispatcher — An object that is associated with this particular load operation that dispatches ResourceEvent.PROGRESS, ResourceEvent.COMPLETE, and ResourceEvent.ERROR events.

See also

removeResourceBundle

()method 
public function removeResourceBundle(locale:String, bundleName:String):void

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Removes the specified ResourceBundle from the ResourceManager so that its resources can no longer be accessed by ResourceManager methods such as getString().

Parameters

locale:String — A locale string such as "en_US".
 
bundleName:String — A bundle name such as "MyResources".

See also

removeResourceBundlesForLocale

()method 
public function removeResourceBundlesForLocale(locale:String):void

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Removes all ResourceBundles for the specified locale from the ResourceManager so that their resources can no longer be accessed by ResourceManager methods such as getString().

Parameters

locale:String — A locale string such as "en_US".

See also

unloadResourceModule

()method 
public function unloadResourceModule(url:String, update:Boolean = true):void

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Begins unloading a loaded resource module.

When the module is unloaded, its resource bundles are removed from the ResourceManager, but the localeChain is left unchanged. If the update parameter is true, the update() method will be called.

Parameters

url:String — The URL that was used to load the resource module.
 
update:Boolean (default = true) — Whether to call the update() method when the module finishes unloading.

update

()method 
public function update():void

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Dispatches a change event from the ResourceManager.

This causes binding expressions to re-evaluate if they involve the ResourceManager methods getObject(), getString(), getStringArray(), getNumber(), getInt(), getUint(), getBoolean(), or getClass().

This also causes the resourcesChanged() method of a UIComponent, Formatter, or Validator to execute. Many components implement this method to update their state based on the latest resources.