asapframework-cvs Mailing List for ASAP ActionScript Application Framework

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Revision: 606
          http://svn.sourceforge.net/asapframework/?rev=606&view=rev
Author:   acidcats
Date:     2006-10-30 13:55:24 -0800 (Mon, 30 Oct 2006)

Log Message:
-----------
Added documentation to management.lang package

Modified Paths:
--------------
    trunk/asapframework/org/asapframework/management/lang/IMultiLanguageTextContainer.as
    trunk/asapframework/org/asapframework/management/lang/ItemData.as
    trunk/asapframework/org/asapframework/management/lang/LanguageManager.as
    trunk/asapframework/org/asapframework/management/lang/MultiLanguageClipData.as
    trunk/asapframework/org/asapframework/management/lang/MultiLanguageTextContainer.as

Modified: trunk/asapframework/org/asapframework/management/lang/IMultiLanguageTextContainer.as
===================================================================

--- trunk/asapframework/org/asapframework/management/lang/IMultiLanguageTextContainer.as	2006-10-30 16:00:14 UTC (rev 605)
+++ trunk/asapframework/org/asapframework/management/lang/IMultiLanguageTextContainer.as	2006-10-30 21:55:24 UTC (rev 606)
@@ -18,7 +18,8 @@
 import org.asapframework.management.lang.ItemData;
 
 /**
-@author stephan.bezoen
+Interface to be implemented by any class that wishes to add itself to the LanguageManager.
+This interface provides two functions that the LanguageManager expects.
 */
  
 interface org.asapframework.management.lang.IMultiLanguageTextContainer {

Modified: trunk/asapframework/org/asapframework/management/lang/ItemData.as
===================================================================
--- trunk/asapframework/org/asapframework/management/lang/ItemData.as	2006-10-30 16:00:14 UTC (rev 605)
+++ trunk/asapframework/org/asapframework/management/lang/ItemData.as	2006-10-30 21:55:24 UTC (rev 606)
@@ -14,10 +14,11 @@
 limitations under the License.
 */
 
-// ASAP classes
-
 /**
-@author stephan.bezoen
+ValueObject class that holds data for a text item. 
+Classes that implement {@link IMultiLanguageTextContainer} get this type of data from the LanguageManager.
+Basic info contained in this class is the text and the id by which it is referenced.
+Optional info are offset values for changing textfields.
 */
  
 class org.asapframework.management.lang.ItemData {

Modified: trunk/asapframework/org/asapframework/management/lang/LanguageManager.as
===================================================================
--- trunk/asapframework/org/asapframework/management/lang/LanguageManager.as	2006-10-30 16:00:14 UTC (rev 605)
+++ trunk/asapframework/org/asapframework/management/lang/LanguageManager.as	2006-10-30 21:55:24 UTC (rev 606)
@@ -18,19 +18,100 @@
 import org.asapframework.events.Dispatcher;
 import org.asapframework.events.Event;
 import org.asapframework.events.EventDelegate;
+import org.asapframework.management.lang.IMultiLanguageTextContainer;
+import org.asapframework.management.lang.ItemData;
+import org.asapframework.management.lang.MultiLanguageClipData;
+import org.asapframework.util.debug.Log;
 import org.asapframework.util.xml.XML2Object;
 import org.asapframework.util.xml.XMLEvent;
 import org.asapframework.util.xml.XMLLoader;
 
-import org.asapframework.management.lang.IMultiLanguageTextContainer;
-import org.asapframework.management.lang.ItemData;
-import org.asapframework.management.lang.MultiLanguageClipData;
+/**
+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.
 
-/**
-@author stephan.bezoen
+The xml file containing the language dependent texts has to be loaded with the method {@link #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 {@link #getTextByID} and {@link #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 {@link MultiLanguageTextContainer}, or write your own implementation of {@link 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 {@link #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:
+<ul><li>The textfield becomes effectively invisible since there is no text in it</li>
+<li>Formatting of the textfield (such as weight or alignment) may be lost when the textfield is cleared</li></ul>
+To allow for easier debugging, the flag {@link 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.
+
+<b>Performance note</b>: 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.
+
+@Examples
+<ul>
+<li>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.
+<code>
+// @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());
+}
+</code>
+</li>
+
+<li>Assigning a text to a textfield manually from anywhere in your code:
+<code>myTextfield.text = LanguageManager.getInstance().getTextByID(23);</code>
+</li>
+
+<li>A class that gets a random text from the first 10 texts of the LanguageManager each time it is loaded:
+<code>
+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);
+	}
+}
+</code>
+</li>
+</ul>
 */
 
 class org.asapframework.management.lang.LanguageManager extends Dispatcher {
+	/** The event sent when the language xml has been loaded and parsed */	
+	public static var EVENT_LOADED:String = "onLanguageLoaded";
 
 	private var textDataItems:Array;	// of ItemData objects
 	private var textClips:Array;		// of MultiLanguageClipData objects
@@ -41,27 +122,12 @@
 	// singleton instance
 	private static var instance:LanguageManager = null;
 	private static var XML_NAME:String = "languagexml";
+
+	private var mURL : String;
 	
-	// The event sent when the language xml has been loaded and parsed	
-	public static var EVENT_LOADED:String = "onLanguageLoaded";
 	
 	
 	/**
-	Private singleton constructor.
-	*/
-	private function LanguageManager() {
-		
-		super();
-		
-		// XML loader
-		mXMLLoader = XMLLoader.getInstance();
-		mXMLLoader.addEventListener(XMLEvent.ON_LOADED, EventDelegate.create(this,onLanguageLoaded));
-		
-		textDataItems = new Array();
-		textClips = new Array();
-	}
-	
-	/**
 	@return The singleton instance of the LanguageManager
 	*/
 	public static function getInstance () : LanguageManager {
@@ -72,23 +138,29 @@
 	}
 	
 	/**
-	Loads language XML
+	Load language XML
+	@param inURL: full path of the xml file to be loaded
 	*/
 	public function loadXML ( inURL:String ) : Void {
+		mURL = inURL;
 		
 		// start loading
 		mXMLLoader.load(inURL,LanguageManager.XML_NAME, true);
 	}
 		
 	/**
-	Flag indicates whether items show their id as text when no text is found in the xml
+	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. 
 	*/
 	public function set generateDebugText (inGenerate:Boolean) : Void {
 		mGenerateDebugText = inGenerate;
 	}
 	
 	/**
-	Adds a multi-laguage container to the LanguageManager
+	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.
+	@param inID: the id to be associated with the container
+	@param inContainer: instance of a class implementing {@link IMultiLanguageTextContainer}
 	*/
 	public function addContainer (inID:Number, inContainer:IMultiLanguageTextContainer) : Void {
 		
@@ -100,7 +172,8 @@
 	}
 
 	/**
-	Removes a multi-laguage container from the LanguageManager
+	Remove a multi-laguage container from the LanguageManager
+	@param inContainer: previously added instance of a class implementing {@link IMultiLanguageTextContainer}
 	*/
 	public function removeContainer (inContainer:IMultiLanguageTextContainer) : Void {
 		var index:Number = getClipDataIndexByContainer(inContainer); 
@@ -111,7 +184,8 @@
 		
 	/**
 	Add text for a specific ID to the language manager.
-	Set the text in any textfield with that id
+	Set the text in any IMultiLanguageTextContainer instance associated with that id.
+	@param inData: {@link ItemData} instance containing necessary data.
 	*/
 	public function addText (inData:ItemData) : Void {
 		
@@ -127,14 +201,18 @@
 	}
 	
 	/**
-	
+	Retrieve a text
+	@param inID: the id for the text to be found
+	@return the text if found, an empty string if generateDebugText is set to false, or '>> id = ' + id if generateDebugText is set to true
 	*/
 	public function getTextByID (inID:Number) : String {
 		return getDataByID(inID).text;
 	}
 	
 	/**
-	
+	Retrieve text data
+	@param inID: the id for the text to be found
+	@return 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
 	*/
 	public function getDataByID (inID:Number) : ItemData {
 		if (textDataItems[inID] == undefined) {
@@ -149,7 +227,7 @@
 	}
 	
 	/**
-	Find the data block for the specified movieclip
+	Find the data block for the specified {@link IMultiLanguageTextContainer} instance
 	@return the data block for the clip, or null if none was found
 	*/
 	private function getClipDataByContainer (inContainer:IMultiLanguageTextContainer) : MultiLanguageClipData {
@@ -162,7 +240,7 @@
 	}
 	
 	/**
-	Find the index of the data block for the specified movieclip
+	Find the index of the data block for the specified {@link IMultiLanguageTextContainer} instance
 	@return the index of the data block, or -1 if none was found
 	*/
 	private function getClipDataIndexByContainer (inContainer:IMultiLanguageTextContainer) : Number {
@@ -209,9 +287,10 @@
 	}
 	
 	/**
-	Triggered by XMLLoader.
+	Handle event from the XMLLoader that the XML file has been loaded.
+	@param e: data for the event
 	*/
-	private function onLanguageLoaded ( e:XMLEvent ) : Void {
+	private function handleLanguageLoaded ( e:XMLEvent ) : Void {
 		// was language file loaded?
 		if (e.name == LanguageManager.XML_NAME) {
 			
@@ -224,6 +303,32 @@
 	}
 	
 	/**
+	Handle error event from the XMLLoader
+	*/
+	private function handleLanguageLoadError (e:XMLEvent) : Void {
+		if (e.name == LanguageManager.XML_NAME) {
+			Log.error("Error loading xml at url: " + mURL, toString());
+		}
+	}
+	
+	/**
+	Private singleton constructor.
+	*/
+	private function LanguageManager() {
+		
+		super();
+		
+		// XML loader
+		mXMLLoader = XMLLoader.getInstance();
+		mXMLLoader.addEventListener(XMLEvent.ON_LOADED, EventDelegate.create(this,handleLanguageLoaded));
+		mXMLLoader.addEventListener(XMLEvent.ON_ERROR, EventDelegate.create(this,handleLanguageLoadError));
+		mXMLLoader.addEventListener(XMLEvent.ON_TIMEOUT, EventDelegate.create(this,handleLanguageLoadError));
+		
+		textDataItems = new Array();
+		textClips = new Array();
+	}
+	
+	/**
 	@return Package and class name.
 	*/
 	public function toString () : String {

Modified: trunk/asapframework/org/asapframework/management/lang/MultiLanguageClipData.as
===================================================================
--- trunk/asapframework/org/asapframework/management/lang/MultiLanguageClipData.as	2006-10-30 16:00:14 UTC (rev 605)
+++ trunk/asapframework/org/asapframework/management/lang/MultiLanguageClipData.as	2006-10-30 21:55:24 UTC (rev 606)
@@ -19,7 +19,7 @@
 
 
 /**
-@author stephan.bezoen
+Internal ValueObject class used by the LanguageManager to store information on text containers.
 */
 
 class org.asapframework.management.lang.MultiLanguageClipData {
@@ -28,7 +28,9 @@
 	public var cnt:IMultiLanguageTextContainer;
 	
 	/**
-	
+	Constructor
+	@param inID: the id of the text assigned to the container
+	@param inContainer: instance of a class implementing {@link IMultiLanguageTextContainer}
 	*/
 	public function MultiLanguageClipData (inID:Number, inContainer:IMultiLanguageTextContainer) {
 		id = inID;

Modified: trunk/asapframework/org/asapframework/management/lang/MultiLanguageTextContainer.as
===================================================================
--- trunk/asapframework/org/asapframework/management/lang/MultiLanguageTextContainer.as	2006-10-30 16:00:14 UTC (rev 605)
+++ trunk/asapframework/org/asapframework/management/lang/MultiLanguageTextContainer.as	2006-10-30 21:55:24 UTC (rev 606)
@@ -20,7 +20,24 @@
 import org.asapframework.management.lang.LanguageManager;
 
 /**
-@author stephan.bezoen
+Basic implementation of {@link IMultiLanguageTextContainer} to be used with the {@link LanguageManager} to provide language dependent texts in an application.
+
+To use this class, perform the following steps:
+<ol>
+<li>Create a new movieclip in the library</li>
+<li>Give it a significant name containing font information, p.e. "arial 11px center"; this allows for easy reuse of containers</li>
+<li>Link it to the class org.asapframework.management.lang.MultiLanguageTextContainer</li>
+<li>Inside the movieclip, create a dynamic textfield. Name it "tf_txt"</li>
+<li>Set font embedding as necessary</li>
+<li>Place instances of the library item on the stage where necessary.</li>
+<li>Name the instances whatever you like, as long as the name ends with underscore, followed by the integer id of the text to be associated with the instance. P.e.: "helloWorld_1"</li>
+<li>In your application, load an xml file containing texts into the LanguageManager: <code>LanguageManager.getInstance().loadXML("texts_en.xml");</code></li>
+</ol>
+
+This class can be used either
+<ul><li>directly,</li>
+<li>as base class for further extension or </li>
+<li>as example of how to implement the {@link IMultiLanguageTextContainer} interface.</li></ul>
 */
 
 class org.asapframework.management.lang.MultiLanguageTextContainer extends MovieClip implements IMultiLanguageTextContainer {
@@ -32,9 +49,9 @@
 	private var base_w:Number;
 
 	/**
-	*	
+	Handle MovieClip onLoad event
 	*/
-	public function onLoad () : Void {
+	private function onLoad () : Void {
 		base_x = tf_txt._x;
 		base_y = tf_txt._y;
 		base_w = tf_txt._width;
@@ -45,14 +62,16 @@
 	}
 	
 	/**
-	*	
+	Handle MovieClip onUnload event
 	*/
-	public function onUnload () : Void {
+	private function onUnload () : Void {
 		LanguageManager.getInstance().removeContainer(this);
 	}
 	
 	/**
-	*	
+	IMultiLanguageTextContainer implementation
+	Set the data for the container
+	@param inData: the object containing the data
 	*/
 	public function setData (inData : ItemData) : Void {
 		setText(inData.text);
@@ -63,7 +82,9 @@
 	}
 	
 	/**
-	*	
+	IMultiLanguageTextContainer implementation
+	Set the text for the container
+	@param inText: the string containing the text
 	*/
 	public function setText (inText:String) : Void {
 		var tf:TextFormat = tf_txt.getTextFormat();


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.




2005	Jan	Feb	Mar	Apr	May	Jun	Jul	Aug	Sep (109)	Oct (25)	Nov (6)	Dec (6)
2006	Jan (263)	Feb (107)	Mar (62)	Apr (25)	May (39)	Jun (15)	Jul (19)	Aug (1)	Sep (54)	Oct (80)	Nov (61)	Dec
2007	Jan (1)	Feb (1)	Mar	Apr	May (22)	Jun (36)	Jul	Aug (3)	Sep (4)	Oct	Nov	Dec

S	M	T	W	T	F	S
1	2 (5)	3 (5)	4 (8)	5 (3)	6 (5)	7 (17)
8 (5)	9 (8)	10 (3)	11	12 (10)	13 (1)	14 (8)
15	16	17	18	19	20	21
22	23	24	25	26	27	28
29	30 (2)	31

asapframework-cvs Mailing List for ASAP ActionScript Application Framework

asapframework-cvs — This list broadcasts all commit changes made to the repository.