asdg>> technotes>> against the use of System.useCodePage

Version: Flash MX
Date Added: January 30, 2003

The System.useCodePage property is suggested by many as a magical cure to character display problems in Flash. Unfortunately, while useCodePage may appear to fix a problem on a single machine, it can create problems on others. This technote is an excerpt from ASDG2 explaining why you should avoid System.useCodePage unless you know *exactly* what you're doing. If you just want to use a special character in Flash and you are exporting to Flash Player 6 or later, you should follow these instructions.

Unicode is an international character set comprising all the characters of the world's languages. Most modern applications, including Flash Player 6, use Unicode to manage and display text. Older applications, including Flash Player 5, manage text using the operating system's so called code page (essentially, a regional character set).

The System.useCodepage property controls:

  • Display of text fields
  • XML.load(), XML.send(), and XML.sendAndLoad() operations
  • LoadVars.load(), LoadVars.send(), and LoadVars.sendAndLoad() operations
  • getURL(), loadMovie(), and loadVariables() actions that transmit/receive variables
  • XMLSocket communications
  • escape() and unescape() functions

When a non-Unicode application renders a character to the screen, it looks up the character by its code point in the system's current code page. The character displayed on screen is the one specified by the code page in use at display time. If the input code page (the one in effect when the character was input) does not match the display code page (the one in use when the application renders the character), the input character specified will likely not match the character displayed. The Unicode standard was introduced to solve this problem. Because Flash 6 uses Unicode, you should have no need for the System.useCodepage property as long as you:

  • Use Unicode (encoded using either UTF-8 or UTF-16) for all external text
  • Use a Unicode escape sequence to include any character you cannot enter via your keyboard in the Flash authoring tool

The Boolean useCodepage property can force Flash Player 6 to use the operating system's current code page, rather than Unicode, when rendering text, as follows:

// Force use of the operating system's code page
System.useCodepage = true;

System.useCodepage can be modified at any time--for example, at the beginning and end of an operation that requires a legacy text encoding, such as loading an existing text file that uses a specific encoding.

When exporting Flash 6-format .swf files from the Flash MX authoring tool, it rarely is necessary to use the useCodepage property (Flash MX automatically converts text entered in the authoring tool to Unicode upon export). However, when the following two conditions are both true, setting the useCodepage property to true will force non-Unicode text to display as intended:

  1. Non-Unicode text is loaded into the Flash Player, from either an external text file or a server script.
  2. The external text happens to be encoded with the same code page that is currently set on the end-user operating system running the Flash Player.

The only time you should ever use useCodePage is when the above conditions are true! The text will not display correctly if the operating system's current code page does not match the input code page! Though forcing the use of the operating system's code page may appear to magically fix text display problems on one computer, setting System.useCodepage to true almost never suitably addresses international text display issues.

Hence, whenever possible, all external files should use Unicode, and useCodepage should be left at its default setting, false.

By default, most western Windows computers use code page CP1252 (WinLatin1). Mappings from CP1252 to Unicode can be found at:

By default, most Japanese Windows computers use code page CP932 (Windows Shift-JIS). Mappings from CP932 to Unicode can be found at:

For a partial list of code pages used by other vendors see: