Runtime Environment: Chapter 3 - ActionScript 3.0 Cookbook
Pages: 1, 2, 3

Section 3.5: Detecting Display Settings

Problem

You want to know the display settings for the device on which the movie is being played.

Solution

Use the screenResolutionX and screenResolutionY properties of the system.capabilities object.

Discussion

You should use the flash.system.Capabilities object to determine the display settings of the device that is playing the movie. The screenResolutionX and screenResolutionY properties return the display resolution in pixels.

// Example output:
// 1024
// 768
trace(flash.system.Capabilities.screenResolutionX);
trace(flash.system.Capabilities.screenResolutionY);

You can use these values to determine how to display a movie, or even which movie to load. These decisions are increasingly important as more handheld devices support the Flash Player. For example, the dimensions of a cellphone screen and a typical desktop computer display are different, so you should load different content based on the playback device.

var resX:int = flash.system.Capabilities.screenResolutionX;
var resY:int = flash.system.Capabilities.screenResolutionY;

// If the resolution is 240 x 320 or less, then load the PocketPC
// movie version. Otherwise, assume the device is a desktop computer 
// and load the regular content.
if ( (resX <= 240) && (resY <= 320) ) {
  var url:String = "main_pocketPC.swf";
}
else {
  var url:String = "main_desktop.swf";
}
loader.load(new URLRequest(url));

You can also use the screen resolution values to center a pop-up browser window:

var resX:int = flash.system.Capabilities.screenResolutionX;
var resY:int = flash.system.Capabilities.screenResolutionY;

// Set variables for the width and height of the new browser window.
var winW:int = 200;
var winH:int = 200;

// Determine the X and Y values to center the window.
var winX:int = (resX / 2) - (winW / 2);
var winY:int = (resY / 2) - (winH / 2);

