LanguageManager

Kind of class:	class
Inherits from:	Dispatcher
Classpath:	org.asapframework.management.lang.LanguageManager
File last modified:	Monday, 06 November 2006, 17:27:17

Class for managing language dependencies in an application.

For text, the language dependent texts are expected to be in an xml per language, with the following structure:

<texts>
    <text id="1">Hello World</text>
    <text id="2" w="10">Hello World wider</text>
    <text id="3" x="50">Hello World shifted to the right</text>
    <text id="4"><[!CDATA[>>>Hello World<<<]]></text>
</texts>

The 'id' attribute is mandatory, and has to be a number. Attributes 'x', 'y' and 'w' are offsets to be applied to textfields, for the x-position, y-position and width respectively. These are optional.
In case the text contains xml characters, the text has to be wrapped in a <![CDATA[[]]> tag.
The id is expected to be unique. When it isn't, the last item is taken.

The xml file containing the language dependent texts has to be loaded with the method loadXML.
When loaded and parsed, the LanguageManager sends an event of type LanguageManager.EVENT_LOADED. Subscribe to this event if you wish to be notified.
No event is sent when the loading fails, only a Log message of level ERROR is output.

Once an xml file has been loaded, data is available by id through getTextByID and getDataByID. Since the LanguageManager is a Singleton, the language dependent data is available throughout your application.

However, the LanguageManager also contains a mechanism for automatic assignment of data. To use this functionality, use the provided class MultiLanguageTextContainer, or write your own implementation of IMultiLanguageTextContainer.
When writing your own class, allow for a way to determine the id of the text that is to be used by a specific instance for your class. In case of the MultiLanguageTextContainer class, this id is retrieved from the name of the movieclip instance to which the class is linked, by taking everything after the last underscore and converting to a number. So "myText_1" gets the text with id=1.
Once the id is known inside your class, add the instance to the LanguageManager with addContainer, providing the id and the instance itself as parameters. If data has been loaded, it is provided to the instance immediately. Whenever new data is loaded, the LanguageManager calls "setData" on each instance that was added, thereby updating language dependent text instantaneously.
A good spot to add an instance to the LanguageManager is in its onLoad() function. Make sure to remove it again in its onUnload() function, to allow for proper memory management. This also makes sure that the instance keeps its text when subject to animation key frames.
Instances can share the same id, and thereby have the same text.

By default, the LanguageManager returns an empty string (or provides an empty string in the data) when a requested id is not found.
This has two drawbacks:

The textfield becomes effectively invisible since there is no text in it
Formatting of the textfield (such as weight or alignment) may be lost when the textfield is cleared

To allow for easier debugging, the flag generateDebugText can be set. If an unknown id is requested, the returned text will be ">> id = #id", where #id is replaced with the actually requested id. This makes it easier to find missing texts from the xml files.

Performance note: The LanguageManager stores texts and containers in Arrays, without any sorting. It may be necessary to find more intricate lookup algorithms when dealing with large numbers of texts and/or containers.

Example:

Loading an xml file into the LanguageManager, specifying a language code to be used in determining the name of the xml file to be loaded.

// @param inCode: 2-letter ISO language code; will be added to filename. Example: with parameter "en" the file "texts_en.xml" will be loaded.
private function loadLanguage (inCode:String) : Void {
    var lm:LanguageManager = LanguageManager.getInstance();
    lm.addEventListener(LanguageManager.EVENT_LOADED, EventDelegate.create(this, handleLanguageLoaded);
    lm.loadXML("../xml/texts_" + inCode + ".xml");
}

private function handleLanguageLoaded () : Void {
    Log.debug("handleLanguageLoaded: Language file loaded.", toString());
}

Assigning a text to a textfield manually from anywhere in your code:
myTextfield.text = LanguageManager.getInstance().getTextByID(23);

A class that gets a random text from the first 10 texts of the LanguageManager each time it is loaded:

class MyText extends MovieClip implements IMultiLanguageTextContainer {
    private var mID:Number;
    private var myTextField:TextField;

    public function setData (inData : ItemData) : Void {
        setText(inData.text);
    }

    public function setText (inText:String) : Void {
        myTextField.text = inText;
    }

    private function onLoad () : Void {
        mID = Math.floor(10 * Math.random());

        LanguageManager.getInstance().addContainer(mID, this);
    }

    private function onUnload () : Void {
        LanguageManager.getInstance().removeContainer(this);
    }
}

Summary

Class properties

EVENT_LOADED

Instance properties

generateDebugText

Class methods

getInstance

Instance methods

loadXML
addContainer
removeContainer
addText
getTextByID
getDataByID
toString

Class properties

EVENT_LOADED

static EVENT_LOADED:String = "onLanguageLoaded"

(read,write)

The event sent when the language xml has been loaded and parsed

Instance properties

generateDebugText

generateDebugText:Boolean

(write)

Flag indicates whether items show their id as text when no text is found in the xml. When false, an empty string is returned when no text is found.

Class methods

getInstance

static function getInstance (

) : LanguageManager

Returns:

The singleton instance of the LanguageManager

Instance methods

addContainer

function addContainer (

inID:Number, inContainer:IMultiLanguageTextContainer) : Void

Add a multi-laguage container to the LanguageManager.
If data has been loaded, the container will receive its data immediately.
If the container had been added already, it will not be added again.

Parameters:

inID :

the id to be associated with the container

inContainer:

instance of a class implementing IMultiLanguageTextContainer

addText

function addText (

inData:ItemData) : Void

Add text for a specific ID to the language manager.
Set the text in any IMultiLanguageTextContainer instance associated with that id.

Parameters:

inData:

ItemData instance containing necessary data.

getDataByID

function getDataByID (

inID:Number) : ItemData

Retrieve text data

Parameters:

inID:

the id for the text to be found

Returns:

the text data with the right text if found, with an empty string if generateDebugText is set to false, or with '>> id = ' + id if generateDebugText is set to true

getTextByID

function getTextByID (

inID:Number) : String

Retrieve a text

Parameters:

inID:

the id for the text to be found

Returns:

the text if found, an empty string if generateDebugText is set to false, or '>> id = ' + id if generateDebugText is set to true

loadXML

function loadXML (

inURL:String) : Void

Load language XML

Parameters:

inURL:

full path of the xml file to be loaded

removeContainer

function removeContainer (

inContainer:IMultiLanguageTextContainer) : Void

Remove a multi-laguage container from the LanguageManager

Parameters:

inContainer:

previously added instance of a class implementing IMultiLanguageTextContainer

toString

function toString (

) : String

Returns:

Package and class name.