Locale (mx.lang.Locale)


Object   |   +-mx.lang.Locale public class Locale extends Object

The mx.lang.Locale class allows you to control how multilanguage text is displayed in a SWF file. The Flash Strings panel allows you to use string IDs instead of string literals in dynamic text fields. This allows you to create a SWF file that displays text loaded from a language-specific XML file. The XML file must use the XML Localization Interchange File Format(XLIFF). There are three ways to display the language-specific strings contained in the XLIFF files:

  • "automatically at runtime" Flash Player replaces string IDs with strings from the XML file matching the default system language code returned by System.capabilities.language.

  • "manually using stage language" String IDs are replaced by strings at compile time and cannot be changed by Flash Player.

  • "via ActionScript at runtime" String ID replacement is controlled using ActionScript at runtime. This option gives you control over both the timing and language of string ID replacement.

You can use the properties and methods of this class when you want to replace the string IDs "via ActionScript at runtime."

All of the properties and methods available are static, which means that they are accessed through the mx.lang.Locale class itself rather than through an instance of the class.

Note: The Locale class is different from the other classes in the ActionScript 2.0 Language Reference, since it is not part of the Flash Player. Since this class installed in the Flash Authoring classpath it is automatically compiled into your SWF files. Using the Locale class increases the SWF size slightly since the class is compiled into the SWF.

Availability: ActionScript 2.0; Flash Player 7

Property summary

Modifiers

Property

Description

static

autoReplace:Boolean

Determines whether strings are replaced automatically after loading the XML file.

static

languageCodeArray:Array [read-only]

An array containing language codes for the languages that have been specified or loaded into the FLA file.

static

stringIDArray:Array [read-only]

An array containing all the string IDs in the FLA file.


Properties inherited from class Object

constructor (Object.constructor property), __proto__ (Object.__proto__ property), prototype (Object.prototype property), __resolve (Object.__resolve property)


Method summary

Modifiers

Signature

Description

static

addDelayedInstance (instance:Object, stringID:String) : Void

Adds the {instance, string ID} pair into the internal array for later use.

static

addXMLPath (langCode:String, path:String) : Void

Adds the {languageCode and languagePath} pair into the internal array for later use.

static

checkXMLStatus () : Boolean

Returns true if the XML file is loaded; false otherwise.

static

getdefaultLang () : String

The default language code as set in the Strings panel dialog box or by calling the setDefaultLang() method.

static

initialize () : Void

Automatically determines the language to use and loads the XML language file.

static

loadLanguageXML (xmlLanguageCode:String, customXmlCompleteCallback:Function) : Void

Loads the specified XML language file.

static

loadString (id:String) : String

Returns the string value associated with the given string ID in the current language.

static

loadStringEx (stringID:String, languageCode:String) : String

Returns the string value associated with the given string ID and language code.

static

setDefaultLang (langCode:String) : Void

Sets the default language code.

static

setLoadCallback (loadCallback:Function) : Void

Sets the callback function that is called after the XML file is loaded.

static

setString (stringID:String, languageCode:String, stringValue:String) : Void

Sets the new string value of a given string ID and language code.


Methods inherited from class Object

addProperty (Object.addProperty method), hasOwnProperty (Object.hasOwnProperty method), isPropertyEnumerable (Object.isPropertyEnumerable method), isPrototypeOf (Object.isPrototypeOf method), registerClass (Object.registerClass method), toString (Object.toString method), unwatch (Object.unwatch method), valueOf (Object.valueOf method), watch (Object.watch method)


addDelayedInstance (Locale.addDelayedInstance method)

public static addDelayedInstance(instance:Object, stringID:String) : Void

Adds the {instance, string ID} pair into the internal array for later use. This is primarily used by Flash when the strings replacement method is "automatically at runtime".

Availability: ActionScript 2.0; Flash Player 7

Parameters

instance:Object - Instance name of the text field to populate.

stringID:String - Language string ID.

Example

The following example uses the autoReplace property and addDelayedInstance() method to populate a text field on the Stage with the IDS_GREETING string from the English XML language file.

import mx.lang.Locale; greeting_txt.autoSize = "left"; Locale.autoReplace = true; Locale.addDelayedInstance(greeting_txt, "IDS_GREETING"); Locale.loadLanguageXML("en");

addXMLPath (Locale.addXMLPath method)

public static addXMLPath(langCode:String, path:String) : Void

Adds the {languageCode and languagePath} pair into the internal array for later use. This is primarily used by Flash when the strings replacement method is "automatically at runtime" or "via ActionScript at runtime".