// Create the code that, when passed to URLLoader.load( )
// opens the new browser window.
var jsCode:String = "javascript:void(
         newWin=window.open('http://www.person13.com/'," + 
         "'newWindow', 'width=" + winW +
         ", height=" +  winH + "," + 
         "left=" + winX + ",top=" + winY + "'));";

// Call the JavaScript function using a URLLoader object
urlLoader.load(new URLRequest(jsCode));

Additionally, it is worth considering using the screen resolution values to determine whether or not to scale a movie. For example, when users have their resolution set to a high value, such as 1600/code>.

The Flash Player defaults to a scale mode of showAll. In this mode, the Flash movie scales to fit the player's size while maintaining the movie's original aspect ratio. The result is that the movie can potentially have borders on the sides if the Player's aspect ratio does not match the movie's aspect ratio. You can set a movie to showAll mode from your main application class as follows (don't forget to import the flash.display.StageScaleMode class):

stage.scaleMode = StageScaleMode.SHOW_ALL;

Note that stage is not a global object, but a property of any display object, so this statement only works in a sprite or other class that extends the DisplayObject class.

The noBorder mode scales a movie to fit the Player while maintaining the original aspect ratio; however, it forces the Player to display no borders around the Stage. If the aspect ratio of the Player does not match that of the movie, some of the movie will be cut off on the sides. You can set a movie to noBorder mode as follows:

stage.scaleMode = StageScaleMode.NO_BORDER;

The exactFit mode scales a movie to fit the Player, and it alters the movie's aspect ratio, if necessary, to match that of the Player. The result is that the movie always fills the Player exactly, but the elements of the movie may be distorted. For example:

stage.scaleMode = StageScaleMode.EXACT_FIT;

In noScale mode, the movie is not scaled, and it maintains its original size and aspect ratio regardless of the Stage's size. When you use the noScale mode, don't forget to set the movie's alignment (see Recipe 3.7, which includes example code that demonstrates the available alignment options). For example:

stage.scaleMode = StageScaleMode.NO_SCALE;

The scaleMode property's value does not prevent the user from being able to scale the movie using the right-click/Control-click menu. However, you can disable those options in the menu, as shown in Recipe 3.8.

See Also

Recipes 3.7 and 3.8

Section 3.7: Changing the Alignment

Problem

You want to change the alignment of the movie within the Player.

Solution

Use the stage.align property.

Discussion

Flash movies appear in the center of the Player by default. You can control the alignment of a movie within the Player by setting the stage.align property of any class that extends DisplayObject. The various alignment modes are implemented as strings, such as "T" for "top," "L" for "left," etc. However, to avoid errors in typing, these have also been made properties of the flash.display.StageAlign class, listed in Table 3-1.

The following class demonstrates the effects of both the scale mode and alignment of a movie within the player. Experiment by changing the stage.scaleMode and stage.align properties to their different values and scaling the browser to various sizes.

package {
  import flash.display.Sprite;
  import flash.display.StageScaleMode;
  import flash.display.StageAlign;

  public class ExampleApplication extends Sprite {
    public function ExampleApplication( ) {

      stage.scaleMode = StageScaleMode.NO_SCALE;
      stage.align = StageAlign.TOP_RIGHT;
      
      graphics.beginFill(0xff0000);
      graphics.drawRect(0, 0, stage.stageWidth, stage.stageHeight);
      graphics.endFill( );
    }
  }
}

Section 3.8: Hiding the Flash Player's Menu Items

Problem

You want to hide the right-click menu under Windows (Control-click on the Mac).

Solution

You can't disable the Flash Player's pop-up menu entirely, but you can minimize the options shown in the menu by setting the stage.showDefaultContextMenu property to false.

Discussion

By default, the following options appear in the Flash Player's pop-up menu when the user right-clicks in Windows (or Control-clicks on the Mac):

• Zoom In

• Zoom Out

• Show All

• Quality (Low, Medium, or High)

• Settings

• Print

• Show Redraw Regions (if using a debug player)

• Debugger (if using a debug player)

• About Adobe Flash Player 9

You can remove many of the options with the following line of ActionScript code, although the Settings and About and debug player options remain in place:

stage.showDefaultContextMenu = false;

Unfortunately, Flash does not provide any way to disable the menu entirely. Furthermore, Windows users are accustomed to using right-click to display a pop-up browser menu that allows them to open a link in a new window, for example. Such options are not available due to the Flash pop-up menu's presence.

See Also

See Recipe 3.11 for a way to display Flash's Settings dialog box without requiring the user to right-click (in Windows) or Control-click (on Mac).

Section 3.9: Detecting the Device's Audio Capabilities

Problem

You want to determine the audio capabilities of the device on which the Flash Player is running.

Solution

Use the hasAudio and hasMP3 properties of the flash.system.Capabilities class.

Discussion

The flash.system.Capabilities.hasAudio property returns true if the user's system has audio capabilities and false otherwise. This is extremely important for playing movies on multiple devices. If a device has no audio support, you want to avoid forcing users to download something they cannot hear (especially because audio can be quite large).

// Load a .swf containing sound only if the Player can play audio
if (flash.system.Capabilities.hasAudio) {
  content = "sound.swf";
} else {
  content = "silent.swf";
}
// code to load the .swf referenced in content

Just because a system has audio capabilities, however, does not necessarily mean that it can play back MP3 sounds. Therefore, if publishing MP3 content, you should test for MP3 capabilities using the flash.system.Capabilities.hasMP3 property. MP3 sounds are preferable, if supported, because they offer better sound quality to file size ratios than ADCP sounds.

// If the Player can play MP3s, load an MP3 using a Sound object. 
// Otherwise, load a .swf containing ADCP sound into a nested 
// sprite.
if (flash.system.Capabilities.hasMP3) {
  var url:URLRequest = new URLRequest("sound.mp3");
  sound = new Sound(url);
  sound.play( );
} else {
  // code to load an external .swf containing a ADCP sound
}

It is important to understand that the hasAudio and hasMP3 property settings are based on the capabilities of the Player and not of the system on which the Player is running. The desktop system players (for Windows, Mac OS, and Linux) always return true for both properties regardless of whether or not the system actually has the hardware (i.e., soundcard and speakers) to play back sounds. However, players for other devices may return false if the device does not support the audio or MP3 features.