Runtime Environment: Chapter 3 - ActionScript 3.0 Cookbook

by Joey Lott, Darron Schall, Keith Peters

This excerpt is from ActionScript 3.0 Cookbook. Well before Ajax and Windows Presentation Foundation, Macromedia Flash provided the first method for building "rich" web pages. Now, Adobe is making Flash a full-fledged development environment, and learning ActionScript 3.0 is key. That's a challenge for even the most experienced Flash developer. This Cookbook offers more than 300 solutions to solve a wide range of coding dilemmas, so you can learn to work with the new version right away.

buy button

Section 3.0: Introduction

Flash Player 9 offers a relatively large amount of information about and control over the runtime environment. The flash.system.Capabilities class has many static methods that return information about the player and the computer on which it is running, such as the operating system, language, audio, and video capabilities. There are other classes such as flash.display.Stage and flash.system.Security that allow you to control other elements of the Player such as the right-click menu under Windows (Control-click on the Macintosh) and the Settings dialog box. The flash.display.Stage class also controls the scaling and alignment of the movie within the Player.

Perhaps one of the most significant updates to Flash Player 7 within this chapter's subject matter is the ability to work with the context menu with more detail and precision than was allowed in previous versions of the player. In Flash Player 7, using the ContextMenu class, you can programmatically remove items from the context menu, and perhaps more importantly, you can add items to the menu. And as the name suggests, you can make the context menu so it is actually contextual, so that items in the menu are based on the object on which the menu is being displayed.

Section 3.1: Detecting the Player Version


You want to ensure that the user has the correct version of the Flash Player.


Use the Flash Player Detection Kit, available on Adobe's web site to check the version of player and, if necessary, initiate a player upgrade (


Detecting the currently installed version of the Flash Player in the user's browser has been a problem for years, and there have been many solutions used by various developers. They generally fall into three categories:

  • Browser-based script detection
  • Server-side detection
  • ActionScript detection

The first method uses JavaScript or VBScript to detect the version of the Flash Player the user has installed. Many of these scripts were prone to errors due to differences in platforms and browser types.

Server-side detection can be difficult if you don't have the ability to create server-side scripts.

Most ActionScript-based player detection techniques won't work directly in an ActionScript 3.0-based .swf. While ActionScript 1.0 and 2.0 had various object methods, variables, and functions that would return the player version, none of those are now valid in an ActionScript 3.0 class. ActionScript 3.0 has its own way of detecting the player version--the flash.system.Capabilities.version property. This, of course, won't work at all with any version of the Flash Player prior to 8.5, so it is rather useless for Flash detection.

Adobe has researched all of these issues thoroughly, and came out with a Flash Player Detection Kit that guides you through the recommended procedures for best detecting the player version.

The kit includes documentation on the various issues and potential solutions, including sample VBScript and JavaScript for browser-based detection; .flas, .as, and .swf files for ActionScript detection; as well as ColdFusion and PHP scripts for server-side detection.

ActionScript-based detection works successfully as long as the user has any version of the Flash Player from Version 4 on up. Basically, it is a Flash 4 .swf that executes a script to detect the current player version; all you need to do is set your minimum content version as a variable in the script. If the player version is at least as high as the content version, it loads the specified content. If not, it redirects the browser to an alternate content page. This page can contain a lower version .swf, a non-Flash version of the content, or a notice instructing the user to upgrade his Flash Player, with a link to the player install page on Adobe's site.

Furthermore, the kit contains a .swf and HTML template that initializes an Express Install of the latest version of the Flash Player. If the user's player is not adequate, the browser is redirected to this .swf, which downloads the latest version of the Flash Player from Adobe's site, automatically installs it, and finally redirects the user back to the specified Flash content, all without the user ever leaving your site. This option requires that the user already have Version of the Flash Player installed.

Using a combination of the techniques included in the Flash Player Detection Kit gives you very precise control over the Flash Player version and the content you deliver to your viewers.

For testing purposes, older versions of the Flash Player can be obtained from Macromedia's site (

Section 3.2: Detecting the Operating System


You want to know the operating system under which the Flash movie is being played, perhaps to indicate which operating systems are not supported or to implement a platform-specific feature.


Use the flash.system.Capabilities.os property.


In ActionScript 3.0, you can use the flash.system.Capabilities.os property, which returns a string indicating the operating system and version name. Possible values include Windows XP, Windows 2000, Windows NT, Windows 98/Me, Windows 95, and Windows CE. On the Macintosh, the string includes the version number, such as Mac OS 9.2.1 or Mac OS X 10.4.4.