Availability: ActionScript 2.0; Flash Player 7

Parameters

langCode:String - The language code.

path:String - The XML path to add.

Example

The following example uses the setInterval() method to check whether the language XML file has successfully loaded.

import mx.lang.Locale; Locale.setLoadCallback(localeCallback); Locale.loadLanguageXML("en"); // create interval to check if language XML file is loaded var locale_int:Number = setInterval(checkLocaleStatus, 10); function checkLocaleStatus():Void {   if (Locale.checkXMLStatus()) {     clearInterval(locale_int);     trace("clearing interval @ " + getTimer() + " ms");   } } // callback function for Locale.setLoadCallback() function localeCallback(success:Boolean):Void {   greeting_txt.text = Locale.loadString("IDS_GREETING"); }

autoReplace (Locale.autoReplace property)

public static autoReplace : Boolean

Determines whether strings are replaced automatically after loading the XML file. If set to true, the text replacement method is equivalent to the Strings panel setting "automatically at runtime". This means that Flash Player will determine the default language of the host environment and automatically display the text in that language. If set to false, the text replacement method is equivalent to the Strings panel setting "via ActionScript at runtime". This means that you are responsible for loading the appropriate XML file to display the text.

The default value of this property reflects the setting that you select for Replace strings in the Strings panel dialog box: TRue for "automatically at runtime" (the default setting) and false for "via ActionScript at runtime".

Availability: ActionScript 2.0; Flash Player 8

Example

The following example uses the Locale.autoReplace property to populate the dynamically created greeting_txt text field on the Stage with the contents of the IDS_GREETING string in the English XML file. In the Strings panel, click the Settings button to open the Settings dialog box. You can add two active languages using the Settings dialog box: English (en) and French (fr), set the replacement strings radio option to "via ActionScript at runtime", and click OK. Finally, enter a string ID of IDS_GREETING in the Strings panel, and add text for each active language.

import mx.lang.Locale; this.createTextField("greeting_txt", 10, 40, 40, 200, 20); greeting_txt.autoSize = "left"; Locale.autoReplace = true; Locale.addDelayedInstance(greeting_txt, "IDS_GREETING"); Locale.loadLanguageXML("en");

checkXMLStatus (Locale.checkXMLStatus method)

public static checkXMLStatus() : Boolean

Returns true if the XML file is loaded; false otherwise.

Availability: ActionScript 2.0; Flash Player 7

Returns

Boolean - Returns TRue if the XML file is loaded; false otherwise.

Example

The following example uses an interval to check every 10 milliseconds to see if the language file has successfully loaded. Once the XML file has loaded, the greeting_txt text field instance on the Stage is populated with the IDS_GREETING string from the language XML file.

import mx.lang.Locale; Locale.setLoadCallback(localeCallback); Locale.loadLanguageXML("en"); // create interval to check if language XML file is loaded var locale_int:Number = setInterval(checkLocaleStatus, 10); function checkLocaleStatus():Void {   if (Locale.checkXMLStatus()) {     clearInterval(locale_int);     trace("clearing interval @ " + getTimer() + " ms");   } } // callback function for Locale.setLoadCallback() function localeCallback(success:Boolean):Void {   greeting_txt.text = Locale.loadString("IDS_GREETING"); }

getDefaultLang (Locale.getDefaultLang method)

public static getDefaultLang() : String

The default language code as set in the Strings panel dialog box or by calling the setDefaultLang() method.

Availability: ActionScript 2.0; Flash Player 8

Returns

String - Returns the default language code.

Example

The following example creates a variable called defLang, which is used to hold the initial default language for the Flash document. You click the Settings button in the Strings panel to launch the Settings dialog box. Then you add two active languages: English (en) and French (fr), set the replace strings radio control to "via ActionScript at runtime", and click OK. In the Strings panel, you add a string ID of IDS_GREETING, and then add text for each active language.

import mx.lang.Locale; var defLang:String = "fr"; Locale.setDefaultLang(defLang); Locale.setLoadCallback(localeCallback); Locale.loadLanguageXML(Locale.getDefaultLang()); function localeCallback(success:Boolean) {   if (success) {   trace(Locale.stringIDArray); // IDS_GREETING   trace(Locale.loadString("IDS_GREETING"));   } else {     trace("unable to load XML");   } }

See also

setDefaultLang (Locale.setDefaultLang method)

initialize (Locale.initialize method)

public static initialize() : Void

Automatically determines the language to use and loads the XML language file. This is primarily used by Flash when the strings replacement method is "automatically at runtime".

Availability: ActionScript 2.0; Flash Player 7

Example

This example shows how to use the initialize() method to automatically populate the greeting_txt text field on the Stage with the user's current OS language. Instead of using the initialize() method directly, use the string replacement method of "automatically at runtime".

import mx.lang.Locale; trace(System.capabilities.language); Locale.autoReplace = true; Locale.addDelayedInstance(greeting_txt, "IDS_GREETING"); Locale.initialize();

languageCodeArray (Locale.languageCodeArray property)

public static languageCodeArray : Array [read-only]

An array containing language codes for the languages that have been specified or loaded into the FLA file. The language codes are not sorted alphabetically.

Availability: ActionScript 2.0; Flash Player 8

Example

The following example loads a language XML file based on the current value of a ComboBox component. You drag a ComboBox component onto the Stage and give it an instance name of lang_cb. Using the Text tool, you create a dynamic text field and give it an instance name of greeting_txt. In the Strings panel, you add at least two active languages, set the replace strings radio option to "via ActionScript at runtime", and click OK. Next, you add a string ID of IDS_GREETING and enter text for each active language. Finally, you add the following ActionScript code to Frame 1 of the main Timeline:

import mx.lang.Locale; Locale.setLoadCallback(localeListener); lang_cb.dataProvider = Locale.languageCodeArray.sort(); lang_cb.addEventListener("change", langListener); function langListener(eventObj:Object):Void {   Locale.loadLanguageXML(eventObj.target.value); } function localeListener(success:Boolean):Void {   if (success) {     greeting_txt.text = Locale.loadString("IDS_GREETING"); } else {   greeting_txt.text = "unable to load language XML file.";   } }

loadLanguageXML (Locale.loadLanguageXML method)

public static loadLanguageXML(xmlLanguageCode:String,   customXmlCompleteCallback:Function) : Void

Loads the specified XML language file.

Availability: ActionScript 2.0; Flash Player 8

Parameters

xmlLanguageCode:String - The language code for the XML language file that you want to load.

customXmlCompleteCallback:Function - Custom callback function to call when XML language file loads.

Example

The following example uses the loadLanguageXML() method to load the English (en) XML language file. Once the language file loads, the localeCallback() method is called and populates the greeting_txt text field on the Stage with the contents of the IDS_GREETING string in the XML file.

import mx.lang.Locale; Locale.setLoadCallback(localeCallback); Locale.loadLanguageXML("en"); // create interval to check if language XML file is loaded var locale_int:Number = setInterval(checkLocaleStatus, 10); function checkLocaleStatus():Void {   if (Locale.checkXMLStatus()) {     clearInterval(locale_int);     trace("clearing interval @ " + getTimer() + " ms");   } } // callback function for Locale.setLoadCallback() function localeCallback(success:Boolean):Void {   greeting_txt.text = Locale.loadString("IDS_GREETING"); }

loadString (Locale.loadString method)

public static loadString(id:String) : String

Returns the string value associated with the given string ID in the current language.

Availability: ActionScript 2.0; Flash Player 7

Parameters

id:String - The identification (ID) number of the string to load.

Returns

String - The string value associated with the given string ID in the current language.

Example

The following example uses an interval to check every 10 milliseconds to see if the language file has successfully loaded. Once the XML file has loaded, the greeting_txt text field instance on the Stage is populated with the IDS_GREETING string from the XML language file.

import mx.lang.Locale; Locale.setLoadCallback(localeCallback); Locale.loadLanguageXML("en"); // create interval to check if language XML file is loaded var locale_int:Number = setInterval(checkLocaleStatus, 10); function checkLocaleStatus():Void {   if (Locale.checkXMLStatus()) {   clearInterval(locale_int);   trace("clearing interval @ " + getTimer() + " ms");   } } // callback function for Locale.setLoadCallback() function localeCallback(success:Boolean):Void {    greeting_txt.text = Locale.loadString("IDS_GREETING"); }

See also

loadStringEx (Locale.loadStringEx method)

loadStringEx (Locale.loadStringEx method)

public static loadStringEx(stringID:String, languageCode:String) : String

Returns the string value associated with the given string ID and language code. To avoid unexpected XML file loading, loadStringEx() does not load the XML language file if the XML file is not already loaded. You should decide on the right time to call the loadLanguageXML() method if you want to load a XML language file.

Availability: ActionScript 2.0; Flash Player 8

Parameters

stringID:String - The identification (ID) number of the string to load.

languageCode:String - The language code.

Returns

String - The string value associated with the given string ID in the language specified by the languageCode parameter.

Example

The following example uses the loadStringEx() method to trace the value of the IDS_GREETING string for the currently loaded French language XML file.

import mx.lang.Locale; Locale.setLoadCallback(localeCallback); Locale.loadLanguageXML("fr"); function localeCallback(success:Boolean) {   trace(success);   trace(Locale.stringIDArray); // IDS_GREETING   trace(Locale.loadStringEx("IDS_GREETING", "fr")); // bonjour }

See also

loadString (Locale.loadString method)

setDefaultLang (Locale.setDefaultLang method)

public static setDefaultLang(langCode:String) : Void

Sets the default language code.

Availability: ActionScript 2.0; Flash Player 7

Parameters

langCode:String - A string representing a language code.

Example

The following example creates a variable called defLang, which is used to hold the initial default language for the Flash document. You click the Settings button in the Strings panel to open the Settings dialog box. Then you add two active languages: English (en) and French (fr), set the replace strings radio control to "via ActionScript at runtime", and click OK. In the Strings panel, you add a string ID of IDS_GREETING, and then add text for each active language.

import mx.lang.Locale; var defLang:String = "fr"; Locale.setDefaultLang(defLang); Locale.setLoadCallback(localeCallback); Locale.loadLanguageXML(Locale.getDefaultLang());   function localeCallback(success:Boolean) {     if (success) {       trace(Locale.stringIDArray); // IDS_GREETING       trace(Locale.loadString("IDS_GREETING"));     } else {       trace("unable to load XML");     } }

See also

getDefaultLang (Locale.getDefaultLang method)

setLoadCallback (Locale.setLoadCallback method)

public static setLoadCallback(loadCallback:Function) : Void

Sets the callback function that is called after the XML file is loaded.

Availability: ActionScript 2.0; Flash Player 7

Parameters

loadCallback:Function - The function to call when the XML language file loads.

Example

The following example uses an interval to check every 10 milliseconds to see if the language file has successfully loaded. Once the XML file has loaded, the greeting_txt text field instance on the Stage is populated with the IDS_GREETING string from the XML language file.

import mx.lang.Locale; Locale.setLoadCallback(localeCallback); Locale.loadLanguageXML("en"); // create interval to check if language XML file is loaded var locale_int:Number = setInterval(checkLocaleStatus, 10); function checkLocaleStatus():Void {   if (Locale.checkXMLStatus()) {      clearInterval(locale_int);      trace("clearing interval @ " + getTimer() + " ms");   } } // callback function for Locale.setLoadCallback() function localeCallback(success:Boolean):Void {   greeting_txt.text = Locale.loadString("IDS_GREETING"); } xs

setString (Locale.setString method)

public static setString(stringID:String, languageCode:String,   stringValue:String) : Void

Sets the new string value of a given string ID and language code.

Availability: ActionScript 2.0; Flash Player 8

Parameters

stringID:String - The identification (ID) number of the string to set.

languageCode:String - The language code.

stringValue:String - A string value.

Example

The following example uses the setString() method to set the IDS_WELCOME string for both English (en) and French (fr).

import mx.lang.Locale; Locale.setString("IDS_WELCOME", "en", "hello"); Locale.setString("IDS_WELCOME", "fr", "bonjour"); trace(Locale.loadStringEx("IDS_WELCOME", "en")); // hello

stringIDArray (Locale.stringIDArray property)

public static stringIDArray : Array [read-only]

An array containing all the string IDs in the FLA file. The string IDs are not sorted alphabetically.

Availability: ActionScript 2.0; Flash Player 8

Example

The following example traces the Locale.stringIDArray property for the currently loaded language XML file. Click the Settings button in the Strings panel to open the Settings dialog box. Next, you add two active languages: English (en) and French (fr), set the replace strings radio control to "via ActionScript at runtime", and click OK. In the Strings panel, you add a string ID of IDS_GREETING, and then add text for each active language.

import mx.lang.Locale; Locale.setLoadCallback(localeCallback); Locale.loadLanguageXML("fr"); function localeCallback(success:Boolean) {   trace(success);   trace(Locale.stringIDArray); // IDS_GREETING   trace(Locale.loadStringEx("IDS_GREETING", "fr")); // bonjour }



ActionScript 2.0 Language Reference for Macromedia Flash 8
ActionScript 2.0 Language Reference for Macromedia Flash 8
ISBN: 0321384040
EAN: 2147483647
Year: 2004
Pages: 113

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net