You can make design choices based on the operating system. For example, your movie might load different assets depending on the user's operating system. Or, you may simply want to record the operating systems of the users who view your movies for statistical analysis.

If all you care about is the general platform type, instead of the specific version, you can check just the first three letters of the string as follows:

var os:String = System.capabilities.os.substr(0, 3);
if (os == "Win") {
  // Windows-specific code goes here
} else if (os == "Mac") {
  // Mac-specific code goes here
} else {
  // Must be Unix or Linux

Section 3.3: Checking the Player Type


You want to know what type of Flash Player the .swf is being run from.


Use the flash.system.Capabilities.playerType property.


The different types of Flash Player include:

  • Browser plug-in that runs in web browsers such as Mozilla or Firefox
  • ActiveX Control used by Internet Explorer
  • Standalone player, which plays .swfs outside of the browser
  • External player, which is the player integrated in the Flash IDE

There are instances when you need to know which player the .swf is currently being run in. For example, if you are doing any type of integration with browser scripts (e.g., JavaScript, VBScript), it may be important to know whether the application is being run in Internet Explorer or some other type of browser, as these browsers can have different behaviors when running scripts. Indeed, it would be vital to know that the .swf was being run in a standalone player, since JavaScript, etc., would not be available at all in such a case.

To check the player type, look at the value of flash.system.Capabilities.playerType. Possible values are PlugIn, ActiveX, StandAlone, and External. You could use this in an if statement:

if(flash.system.Capabilities.playerType == "Plugin") {
  // do actions for Mozilla, etc. browsers
else if(flash.system.Capabilities.playerType == "ActiveX") {
  // do actions for IE
else {
  // do actions for no browser

Section 3.4: Checking the System Language


You want to know what language is used on the computer viewing the movie and how the user will input text.


Use the flash.system.Capabilities.language property and the flash.system.IME class.


You can use the flash.system.Capabilities.language property to determine the language that is used on the computer on which the movie is being played. The property returns a two-letter ISO-639-1 language code (e.g., "fr" for French). Where applicable, a two-letter country code is appended, separated from the country code with a hyphen (e.g., "zh-CN" for Simplified Chinese and "zh-TW" for Traditional Chinese).

For a summary of language codes, see and

Here is an example of how to use the language property:

// Example output: en-US

You can use this property to dynamically load content in the appropriate language:

// Create an associative array with language codes for the keys 
// and greetings for the values.
var greetings:Array = new Array( );
greetings["en"] = "Hello";
greetings["es"] = "Hola";
greetings["fr"] = "Bonjour";

// Extract the first two characters from the language code.
var lang:String = flash.system.Capabilities.language.substr(0, 2);

// Use a default language if the language is not in the list
if (greetings[lang] == undefined) {
  lang = "en";

// Display the greeting in the appropriate language.

When you want to offer multiple language capabilities in your movies, you can choose from several different approaches. One, as shown in the preceding code, is to create associative arrays for all the text that appears in the movie. Another approach is to create static content in multiple movies (one for each language) and to load those movies based on the language code. With this technique, each .swf filename should include the language code, such as myMovie_en.swf, myMovie_es.swf, myMovie_fr.swf, etc.

// Get the language from the capabilities object.
var lang:String = System.capabilities.language.substr(0, 2);

// Create an array of the languages you are supporting (i.e., 
// the languages for which you have created movies).
var supportedLanguages:Array = ["en", "es", "fr"];

// Set a default language in case you don't support the user's 
// language.
var useLang:String = "en";

// Loop through the supported languages to find a match to the 
// user's language. If you find one, set useLang to that value 
// and then exit the for statement.
for (var i:int = 0; i < supportedLanguages.length; i++) {
  if (supportedLanguages[i] == lang) {
    useLang = lang;

// Load the corresponding movie.
var movieURL:String =  "myMovie_" + useLang + ".swf");

It is also often important to know how a user will be entering text on her system. Languages, such as Chinese, Japanese, and Korean, can have thousands of possible characters. To enter these characters via the keyboard, a special program called an Input Method Editor (IME) is required. This is usually part of the operating system of the particular language.

To detect if the user's system has an IME, check the value of flash.system.Capabilities.hasIME, which will return true or false. Then use the flash.system.IME class to get more information about and interact with the IME. The flash.system.IME.enabled property tells you whether the user is using the IME or entering text straight from the keyboard. This property is actually writable, so you can use it to turn on the IME. On some platforms and OS versions, you can send a string to the IME to be converted into the correct characters, and accept the output of the IME back into a selected text field. Since this does not work on all systems, it is best to check the OS first (see Recipe 3.2).

See Also

Recipe 3.2

Pages: 1, 2, 3

Next Pagearrow